diff options
113 files changed, 1301 insertions, 1113 deletions
diff --git a/docs/source/adc.rst b/docs/source/adc.rst index b943808..af613cc 100644 --- a/docs/source/adc.rst +++ b/docs/source/adc.rst @@ -6,23 +6,12 @@ Analog-Digital Conversion is the process of reading a physical voltage as a number. The Maple has a large number of pins which are capable of -taking 12-bit ADC measurements, which means that voltages from ground -to +3.3v are read as numbers from 0 to 4095; this corresponds to a +taking 12-bit ADC measurements, which means that voltages from 0 to +3.3V are read as numbers from 0 to 4095. This corresponds to a theoretical sensitivity of just under 1 millivolt. In reality, a -number of factors introduce noise and bias into this reading and a +number of factors introduce noise and bias into this reading, and a number of techniques must be used to get good precision and accuracy. -.. compound:: - - The header pins with ADC functionality (marked as "AIN" on the - silkscreen) are: - - D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 - - Note that pins 3, 27, and 28 are not marked AIN on the silkscreen - for Maple revisions through Rev 5, however, they **do work** as - analog input pins. - .. contents:: Contents :local: @@ -31,13 +20,15 @@ number of techniques must be used to get good precision and accuracy. Noise and Bias -------------- +.. FIXME [0.0.10, Maple-specific] + The biggest issues with analog-digital conversion are noise and bias. With the Maple, we have tried to isolate the ADC pins and traces from -strong noise sources but there are always trade--offs between noise, +strong noise sources, but there are always trade--offs between noise, additional functionality, cost, and package size. The 6 ADC pins in a bank (D15--D20) generally have the least -noise and should be used for fine measurements. If the input voltage +noise, and should be used for fine measurements. If the input voltage changes relatively slowly, a number of samples can be taken in succession and averaged together, or the same voltage can even be sampled by multiple ADC pins at the same time. @@ -47,34 +38,40 @@ voltages that the sample is being compared against. In the case of the Maple, the high reference is |vcc| and the low reference is ground. This means that noise or fluctuations on either |vcc| or ground will affect the measurement. It also means that the voltage you are trying -to sample must be between ground and 3.3V. In the case of a variable -reading, it is best if the voltage varies over the entire range of -0--3.3V; otherwise, only a fraction of the sensitivity is being -leveraged. Resistor dividers and constant voltage diodes are basic -tools which can help bring a given voltage signal into the appropriate -range; opamps and other powered components can also be used. +to sample must be between ground and 3.3V. + +.. _adc-range: + +In the case of a variable reading, it is best if the voltage varies +over the entire range of 0--3.3V; otherwise, only a fraction of the +sensitivity is being leveraged. Some basic tools to accomplish this +are `resistor dividers +<http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener diodes +<http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\ +. However, `operational amplifiers +<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other +powered components can also be used if greater precision is required. .. _adc-function-reference: Function Reference ------------------ -.. doxygenfunction:: analogRead - -.. doxygenfunction:: pinMode - -.. doxygenenum:: WiringPinMode +* :ref:`lang-analogread` +* :ref:`lang-pinmode` .. _adc-recommended-reading: Recommended Reading ------------------- -* `Wikipedia article on Analog-to-digital converter <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ - -* `Arduino Analog Input Tutorial <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ - -* STMicro documentation: +* `Wikipedia: Analog-to-Digital Converter + <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ +* `Arduino Analog Input Tutorial + <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ +* ST documentation: - * `Application Note on ADC Modes (pdf) <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ - * `Application Note on ADC Oversampling (pdf) <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ + * `Application Note on ADC Modes + <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ (PDF) + * `Application Note on ADC Oversampling + <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ (PDF) diff --git a/docs/source/lang/api/cc-attribution.txt b/docs/source/arduino-cc-attribution.txt index e100140..ad1c1e0 100644 --- a/docs/source/lang/api/cc-attribution.txt +++ b/docs/source/arduino-cc-attribution.txt @@ -1,9 +1,9 @@ -.. Included in all this directory's files in order to satisfy the -.. Arduino CC Attribution-ShareAlike 3.0 License +.. Included in all relevant files in order to satisfy the Arduino +.. CC Attribution-ShareAlike 3.0 License .. admonition:: License and Attribution - This documentation page was adapted from the `Arduino Reference + Portions of this page were adapted from the `Arduino Reference Documentation <http://arduino.cc/en/Reference/HomePage>`_\ , which is released under a `Creative Commons Attribution-ShareAlike 3.0 License <http://creativecommons.org/licenses/by-sa/3.0/>`_. diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 85b2674..ec4fe73 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -1,8 +1,9 @@ .. highlight:: sh -===================== - Maple Bootloader(s) -===================== +.. _bootloader: + +Maple Bootloader(s) +=================== The firmware which allows the Maple to be reprogrammed via a USB connection. Every Maple board comes programmed with this by default, diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst index b2cbbb1..ac065a4 100644 --- a/docs/source/external-interrupts.rst +++ b/docs/source/external-interrupts.rst @@ -6,73 +6,42 @@ External Interrupts =================== External interrupts can be used to trigger routines to run in response -to changes in voltage on a pin. Each GPIO pin on the Maple can be used -to detect transitions such as when the voltage goes from low to high, -or from high to low. This technique can be used to avoid unnecessary -polling of the state of a pin. +to changes in voltage on a pin. Each :ref:`GPIO pin <gpio>` can be +used to detect transitions, such as when the voltage goes from +:ref:`LOW <lang-constants-low>` to :ref:`HIGH <lang-constants-high>`, +or from ``HIGH`` to ``LOW``. This can be used to avoid checking for +changes on a pin "manually" by waiting in a loop until the pin +changes. .. _contents: Contents :local: - Overview -------- External interrupts are often used to detect when events happen -outside of the microcontroller. These can be used to tell the Maple -when events happen, such as when a sensor has data ready to be read, -or when a button has been pushed. When such an event happens, an -interrupt is raised and the Maple can react to it with a preset -*interrupt handler*. - -Every GPIO pin on the Maple can be used as an external interrupt, -subject to certain constraints; there can be a maximum of 16 different -external interrupts set up at a time on the Maple. This is because the -external interrupt lines on the STM32 are multiplexed between GPIO -ports. In effect, this means that every pin on the Maple maps to a -certain EXTI line, and within that EXTI line, only one of the pins -that maps to it can be used as an external interrupt at a time. - -The following table shows which pins can be used on which lines. - -.. list-table:: - :widths: 1 1 - :header-rows: 1 - - * - EXTI Line - - Maple pins - * - EXTI0 - - 2, 15, 27 - * - EXTI1 - - 3, 16, 28 - * - EXTI2 - - 1, 17, 25 - * - EXTI3 - - 0, 18 - * - EXTI4 - - 10, 19 - * - EXTI5 - - 4, 13, 20 - * - EXTI6 - - 5, 12, 35 - * - EXTI7 - - 9, 11, 36 - * - EXTI8 - - 6, 14, 37 - * - EXTI9 - - 7, 25, 28 - * - EXTI10 - - 8, 26, 29 - * - EXTI11 - - 30 - * - EXTI12 - - 31 - * - EXTI13 - - 21, 32 - * - EXTI14 - - 22, 33 - * - EXTI15 - - 23, 34 +outside of the microcontroller. These can be used to tell Maple when +events happen, such as when a sensor has data ready to be read, or +when a button has been pushed. When such an event happens, an +interrupt is raised, and the Maple can react to it with a preset +*interrupt handler*, which is a function that gets called whenever the +event occurs. + +.. _external-interrupts-exti-line: + +Every GPIO pin can generate an external interrupt, subject to certain +constraints. There can be a maximum of 16 different external +interrupts set up at a time. This is because the external interrupt +lines on the STM32 are shared between GPIO ports. In effect, this +means that every pin on the Maple connects to what is called an *EXTI +line*, and within an EXTI line, only one of the pins that connects to +it can be used to detect external interrupts at a time. + +The EXTI Line Pin Map for your board lists which pins connect to which +EXTI lines: + +* :ref:`Maple <maple-exti-map>` +* :ref:`Maple RET6 Edition <maple-ret6-exti-map>` .. note:: @@ -80,40 +49,16 @@ The following table shows which pins can be used on which lines. desired pin to an input mode (e.g ``INPUT`` or ``INPUT_FLOATING``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``). - Function Reference ------------------ - :ref:`attachInterrupt() <lang-attachinterrupt>` - :ref:`detachInterrupt() <lang-detachinterrupt>` -Code example ------------- - -Blink the LED on every transition:: - - int pin = 13; - volatile int state = LOW; - - void setup() { - pinMode(pin, OUTPUT); - pinMode(0, INPUT_FLOATING); - attachInterrupt(0, blink, CHANGE); - } - - void loop() { - digitalWrite(pin, state); - } - - void blink() { - state = !state; - } - - Recommended Reading ------------------- -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) +* ST manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF), Chapter 9, "General-purpose and alternate-function I/Os", and + Chapter 10, "Interrupts and Events". diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst index 0f9f4df..74be3d4 100644 --- a/docs/source/gpio.rst +++ b/docs/source/gpio.rst @@ -3,86 +3,54 @@ GPIO ==== -.. FIXME [Maple-specific values] +Each LeafLabs board comes with ready-to-use General Purpose +Input/Output (GPIO) pins, which are numbered starting from zero. +These numbers are listed on your board's silkscreen, next to where the +pin is broken out to a header. Many pins may additionally be used for +special features or peripheral functions. -The Maple features 38 ready-to-use general purpose input/output (GPIO) -pins for digital input/output, numbered D0 through D37. These numbers -correspond to the numeric values next to each header on the Maple -silkscreen. +.. contents:: Contents + :local: -Many of these pins may additionally be used for special features or -peripheral functions. This page documents those capabilities, by pin. +.. _gpio-pin-maps: -The current and voltage limitations have been copied over from the -STM32 datasheet (see the :ref:`Recommended Reading -<gpio-recommended-reading>` for a link). In particular, a number of -GPIO pins are 5V tolerant (which means that applying 5 volts to a pin -and reading it as input or allowing it to drain to ground will not -damage that pin), while some are not. +Pin Maps +-------- -.. contents:: Contents - :local: +The hardware documentation for your board lists each pin's +capabilities, by pin number: + +.. TODO [0.1.0] Uncomment Mini and Native GPIO links + +* :ref:`Maple <maple-gpios>` +* :ref:`Maple RET6 Edition <maple-ret6-gpios>` -.. _pin-mapping-mega-table: - -Pin Mapping Mega Table ----------------------- - -This table shows the available functionality on every GPIO pin, by -peripheral type. The "STM32" column refers to the port and number that -the header is connected to on the microcontroller. The "5V?" column -documents whether or not the pin is 5 volt tolerant (see above). - -.. TODO silkscreen pictures which let you know what each abbreviation -.. means, with links to the relevant documentation. - -.. csv-table:: - :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?" - - "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" - "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" - "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" - "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" - "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" - "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" - "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" - "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" - "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" - "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" - "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" - "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" - "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" - "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" - "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" - "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" - "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" - "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" - "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" - "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" - "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" - "D21", "PC13", "-", "-", "-", "-", "-", "No" - "D22", "PC14", "-", "-", "-", "-", "-", "No" - "D23", "PC15", "-", "-", "-", "-", "-", "No" - "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" - "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" - "D26", "PC10", "-", "-", "-", "-", "-", "Yes" - "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" - "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" - "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" - "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" - "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBAL", "USART3_CK", "SPI2_NSS", "Yes" - "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" - "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" - "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" - "D35", "PC6", "-", "-", "-", "-", "-", "Yes" - "D36", "PC7", "-", "-", "-", "-", "-", "Yes" - "D37", "PC8", "-", "-", "-", "-", "-", "Yes" +.. * :ref:`Maple Mini <maple-mini-gpios>` +.. * :ref:`Maple Native <maple-native-gpios>` + +The current and voltage limitations were determined using the STM32 +datasheets. In particular, only some GPIO pins are **5V tolerant**, +which means that applying 5 volts to a pin and reading it as input or +allowing it to drain to ground will not damage that pin. Connecting a +voltage higher than 3.3V to a non-5V tolerant pin may damage your +board. .. _gpio-modes: GPIO Modes ---------- +Each of the GPIO pins on a Maple board may be configured using +pinMode() to behave in a number of ways: as a digital output pin, +or as an analog input pin, etc., depending on the particular pin. + +A ``WiringPinMode`` value specifies the complete set of possible +configurations; not every pin can have all of these modes. For +example, on the Maple, pin 15 may have mode ``INPUT_ANALOG``, but not +``PWM``. See your :ref:`board's pin maps <gpio-pin-maps>` and its +silkscreen for more information on what functionality is available on +each pin. + .. doxygenenum:: WiringPinMode Function Reference @@ -105,7 +73,11 @@ Function Reference Recommended Reading ------------------- -STMicro documentation for STM32F103RB microcontroller: +* ST Documentation for the STM32F103 series of microcontrollers: - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) + + * `Programming Manual + <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ + (PDF; assembly language and register reference) + diff --git a/docs/source/hardware/maple-ret6.rst b/docs/source/hardware/maple-ret6.rst new file mode 100644 index 0000000..06dcaff --- /dev/null +++ b/docs/source/hardware/maple-ret6.rst @@ -0,0 +1,276 @@ +.. highlight:: sh + +.. _maple-ret6: + +Maple RET6 Edition +================== + +.. contents:: Contents + :local: + +Technical Specifications +------------------------ + + * MCU: **STM32F103RET6**, a 32-bit ARM Cortex M3 microprocessor + * Clock Speed: **72 MHz** + * Operating Voltage: 3.3V + * Input Voltage (recommended): 3V-12V + * 39 Digital I/O Pins (:ref:`GPIO <gpio>`) + * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC <adc>`) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`) + * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`) + * External **JTAG** interface (:ref:`JTAG <jtag>`) + * **512KB Flash** and **64KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * Integrated **SPI** (:ref:`SPI <spi>`) + * Integrated **I2C** (:ref:`I2C <i2c>`) + * 12 Channels of Direct Memory Access (**DMA**) + * 3 **USART** and 2 **UART** devices (:ref:`USART <usart>`) + * Six 4-channel and two basic **timers** (:ref:`Timers <timers>`) + * Supplies up to 800mA @ 3.3v + * Support for low power and sleep modes (<500uA) + * Dimensions are 2.05″x2.1″ + +.. _maple-ret6-powering: + +Powering the Maple RET6 Edition +------------------------------- + +The Maple RET6 Edition's power source is determined by the header to +the left of the "LeafLabs" label on the silkscreen. The RET6 Edition +can be powered from the barrel jack connector, USB, or a LiPo battery. +We ship the RET6 Edition with a jumper on the USB selector. In order +to power it off of an alternative source, unplug the board, then move +the jumper to the desired selector before reconnecting power. + +You can also power the Maple via the pin labeled "Vin" on the lower +header. However, don't do this while simultaneously powering the +board from another source, or you could damage the it. + +Using the Built-in Battery Charger +---------------------------------- + +The RET6 Edition has a built-in LiPo battery charger. In order to use +it, put a jumper across the CHRG header on the power selection header +and across the USB, or EXT selectors, depending on whether you're +charging the battery via USB cable or barrel jack connector. The LED +labeled CHRG will light up while the battery is being charged. When +the battery is finished charging, the LED labeled DONE will also light +up. + +.. _maple-ret6-gpios: + +GPIO Information +---------------- + +The RET6 Edition features 38 ready-to-use general purpose input/output +(GPIO) pins for digital input/output, numbered ``D0`` through ``D37``. +These numbers correspond to the numeric values next to each header on +the Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +available through use in combination with the +:ref:`lang-disabledebugports` function; see the :ref:`board-specific +debug pin constants <lang-board-values-debug>` for more information. + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-ret6-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +.. TODO [0.0.10] Update from base Maple information + +This table shows the available functionality on every GPIO pin, by +peripheral type. The "STM32" column refers to the port and number that +the header is connected to on the microcontroller. The "5V?" column +documents whether or not the pin is 5 volt tolerant. + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" + "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" + "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" + "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" + "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" + "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" + "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" + "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" + "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" + "D21", "PC13", "-", "-", "-", "-", "-", "No" + "D22", "PC14", "-", "-", "-", "-", "-", "No" + "D23", "PC15", "-", "-", "-", "-", "-", "No" + "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" + "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" + "D26", "PC10", "-", "-", "-", "-", "-", "Yes" + "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" + "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" + "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" + "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" + "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" + "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" + "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" + "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" + "D35", "PC6", "-", "-", "-", "-", "-", "Yes" + "D36", "PC7", "-", "-", "-", "-", "-", "Yes" + "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + +.. TODO [0.0.10] Another table for the JTAG pins + +Timer Pin Map +^^^^^^^^^^^^^ + +.. TODO [0.0.10] Add Timer 5,6,7,8 information + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D6 | D7 | D8 | - + 2 | D2 | D3 | D1 | D0 + 3 | D12 | D11 | D27 | D28 + 4 | D5 | D9 | D14 | D24 + +.. _maple-ret6-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +<external-interrupts-exti-line>` on the Maple RET6 Edition. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - 2, 15, 27 + * - EXTI1 + - 3, 16, 28 + * - EXTI2 + - 1, 17, 25 + * - EXTI3 + - 0, 18 + * - EXTI4 + - 10, 19 + * - EXTI5 + - 4, 13, 20 + * - EXTI6 + - 5, 12, 35 + * - EXTI7 + - 9, 11, 36 + * - EXTI8 + - 6, 14, 37 + * - EXTI9 + - 7, 25, 28 + * - EXTI10 + - 8, 26, 29 + * - EXTI11 + - 30 + * - EXTI12 + - 31 + * - EXTI13 + - 21, 32 + * - EXTI14 + - 22, 33 + * - EXTI15 + - 23, 34 + +.. _maple-ret6-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +.. FIXME [0.0.10] UART4 and UART5 information + +The Maple RET6 Edition has three serial ports (also known as a UARTs +or USARTs): ``Serial1``, ``Serial2``, and ``Serial3``. They +communicate using the pins summarized in the following table: + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | 7 | 8 | 6 | - | - + ``Serial2`` | 1 | 0 | 10 | 2 | 3 + ``Serial3`` | 29 | 30 | 31 | 32 | 33 + +Board-Specific Values +--------------------- + +.. TODO [0.0.10] + +Stub. + +Hardware Design Files +--------------------- + +The hardware schematics and board layout files are available in the +`Maple Github repository <https://github.com/leaflabs/maple>`_. Other +than the processor used, the design files for the Maple RET6 edition +are identical to the Maple Rev 5, which are in the ``maple-r5`` +subdirectory of the Maple repository. A schematic for a JTAG adapter +suitable for use with Maple is available in the ``jtagadapter`` +directory. + +From the Github repository main page, you can download the entire +repository by clicking the "Download" button. If you are familiar +with `git <http://git-scm.com/>`_, you can also clone the repository +at the command line with :: + + $ git clone git://github.com/leaflabs/maple.git + +.. _maple-ret6-failure-modes: + +Failure Modes +------------- + +The following known failure modes apply to all Maple boards. The +failure modes aren't design errors, but are easy ways to break or +damage your board permanently. + +* **High voltage on non-tolerant pins**: not all header pins are 5V + compatible; so e.g. connecting certain serial devices in the wrong + way could over-voltage the pins. The :ref:`pin-mapping master table + <maple-ret6-pin-map-master>` details which pins are 5V-tolerant. + +Errata +------ + +This section lists known issues and warnings for the Maple RET6 Edition. + +* **DAC, UART4, UART5 GPIOs unavailable**: Pins related to the digital + to analog converter (DAC) and UARTs 4 and 5 are not broken out to + headers. The RET6 Edition's hardware layout is identical to that of + the Maple Rev 5, which wasn't designed for use with these + STM32F103RET6-only peripherals. + +Recommended Reading +------------------- + +* STMicro documentation for STM32F103RE microcontroller: + + * `Datasheet + <http://www.st.com/internet/com/TECHNICAL_RESOURCES/TECHNICAL_LITERATURE/DATASHEET/CD00191185.pdf>`_ (PDF) + * `Reference Manual + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (PDF) + * `Programming Manual + <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ + (PDF; assembly language and register reference) diff --git a/docs/source/hardware/maple.rst b/docs/source/hardware/maple.rst index 1fa4f3f..44848a7 100644 --- a/docs/source/hardware/maple.rst +++ b/docs/source/hardware/maple.rst @@ -1,6 +1,6 @@ .. highlight:: sh -.. _hardware-maple: +.. _maple: Maple ===== @@ -16,15 +16,14 @@ Technical Specifications * Operating Voltage: 3.3V * Input Voltage (recommended): 3V-12V * 39 Digital I/O Pins (:ref:`GPIO <gpio>`) - * 16 Analog Input Pins - * 12-bit **ADC** resolution (:ref:`ADC <adc>`) + * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC <adc>`) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM <pwm>`) - * Dedicated **USB** port for programming and communications (:ref:`USB<usb>`) - * External **JTAG** interface (:ref:`USB <jtag>`) - * **128 Flash** and **20KB SRAM** + * Dedicated **USB** port for programming and communications (:ref:`USB <usb>`) + * External **JTAG** interface (:ref:`JTAG <jtag>`) + * **128KB Flash** and **20KB SRAM** * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) - * Integrated **SPI** (:ref:`SPI<spi>`) - * Integrated **I2C** (:ref:`I2C<i2c>`) + * Integrated **SPI** (:ref:`SPI <spi>`) + * Integrated **I2C** (:ref:`I2C <i2c>`) * 7 Channels of Direct Memory Access (**DMA**) * 3 **USART** divices (:ref:`USART <usart>`) * Four 4-channel **timers** (:ref:`Timers <timers>`) @@ -32,7 +31,7 @@ Technical Specifications * Support for low power and sleep modes (<500uA) * Dimensions are 2.05″x2.1″ -.. _maple-hardware-identify-rev: +.. _maple-identify-rev: Identifying your Rev -------------------- @@ -79,7 +78,7 @@ have a light red silkscreen and a single pixelated leaf as a logo. :align: center :alt: Maple Rev 1 -.. _hardware-maple-powering: +.. _maple-powering: Powering the Maple ------------------ @@ -106,17 +105,174 @@ connector. The LED labeled CHRG will light up while the battery is being charged. When the battery is finished charging, the LED labeled DONE will also light up. +.. _maple-gpios: + +GPIO Information +---------------- + +The Maple features 38 ready-to-use general purpose input/output (GPIO) +pins for digital input/output, numbered ``D0`` through ``D37``. These +numbers correspond to the numeric values next to each header on the +Maple silkscreen. More GPIOs (numbered ``D39``\ --``43``) are +available through use in combination with the +:ref:`lang-disabledebugports` function; see the :ref:`board-specific +debug pin constants <lang-board-values-debug>` for more information. + +.. TODO [0.1.0] silkscreen pictures which expand abbreviations + +.. _maple-pin-map-master: + +Master Pin Map +^^^^^^^^^^^^^^ + +This table shows the available functionality on every GPIO pin, by +peripheral type. The "STM32" column refers to the port and number that +the header is connected to on the microcontroller. The "5V?" column +documents whether or not the pin is 5 volt tolerant. + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", "-", "-", "SPI1_MISO", "No" + "D13", "PA5", "ADC5", "-", "-", "-", "SPI1_SCK", "No" + "D14", "PB8", "-", "TIM4_CH3", "-", "-", "-", "Yes" + "D15", "PC0", "ADC10", "-", "-", "-", "-", "No" + "D16", "PC1", "ADC11", "-", "-", "-", "-", "No" + "D17", "PC2", "ADC12", "-", "-", "-", "-", "No" + "D18", "PC3", "ADC13", "-", "-", "-", "-", "No" + "D19", "PC4", "ADC14", "-", "-", "-", "-", "No" + "D20", "PC5", "ADC15", "-", "-", "-", "-", "No" + "D21", "PC13", "-", "-", "-", "-", "-", "No" + "D22", "PC14", "-", "-", "-", "-", "-", "No" + "D23", "PC15", "-", "-", "-", "-", "-", "No" + "D24", "PB9", "-", "TIM4_CH4", "-", "-", "-", "Yes" + "D25", "PD2", "-", "TIM3_ETR", "-", "-", "-", "Yes" + "D26", "PC10", "-", "-", "-", "-", "-", "Yes" + "D27", "PB0", "ADC8", "TIM3_CH3", "-", "-", "-", "No" + "D28", "PB1", "ADC9", "TIM3_CH4", "-", "-", "-", "No" + "D29", "PB10", "-", "-", "I2C2_SCL", "USART3_TX", "-", "Yes" + "D30", "PB11", "-", "-", "I2C2_SDA", "USART3_RX", "-", "Yes" + "D31", "PB12", "-", "TIM1_BKIN", "I2C2_SMBA", "USART3_CK", "SPI2_NSS", "Yes" + "D32", "PB13", "-", "TIM1_CH1N", "-", "USART3_CTS", "SPI2_SCK", "Yes" + "D33", "PB14", "-", "TIM1_CH2N", "-", "USART3_RTS", "SPI2_MISO", "Yes" + "D34", "PB15", "-", "TIM1_CH3N", "-", "-", "SPI2_MOSI", "Yes" + "D35", "PC6", "-", "-", "-", "-", "-", "Yes" + "D36", "PC7", "-", "-", "-", "-", "-", "Yes" + "D37", "PC8", "-", "-", "-", "-", "-", "Yes" + +.. TODO [0.0.10] JTAG pins + +Timer Pin Map +^^^^^^^^^^^^^ + +The following table shows what pins are associated with a particular +timer's capture/compare channels. + +.. csv-table:: + :header: Timer, Ch. 1, Ch. 2, Ch. 3, Ch. 4 + :delim: | + + 1 | D6 | D7 | D8 | - + 2 | D2 | D3 | D1 | D0 + 3 | D12 | D11 | D27 | D28 + 4 | D5 | D9 | D14 | D24 + +.. _maple-exti-map: + +EXTI Line Pin Map +^^^^^^^^^^^^^^^^^ + +The following table shows which pins connect to which :ref:`EXTI lines +<external-interrupts-exti-line>` on the Maple. + +.. list-table:: + :widths: 1 1 + :header-rows: 1 + + * - EXTI Line + - Pins + * - EXTI0 + - 2, 15, 27 + * - EXTI1 + - 3, 16, 28 + * - EXTI2 + - 1, 17, 25 + * - EXTI3 + - 0, 18 + * - EXTI4 + - 10, 19 + * - EXTI5 + - 4, 13, 20 + * - EXTI6 + - 5, 12, 35 + * - EXTI7 + - 9, 11, 36 + * - EXTI8 + - 6, 14, 37 + * - EXTI9 + - 7, 25, 28 + * - EXTI10 + - 8, 26, 29 + * - EXTI11 + - 30 + * - EXTI12 + - 31 + * - EXTI13 + - 21, 32 + * - EXTI14 + - 22, 33 + * - EXTI15 + - 23, 34 + +.. _maple-usart-map: + +USART Pin Map +^^^^^^^^^^^^^ + +.. FIXME [0.0.10] UART4, UART5 + +The Maple has three serial ports (also known as a UARTs or USARTs): +``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the +pins summarized in the following table: + +.. csv-table:: + :header: Serial Port, TX, RX, CK, CTS, RTS + :delim: | + + ``Serial1`` | 7 | 8 | 6 | - | - + ``Serial2`` | 1 | 0 | 10 | 2 | 3 + ``Serial3`` | 29 | 30 | 31 | 32 | 33 + +Board-Specific Values +--------------------- + +.. TODO [0.0.10] + +Stub. + Hardware Design Files --------------------- The hardware schematics and board layout files are available in the -`Maple github repository <https://github.com/leaflabs/maple>`_. The +`Maple Github repository <https://github.com/leaflabs/maple>`_. The design files for Rev 1, Rev 3, and Rev 5 are respectively in the ``maple-r1``, ``maple-r3``, and ``maple-r5`` subdirectories. A schematic for a JTAG adapter suitable for use with Maple is available in the ``jtagadapter`` directory. -From the github repository main page, you can download the entire +From the Github repository main page, you can download the entire repository by clicking the "Download" button. If you are familiar with `git <http://git-scm.com/>`_, you can also clone the repository at the command line with :: @@ -128,14 +284,14 @@ at the command line with :: Failure Modes ------------- -The following known failure modes apply to all Maple versions. The -failure modes aren't design errors, but are easy ways to break or -damage your board permanently. +The following are known failure modes. The failure modes aren't +design errors, but are easy ways to break or damage your board +permanently. * **High voltage on non-tolerant pins**: not all header pins are 5V compatible; so e.g. connecting certain serial devices in the wrong - way could over-voltage the pins. The :ref:`Pin-Mapping Mega Table - <pin-mapping-mega-table>` details which pins are 5V-tolerant. + way could over-voltage the pins. The :ref:`pin-mapping master table + <maple-pin-map-master>` details which pins are 5V-tolerant. Errata ------ @@ -145,16 +301,18 @@ Maple board. Rev 5 ^^^^^ -Known issues: -* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on - boards sold in during Fall 2010, the corresponding "AIN" is missing +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but on Rev + 5s manufactured during Fall 2010, the corresponding "AIN" is missing from its silkscreen. This mistake was fixed in later manufacturing runs. Rev 3 ^^^^^ +* **Pin 3 AIN missing**: Pin 3 is capable of analog input, but the + corresponding "AIN" is missing from the Rev 3 silkscreen. + * **Bad/Sticky Buttons**: a number of Rev 3 boards sold in May-June 2010 have questionable RESET and BUT buttons. @@ -231,9 +389,15 @@ Recommended Reading * STMicro documentation for STM32F103RB microcontroller: - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) - * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference) + * `Datasheet + <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ + (PDF) + * `Reference Manual + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF) + * `Programming Manual + <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ + (PDF; assembly language and register reference) .. rubric:: Footnotes diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst index 15190a8..e3d68c0 100644 --- a/docs/source/i2c.rst +++ b/docs/source/i2c.rst @@ -14,10 +14,8 @@ Higher level functionality, such as reading a particular register value, is achieved by writing to set the memory location then reading to pull out the data. -.. FIXME [Maple-specific values] - Note that the master/slave designation is on a message-by-message -basis. The Maple can act as both a master (messages initiated by user +basis. Maple can act as both a master (messages initiated by user code) and slave device (responding to requests via configurable interrupt handlers) at the same time. @@ -27,15 +25,15 @@ interrupt handlers) at the same time. Hardware/Circuit Design ----------------------- -The Maple has two |i2c| ports. Port 1 (I2C1) has SDA on header D9 and -SCL on D5; Port 2 (I2C2) has SDA on D30 and SCL on D29. +.. FIXME [0.0.10 add links to board-specific values] -The Maple reliably communicates with up to a 400kHz clock speed; this -doesn't translate into a 400kbps data rate except in extreme cases -because of addressing and protocol overhead. We have tested clock -speeds up to a megahertz and have had mixed results; in theory it -could be possible to achieve even higher rates, but signal quality -degrades rapidly and the bus becomes unreliable. +Maple boards have two |i2c| ports. Maples reliably communicate with +up to a 400kHz clock speed; this doesn't translate into a 400kbps data +rate except in extreme cases because of addressing and protocol +overhead. We have tested clock speeds up to a megahertz and have had +mixed results; in theory it could be possible to achieve even higher +rates, but signal quality degrades rapidly, and the bus becomes +unreliable. Proper wiring and pull-up resistor selection are essential when incorporating |i2c| into a circuit, especially with data rates above @@ -56,22 +54,16 @@ Wiring-style library is planned for a future release. SMBus ----- -The STM32 microcontroller has hardware support for SMBus; we simply -have not written software for it. The SMBAL line for I2C1 is on header -D4 and for I2C2 is on D31. +The STM32 microcontroller has hardware support for SMBus, but software +for it is not yet implemented. .. _i2c-recommended-reading: Recommended Reading ------------------- -* `i2c-bus.org <http://www.i2c-bus.org/>`_ -* `Wikipedia Article on i2c <http://en.wikipedia.org/wiki/I%C2%B2C>`_ -* `Arduino i2c/TWI reference <http://www.arduino.cc/playground/Learning/I2C>`_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) - * `Application Note on Advanced I2C Usage - <http://www.st.com/stonline/products/literature/an/15021.pdf>`_ - (pdf) +* `I2C Bus <http://www.i2c-bus.org/>`_ +* `Wikipedia: I2C <http://en.wikipedia.org/wiki/I%C2%B2C>`_ +* `Arduino I2C/TWI reference <http://www.arduino.cc/playground/Learning/I2C>`_ +* ST `Application Note on Advanced I2C Usage + <http://www.st.com/stonline/products/literature/an/15021.pdf>`_ (PDF) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9db5ff0..8c7ac84 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,15 +1,12 @@ .. _index: -Maple Documentation Contents +LeafLabs Documentation Index ============================ -.. FIXME [Maple-specific values] errata page links to Maple - Welcome! This is the Maple documentation index. If you just bought a -Maple, you probably want to head to the :ref:`quickstart +Maple board, you probably want to head to the :ref:`quickstart <maple-quickstart>`. If you're having problems, check out the -:ref:`troubleshooting <troubleshooting>` :ref:`known problems -<maple-errata>` pages. +:ref:`troubleshooting <troubleshooting>` page. Have fun! @@ -59,7 +56,7 @@ Have fun! usb usart -.. _index-schematics: +.. _index-boards: **Board Hardware Documentation:** @@ -67,6 +64,7 @@ Have fun! :maxdepth: 1 hardware/maple.rst + hardware/maple-ret6.rst .. TODO write/include these upon Mini and Native release diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst index cc6d34a..4151a53 100644 --- a/docs/source/jtag.rst +++ b/docs/source/jtag.rst @@ -6,7 +6,7 @@ JTAG ====== -.. FIXME update adapter schematic, add better information +.. FIXME [0.1.0] Updated adapter schematic, better information JTAG is an interface for low-level debugging of digital devices. It gives instruction by instruction control over the microprocessor and @@ -63,11 +63,21 @@ functions. Recommended Reading ------------------- -* `Wikipedia Article on Joint Test Action Group (JTAG) <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ -* `STM32, GDB, OpenOCD How To <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ -* STMicro documentation for STM32F103RB microcontroller: +* `Wikipedia Article on Joint Test Action Group (JTAG) + <http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) -* `LeafLabs Wiki JTAG How To <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ -* `Forum thread on JTAG <http://forums.leaflabs.com/topic.php?id=536>`_ +* `STM32, GDB, OpenOCD How To + <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ + +* `LeafLabs Wiki JTAG How To + <http://wiki.leaflabs.com/index.php?title=Maple_JTAG_How_To>`_ + +* `LeafLabs forum thread on JTAG + <http://forums.leaflabs.com/topic.php?id=536>`_ + +* ST documentation: + + * Reference Manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF), Chapter 31, "Debug support", and Chapter 9, + "General-purpose and alternate function I/Os". diff --git a/docs/source/lang/api/abs.rst b/docs/source/lang/api/abs.rst index 0cc6c23..d9f1ca3 100644 --- a/docs/source/lang/api/abs.rst +++ b/docs/source/lang/api/abs.rst @@ -45,5 +45,4 @@ Arduino Compatibility Maple's implementation of ``abs()`` is compatible with Arduino. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst index 7099b69..6665a94 100644 --- a/docs/source/lang/api/analogread.rst +++ b/docs/source/lang/api/analogread.rst @@ -20,32 +20,33 @@ Library Documentation Discussion ---------- -Reads the value from the specified analog pin. The Maple board -contains a 16-channel, 12-bit analog to digital converter. This means -that it will map input voltages between 0 and 3.3 volts into integer -values between 0 and 4095. This yields a resolution between readings -of 3.3V / 4096 units, or 0.8 millivolts. However, a number of factors +Reads the value from the specified analog pin. The Maple boards +contain 16-channel, 12-bit analog to digital converters. This means +that a converter will map input voltages between 0 and 3.3 volts into +integer values between 0 and 4095. However, a number of factors interfere with getting full accuracy and precision. For more information, see :ref:`adc`. Before calling analogRead() on a pin, that pin must first be -configured for analog input, using :ref:`lang-pinMode` (you only -have to do this once, so it's usually done in :ref:`lang-setup`\ ). +configured for analog input, using :ref:`lang-pinMode`. You only have +to do this once, so it's usually done in :ref:`lang-setup`\ . Parameter Discussion -------------------- -.. FIXME generalize Maple-specific information - The pin parameter is the number of the analog input pin to read from. -Header pins on the Maple with ADC functionality (marked as "AIN" on -the silkscreen) are: - - 0, 1, 2, 3, 10, 11, 12, 13, 15, 16, 17, 18, 19, 20, 27, 28 - -Note that pins 3, 27, and 28 are not marked AIN on the silkscreen -for Maple revisions through Rev 5, however, they **do work** as -analog input pins. +The pins which support analog to digital conversion have ``AIN`` +listed underneath their number on your board's silkscreen. These pin +numbers are available to your program in the :ref:`boardADCPins +<lang-board-values-adc-pins>` board-specific array. The number of +pins which are capable of analog to digital conversion on your board +is given by the ``BOARD_NR_ADC_PINS`` constant. These values are +documented for each board in the :ref:`Board Hardware Documentation +<index-boards>` pages. + +.. note:: Pin 3 is not marked ``AIN`` on the silkscreen for Maple + revisions through Rev 5; however **it does work** as an analog + input pin. Note ---- @@ -55,7 +56,6 @@ returned by ``analogRead()`` will fluctuate due to a number of reasons (like the values of the other analog inputs, how close your hand is to the board, etc.) in a "random" way. - Example ------- @@ -78,7 +78,6 @@ Example // a serial monitor } - Arduino Compatibility --------------------- @@ -100,27 +99,21 @@ shift <lang-bitshift>` the value of a Maple readout by 2, like so:: // be aware that you're losing a lot of precision if you do this int adc_reading = analogRead(pin) >> 2; -.. FIXME Mention Native can do analogReference(), when it's time +.. FIXME [0.1.0] Mention that Native can do analogReference() On the Arduino, the input range and resolution can be changed using -their implementation of `analogReference() -<http://arduino.cc/en/Reference/AnalogReference>`_\ . Because of the -way its hardware (as of Rev 5) was designed, it's not possible to -implement analogReference on the Maple, so this function doesn't -exist. If your inputs lie in a different voltage range than 0V--3.3V, -you'll need to bring them into that range before using -``analogRead()``. Some basic tools to accomplish this are `resistor -dividers <http://en.wikipedia.org/wiki/Voltage_divider>`_ and `Zener -diodes -<http://en.wikipedia.org/wiki/Voltage_source#Zener_voltage_source>`_\ -. However, `operational amplifiers -<http://en.wikipedia.org/wiki/Operational_amplifier>`_ and other -powered components can also be used if greater precision is required. - -See also +the `analogReference() +<http://arduino.cc/en/Reference/AnalogReference>`_ function. Because +of hardware restrictions, this function is not available on the Maple +and Maple RET6 Edition. If your inputs lie in a different voltage +range than 0V--3.3V, you'll need to bring them into that range before +using ``analogRead()``. See the :ref:`ADC reference <adc-range>` for +more information. + +See Also -------- - :ref:`ADC tutorial <adc>` - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst index 9147b96..e789305 100644 --- a/docs/source/lang/api/analogwrite.rst +++ b/docs/source/lang/api/analogwrite.rst @@ -65,12 +65,12 @@ This will convert values in the range 0-255 to values in the range which control PWM output. See the :ref:`timers reference <timers>` for more information. -Another fix is to consult the :ref:`pin mapping mega table -<pin-mapping-mega-table>` to find the timer which controls PWM on the -pin you're using, then set that Timer's overflow to 255. Subsequent -calls to analogWrite() should work as on the Arduino (with the same -loss of precision). Note, however, that that affects the overflow for -the **entire timer**, so other code relying on that timer (such as any +Another fix is to consult your board's :ref:`pin maps <gpio-pin-maps>` +to find the timer which controls PWM on the pin you're using, then set +that Timer's overflow to 255. Subsequent calls to analogWrite() +should work as on the Arduino (with the same loss of precision). +Note, however, that that affects the overflow for the **entire +timer**, so other code relying on that timer (such as any :ref:`interrupts <lang-attachinterrupt>` the timer controls) will likely need to be modified as well. @@ -140,9 +140,9 @@ If your application definitely requires Arduino's PWM frequency, then the steps are: 1. Figure out which :ref:`timer <lang-hardwaretimer>` controls PWM - output on your pin (\ :ref:`this table <pwm-timer-table>` is your - friend here). Let's say it's ``Timern``\ , where ``n`` is some - number 1, 2, 3, or 4. + output on your pin (\ :ref:`your board's Timer Pin Map + <gpio-pin-maps>` is your friend here). Let's say it's ``Timern``\ + , where ``n`` is some number 1, 2, 3, or 4. 2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's period to approximately 2041 microseconds, which is a frequency of @@ -154,7 +154,7 @@ timer. The important examples are :ref:`timer interrupts <lang-hardwaretimer-attachinterrupt>` and :ref:`PWM <timers-pwm-conflicts>`\ . -See also +See Also -------- - :ref:`Maple PWM tutorial <pwm>` @@ -169,5 +169,4 @@ See also Maple uses 2 bytes of memory, and an unsigned (i.e., nonnegative) integer with size 2 bytes can hold the values between 0 and 65,535. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/attachinterrupt.rst b/docs/source/lang/api/attachinterrupt.rst index 7c5a6c7..39902ac 100644 --- a/docs/source/lang/api/attachinterrupt.rst +++ b/docs/source/lang/api/attachinterrupt.rst @@ -5,9 +5,8 @@ attachInterrupt() ================= -Used to specify a function to call when an external interrupt (like an -GPIO changing from LOW to HIGH, a button getting pressed, etc.) -occurs. +Used to specify a function to call when an :ref:`external interrupt +<external-interrupts>` occurs. .. contents:: Contents :local: @@ -15,9 +14,9 @@ occurs. Library Documentation --------------------- -.. FIXME once breathe knows how to get the correct attachInterupt -.. (right now it's copying from HardwareTimer), replace with a -.. doxygenfunction directive +.. FIXME [doxygenfunction] once Breathe knows how to get the correct +.. attachInterupt (right now it's copying from HardwareTimer), replace +.. with a doxygenfunction directive .. cpp:function:: void attachInterrupt(uint8 pin, voidFuncPtr handler, ExtIntTriggerMode mode) @@ -47,49 +46,29 @@ Discussion Because the function will run in interrupt context, inside of it, :ref:`lang-delay` won't work, and the value returned by -:ref:`lang-millis` will not increment. Serial data received while -in the function may be lost. You should declare as ``volatile`` any +:ref:`lang-millis` will not increment. Serial data received while in +the function may be lost. You should declare as ``volatile`` any global variables that you modify within the attached function. -There are a few constraints you should be aware of if you're using -more than one interrupt at a time; the :ref:`external-interrupts` page -has the details. - -Using Interrupts ----------------- - -Interrupts are useful for making things happen automatically in -microcontroller programs, and can help solve timing problems. A -good task for using an interrupt might be reading a rotary encoder, -or monitoring user input. - -If you wanted to insure that a program always caught the pulses -from a rotary encoder, never missing a pulse, it would make it very -tricky to write a program to do anything else, because the program -would need to constantly poll the sensor lines for the encoder, in -order to catch pulses when they occurred. Other sensors have a -similar interface dynamic too, such as trying to read a sound -sensor that is trying to catch a click, or an infrared slot sensor -(photo-interrupter) trying to catch a coin drop. In all of these -situations, using an interrupt can free the microcontroller to get -some other work done while not missing the doorbell. +There are a few limits you should be aware of if you're using more +than one interrupt at a time; the :ref:`External Interrupts +<external-interrupts-exti-line>` page has more information. Example ------- -:: + :: - int maple_led_pin = 13; volatile int state = LOW; // must declare volatile, since it's - // modified within the blink handler + // modified within the blink() handler void setup() { - pinMode(maple_led_pin, OUTPUT); + pinMode(BOARD_LED_PIN, OUTPUT); attachInterrupt(0, blink, CHANGE); } void loop() { - digitalWrite(maple_led_pin, state); + digitalWrite(BOARD_LED_PIN, state); } void blink() { @@ -106,10 +85,10 @@ additional four: numbers 2 (pin 21), 3 (pin 20), 4 (pin 19), and 5 number goes with which pin -- just tell ``attachInterrupt()`` the pin you want. -See also +See Also -------- -- :ref:`detachInterrupt <lang-detachinterrupt>` -- :ref:`external-interrupts` +- :ref:`lang-detachinterrupt` +- :ref:`external-interrupts` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bit.rst b/docs/source/lang/api/bit.rst index dd5c050..3df042c 100644 --- a/docs/source/lang/api/bit.rst +++ b/docs/source/lang/api/bit.rst @@ -12,33 +12,27 @@ Syntax ``bit(n)`` - Parameters ---------- * **n** the bit to set. - Value ----- The value of an integer with the given bit set. - Arduino Compatibility --------------------- -The Maple implementation of bit is compatible with Arduino. +The Maple implementation of ``bit()`` is compatible with Arduino. - -See also +See Also -------- - - :ref:`lang-bitread` - :ref:`lang-bitwrite` - :ref:`lang-bitset` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitclear.rst b/docs/source/lang/api/bitclear.rst index 941f912..f487059 100644 --- a/docs/source/lang/api/bitclear.rst +++ b/docs/source/lang/api/bitclear.rst @@ -10,7 +10,6 @@ Syntax ``bitClear(x, n)`` - Parameters ---------- @@ -19,20 +18,17 @@ Parameters * **n** which bit to clear, starting at 0 for the least-significant (rightmost) bit - Returns ------- -None. - +Nothing. Arduino Compatibility --------------------- -This implementation is compatible with that of Arduino. +The Maple implementation of ``bitClear()`` is compatible with Arduino. - -See also +See Also -------- - :ref:`bit <lang-bit>`\ () @@ -40,5 +36,4 @@ See also - :ref:`bitWrite <lang-bitwrite>`\ () - :ref:`bitSet <lang-bitset>`\ () - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitread.rst b/docs/source/lang/api/bitread.rst index 46b4478..fd9fbbe 100644 --- a/docs/source/lang/api/bitread.rst +++ b/docs/source/lang/api/bitread.rst @@ -5,13 +5,11 @@ bitRead() (Macro) Gets the value of a bit in a number. - Syntax ------ ``bitRead(x, n)`` - Parameters ---------- @@ -20,27 +18,22 @@ Parameters * **n** which bit to read, starting at 0 for the least-significant (rightmost) bit - Value ----- The value of the bit (0 or 1). - Arduino Compatibility --------------------- The Maple implementation of ``bitRead`` is compatible with Arduino. - -See also +See Also -------- - - :ref:`lang-bit` - :ref:`lang-bitwrite` - :ref:`lang-bitset` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitset.rst b/docs/source/lang/api/bitset.rst index ccd76de..83ab5f8 100644 --- a/docs/source/lang/api/bitset.rst +++ b/docs/source/lang/api/bitset.rst @@ -5,13 +5,11 @@ bitSet() (Macro) Sets (writes a 1 to) a bit of a numeric variable. - Syntax ------ ``bitSet(x, n)`` - Parameters ---------- @@ -20,19 +18,16 @@ Parameters * **n** which bit to set, starting at 0 for the least-significant (rightmost) bit - Value ----- None. - Arduino Compatibility --------------------- The Maple implementation of bitSet is compatible with Arduino. - See Also -------- @@ -41,6 +36,4 @@ See Also - :ref:`lang-bitwrite` - :ref:`lang-bitclear` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/bitwrite.rst b/docs/source/lang/api/bitwrite.rst index b3feff2..6106545 100644 --- a/docs/source/lang/api/bitwrite.rst +++ b/docs/source/lang/api/bitwrite.rst @@ -32,9 +32,9 @@ Nothing. Arduino Compatibility --------------------- -Maple's version of ``bitWrite()`` is compatible with Arduino. +Maple's implementation of ``bitWrite()`` is compatible with Arduino. -See also +See Also -------- - :ref:`bit() <lang-bit>` @@ -42,5 +42,4 @@ See also - :ref:`bitSet() <lang-bitSet>` - :ref:`bitClear() <lang-bitClear>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/board-values.rst b/docs/source/lang/api/board-values.rst index e274163..05e3837 100644 --- a/docs/source/lang/api/board-values.rst +++ b/docs/source/lang/api/board-values.rst @@ -12,6 +12,9 @@ it easier to share your code with other people who have different boards. Some example usages are given :ref:`below <lang-board-values-examples>`. +The actual values for each board are given in the :ref:`Board Hardware +Documentation <index-boards>`. + .. contents:: Contents :local: @@ -111,8 +114,6 @@ Pin Arrays Some :ref:`arrays <lang-array>` of pin numbers are available which you can use to find out certain important information about a given pin. -.. TODO [0.1.0] links to board-specific hardware information - - ``boardPWMPins``: Pin numbers of each pin capable of :ref:`PWM <pwm>` output, using :ref:`pwmWrite() <lang-pwmwrite>`. The total number of these pins is :ref:`BOARD_NR_PWM_PINS diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst index c5a7c0c..00c1a5c 100644 --- a/docs/source/lang/api/constants.rst +++ b/docs/source/lang/api/constants.rst @@ -320,4 +320,4 @@ See Also - :ref:`double <lang-double>` - :ref:`Board-Specific Values <lang-board-values>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/constrain.rst b/docs/source/lang/api/constrain.rst index d19b61c..28af1e3 100644 --- a/docs/source/lang/api/constrain.rst +++ b/docs/source/lang/api/constrain.rst @@ -59,11 +59,10 @@ Arduino Compatibility Maple's implementation of ``constrain()`` is compatible with Arduino. -See also +See Also -------- - :ref:`min() <lang-min>` - :ref:`max() <lang-max>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/cos.rst b/docs/source/lang/api/cos.rst index 3fbb0af..c340f09 100644 --- a/docs/source/lang/api/cos.rst +++ b/docs/source/lang/api/cos.rst @@ -19,14 +19,12 @@ Note that the Maple implementation comes from `newlib <http://sourceware.org/newlib/>`_\ , while Arduino's is that of `avr-libc <http://avr-libc.nongnu.org/>`_\ . -See also +See Also -------- - - :ref:`sin() <lang-sin>` - :ref:`tan() <lang-tan>` - :ref:`float <lang-float>` - :ref:`double <lang-double>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/delay.rst b/docs/source/lang/api/delay.rst index 90ca268..9ef06a0 100644 --- a/docs/source/lang/api/delay.rst +++ b/docs/source/lang/api/delay.rst @@ -57,10 +57,9 @@ Example .. _lang-delay-seealso: -See also +See Also -------- - - :ref:`millis() <lang-millis>` - :ref:`micros() <lang-micros>` - :ref:`delayMicroseconds() <lang-delayMicroseconds>` @@ -68,5 +67,4 @@ See also <http://arduino.cc/en/Tutorial/BlinkWithoutDelay>`_ example (works unmodified on Maple) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/delaymicroseconds.rst b/docs/source/lang/api/delaymicroseconds.rst index 24a8286..7078660 100644 --- a/docs/source/lang/api/delaymicroseconds.rst +++ b/docs/source/lang/api/delaymicroseconds.rst @@ -48,9 +48,9 @@ Arduino Compatibility --------------------- While we have made every effort we could to ensure that the timing of -delayMicroseconds is as accurate as possible, we cannot guarantee it -will behave as the Arduino implementation down to the microsecond, -especially for smaller values of ``us``. +``delayMicroseconds()`` is as accurate as possible, we cannot +guarantee it will behave as the Arduino implementation down to the +microsecond, especially for smaller values of ``us``. See Also -------- @@ -59,7 +59,4 @@ See Also - :ref:`micros <lang-micros>` - :ref:`delay <lang-delay>` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/detachinterrupt.rst b/docs/source/lang/api/detachinterrupt.rst index 41642a7..82ce974 100644 --- a/docs/source/lang/api/detachinterrupt.rst +++ b/docs/source/lang/api/detachinterrupt.rst @@ -9,9 +9,8 @@ Used to disable an interrupt specified with Library Documentation --------------------- -.. FIXME once breathe knows how to get the correct detachInterupt -.. (right now it's copying from HardwareTimer), replace with a -.. doxygenfunction directive +.. FIXME [Breathe] once we can get the correct detachInterupt(), +.. replace with doxygenfunction. .. cpp:function:: void detachInterrupt(uint8 pin) @@ -39,5 +38,6 @@ See Also -------- - :ref:`attachInterrupt() <lang-attachInterrupt>` +- :ref:`external-interrupts` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalread.rst b/docs/source/lang/api/digitalread.rst index 3502587..ccf4a4c 100644 --- a/docs/source/lang/api/digitalread.rst +++ b/docs/source/lang/api/digitalread.rst @@ -8,51 +8,44 @@ digitalRead() Reads the value from a specified digital pin, either :ref:`HIGH <lang-constants-high>` or :ref:`LOW <lang-constants-low>`. - Library Documentation --------------------- .. doxygenfunction:: digitalRead +Discussion +---------- + +If the pin isn't connected to anything, ``digitalRead()`` can return +either HIGH or LOW (and this will change in a way that seems random). Example ------- -The following example turns the LED on when the button is pressed:: - - int ledPin = 13; // LED connected to Maple pin 13 - int buttonPin = 38; // BUT connected to Maple pin 38 +The following example turns the LED on or off when the button is pressed:: void setup() { - pinMode(ledPin, OUTPUT); - pinMode(buttonPin, INPUT); + pinMode(BOARD_LED_PIN, OUTPUT); + pinMode(BOARD_BUTTON_PIN, INPUT); } void loop() { - int val = digitalRead(buttonPin); // reads the input pin - digitalWrite(ledPin, val); + int val = digitalRead(BOARD_BUTTON_PIN); // reads the input pin + togglePin(BOARD_LED_PIN, val); } -Note ----- - -If the pin isn't connected to anything, ``digitalRead()`` can return -either HIGH or LOW (and this can change in a way that seems random). - Arduino Compatibility --------------------- The Maple version of ``digitalRead()`` is compatible with Arduino. - See Also -------- -- :ref:`pinMode <lang-pinMode>` -- :ref:`digitalWrite <lang-digitalWrite>` - - - - +- :ref:`BOARD_BUTTON_PIN <lang-board-values-but>` +- :ref:`lang-isButtonPressed` +- :ref:`lang-pinmode` +- :ref:`lang-digitalWrite` +- :ref:`lang-togglepin` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/digitalwrite.rst b/docs/source/lang/api/digitalwrite.rst index 6124d5f..376cbc3 100644 --- a/docs/source/lang/api/digitalwrite.rst +++ b/docs/source/lang/api/digitalwrite.rst @@ -21,42 +21,26 @@ If the pin has been configured as an ``OUTPUT`` with :ref:`pinMode() <lang-pinmode>` its voltage will be set to the corresponding value: 3.3V for ``HIGH``, and 0V (ground) for ``LOW``. -.. TODO make the following paragraphs true, but refer the reader to -.. INPUT_PULLUP and INPUT_PULLDOWN: - -If the pin is configured as an ``INPUT``, writing a ``HIGH`` value -with ``digitalWrite()`` will enable an internal pullup resistor. -Writing ``LOW`` will disable the pullup. The pullup resistor is enough -to light an LED dimly, so if LEDs appear to work, but very dimly, this -is a likely cause. The remedy is to set the pin to an output with the -:ref:`pinMode() <lang-pinmode>` function. - -.. note:: Pin 13 is harder to use as an input than the other pins - because it has an LED and resistor soldered to it in series. If you - enable its internal pull-up resistor, it will likely hang at around - 1.1V instead of the expected 3.3V because the onboard LED and - series resistor pull the voltage level down. If you must use pin 13 - as a digital input, use an external pull-down resistor. +Because it is soldered to an LED and resistor in series, your board's +:ref:`BOARD_LED_PIN <lang-board-values-led>` will respond slightly +more slowly as an output than the other pins. Example ------- The following example sets pin 13 to ``HIGH``, makes a one-second-long delay, sets the pin back to ``LOW``, and delays again, causing a -blinking pattern:: - - - int ledPin = 13; // LED connected to digital pin 13 +blinking pattern (you could also use :ref:`lang-toggleled`):: void setup() { - pinMode(ledPin, OUTPUT); // sets the digital pin as output + pinMode(BOARD_LED_PIN, OUTPUT); // sets the digital pin as output } void loop() { - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(BOARD_LED_PIN, LOW); // sets the LED off + delay(1000); // waits for a second } See Also @@ -64,5 +48,8 @@ See Also - :ref:`pinMode <lang-pinmode>` - :ref:`digitalRead <lang-digitalread>` +- :ref:`BOARD_LED_PIN <lang-board-values-led>` +- :ref:`lang-toggleled` +- :ref:`lang-togglepin` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst index 3f086ca..526beb6 100644 --- a/docs/source/lang/api/hardwaretimer.rst +++ b/docs/source/lang/api/hardwaretimer.rst @@ -10,8 +10,7 @@ built-in timer peripherals. More information on these peripherals (including code examples) is available in the :ref:`timers reference <timers>`. -.. FIXME update HardwareTimer documentation after redoing it in terms -.. of the new timer interface. +.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation .. warning:: This class has been deprecated. It is not available in the current build. @@ -27,8 +26,7 @@ documented below on one of the predefined ``HardwareTimer`` instances. For example, to set the prescale factor on timer 1 to 5, call ``Timer1.setPrescaleFactor(5)``. -.. TODO add code examples that people can copy and paste in case -.. they're unfamiliar with namespace syntax +.. TODO add tutorial-style examples .. cpp:class:: HardwareTimer @@ -92,9 +90,8 @@ For example, to set the prescale factor on timer 1 to 5, call Set the given channel of this timer to the given :ref:`mode <lang-hardwaretimer-modes>`. The parameter ``channel`` is one of 1, 2, 3, and 4, and corresponds to the compare channel you would - like to set. Refer to the full :ref:`pin mapping table - <pin-mapping-mega-table>` to match up timer channels and pin - numbers. + like to set. Refer to your board's :ref:`master pin map + <gpio-pin-maps>` to match up timer channels and pin numbers. .. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) @@ -377,3 +374,87 @@ different. Other Functions ^^^^^^^^^^^^^^^ .. doxygenfunction:: getTimer + +Examples +^^^^^^^^ + +**LED blink**:: + + #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles + + void handler_led(void); + + void setup() + { + // Set up the LED to blink + pinMode(BOARD_LED_PIN, OUTPUT); + + // Setup Timer + Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer2.setPeriod(LED_RATE); // in microseconds + Timer2.setCompare1(1); // overflow might be small + Timer2.attachCompare1Interrupt(handler_led); + } + + void loop() { + // Nothing! It's all in the interrupts + } + + void handler_led(void) { + toggleLED(); + } + +**Racing Counters**:: + + void handler_count1(void); + void handler_count2(void); + + int count1 = 0; + int count2 = 0; + + void setup() + { + // Set up BUT for input + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); + + // Setup Counting Timers + Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); + Timer3.pause(); + Timer4.pause(); + Timer3.setCount(0); + Timer4.setCount(0); + Timer3.setOverflow(30000); + Timer4.setOverflow(30000); + Timer3.setCompare1(1000); // somewhere in the middle + Timer4.setCompare1(1000); + Timer3.attachCompare1Interrupt(handler1); + Timer4.attachCompare1Interrupt(handler2); + Timer3.resume(); + Timer4.resume(); + } + + void loop() { + // Display the running counts + SerialUSB.print("Count 1: "); + SerialUSB.print(count1); + SerialUSB.print("\t\tCount 2: "); + SerialUSB.println(count2); + + // Run... while BUT is held, pause Count2 + for(int i = 0; i<1000; i++) { + if(digitalRead(BOARD_BUTTON_PIN)) { + Timer4.pause(); + } else { + Timer4.resume(); + } + delay(1); + } + } + + void handler1(void) { + count1++; + } + void handler2(void) { + count2++; + } diff --git a/docs/source/lang/api/highbyte.rst b/docs/source/lang/api/highbyte.rst index 50a1fa6..4cb6f9b 100644 --- a/docs/source/lang/api/highbyte.rst +++ b/docs/source/lang/api/highbyte.rst @@ -52,8 +52,4 @@ See Also - :ref:`lowByte() <lang-lowbyte>` - - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/loop.rst b/docs/source/lang/api/loop.rst index d8f6183..c2a5097 100644 --- a/docs/source/lang/api/loop.rst +++ b/docs/source/lang/api/loop.rst @@ -15,7 +15,6 @@ Example :: - int buttonPin = 38; // setup initializes serial and the button pin @@ -42,4 +41,4 @@ See Also - :ref:`setup() <lang-setup>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/lowbyte.rst b/docs/source/lang/api/lowbyte.rst index 58e622f..c513711 100644 --- a/docs/source/lang/api/lowbyte.rst +++ b/docs/source/lang/api/lowbyte.rst @@ -22,4 +22,4 @@ Returns The low byte's value (this will be between 0 and 255). -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/map.rst b/docs/source/lang/api/map.rst index 79122b3..69661a0 100644 --- a/docs/source/lang/api/map.rst +++ b/docs/source/lang/api/map.rst @@ -65,4 +65,4 @@ See Also - :ref:`constrain() <lang-constrain>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/max.rst b/docs/source/lang/api/max.rst index d38eebe..d356f08 100644 --- a/docs/source/lang/api/max.rst +++ b/docs/source/lang/api/max.rst @@ -53,7 +53,7 @@ functions inside the parentheses. It may lead to incorrect results:: Arduino Compatibility --------------------- -The Maple version of ``max()`` is compatible with Arduino. +The Maple implementation of ``max()`` is compatible with Arduino. See Also -------- @@ -61,5 +61,4 @@ See Also - :ref:`min() <lang-min>` - :ref:`constrain() <lang-constrain>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/micros.rst b/docs/source/lang/api/micros.rst index f12976b..de85303 100644 --- a/docs/source/lang/api/micros.rst +++ b/docs/source/lang/api/micros.rst @@ -43,4 +43,4 @@ See Also - :ref:`delay() <lang-delay>` - :ref:`delayMicroseconds() <lang-delaymicroseconds>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/millis.rst b/docs/source/lang/api/millis.rst index 0288c56..db0531c 100644 --- a/docs/source/lang/api/millis.rst +++ b/docs/source/lang/api/millis.rst @@ -49,4 +49,4 @@ See Also - :ref:`delay <lang-delay>` - :ref:`delayMicroseconds <lang-delaymicroseconds>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/min.rst b/docs/source/lang/api/min.rst index 1245f6f..3307105 100644 --- a/docs/source/lang/api/min.rst +++ b/docs/source/lang/api/min.rst @@ -62,5 +62,4 @@ See Also - :ref:`max() <lang-max>` - :ref:`constrain() <lang-constrain>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst index 03cbcfa..8cee3e5 100644 --- a/docs/source/lang/api/pinmode.rst +++ b/docs/source/lang/api/pinmode.rst @@ -60,13 +60,13 @@ set up a pin for these purposes before a call to, e.g., :ref:`lang-analogRead`. In practice, this should only add a few lines to your :ref:`lang-setup` function. -.. TODO verify following before putting it in: +.. TODO [0.1.0] verify following before putting it in: .. ``OUTPUT_OPEN_DRAIN``, ``INPUT_PULLUP``, ``INPUT_PULLDOWN``, and .. ``PWM_OPEN_DRAIN`` modes represent functionality not currently .. available on Arduino boards. -See also +See Also -------- - :ref:`lang-constants` @@ -74,6 +74,4 @@ See also - :ref:`lang-digitalread` - Maple :ref:`GPIO <gpio>` reference page - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/pow.rst b/docs/source/lang/api/pow.rst index 4280400..219a866 100644 --- a/docs/source/lang/api/pow.rst +++ b/docs/source/lang/api/pow.rst @@ -10,8 +10,6 @@ Library Documentation .. doxygenfunction:: pow -.. TODO LATER some examples - See Also -------- @@ -19,5 +17,4 @@ See Also - :ref:`float <lang-float>` - :ref:`double <lang-double>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst index cea602b..5cc112e 100644 --- a/docs/source/lang/api/pwmwrite.rst +++ b/docs/source/lang/api/pwmwrite.rst @@ -11,10 +11,13 @@ pwmWrite(), the pin will output a steady square wave with the given duty cycle. You can change the duty cycle later by calling pwmWrite() again with the same pin and a different duty. -.. FIXME board-specific information - -On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, 14, 24, 27, and 28. +The pins which support PWM have ``PWM`` listed underneath their number +on your board's silkscreen. These pin numbers are available to your +program in the :ref:`boardPWMPins <lang-board-values-pwm-pins>` +board-specific array. The number of pins which are capable of PWM on +your board is given by the ``BOARD_NR_PWM_PINS`` constant. These +values are documented for each board in the :ref:`Board Hardware +Documentation <index-boards>` pages. The Arduino function :ref:`analogWrite() <lang-analogwrite>` is an alias for ``pwmWrite()``, but it is badly named, and its use is @@ -54,4 +57,5 @@ potentiometer:: See Also -------- -- :ref:`Maple PWM tutorial <pwm>` +- :ref:`Maple PWM tutorial <pwm>` +- :ref:`boardPWMPins <lang-board-values-pwm-pins>` diff --git a/docs/source/lang/api/random.rst b/docs/source/lang/api/random.rst index dd8871d..9875ee6 100644 --- a/docs/source/lang/api/random.rst +++ b/docs/source/lang/api/random.rst @@ -10,9 +10,7 @@ The ``random()`` function generates pseudo-random numbers. Library Documentation --------------------- -.. FIXME keep tracking Sphinx/Breathe's ability to reference -.. overloaded functions so we can use doxygenfunction instead of -.. manually documenting. +.. FIXME [Breathe] use doxygenfunction when possible .. cpp:function:: random(long max) @@ -70,4 +68,4 @@ See Also - :ref:`randomSeed() <lang-randomseed>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/randomseed.rst b/docs/source/lang/api/randomseed.rst index d0a15b7..ca7b75f 100644 --- a/docs/source/lang/api/randomseed.rst +++ b/docs/source/lang/api/randomseed.rst @@ -57,4 +57,4 @@ See Also - :ref:`random() <lang-random>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/serial.rst b/docs/source/lang/api/serial.rst index 417063d..0821f43 100644 --- a/docs/source/lang/api/serial.rst +++ b/docs/source/lang/api/serial.rst @@ -12,49 +12,20 @@ devices. Introduction ------------ -.. FIXME [Maple-specific values] -.. FIXME [0.0.10] Serial4, Serial5 updates for high-density devices +.. FIXME [0.0.10] UART4, UART5 -The Maple has three serial ports (also known as a UARTs or USARTs): -``Serial1``, ``Serial2``, and ``Serial3``. They communicate using the -pins summarized in the following table: - -.. list-table:: - :header-rows: 1 - - * - Serial port - - TX, RX, CK - - CTS, RTS (if present) - - * - ``Serial1`` - - 7, 8, 6 - - - - * - ``Serial2`` - - 1, 0, 10 - - 2, 3 - - * - ``Serial3`` - - 29, 30, 31 - - 32, 33 - -Thus, if you use a particular serial port, you cannot also use its -communication pins for other purposes at the same time. - -If you want to communicate with the Maple using the provided USB port, -use :ref:`SerialUSB <lang-serialusb>` instead. - -To use them to communicate with an external TTL serial device, connect -the TX pin to your device's RX pin, the RX to your device's TX pin, -and the ground of your Maple to your device's ground. +To use a serial port to communicate with an external serial device, +connect the TX pin to your device's RX pin, the RX to your device's TX +pin, and your Maple board's ground to your device's ground. .. warning:: Don't connect these pins directly to an RS232 serial port; they operate at +/- 12V and can damage your board. - Library Documentation --------------------- +.. FIXME [0.1.0] Tutorial-style usage introduction + All of the ``Serial[1,2,3]`` objects are instances of the ``HardwareSerial`` class, which is documented in this section. (This means that you can use any of these functions on any of ``Serial1``, @@ -209,9 +180,10 @@ Arduino Compatibility Note -------------------------- Unlike the Arduino, none of the Maple's serial ports is connected to -the USB port on the Maple board (for that, use :ref:`SerialUSB -<lang-serialusb>`). Thus, to use these pins to communicate with your -personal computer, you will need an additional USB-to-serial adapter. +the USB port on the Maple board. If you want to communicate using the +built-in USB port, use :ref:`SerialUSB <lang-serialusb>` instead. You +will need an additional USB-to-serial adapter to communicate between a +USART and your computer. .. FIXME [0.1.0] port these examples over @@ -226,4 +198,4 @@ personal computer, you will need an additional USB-to-serial adapter. .. - `Serial Call Response <http://arduino.cc/en/Tutorial/SerialCallResponse>`_ .. - `Serial Call Response ASCII <http://arduino.cc/en/Tutorial/SerialCallResponseASCII>`_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/setup.rst b/docs/source/lang/api/setup.rst index 837ddd6..1e8e3b8 100644 --- a/docs/source/lang/api/setup.rst +++ b/docs/source/lang/api/setup.rst @@ -26,4 +26,4 @@ Example // ... } -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/sin.rst b/docs/source/lang/api/sin.rst index 398b8f3..3e28c0b 100644 --- a/docs/source/lang/api/sin.rst +++ b/docs/source/lang/api/sin.rst @@ -28,5 +28,4 @@ See Also - :ref:`float <lang-float>` - :ref:`double <lang-double>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/sq.rst b/docs/source/lang/api/sq.rst index bd32648..96724d3 100644 --- a/docs/source/lang/api/sq.rst +++ b/docs/source/lang/api/sq.rst @@ -42,5 +42,4 @@ Arduino Compatibility Maple's implementation of ``sq()`` is compatible with Arduino. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/tan.rst b/docs/source/lang/api/tan.rst index 4bbe0db..b1aed31 100644 --- a/docs/source/lang/api/tan.rst +++ b/docs/source/lang/api/tan.rst @@ -22,10 +22,9 @@ Note that the Maple implementation comes from `newlib See Also -------- - - :ref:`sin <lang-sin>` - :ref:`cos <lang-cos>` - :ref:`float <lang-float>` - :ref:`double <lang-double>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/api/volatile.rst b/docs/source/lang/api/volatile.rst index 276bb6a..1b72897 100644 --- a/docs/source/lang/api/volatile.rst +++ b/docs/source/lang/api/volatile.rst @@ -24,8 +24,8 @@ for efficiency). A variable should be declared ``volatile`` whenever its value can be changed by something beyond the control of the code section in which it appears, such as an :ref:`external interrupt -<external-interrupts>`. On the Maple, the only place that this is -likely to occur is in sections of code associated with interrupts. +<external-interrupts>`. (The only place that this is likely to occur +in most programs is inside of code called by interrupts). Example ------- @@ -55,11 +55,11 @@ Example } } -See also +See Also -------- - :ref:`External Interrupts <external-interrupts>` - :ref:`lang-attachinterrupt` - :ref:`lang-detachinterrupt` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cc-attribution.txt b/docs/source/lang/cc-attribution.txt index e100140..11302b2 100644 --- a/docs/source/lang/cc-attribution.txt +++ b/docs/source/lang/cc-attribution.txt @@ -3,7 +3,8 @@ .. admonition:: License and Attribution - This documentation page was adapted from the `Arduino Reference - Documentation <http://arduino.cc/en/Reference/HomePage>`_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License <http://creativecommons.org/licenses/by-sa/3.0/>`_. + Some information in this page was adapted from the `Arduino + Reference Documentation + <http://arduino.cc/en/Reference/HomePage>`_\ , which is released + under a `Creative Commons Attribution-ShareAlike 3.0 License + <http://creativecommons.org/licenses/by-sa/3.0/>`_. diff --git a/docs/source/lang/cpp/arithmetic.rst b/docs/source/lang/cpp/arithmetic.rst index 26e2811..cef3954 100644 --- a/docs/source/lang/cpp/arithmetic.rst +++ b/docs/source/lang/cpp/arithmetic.rst @@ -121,4 +121,4 @@ See Also - :ref:`sizeof <lang-sizeof>`\ () -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/array.rst b/docs/source/lang/cpp/array.rst index 30a818f..39d4d91 100644 --- a/docs/source/lang/cpp/array.rst +++ b/docs/source/lang/cpp/array.rst @@ -113,11 +113,9 @@ Arduino Compatibility Arrays on Maple are identical those on Arduino. -See also +See Also -------- - :ref:`Storing arrays in FLASH memory <arm-gcc-attribute-flash>` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/assignment.rst b/docs/source/lang/cpp/assignment.rst index f9430b4..6379298 100644 --- a/docs/source/lang/cpp/assignment.rst +++ b/docs/source/lang/cpp/assignment.rst @@ -57,4 +57,4 @@ See Also <http://icu-project.org/docs/papers/cpp_report/the_anatomy_of_the_assignment_operator.html>`_ for more information. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bitshift.rst b/docs/source/lang/cpp/bitshift.rst index e1c8de0..47413f2 100644 --- a/docs/source/lang/cpp/bitshift.rst +++ b/docs/source/lang/cpp/bitshift.rst @@ -140,5 +140,4 @@ See Also - :ref:`lang-bitwrite` - :ref:`lang-bitclear` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bitwisemath.rst b/docs/source/lang/cpp/bitwisemath.rst index 28fe6bf..59794ba 100644 --- a/docs/source/lang/cpp/bitwisemath.rst +++ b/docs/source/lang/cpp/bitwisemath.rst @@ -182,5 +182,4 @@ See Also - :ref:`Compound bitwise operations <lang-compoundbitwise>` (``&=``, ``|=``, ``^=``). - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/boolean.rst b/docs/source/lang/cpp/boolean.rst index 8d6aa5c..f09345e 100644 --- a/docs/source/lang/cpp/boolean.rst +++ b/docs/source/lang/cpp/boolean.rst @@ -87,5 +87,4 @@ See Also ``|=``, ``^=``). - :ref:`if statement <lang-if>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/booleanvariables.rst b/docs/source/lang/cpp/booleanvariables.rst index 6051b8c..0d76a12 100644 --- a/docs/source/lang/cpp/booleanvariables.rst +++ b/docs/source/lang/cpp/booleanvariables.rst @@ -42,13 +42,11 @@ Example } } -See also +See Also -------- - - :ref:`Boolean constants <lang-constants-bool>` - :ref:`Boolean operators <lang-boolean>` - :ref:`Variables <lang-variables>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/break.rst b/docs/source/lang/cpp/break.rst index ce8ac17..f367b99 100644 --- a/docs/source/lang/cpp/break.rst +++ b/docs/source/lang/cpp/break.rst @@ -29,7 +29,4 @@ Example delay(50); } - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/byte.rst b/docs/source/lang/cpp/byte.rst index 45c9d5f..4634594 100644 --- a/docs/source/lang/cpp/byte.rst +++ b/docs/source/lang/cpp/byte.rst @@ -30,5 +30,4 @@ See Also - :ref:`byte() <lang-bytecast>` (casting a value to a byte) - :ref:`Variables <lang-variables>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/bytecast.rst b/docs/source/lang/cpp/bytecast.rst index b3f0de2..24c3b9e 100644 --- a/docs/source/lang/cpp/bytecast.rst +++ b/docs/source/lang/cpp/bytecast.rst @@ -24,13 +24,11 @@ Syntax ``byte(x)`` - Parameters ---------- **x**: a value of any integer type - Returns ------- @@ -38,13 +36,9 @@ The value, converted to a ``byte``. Note, however, that if the value is larger than the maximum value you can store in a byte (255), then the results might be strange and unexpected. - See Also -------- - :ref:`lang-byte` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/char.rst b/docs/source/lang/cpp/char.rst index b8747f3..686c0d1 100644 --- a/docs/source/lang/cpp/char.rst +++ b/docs/source/lang/cpp/char.rst @@ -10,7 +10,6 @@ value from -128 to 127). Character literals are written in single quotes, like this: ``'A'`` (for multiple characters - strings - use double quotes: ``"ABC"``). - Just like everything else on a computer, characters are stored as numbers. You can see the specific encoding in the `ASCII chart <http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters>`_\ @@ -25,26 +24,21 @@ The ``char`` datatype is a signed type, meaning that it encodes numbers from -128 to 127. For an unsigned type, which stores values from 0 to 255, just use the type ``unsigned char`` (two words). - Example ------- :: - // the following two lines are equivalent, using the ASCII + // The following two lines are equivalent, using the ASCII // character encoding: char c = 'A'; char c = 65; - -See also +See Also -------- - - :ref:`lang-int` - :ref:`lang-array` (a string is just an array of ``char``\ s) - :ref:`Serial.println() <lang-serial-println>` - - .. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/charcast.rst b/docs/source/lang/cpp/charcast.rst index a480dec..640ad85 100644 --- a/docs/source/lang/cpp/charcast.rst +++ b/docs/source/lang/cpp/charcast.rst @@ -12,13 +12,11 @@ Syntax ``char(x)`` - Parameters ---------- **x**: a value of any type - Returns ------- @@ -26,11 +24,9 @@ The value, converted to a ``char``. Note, however, that if the value is outside the range of a ``char`` (-128 to 127), then the results might be strange and unexpected. - See Also -------- - :ref:`char <lang-char>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/comments.rst b/docs/source/lang/cpp/comments.rst index c5f118a..1428dc3 100644 --- a/docs/source/lang/cpp/comments.rst +++ b/docs/source/lang/cpp/comments.rst @@ -61,7 +61,4 @@ just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/comparison.rst b/docs/source/lang/cpp/comparison.rst index b24355f..9cd0a9f 100644 --- a/docs/source/lang/cpp/comparison.rst +++ b/docs/source/lang/cpp/comparison.rst @@ -83,5 +83,4 @@ Comparison operators, along with :ref:`boolean operators appears within a conditional doesn't mean it's automatically wrong. Be careful to know what you mean.) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/compoundarithmetic.rst b/docs/source/lang/cpp/compoundarithmetic.rst index 420f1db..d70a43c 100644 --- a/docs/source/lang/cpp/compoundarithmetic.rst +++ b/docs/source/lang/cpp/compoundarithmetic.rst @@ -40,5 +40,4 @@ See Also - :ref:`Arithmetic operators <lang-arithmetic>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/compoundbitwise.rst b/docs/source/lang/cpp/compoundbitwise.rst index 8231130..4efe5df 100644 --- a/docs/source/lang/cpp/compoundbitwise.rst +++ b/docs/source/lang/cpp/compoundbitwise.rst @@ -226,5 +226,4 @@ See Also - :ref:`Boolean operations <lang-boolean>` (``&&``, ``||``) - :ref:`Bitwise operators <lang-bitwisemath>` (``&``, ``|``, ``^``, ``~``) - .. include:: cc-attribution.txt diff --git a/docs/source/lang/cpp/const.rst b/docs/source/lang/cpp/const.rst index 52de85f..ad0c580 100644 --- a/docs/source/lang/cpp/const.rst +++ b/docs/source/lang/cpp/const.rst @@ -21,7 +21,7 @@ method for defining constants than ``#define``. Example ------- -:: + :: // this defines a variable called "pi", which cannot be changed: const float pi = 3.14; @@ -33,7 +33,6 @@ Example pi = 7; // illegal - you can't write to (modify) a constant - **#define** or **const** ------------------------ @@ -48,5 +47,4 @@ See Also - :ref:`#define <lang-define>` - :ref:`volatile <lang-volatile>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/continue.rst b/docs/source/lang/cpp/continue.rst index 13d1815..2a694f6 100644 --- a/docs/source/lang/cpp/continue.rst +++ b/docs/source/lang/cpp/continue.rst @@ -27,6 +27,4 @@ Example delay(50); } - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/curly-braces.rst b/docs/source/lang/cpp/curly-braces.rst index a4bd3dc..df2fe2a 100644 --- a/docs/source/lang/cpp/curly-braces.rst +++ b/docs/source/lang/cpp/curly-braces.rst @@ -99,11 +99,8 @@ reference page for more information):: .. rubric:: Footnotes -.. TODO remove this once IDE 0.1.0 released - .. [#fbug] At present this feature is slightly buggy as the IDE will often find (incorrectly) a brace in text that has been commented out. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/define.rst b/docs/source/lang/cpp/define.rst index 677390d..bdf7283 100644 --- a/docs/source/lang/cpp/define.rst +++ b/docs/source/lang/cpp/define.rst @@ -13,7 +13,6 @@ defined value at compile time. This can have some unwanted side effects. In general, the :ref:`const <lang-const>` keyword is preferred for defining constants. - Syntax ------ @@ -42,7 +41,7 @@ is, **don't do this, either**:: Example ------- -:: + :: #define LED_PIN 13 // The compiler will replace any mention of LED_PIN with @@ -52,5 +51,4 @@ See Also -------- - :ref:`const <lang-const>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/double.rst b/docs/source/lang/cpp/double.rst index 1527778..59422eb 100644 --- a/docs/source/lang/cpp/double.rst +++ b/docs/source/lang/cpp/double.rst @@ -43,6 +43,4 @@ See Also - :ref:`float <lang-float>` - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/doublecast.rst b/docs/source/lang/cpp/doublecast.rst index 16a9907..d3f32ce 100644 --- a/docs/source/lang/cpp/doublecast.rst +++ b/docs/source/lang/cpp/doublecast.rst @@ -24,4 +24,4 @@ See Also - :ref:`float <lang-float>` - :ref:`float() <lang-floatcast>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/dowhile.rst b/docs/source/lang/cpp/dowhile.rst index fe92226..d229122 100644 --- a/docs/source/lang/cpp/dowhile.rst +++ b/docs/source/lang/cpp/dowhile.rst @@ -23,5 +23,4 @@ Example:: x = readSensors(); // check the sensors } while (x < 100); - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/float.rst b/docs/source/lang/cpp/float.rst index 6937c8c..5195fac 100644 --- a/docs/source/lang/cpp/float.rst +++ b/docs/source/lang/cpp/float.rst @@ -47,4 +47,4 @@ See Also - :ref:`double <lang-double>` - :ref:`Variables <lang-variables>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/floatcast.rst b/docs/source/lang/cpp/floatcast.rst index 4766478..af92543 100644 --- a/docs/source/lang/cpp/floatcast.rst +++ b/docs/source/lang/cpp/floatcast.rst @@ -25,4 +25,4 @@ See Also - :ref:`double <lang-double>` - :ref:`double() <lang-doublecast>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/for.rst b/docs/source/lang/cpp/for.rst index 71c5aca..78ea562 100644 --- a/docs/source/lang/cpp/for.rst +++ b/docs/source/lang/cpp/for.rst @@ -123,7 +123,7 @@ questions (answers are in footnote [#fanswers]_\ ): 2. Why does it stop at 64? -See also +See Also -------- - :ref:`while <lang-while>` loops @@ -139,4 +139,4 @@ See also false, and the loop stops. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/goto.rst b/docs/source/lang/cpp/goto.rst index ff2f248..2c0b3b0 100644 --- a/docs/source/lang/cpp/goto.rst +++ b/docs/source/lang/cpp/goto.rst @@ -126,5 +126,4 @@ See Also - Knuth, Donald. `Structured Programming with go to Statements <http://pplab.snu.ac.kr/courses/adv_pl05/papers/p261-knuth.pdf>`_ (PDF) - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/if.rst b/docs/source/lang/cpp/if.rst index bef89e2..d57b9f1 100644 --- a/docs/source/lang/cpp/if.rst +++ b/docs/source/lang/cpp/if.rst @@ -118,4 +118,4 @@ See Also - :ref:`boolean operators <lang-boolean>` - :ref:`comparison operators <lang-comparison>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/include.rst b/docs/source/lang/cpp/include.rst index 74fe7af..163509d 100644 --- a/docs/source/lang/cpp/include.rst +++ b/docs/source/lang/cpp/include.rst @@ -67,6 +67,4 @@ root <http://en.wikipedia.org/wiki/Cube_root>`_ of a number:: SerialUSB.println(cubeRootOf3); } - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/increment.rst b/docs/source/lang/cpp/increment.rst index 6dffa80..c423d1a 100644 --- a/docs/source/lang/cpp/increment.rst +++ b/docs/source/lang/cpp/increment.rst @@ -34,4 +34,4 @@ See Also - :ref:`lang-compoundarithmetic` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/intcast.rst b/docs/source/lang/cpp/intcast.rst index 386fe14..da838c7 100644 --- a/docs/source/lang/cpp/intcast.rst +++ b/docs/source/lang/cpp/intcast.rst @@ -23,7 +23,4 @@ See Also - :ref:`int <lang-int>` - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/longcast.rst b/docs/source/lang/cpp/longcast.rst index f588fc6..493ad67 100644 --- a/docs/source/lang/cpp/longcast.rst +++ b/docs/source/lang/cpp/longcast.rst @@ -24,4 +24,4 @@ See Also - :ref:`long <lang-long>` - :ref:`long long <lang-longlong>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/longlong.rst b/docs/source/lang/cpp/longlong.rst index 0ba56ed..d942cb4 100644 --- a/docs/source/lang/cpp/longlong.rst +++ b/docs/source/lang/cpp/longlong.rst @@ -53,4 +53,4 @@ See Also - :ref:`Integer Constants <lang-constants-integers>` - :ref:`Variables <lang-variables>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/modulo.rst b/docs/source/lang/cpp/modulo.rst index 289fba0..013d07e 100644 --- a/docs/source/lang/cpp/modulo.rst +++ b/docs/source/lang/cpp/modulo.rst @@ -67,4 +67,4 @@ See Also - :ref:`Arithmetic <lang-arithmetic>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/pointer.rst b/docs/source/lang/cpp/pointer.rst index 0a42270..ff4ec32 100644 --- a/docs/source/lang/cpp/pointer.rst +++ b/docs/source/lang/cpp/pointer.rst @@ -28,4 +28,4 @@ See Also - http://xkcd.com/138/ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/return.rst b/docs/source/lang/cpp/return.rst index b4ef5fd..d9aecbe 100644 --- a/docs/source/lang/cpp/return.rst +++ b/docs/source/lang/cpp/return.rst @@ -57,5 +57,4 @@ See Also - :ref:`comments <lang-comments>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/scope.rst b/docs/source/lang/cpp/scope.rst index 7b65bab..a270428 100644 --- a/docs/source/lang/cpp/scope.rst +++ b/docs/source/lang/cpp/scope.rst @@ -117,4 +117,4 @@ See Also - `C++ programming Wikibook <http://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Scope>`_. - Wikipedia article on `scope <http://en.wikipedia.org/wiki/Scope_%28programming%29>`_ -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/semicolon.rst b/docs/source/lang/cpp/semicolon.rst index 8164616..05e6218 100644 --- a/docs/source/lang/cpp/semicolon.rst +++ b/docs/source/lang/cpp/semicolon.rst @@ -19,7 +19,4 @@ compiler error comes up, one of the first things to check is a missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. - - - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/sizeof.rst b/docs/source/lang/cpp/sizeof.rst index eae509c..ec2dea6 100644 --- a/docs/source/lang/cpp/sizeof.rst +++ b/docs/source/lang/cpp/sizeof.rst @@ -60,5 +60,5 @@ would look something like this:: standard guarantees, however, is that a ``char`` occupies at *least* 8 bits. -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/sqrt.rst b/docs/source/lang/cpp/sqrt.rst index 956a754..fbabf82 100644 --- a/docs/source/lang/cpp/sqrt.rst +++ b/docs/source/lang/cpp/sqrt.rst @@ -21,5 +21,4 @@ See Also - :ref:`pow <lang-pow>` - :ref:`sq <lang-sq>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/static.rst b/docs/source/lang/cpp/static.rst index 5d1802e..8c52ba0 100644 --- a/docs/source/lang/cpp/static.rst +++ b/docs/source/lang/cpp/static.rst @@ -53,5 +53,4 @@ then incremented, so it starts out at one. Subsequent calls to it was declared ``static``. Thus, ``numSensorReadings`` is a count of the number of times that ``readSensors()`` has been called. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/string.rst b/docs/source/lang/cpp/string.rst index 0a270da..84917c1 100644 --- a/docs/source/lang/cpp/string.rst +++ b/docs/source/lang/cpp/string.rst @@ -124,5 +124,4 @@ See Also - :ref:`__attribute__ <arm-gcc-attribute-flash>` - :ref:`Variables <lang-variables>` - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/switchcase.rst b/docs/source/lang/cpp/switchcase.rst index b484bc5..e31ccf3 100644 --- a/docs/source/lang/cpp/switchcase.rst +++ b/docs/source/lang/cpp/switchcase.rst @@ -110,9 +110,9 @@ value as the variable to compare. In this case, you can write down all of the values the ``enum`` takes as ``case`` statements, and be sure you've covered all the possibilities. -See also: +See Also: --------- - :ref:`if/else <lang-if>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedchar.rst b/docs/source/lang/cpp/unsignedchar.rst index 5b946ed..45fedeb 100644 --- a/docs/source/lang/cpp/unsignedchar.rst +++ b/docs/source/lang/cpp/unsignedchar.rst @@ -16,18 +16,17 @@ won't store negative numbers; it is also subject to the same Example ------- -:: + :: unsigned char c = 240; See Also -------- - - :ref:`byte <lang-byte>` - :ref:`int <lang-int>` - :ref:`array <lang-array>` - :ref:`SerialUSB.println() <lang-serialusb-println>` - :ref:`Serial.println() <lang-serial-println>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedint.rst b/docs/source/lang/cpp/unsignedint.rst index ad3e2f2..b7d9716 100644 --- a/docs/source/lang/cpp/unsignedint.rst +++ b/docs/source/lang/cpp/unsignedint.rst @@ -56,4 +56,4 @@ See Also - :ref:`Integer Constants <lang-constants-integers>` - :ref:`Variables <lang-variables>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/unsignedlonglong.rst b/docs/source/lang/cpp/unsignedlonglong.rst index 910b7e4..a1143f0 100644 --- a/docs/source/lang/cpp/unsignedlonglong.rst +++ b/docs/source/lang/cpp/unsignedlonglong.rst @@ -40,4 +40,4 @@ See Also - :ref:`Integer Constants <lang-constants-integers>` - :ref:`Variables <lang-variables>` -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst index 336d5ab..9ffdd1d 100644 --- a/docs/source/lang/cpp/variables.rst +++ b/docs/source/lang/cpp/variables.rst @@ -165,6 +165,5 @@ See Also (usually) stored <http://en.wikipedia.org/wiki/Two%27s_complement>`_ on computers. - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst index 88c9c64..7af0acd 100644 --- a/docs/source/lang/cpp/void.rst +++ b/docs/source/lang/cpp/void.rst @@ -28,6 +28,4 @@ Example // ... } -.. TODO doc page on function declaration? - -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/cpp/while.rst b/docs/source/lang/cpp/while.rst index 9047d05..e66e0aa 100644 --- a/docs/source/lang/cpp/while.rst +++ b/docs/source/lang/cpp/while.rst @@ -35,4 +35,4 @@ Example var++; } -.. include:: cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/lang/unimplemented/notone.rst b/docs/source/lang/unimplemented/notone.rst index 485c9c5..8af878b 100644 --- a/docs/source/lang/unimplemented/notone.rst +++ b/docs/source/lang/unimplemented/notone.rst @@ -10,41 +10,28 @@ Stops the generation of a square wave triggered by `tone <http://arduino.cc/en/Reference/Tone>`_\ (). Has no effect if no tone is being generated. - - **NOTE:** if you want to play different pitches on multiple pins, you need to call noTone() on one pin before calling tone() on the next pin. - - Syntax ------ noTone(pin) - - Parameters ---------- pin: the pin on which to stop generating the tone - - Returns ------- -nothing - - +Nothing. -See also +See Also -------- - - `tone <http://arduino.cc/en/Reference/Tone>`_ () - - .. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/tone.rst b/docs/source/lang/unimplemented/tone.rst index f83bf6b..13d581e 100644 --- a/docs/source/lang/unimplemented/tone.rst +++ b/docs/source/lang/unimplemented/tone.rst @@ -12,70 +12,47 @@ continues until a call to `noTone <http://arduino.cc/en/Reference/NoTone>`_\ (). The pin can be connected to a piezo buzzer or other speaker to play tones. - - Only one tone can be generated at a time. If a tone is already playing on a different pin, the call to tone() will have no effect. If the tone is playing on the same pin, the call will set its frequency. - - Use of the tone() function will interfere with PWM output on pins 3 and 11 (on boards other than the Mega). - - **NOTE:** if you want to play different pitches on multiple pins, you need to call noTone() on one pin before calling tone() on the next pin. - - Syntax ------ tone(pin, frequency) tone(pin, frequency, duration) - - Parameters ---------- pin: the pin on which to generate the tone - - frequency: the frequency of the tone in hertz - - duration: the duration of the tone in milliseconds (optional) - - Returns ------- nothing - - -See also +See Also -------- - - `noTone <http://arduino.cc/en/Reference/NoTone>`_\ () - `analogWrite <http://arduino.cc/en/Reference/AnalogWrite>`_\ () - `Tutorial:Tone <http://arduino.cc/en/Tutorial/Tone>`_ - `Tutorial:Pitch follower <http://arduino.cc/en/Tutorial/Tone2>`_ - `Tutorial:Simple Keyboard <http://arduino.cc/en/Tutorial/Tone3>`_ - `Tutorial: multiple tones <http://arduino.cc/en/Tutorial/Tone4>`_ - - - `Tutorial: PWM <http://arduino.cc/en/Tutorial/PWM>`_ - - -.. include:: /lang/cc-attribution.txt +.. include:: /arduino-cc-attribution.txt diff --git a/docs/source/language-index.rst b/docs/source/language-index.rst index a064b3e..225a9ae 100644 --- a/docs/source/language-index.rst +++ b/docs/source/language-index.rst @@ -10,8 +10,21 @@ API references for documented libmaple functionality. The "C++ for Maple" pages are intended as a minimal reference/refresher for programmers familiar with the Arduino language. -**Looking for something else?** The low-level :ref:`libmaple library -interfaces <libmaple>` are documented separately. +.. admonition:: **Looking for Something Else?** + + - See the :ref:`libraries` for extra built-in libraries for dealing + with different kinds of hardware. + + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + <arm-gcc>` used to compile your programs is configured to link + against `newlib <http://sourceware.org/newlib/>`_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. + + - If you're looking for pointers to low-level details, see the + :ref:`Language Recommended Reading + <language-recommended-reading>`. .. _index-language-index-cpp: .. _index-language-index-api: diff --git a/docs/source/language.rst b/docs/source/language.rst index 111a1f1..3ecbe43 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -10,8 +10,7 @@ The Maple can be programmed in the `Wiring <http://www.wiring.org.co/reference/>`_ language, which is the same language used to program the `Arduino <http://arduino.cc/>`_ boards. -.. TODO Wiring tutorial -- just describe setup()/loop(), then link to -.. some of the the bajillion external tutorials +.. TODO [0.2.0?] Wiring tutorial C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the @@ -20,31 +19,29 @@ language and C++ may wish to skip to the .. contents:: Contents :local: -.. _language-lang-docs: - -Maple Language Reference ------------------------- +.. admonition:: **Looking for Something Else?** -The following table summarizes the available core language features. -A more exhaustive index is available at the :ref:`language-index`. + - See the :ref:`libraries` for extra built-in libraries for dealing + with different kinds of hardware. -.. FIXME mention Maple Native supports malloc(), free(), operator -.. new(), and operator delete(), when that is a true thing to say. + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + <arm-gcc>` used to compile your programs is configured to link + against `newlib <http://sourceware.org/newlib/>`_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. -**Looking for something else?** + - If you're looking for pointers to low-level details, see this page's + :ref:`Recommended Reading <language-recommended-reading>`. -- See the :ref:`libraries` for extra built-in libraries for dealing - with different kinds of hardware. +.. _language-lang-docs: -- If you're looking for something from the C standard library (like - ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler - <arm-gcc>` used to compile your programs is configured to link - against `newlib <http://sourceware.org/newlib/>`_, and allows the - use of any of its header files. However, dynamic memory allocation - (``malloc()``, etc.) is not available. +Maple Language Reference +------------------------ -- If you're looking for low-level details, see the :ref:`libmaple - <libmaple>` reference page. +The following table summarizes the most important core language +features. An exhaustive index is available at the +:ref:`language-index`. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -458,14 +455,26 @@ Which could plausibly be turned into the final source file :: while (true) loop(); } +.. _language-recommended-reading: + Recommended Reading ------------------- -* `newlib Documentation <http://sourceware.org/newlib/>`_ - * :ref:`libmaple Documentation <libmaple>` - -* ST documentation: - - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) - * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference) +* Your board's :ref:`Board Hardware Documentation <index-boards>` page +* ST Documentation: + * Reference Manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF). This is the most important reference work on the STM32 + line, and covers the low-level hardware capabilities and + interfaces in great detail. + * `Programming Manual + <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ + (PDF). This is an assembly language and register reference for + the STM32 line. +* ARM Documentation: + * `Cortex-M3 Technical Reference Manual, Revision r1p1 + <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0337e/DDI0337E_cortex_m3_r1p1_trm.pdf>`_ + (PDF). This ARM manual specifies much of the the Cortex M3 + Architecture, including instruction timings. +* `newlib Documentation <http://sourceware.org/newlib/>`_ diff --git a/docs/source/libmaple/api/systick.rst b/docs/source/libmaple/api/systick.rst index 5ec906c..a02b8e4 100644 --- a/docs/source/libmaple/api/systick.rst +++ b/docs/source/libmaple/api/systick.rst @@ -1,6 +1,14 @@ .. highlight:: c + + .. _libmaple-systick: +.. FIXME [0.0.10] move these to the right places: + +.. _libmaple-systick_disable: + +.. _libmaple-systick_resume: + ``systick.h`` ============= diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 7623963..2bc8b11 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -10,13 +10,13 @@ .. Note: if you port an Arduino library and document it here, be sure .. to update compatibility.rst to reflect that fact. -This page briefly summarizes the Arduino libraries that have been -ported to Maple. You can use a library from within a sketch by going -to Sketch > Import Library... from within the IDE, then choosing the -library you want. +This page lists the extra libraries that are part of the :ref:`Maple +IDE <ide>` (along with the rest of :ref:`libmaple <libmaple>`). You +can use a library from within a sketch by going to Sketch > Import +Library... from within the IDE, then choosing the library you want. -Any incompatibilities between the Maple and Arduino versions are noted -in the description of the library. +Any incompatibilities between the Maple and Arduino versions of a +library are noted in the library's documentation. .. contents:: Contents :local: @@ -25,70 +25,47 @@ in the description of the library. :hidden: libs/servo.rst + libs/wire.rst -.. _libraries-servo: - -Servo ------ - -The Servo library is provided for convenient control of RC -servomotors. For more information, see the :ref:`Servo <libs-servo>` -reference. +.. admonition:: **Looking for Something Else?** -**Compatibility Note** + - See the :ref:`language` for information on the core functions + used for programming a Maple board. -The Servo class provides a public interface identical to the Arduino -version's documented functionality (as of Arduino 0021), so in most -cases, this library will be a drop-in replacement. + - If you're looking for something from the C standard library (like + ``atoi()``, for instance): the :ref:`CodeSourcery GCC compiler + <arm-gcc>` used to compile your programs is configured to link + against `newlib <http://sourceware.org/newlib/>`_, and allows the + use of any of its header files. However, dynamic memory allocation + (``malloc()``, etc.) is not available. -However, there are some differences, essentially at the level of -implementation details. + - If you're looking for low-level hardware support libraries, see + the :ref:`libmaple Reference`. -The major difference is that while the Arduino implementation drives -the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple -implementation uses :ref:`timers <timers>` to drive the PWM directly. - -Consequently, **the Maple implementation only allows Servo instances -to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**. - -To determine if a pin supports PWM (15 Maple pins do), you can either -check if "PWM" appears next to its number on the Maple silkscreen, or -consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation. - -RC Servos expect a pulse approximately every 20ms. In the Maple -implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set -for entire timers, rather than individual channels. Thus, -``attach()``\ ing a Servo to a pin can interfere with other pins -associated with the same timer\ [#fard-servo]_. +.. _libraries-servo: -Because of this, we recommend connecting multiple servomotors to pins -which share a timer, in order to keep as many timers free for other -purposes as possible. Consult the :ref:`table provided in the timers -reference <timers-pin-channel-map>` to match up pins and timer -channels. +Servo +----- -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer -channel associated with the newly-attached pin, or 0 on failure (as of -Arduino 0021). The Maple implementation returns true on success, and -false on failure (and this is its documented behavior). +The :ref:`Servo <libs-servo>` library is provided for convenient +control of RC servomotors. .. _libraries-liquid-crystal: LiquidCrystal ------------- -.. TODO 0.0.10 make our own LiquidCrystal docs +.. TODO [0.1.0] LiquidCrystal docs under libs/liquidcrystal.rst The LiquidCrystal library allows Maple to control LCD screens. For more information, see the `Arduino LiquidCrystal documentation <http://www.arduino.cc/en/Reference/LiquidCrystal>`_. -**Compatibility Note** +**Arduino Compatibility** At this time, no incompatibilities between the Maple and Arduino -versions are known. Any observed differences should be considered +versions are known (although the Maple version should perform +significantly faster). Any observed differences should be considered bugs, and reported on the forums. .. _libraries-wire: @@ -96,99 +73,8 @@ bugs, and reported on the forums. Wire ---- -We provide a soft (bit-banged) implementation of the `Wire I2C library -<http://arduino.cc/en/Reference/WireBegin>`_. - -**Compatibility Note** - -This implementation is synchronous, and thus supports only a subset of -the full Wire interface (however, the functionality which is supported -is fully compatible with Arduino). For now, please use the function -reference which follows when developing projects using our -implementation. - -Please note that the current implementation only supports master mode -using a bit-banged (software) protocol. Future enhancements will use -the hardware i2c peripheral on the stm32 as well as the DMA for -performance. Support for slave, smBUS, and multimaster modes are also -slated for inclusion in the enhanced Wire port. - -.. TODO 0.0.10 Wire docs in the cpp domain in own page under /libs/ - -Wire Function Reference -^^^^^^^^^^^^^^^^^^^^^^^ - -``Wire.begin()`` - Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL - (this is compatible with the pin settings on the Arduino Mega). - -``Wire.begin(sda, scl)`` - Like ``Wire.begin()``, but with the given pins as SDA and - SCL. - -``Wire.beginTransmission(slave_address)`` - Set up a transmission to a slave device with the given (7-bit) - address. Bytes subsequently queued for transmission (using - ``Wire.send``) will be sent to ``slave_address`` when ``void - Wire.endTransmission()`` is called. - -``void Wire.send(byte)`` - Queues the given byte (``uint8`` or ``int``) to the slave address - previously specified by a call to ``Wire.beginTransmission``. At - most 32 bytes may be queued in a single transmission. - -``Wire.send(string)`` - Queues a given string (``char*``) for transmission. The characters - of the string are individually queued for transmission as - bytes. At most 32 bytes may be queued in a single transmission. - -``Wire.send(buffer, length)`` - Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with - ``length`` elements, for transmission. At most 32 bytes may be - queued in a single transmission. - -``Wire.endTransmission()`` - Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), - and actually sends the bytes queued by calls to Wire.send. - - The return value is one of the following status codes: - - * ``SUCCESS``: All bytes were transmitted successfully. - - * ``EDATA``: More than 32 bytes were queued for transmission. No - bytes are actually sent when this happens. - - * ``ENACKADDR``: Did not receive ACK on transmit of address. No - bytes are actually sent when this happens. - - * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some - bytes may have been sent when this happens; however, the - transmission is aborted after the first byte of data which is - not ACKed by the slave device. - - * ``EOTHER``: Other error occurred. - -``Wire.requestFrom(address, num_bytes)`` - Requests ``num_bytes`` bytes from 7-bit slave address - address. Returns the actual number of bytes read. These bytes may - subsequently be read one at a time using ``Wire.receive()``. - - Note: if ``num_bytes`` exceeds the size of the transmit/receive - buffer (currently 32), it will be truncated to 32. - -``Wire.receive()`` - Get and return the next byte read during the previous call to - ``Wire.requestFrom(uint8, int)``. You can check how many bytes are - left to read using ``uint8 Wire.available()``. - -``Wire.available()`` - Returns the number of bytes which are still available for reading - (with ``Wire.receive()``) from the last call to - ``Wire.requestFrom(uint8, int)``. - -.. rubric:: Footnotes +.. FIXME [0.1.0] Update with hard Wire implementation info -.. [#fard-servo] The Arduino implementation also captures timer - channels in groups as more Servo objects are attached, but the - details of which channels have their periods reset when are - slightly different. +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire <libs-wire>` I2C library. A hardware version is planned +for Maple IDE release 0.1.0. diff --git a/docs/source/libs/servo.rst b/docs/source/libs/servo.rst index 475f7dd..891f151 100644 --- a/docs/source/libs/servo.rst +++ b/docs/source/libs/servo.rst @@ -2,9 +2,8 @@ .. _libs-servo: -======= - Servo -======= +Servo +===== .. FIXME [0.0.10] this is out of date @@ -16,7 +15,8 @@ You can use this library in the :ref:`IDE <ide>` by choosing the Servo item under the Sketch > Import Library... menu. If you are using the :ref:`Unix toolchain <unix-toolchain>`, the -library is located in ``$LIB_MAPLE_HOME/libraries/Servo/``. +library is located in the ``/libraries/Servo/`` :ref:`libmaple` +directory. Servo Class Reference --------------------- @@ -108,3 +108,54 @@ servomotor attached to pin 9, you could write :: microseconds. This will be clamped to lie in the [``min``, ``max``\ ] pulse width range set during :ref:`attach() <libs-servo-attach>`. + +Arduino Compatibility +--------------------- + +The Servo class provides a public interface identical to the Arduino +version's documented functionality (as of Arduino 0021), so in most +cases, this library will be a drop-in replacement. + +However, there are some differences, essentially at the level of +implementation details. + +The major difference is that while the Arduino implementation drives +the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple +implementation uses :ref:`timers <timers>` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**. + +To determine if a pin supports PWM (15 Maple pins do), you can either +check if "PWM" appears next to its number on the Maple silkscreen, or +consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set +for entire timers, rather than individual channels. Thus, +``attach()``\ ing a Servo to a pin can interfere with other pins +associated with the same timer\ [#fard-servo]_. + +Because of this, we recommend connecting multiple servomotors to pins +which share a timer, in order to keep as many timers free for other +purposes as possible. Consult your board's :ref:`Timer Pin Map +<gpio-pin-maps>` to match up pins and timer channels. + +Another difference: although it is not publicly documented to do so, +the Arduino implementation of `attach() +<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer +channel associated with the newly-attached pin, or 0 on failure (as of +Arduino 0021). The Maple implementation returns :ref:`true +<lang-constants-true>` on success, and :ref:`false +<lang-constants-false>` on failure (and this is its documented +behavior). + +We currently provide a soft (bit-banged) implementation of the +:ref:`Wire <libs-wire>` I2C library. + +.. rubric:: Footnotes + +.. [#fard-servo] The Arduino implementation also captures timer + channels in groups as more Servo objects are attached, but the + details of which channels have their periods reset when are + slightly different. diff --git a/docs/source/libs/wire.rst b/docs/source/libs/wire.rst new file mode 100644 index 0000000..2c5bed9 --- /dev/null +++ b/docs/source/libs/wire.rst @@ -0,0 +1,104 @@ +.. highlight:: cpp + +.. _libs-wire: + +Wire +==== + +.. TODO [0.1.0] Format this correctly, using Breathe + +This page documents the Wire library for the :ref:`i2c` protocol. You +can use this library in the :ref:`Maple IDE <ide>` by choosing the +Wire item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain <unix-toolchain>`, the +library is located in the ``/libraries/Wire/`` :ref:`libmaple` +directory. + +Wire Function Reference +----------------------- + +``Wire.begin()`` + Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL + (this is compatible with the pin settings on the Arduino Mega). + +``Wire.begin(sda, scl)`` + Like ``Wire.begin()``, but with the given pins as SDA and + SCL. + +``Wire.beginTransmission(slave_address)`` + Set up a transmission to a slave device with the given (7-bit) + address. Bytes subsequently queued for transmission (using + ``Wire.send``) will be sent to ``slave_address`` when ``void + Wire.endTransmission()`` is called. + +``void Wire.send(byte)`` + Queues the given byte (``uint8`` or ``int``) to the slave address + previously specified by a call to ``Wire.beginTransmission``. At + most 32 bytes may be queued in a single transmission. + +``Wire.send(string)`` + Queues a given string (``char*``) for transmission. The characters + of the string are individually queued for transmission as + bytes. At most 32 bytes may be queued in a single transmission. + +``Wire.send(buffer, length)`` + Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with + ``length`` elements, for transmission. At most 32 bytes may be + queued in a single transmission. + +``Wire.endTransmission()`` + Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), + and actually sends the bytes queued by calls to Wire.send. + + The return value is one of the following status codes: + + * ``SUCCESS``: All bytes were transmitted successfully. + + * ``EDATA``: More than 32 bytes were queued for transmission. No + bytes are actually sent when this happens. + + * ``ENACKADDR``: Did not receive ACK on transmit of address. No + bytes are actually sent when this happens. + + * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some + bytes may have been sent when this happens; however, the + transmission is aborted after the first byte of data which is + not ACKed by the slave device. + + * ``EOTHER``: Other error occurred. + +``Wire.requestFrom(address, num_bytes)`` + Requests ``num_bytes`` bytes from 7-bit slave address + address. Returns the actual number of bytes read. These bytes may + subsequently be read one at a time using ``Wire.receive()``. + + Note: if ``num_bytes`` exceeds the size of the transmit/receive + buffer (currently 32), it will be truncated to 32. + +``Wire.receive()`` + Get and return the next byte read during the previous call to + ``Wire.requestFrom(uint8, int)``. You can check how many bytes are + left to read using ``uint8 Wire.available()``. + +``Wire.available()`` + Returns the number of bytes which are still available for reading + (with ``Wire.receive()``) from the last call to + ``Wire.requestFrom(uint8, int)``. + +Arduino Compatibility +--------------------- + +.. FIXME [0.1.0] Replace this section when i2c Wire wrapper is done + +This implementation is synchronous, and thus supports only a subset of +the full Wire interface (however, the functionality which is supported +is fully compatible with Arduino). For now, please use the function +reference which follows when developing projects using our +implementation. + +Please note that the current implementation only supports master mode +using a bit-banged (software) protocol. For now, use of the hardware +:ref:`i2c` peripheral is only available through :ref:`libmaple-i2c`. + + diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst index 899f720..c7596ce 100644 --- a/docs/source/maple-quickstart.rst +++ b/docs/source/maple-quickstart.rst @@ -6,7 +6,7 @@ Maple Quickstart Guide ======================== -.. TODO update the images since we changed "to FLASH" -> "to Flash" +.. TODO [0.1.0] Update the images; we've changed "to FLASH" -> "to Flash" You'll need a `Maple board <http://leaflabs.com/store/>`_, a `Mini-B USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a @@ -73,12 +73,14 @@ window, and then a confirmation message will appear: Upload that program! -------------------- +.. FIXME [0.1.0 Maple-specific image; add one for Native] + Now it's time to plug in your Maple. Use a Mini-B cable, making sure -that the :ref:`power source jumper <hardware-maple-powering>` is on -the USB header first. We ship the Maple with the power source jumper -configured that way, so you shouldn't have to do anything. For -reference, it should look like this (don't worry if a jumper is -hanging half off of the CHRG header): +that the :ref:`power source jumper <maple-powering>` is on the USB +header first. We ship Maples with the power source jumper configured +that way, so you shouldn't have to do anything. For reference, it +should look like this (don't worry if a jumper is hanging half off of +the CHRG header): .. image:: /_static/img/plugged-in-maple.png :align: center diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst index 1144d55..ac67689 100644 --- a/docs/source/pwm.rst +++ b/docs/source/pwm.rst @@ -19,29 +19,14 @@ filtering) generate audio waveforms. Overview -------- -The Maple has a large number of 16-bit PWM outputs, each connected to -one of 4 timers. Some configuration, such as the clock rate or -prescaling, must be common to the entire timer; see the :ref:`timer -documentation <timers>` for more information. - -Note that unlike the Arduino, the Maple does not have PWM -functionality on pin D10; all other pins are :ref:`compatible -<arduino-compatibility>`. - -The following table shows which timer can generate which PWM -outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` to -track down exactly which timer *channel* corresponds to each pin. - -.. _pwm-timer-table: - -.. csv-table:: - :header: Timer, PWM Headers - :delim: | - - Timer1 | D6,D7,D8 - Timer2 | D0,D1,D2,D3 - Timer3 | D11,D12,D27,D28 - Timer4 | D5,D9,D14,D24 +.. FIXME [0.1.0] More information about how timer channels drive PWM + +Each PWM output is driven by an output channel connected to one of 4 +timers. Some configuration, such as the clock rate or prescaling, +must be common to the entire timer; see the :ref:`timer documentation +<timers>` for more information. See your board's :ref:`pin mapping +tables <gpio-pin-mapping-tables>` to track down the correspondence +between timer channels and GPIO pins. Background ---------- diff --git a/docs/source/spi.rst b/docs/source/spi.rst index ba43eef..2da4bf8 100644 --- a/docs/source/spi.rst +++ b/docs/source/spi.rst @@ -20,11 +20,15 @@ Recommended Reading * `Wikipedia Article on Serial Peripheral Interface Bus (SPI) <http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus>`_ + * `Arduino reference on SPI <http://www.arduino.cc/playground/Code/Spi>`_ + * `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64 -* STMicro documentation for STM32F103RB microcontroller: - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) +* ST Documentation: + + * Reference Manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF), Chapter 25, "Serial Peripheral Interface" diff --git a/docs/source/timers.rst b/docs/source/timers.rst index 56dd686..cb30081 100644 --- a/docs/source/timers.rst +++ b/docs/source/timers.rst @@ -5,6 +5,8 @@ Timers ====== +.. FIXME [0.0.10] links to systick.h in a few places on this page + There are four general purpose timers in the Maple microcontroller that can be configured to generate periodic or delayed events with minimal work done by the microcontroller. For example, the :ref:`PWM @@ -43,164 +45,66 @@ event" interrupt is generated. You can configure the Maple to notify you when this takes place, by registering an interrupt handler, which is a function that will be called when the update event occurs. -libmaple Reference +Function Reference ------------------ -The libmaple API for interacting with timers is documented at the -:ref:`HardwareTimer reference <lang-hardwaretimer>`. +* :ref:`HardwareTimer <lang-hardwaretimer>` Caveats ------- +Working with timers and interrupts can be tricky; they are a somewhat +"advanced" topic. The following subsections explain some common +problems associated with using timers and timer interrupts. + +In general: start simple, test with :ref:`ASSERT() <language-assert>`, +and don't try to do too much in your interrupt handlers! Make sure +that what you're trying to do in a handler isn't going to block other +interrupts from firing, if those other interrupts are important for +your program. + .. _timers-pwm-conflicts: -**PWM Conflicts:** Because PWM functionality on a given pin depends on +PWM Conflicts +^^^^^^^^^^^^^ + +Because PWM functionality on a given pin depends on the configuration of the timer and channel, you must chose your channels carefully if you want to use both timer interrupts and PWM in -the same program. Refer to the following table to match up timer -channels and Maple header pin numbers: - -.. _timers-pin-channel-map: - -.. csv-table:: - :header: Timer, Ch. 1 pin, Ch. 2 pin, Ch. 3 pin, Ch. 4 pin - - ``Timer1``, 6, 7, 8, -- - ``Timer2``, 2, 3, 1, 0 - ``Timer3``, 12, 11, 27, 28 - ``Timer4``, 5, 9, 14, 24 - -**Overhead:** there is some overhead associated with function and -interrupt calls (loading and unloading the stack, preparing state, -etc.) and this overhead can fudge your timing. Imperfect code -branching also means that, e.g., channel 1 interrupts may get called a -couple clock cycles sooner than a channel 4 interrupt, all other -configuration being the same. - -.. compound:: - - **Jitter:** other interrupts (USB, Serial, SysTick, or other - timers) can and will get called before or during the timer - interrupt routines, causing pseudorandom delays and other - frustrations. - - Disabling the USB port (by calling ``SerialUSB.end()``, or just - running off a battery) helps a lot, but then you lose the - auto-reset and communications functionality. This will require - that you put your Maple into :ref:`perpetual bootloader mode - <troubleshooting-perpetual-bootloader>` before uploading a new - program to it (or somehow causing your program to re-enable serial - over USB using :ref:`SerialUSB.begin() <lang-serialusb-begin>`). - - Disabling SysTick with ``systick_disable()`` helps as well. - However, calling this function will break the ``micros()`` and - ``millis()`` functions. - -**General:** working with timers and interrupts can be tricky and hard -to debug; they are a somewhat "advanced" topic. Start simple, test -with :ref:`ASSERT() <language-assert>`, and don't try to do too much -in your interrupt handlers! Make sure that what you're trying to do in -a handler isn't going to block other interrupts from firing (e.g. USB, -Serial, SysTick) if those other interrupts are important for your -program. - -SysTick Peripheral ------------------- - -The SysTick peripheral allows another, simple way to perform periodic -or delayed events. This separate timer does not conflict with any -other peripherals, but the associated 1kHz interrupt can jitter the -general purpose timer interrupts; this is clearly seen when running -VGA code, where the timing jitters are transformed into visual jags in -the image. The SysTick peripheral can be disabled by calling -``systick_disable()``, and re-enabled using ``systick_resume()``. - -Code Examples -------------- - -LED blink -^^^^^^^^^ - -:: - - #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles - - void handler_led(void); - - void setup() - { - // Set up the LED to blink - pinMode(BOARD_LED_PIN, OUTPUT); - - // Setup Timer - Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer2.setPeriod(LED_RATE); // in microseconds - Timer2.setCompare1(1); // overflow might be small - Timer2.attachCompare1Interrupt(handler_led); - } - - void loop() { - // Nothing! It's all in the interrupts - } - - void handler_led(void) { - toggleLED(); - } - -Racing Counters -^^^^^^^^^^^^^^^ - -:: - - void handler_count1(void); - void handler_count2(void); - - int count1 = 0; - int count2 = 0; - - void setup() - { - // Set up BUT for input - pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); - - // Setup Counting Timers - Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer4.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer3.pause(); - Timer4.pause(); - Timer3.setCount(0); - Timer4.setCount(0); - Timer3.setOverflow(30000); - Timer4.setOverflow(30000); - Timer3.setCompare1(1000); // somewhere in the middle - Timer4.setCompare1(1000); - Timer3.attachCompare1Interrupt(handler1); - Timer4.attachCompare1Interrupt(handler2); - Timer3.resume(); - Timer4.resume(); - } - - void loop() { - // Display the running counts - SerialUSB.print("Count 1: "); - SerialUSB.print(count1); - SerialUSB.print("\t\tCount 2: "); - SerialUSB.println(count2); - - // Run... while BUT is held, pause Count2 - for(int i = 0; i<1000; i++) { - if(digitalRead(BOARD_BUTTON_PIN)) { - Timer4.pause(); - } else { - Timer4.resume(); - } - delay(1); - } - } - - void handler1(void) { - count1++; - } - void handler2(void) { - count2++; - } +the same program. Refer to your board's :ref:`Timer Pin Map +<gpio-pin-maps>` to match up timer channels and pin numbers. + +Overhead +^^^^^^^^ + +There is some overhead associated with function and interrupt calls +(loading and unloading the stack, preparing state, etc.) and this +overhead can fudge your timing. Imperfect code branching also means +that, e.g., channel 1 interrupts may get called a couple clock cycles +sooner than a channel 4 interrupt, all other configuration being the +same. + +Jitter +^^^^^^ + +Other interrupts can and will get called before or during the timer +interrupt routines, causing pseudorandom delays and other +frustrations. + +Disabling the :ref:`USB <usb>` port (by calling ``SerialUSB.end()``, +or just running off a battery) helps a lot, but then you lose the +auto-reset and communications functionality. This will require that +you put your Maple into :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>` before uploading a new program +to it (or somehow causing your program to re-enable serial over USB +using :ref:`SerialUSB.begin() <lang-serialusb-begin>`). + +The SysTick peripheral another way to perform periodic or delayed +events. Its separate timer does not conflict with any other +peripherals, but the associated 1 kHz interrupt can jitter the general +purpose timer interrupts. The SysTick peripheral can be disabled by +calling :ref:`systick_disable() <libmaple-systick_disable>`, and +re-enabled using :ref:`systick_resume() <libmaple-systick_resume>`. +However, be aware that calling ``systick_disable()`` will stop the +values coming from :ref:`lang-micros` and :ref:`lang-millis` from +increasing. diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 2151171..f49580c 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -100,8 +100,6 @@ a board selected. The work-around is to restart the IDE. Mysterious! A classic! Make sure you have selected a board from the pulldown menu. -.. TODO: remove when Python version is released - ``undefined reference to setup()/loop()`` ----------------------------------------- @@ -133,8 +131,6 @@ There is an intermittent bug with the temporary directory build system that on occasion will lose many of the ``#include``\ d libmaple files. If you recompile everything, it should be fine. -.. TODO remove when the Python version is released - .. _troubleshooting-upload: ======================== diff --git a/docs/source/usart.rst b/docs/source/usart.rst index 3beb3fc..9506cc8 100644 --- a/docs/source/usart.rst +++ b/docs/source/usart.rst @@ -4,23 +4,34 @@ USART ======= -.. contents:: +.. contents:: Contents :local: Hardware/Circuit Design ----------------------- +.. FIXME [0.0.10] UART4 and UART5 +.. FIXME [0.1.0] Maple Native and Mini info and links + The Maple has 3 separate USART devices. In the most simple use case, the RX and TX pins are used to send data at a predetermined baudrate with the line voltage level relative to ground. Their usage is documented in the :ref:`Serial Ports <lang-serial>` language reference -page. +page. Which pins correspond to the USART TX and RX pins are given on +your board's silkscreen, and also in the board-specific USART pin maps +available here: + +* :ref:`Maple <maple-usart-map>` +* :ref:`Maple RET6 Edition <maple-ret6-usart-map>` + +If you use a particular serial port, you cannot also use its +communication pins for other purposes at the same time. Compatible Devices and Specifications ------------------------------------- -We have successfully used the Maple USART ports with an FT232R-based -USB-serial converter at up to 115200 baud; higher speeds should +We have successfully used the USART ports with an FT232R-based +USB-serial converter at up to 115200 baud. Higher speeds should certainly be possible. Recommended Reading diff --git a/docs/source/usb.rst b/docs/source/usb.rst index f040034..a67d710 100644 --- a/docs/source/usb.rst +++ b/docs/source/usb.rst @@ -2,34 +2,32 @@ .. _usb: -===== - USB -===== +USB +=== -The Maple STM32 microprocessor includes a dedicated USB peripheral -which can be configured to act as a general USB slave device with -transfer rates up to 12Mbps (it unfortunately can't be configured as a -host or on-the-go device). By default, the peripheral is configured -for two uses: first, to receive sketch/program uploads from the IDE, -and second, to emulate a regular serial port for use as a terminal -(text read/write). +The STM32 microprocessors include a dedicated USB peripheral which can +be configured to act as a general USB slave device with transfer rates +up to 12Mbps. (It unfortunately can't be configured as a host or +on-the-go device). By default, the peripheral is configured for two +uses: first, to receive sketch/program uploads from the :ref:`IDE +<ide>`, and second, to emulate a regular serial port for use as a +terminal (text read/write). The emulated terminal is relatively slow and inefficient; it is best for transferring data at regular serial speeds (kilobaud). Library support for accessing the emulated terminal is available at the :ref:`SerialUSB <lang-serialusb>` reference. -The SerialUSB channel is used as part of the auto-reset feature of the -IDE to program the board on Maple Rev 3 and Rev 5: a :ref:`magic -sequence of control line toggles and transmitted data -<bootloader-rev3>` causes the Maple to reset itself and enter -bootloader mode. As an unfortunate consequence, the auto-reset will -not work if the IDE can not access the serial port, either due to a -conflict with another program (serial monitor) or because the -interface has been disabled from the Maple side (through -:ref:`SerialUSB.end() <lang-serialusb-end>`). A solution to the -second problem is the use of :ref:`perpetual bootloader mode -<troubleshooting-perpetual-bootloader>`. +The SerialUSB channel is used with the :ref:`Maple bootloader +<bootloader>` to reprogram the board: a :ref:`magic sequence of +control line toggles and transmitted data <bootloader-rev3>` causes a +Maple to reset itself and enter bootloader mode. As an unfortunate +consequence, the auto-reset will not work if the IDE can not access +the serial port, either due to a conflict with another program (serial +monitor) or because the interface has been disabled from the Maple +side (through :ref:`SerialUSB.end() <lang-serialusb-end>`). A +solution to the second problem is the use of :ref:`perpetual +bootloader mode <troubleshooting-perpetual-bootloader>`. Recommended Reading ------------------- @@ -40,9 +38,11 @@ Recommended Reading * `Embedded USB - a brief tutorial <http://www.computer-solutions.co.uk/info/Embedded_tutorials/usb_tutorial.htm>`_ * `Wikipedia article on Universal Serial Bus (USB) <http://en.wikipedia.org/wiki/Universal_Serial_Bus>`_ * Linux Kernel documentation for `USB ACM <http://www.kernel.org/doc/Documentation/usb/acm.txt>`_ and `USB Serial <http://www.kernel.org/doc/Documentation/usb/usb-serial.txt>`_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) - * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) - * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (pdf; assembly - language and register reference) +* ST documentation: + * Reference Manual `RM0008 + <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + (PDF), Chapter 23, "Universal serial bus full-speed device + interface" + * `Programming Manual + <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ + (PDF; assembly language and register reference) |