From b13926073f47012d6654b0236f195c4356831fc2 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 30 Mar 2011 00:55:51 -0400 Subject: Board-specific values; corresponding QA test generalizations. Various board-specific #defines and arrays of pins added. For the changelog (some of this information predates this commit): * wirish/boards.h now declares the following arrays of pin numbers: * boardPWMPins - PWM-capable pins * boardADCPins - ADC-capable pins * boardUsedPins - pins already in use, e.g. BOARD_BUTTON_PIN It also declares a bool boardUsesPin(uint8 pin) function for convenient testing of whether a pin is in use. * wirish/boards/*.h now define: * BOARD_USART1_TX_PIN * BOARD_USART1_RX_PIN * BOARD_USART2_TX_PIN * BOARD_USART2_RX_PIN * BOARD_USART3_TX_PIN * BOARD_USART3_RX_PIN * BOARD_NR_GPIO_PINS (renamed from NR_GPIO_PINS) * BOARD_NR_USARTS (renamed from NR_USARTS) * BOARD_NR_PWM_PINS * BOARD_NR_ADC_PINS * BOARD_NR_USED_PINS * wirish/boards/maple_native.h now defines: * BOARD_UART4_TX_PIN * BOARD_UART4_RX_PIN * BOARD_UART5_TX_PIN * BOARD_UART5_RX_PIN (Unfortunately, wirish/boards/maple_RET6.h cannot, since at least one of the UART4/UART5 pins are used already; this will require layout changes for a wide-release Maple form factor RET6 board). * wirish/boards/*.cpp all include the corresponding array definitions. They all live in flash by default, thanks to the new __FLASH__ macro in wirish/wirish_types.h, which is a synonym for the existing __attr_flash #define in libmaple/libmaple_types.h. The documentation was updated to include this information. It also gained various FIXME/TODO comments related to its generalization across boards. The quality assurance-related examples (examples/qa-slave-shield.cpp and examples/test-session.cpp) now make heavy use of board-specific values to ensure portability. --- docs/source/lang/api/hardwaretimer.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/source/lang/api/hardwaretimer.rst') diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst index c7a630d..3f086ca 100644 --- a/docs/source/lang/api/hardwaretimer.rst +++ b/docs/source/lang/api/hardwaretimer.rst @@ -10,6 +10,12 @@ built-in timer peripherals. More information on these peripherals (including code examples) is available in the :ref:`timers reference `. +.. FIXME update HardwareTimer documentation after redoing it in terms +.. of the new timer interface. + +.. warning:: This class has been deprecated. It is not available in + the current build. + Library Documentation --------------------- -- cgit v1.2.3 From 1f98566c939c84a986ee8b60fde6aa601c3521da Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Tue, 26 Apr 2011 03:27:10 -0400 Subject: 0.0.10 Documentation checkpoint. The vast majority of the Maple-specific values have been pulled out of the higher-level overview pages and replaced with refs into documents under /docs/source/hardware/. Much of the work that's left to be done in this regard is labeled with versioned TODO and FIXME comments. Suggestions from StephenFromNYC and gbulmer were incorporated from this forum thread: http://forums.leaflabs.com/topic.php?id=703 --- docs/source/adc.rst | 65 ++++--- docs/source/arduino-cc-attribution.txt | 9 + docs/source/bootloader.rst | 7 +- docs/source/external-interrupts.rst | 119 ++++-------- docs/source/gpio.rst | 114 +++++------- docs/source/hardware/maple-ret6.rst | 276 ++++++++++++++++++++++++++++ docs/source/hardware/maple.rst | 210 ++++++++++++++++++--- docs/source/i2c.rst | 40 ++-- docs/source/index.rst | 12 +- docs/source/jtag.rst | 26 ++- docs/source/lang/api/abs.rst | 3 +- docs/source/lang/api/analogread.rst | 65 +++---- docs/source/lang/api/analogwrite.rst | 23 ++- docs/source/lang/api/attachinterrupt.rst | 57 ++---- docs/source/lang/api/bit.rst | 12 +- docs/source/lang/api/bitclear.rst | 13 +- docs/source/lang/api/bitread.rst | 11 +- docs/source/lang/api/bitset.rst | 9 +- docs/source/lang/api/bitwrite.rst | 7 +- docs/source/lang/api/board-values.rst | 5 +- docs/source/lang/api/cc-attribution.txt | 9 - docs/source/lang/api/constants.rst | 2 +- docs/source/lang/api/constrain.rst | 5 +- docs/source/lang/api/cos.rst | 6 +- docs/source/lang/api/delay.rst | 6 +- docs/source/lang/api/delaymicroseconds.rst | 11 +- docs/source/lang/api/detachinterrupt.rst | 8 +- docs/source/lang/api/digitalread.rst | 39 ++-- docs/source/lang/api/digitalwrite.rst | 39 ++-- docs/source/lang/api/hardwaretimer.rst | 95 +++++++++- docs/source/lang/api/highbyte.rst | 6 +- docs/source/lang/api/loop.rst | 3 +- docs/source/lang/api/lowbyte.rst | 2 +- docs/source/lang/api/map.rst | 2 +- docs/source/lang/api/max.rst | 5 +- docs/source/lang/api/micros.rst | 2 +- docs/source/lang/api/millis.rst | 2 +- docs/source/lang/api/min.rst | 3 +- docs/source/lang/api/pinmode.rst | 8 +- docs/source/lang/api/pow.rst | 5 +- docs/source/lang/api/pwmwrite.rst | 14 +- docs/source/lang/api/random.rst | 6 +- docs/source/lang/api/randomseed.rst | 2 +- docs/source/lang/api/serial.rst | 50 ++--- docs/source/lang/api/setup.rst | 2 +- docs/source/lang/api/sin.rst | 3 +- docs/source/lang/api/sq.rst | 3 +- docs/source/lang/api/tan.rst | 3 +- docs/source/lang/api/volatile.rst | 8 +- docs/source/lang/cc-attribution.txt | 9 +- docs/source/lang/cpp/arithmetic.rst | 2 +- docs/source/lang/cpp/array.rst | 6 +- docs/source/lang/cpp/assignment.rst | 2 +- docs/source/lang/cpp/bitshift.rst | 3 +- docs/source/lang/cpp/bitwisemath.rst | 3 +- docs/source/lang/cpp/boolean.rst | 3 +- docs/source/lang/cpp/booleanvariables.rst | 6 +- docs/source/lang/cpp/break.rst | 5 +- docs/source/lang/cpp/byte.rst | 3 +- docs/source/lang/cpp/bytecast.rst | 8 +- docs/source/lang/cpp/char.rst | 10 +- docs/source/lang/cpp/charcast.rst | 6 +- docs/source/lang/cpp/comments.rst | 5 +- docs/source/lang/cpp/comparison.rst | 3 +- docs/source/lang/cpp/compoundarithmetic.rst | 3 +- docs/source/lang/cpp/compoundbitwise.rst | 1 - docs/source/lang/cpp/const.rst | 6 +- docs/source/lang/cpp/continue.rst | 4 +- docs/source/lang/cpp/curly-braces.rst | 5 +- docs/source/lang/cpp/define.rst | 6 +- docs/source/lang/cpp/double.rst | 4 +- docs/source/lang/cpp/doublecast.rst | 2 +- docs/source/lang/cpp/dowhile.rst | 3 +- docs/source/lang/cpp/float.rst | 2 +- docs/source/lang/cpp/floatcast.rst | 2 +- docs/source/lang/cpp/for.rst | 4 +- docs/source/lang/cpp/goto.rst | 3 +- docs/source/lang/cpp/if.rst | 2 +- docs/source/lang/cpp/include.rst | 4 +- docs/source/lang/cpp/increment.rst | 2 +- docs/source/lang/cpp/intcast.rst | 5 +- docs/source/lang/cpp/longcast.rst | 2 +- docs/source/lang/cpp/longlong.rst | 2 +- docs/source/lang/cpp/modulo.rst | 2 +- docs/source/lang/cpp/pointer.rst | 2 +- docs/source/lang/cpp/return.rst | 3 +- docs/source/lang/cpp/scope.rst | 2 +- docs/source/lang/cpp/semicolon.rst | 5 +- docs/source/lang/cpp/sizeof.rst | 2 +- docs/source/lang/cpp/sqrt.rst | 3 +- docs/source/lang/cpp/static.rst | 3 +- docs/source/lang/cpp/string.rst | 3 +- docs/source/lang/cpp/switchcase.rst | 4 +- docs/source/lang/cpp/unsignedchar.rst | 5 +- docs/source/lang/cpp/unsignedint.rst | 2 +- docs/source/lang/cpp/unsignedlonglong.rst | 2 +- docs/source/lang/cpp/variables.rst | 3 +- docs/source/lang/cpp/void.rst | 4 +- docs/source/lang/cpp/while.rst | 2 +- docs/source/lang/unimplemented/notone.rst | 17 +- docs/source/lang/unimplemented/tone.rst | 27 +-- docs/source/language-index.rst | 17 +- docs/source/language.rst | 65 ++++--- docs/source/libmaple/api/systick.rst | 8 + docs/source/libraries.rst | 176 ++++-------------- docs/source/libs/servo.rst | 59 +++++- docs/source/libs/wire.rst | 104 +++++++++++ docs/source/maple-quickstart.rst | 14 +- docs/source/pwm.rst | 31 +--- docs/source/spi.rst | 10 +- docs/source/timers.rst | 206 ++++++--------------- docs/source/troubleshooting.rst | 4 - docs/source/usart.rst | 19 +- docs/source/usb.rst | 54 +++--- 114 files changed, 1307 insertions(+), 1119 deletions(-) create mode 100644 docs/source/arduino-cc-attribution.txt create mode 100644 docs/source/hardware/maple-ret6.rst delete mode 100644 docs/source/lang/api/cc-attribution.txt create mode 100644 docs/source/libs/wire.rst (limited to 'docs/source/lang/api/hardwaretimer.rst') 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 +`_ and `Zener diodes +`_\ +. However, `operational amplifiers +`_ 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 `_ - -* `Arduino Analog Input Tutorial `_ - -* STMicro documentation: +* `Wikipedia: Analog-to-Digital Converter + `_ +* `Arduino Analog Input Tutorial + `_ +* ST documentation: - * `Application Note on ADC Modes (pdf) `_ - * `Application Note on ADC Oversampling (pdf) `_ + * `Application Note on ADC Modes + `_ (PDF) + * `Application Note on ADC Oversampling + `_ (PDF) diff --git a/docs/source/arduino-cc-attribution.txt b/docs/source/arduino-cc-attribution.txt new file mode 100644 index 0000000..ad1c1e0 --- /dev/null +++ b/docs/source/arduino-cc-attribution.txt @@ -0,0 +1,9 @@ +.. Included in all relevant files in order to satisfy the Arduino +.. CC Attribution-ShareAlike 3.0 License + +.. admonition:: License and Attribution + + Portions of this page were adapted from the `Arduino Reference + Documentation `_\ , which + is released under a `Creative Commons Attribution-ShareAlike 3.0 + License `_. 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 ` can be +used to detect transitions, such as when the voltage goes from +:ref:`LOW ` to :ref:`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 ` +* :ref:`Maple RET6 Edition ` .. 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() ` - :ref:`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 `_ (pdf) - * `Reference Manual `_ (pdf) +* ST manual `RM0008 + `_ + (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 -` 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 ` +* :ref:`Maple RET6 Edition ` -.. _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 `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`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 ` +.. * :ref:`Maple Native ` + +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 ` 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 `_ (pdf) * `Reference Manual `_ (pdf) + + * `Programming Manual + `_ + (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 `) + * 16 Analog Input pins, 12 bit **ADC** resolution (:ref:`ADC `) + * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) + * Dedicated **USB** port for programming and communications (:ref:`USB`) + * External **JTAG** interface (:ref:`JTAG `) + * **512KB Flash** and **64KB SRAM** + * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) + * Integrated **SPI** (:ref:`SPI `) + * Integrated **I2C** (:ref:`I2C `) + * 12 Channels of Direct Memory Access (**DMA**) + * 3 **USART** and 2 **UART** devices (:ref:`USART `) + * Six 4-channel and two basic **timers** (:ref:`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 ` 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 `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`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 +` 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 `_. 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 `_, 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 + ` 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 + `_ (PDF) + * `Reference Manual + `_ (PDF) + * `Programming Manual + `_ + (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 `) - * 16 Analog Input Pins - * 12-bit **ADC** resolution (:ref:`ADC `) + * 16 Analog Input Pins, 12-bit **ADC** resolution (:ref:`ADC `) * 15 **PWM** pins at 16-bit resolution (:ref:`PWM `) - * Dedicated **USB** port for programming and communications (:ref:`USB`) - * External **JTAG** interface (:ref:`USB `) - * **128 Flash** and **20KB SRAM** + * Dedicated **USB** port for programming and communications (:ref:`USB `) + * External **JTAG** interface (:ref:`JTAG `) + * **128KB Flash** and **20KB SRAM** * 64 Channel nested vector interrupt handler (including external interrupt on GPIOs) - * Integrated **SPI** (:ref:`SPI`) - * Integrated **I2C** (:ref:`I2C`) + * Integrated **SPI** (:ref:`SPI `) + * Integrated **I2C** (:ref:`I2C `) * 7 Channels of Direct Memory Access (**DMA**) * 3 **USART** divices (:ref:`USART `) * Four 4-channel **timers** (:ref:`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 ` 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 `", ":ref:`Timer `", ":ref:`I2C `", ":ref:`UART `", ":ref:`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 +` 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 `_. The +`Maple Github repository `_. 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 `_, 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 - ` details which pins are 5V-tolerant. + way could over-voltage the pins. The :ref:`pin-mapping master table + ` 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 `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (assembly language and register reference) + * `Datasheet + `_ + (PDF) + * `Reference Manual + `_ + (PDF) + * `Programming Manual + `_ + (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 `_ -* `Wikipedia Article on i2c `_ -* `Arduino i2c/TWI reference `_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Application Note on Advanced I2C Usage - `_ - (pdf) +* `I2C Bus `_ +* `Wikipedia: I2C `_ +* `Arduino I2C/TWI reference `_ +* ST `Application Note on Advanced I2C Usage + `_ (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 `. If you're having problems, check out the -:ref:`troubleshooting ` :ref:`known problems -` pages. +:ref:`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) `_ -* `STM32, GDB, OpenOCD How To `_ -* STMicro documentation for STM32F103RB microcontroller: +* `Wikipedia Article on Joint Test Action Group (JTAG) + `_ - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) -* `LeafLabs Wiki JTAG How To `_ -* `Forum thread on JTAG `_ +* `STM32, GDB, OpenOCD How To + `_ + +* `LeafLabs Wiki JTAG How To + `_ + +* `LeafLabs forum thread on JTAG + `_ + +* ST documentation: + + * Reference Manual `RM0008 + `_ + (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 +` 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 +` 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 ` 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() -`_\ . 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 `_ and `Zener -diodes -`_\ -. However, `operational amplifiers -`_ and other -powered components can also be used if greater precision is required. - -See also +the `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 ` for +more information. + +See Also -------- - :ref:`ADC tutorial ` - `(Arduino) Tutorial: Analog Input Pins `_ -.. 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 ` for more information. -Another fix is to consult the :ref:`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 ` +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 ` 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 ` controls PWM - output on your pin (\ :ref:`this 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 + ` 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 ` and :ref:`PWM `\ . -See also +See Also -------- - :ref:`Maple PWM tutorial ` @@ -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 +` 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 +` 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 ` -- :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 `\ () @@ -40,5 +36,4 @@ See also - :ref:`bitWrite `\ () - :ref:`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() ` @@ -42,5 +42,4 @@ See also - :ref:`bitSet() ` - :ref:`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 `. +The actual values for each board are given in the :ref:`Board Hardware +Documentation `. + .. contents:: Contents :local: @@ -111,8 +114,6 @@ Pin Arrays Some :ref:`arrays ` 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 ` output, using :ref:`pwmWrite() `. The total number of these pins is :ref:`BOARD_NR_PWM_PINS diff --git a/docs/source/lang/api/cc-attribution.txt b/docs/source/lang/api/cc-attribution.txt deleted file mode 100644 index e100140..0000000 --- a/docs/source/lang/api/cc-attribution.txt +++ /dev/null @@ -1,9 +0,0 @@ -.. Included in all this directory's 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 - Documentation `_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License `_. 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 ` - :ref:`Board-Specific 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() ` - :ref:`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 `_\ , while Arduino's is that of `avr-libc `_\ . -See also +See Also -------- - - :ref:`sin() ` - :ref:`tan() ` - :ref:`float ` - :ref:`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() ` - :ref:`micros() ` - :ref:`delayMicroseconds() ` @@ -68,5 +67,4 @@ See also `_ 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 ` - :ref:`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() ` +- :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 ` or :ref:`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 ` -- :ref:`digitalWrite ` - - - - +- :ref:`BOARD_BUTTON_PIN ` +- :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() ` 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() ` 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 ` 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 ` - :ref:`digitalRead ` +- :ref:`BOARD_LED_PIN ` +- :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 `. -.. 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 `. 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 - ` to match up timer channels and pin - numbers. + like to set. Refer to your board's :ref:`master pin map + ` 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() ` - - - - -.. 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() ` -.. 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() ` -.. 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() ` - :ref:`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() ` - :ref:`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 ` - :ref:`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() ` - :ref:`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 ` 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 ` - :ref:`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 ` +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 ` pages. The Arduino function :ref:`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 ` +- :ref:`Maple PWM tutorial ` +- :ref:`boardPWMPins ` 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() ` -.. 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() ` -.. 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 ` 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 -`). 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 ` 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 `_ .. - `Serial Call Response ASCII `_ -.. 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 ` - :ref:`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 ` - :ref:`cos ` - :ref:`float ` - :ref:`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 -`. On the Maple, the only place that this is -likely to occur is in sections of code associated with 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 ` - :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 `_\ , which - is released under a `Creative Commons Attribution-ShareAlike 3.0 - License `_. + Some information in this page was adapted from the `Arduino + Reference Documentation + `_\ , which is released + under a `Creative Commons Attribution-ShareAlike 3.0 License + `_. 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 `\ () -.. 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 ` - - -.. 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 `_ 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 ` (``&=``, ``|=``, ``^=``). - -.. 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 ` - -.. 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 ` - :ref:`Boolean operators ` - :ref:`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() ` (casting a value to a byte) - :ref:`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 `_\ @@ -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() ` - - .. 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 ` - -.. 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 ` - -.. 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 ` (``&&``, ``||``) - :ref:`Bitwise operators ` (``&``, ``|``, ``^``, ``~``) - .. 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 ` - :ref:`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 ` 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 ` - -.. 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 ` - - -.. 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 ` - :ref:`float() ` -.. 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 ` - :ref:`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 ` - :ref:`double() ` -.. 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 ` 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 `_ (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 ` - :ref:`comparison operators ` -.. 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 `_ 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 ` - - - -.. 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 ` - :ref:`long long ` -.. 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 ` - :ref:`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 ` -.. 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 ` - -.. 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 `_. - Wikipedia article on `scope `_ -.. 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 ` - :ref:`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__ ` - :ref:`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 ` -.. 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 ` - :ref:`int ` - :ref:`array ` - :ref:`SerialUSB.println() ` - :ref:`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 ` - :ref:`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 ` - :ref:`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 `_ 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 `_\ (). 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 `_ () - - .. 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 `_\ (). 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 `_\ () - `analogWrite `_\ () - `Tutorial:Tone `_ - `Tutorial:Pitch follower `_ - `Tutorial:Simple Keyboard `_ - `Tutorial: multiple tones `_ - - - `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 ` 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 + ` used to compile your programs is configured to link + against `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 + `. .. _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 `_ language, which is the same language used to program the `Arduino `_ 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 + ` used to compile your programs is configured to link + against `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 `. -- 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 - ` used to compile your programs is configured to link - against `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 - ` 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 `_ - * :ref:`libmaple Documentation ` - -* ST documentation: - - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (assembly language and register reference) +* Your board's :ref:`Board Hardware Documentation ` page +* ST Documentation: + * Reference Manual `RM0008 + `_ + (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 + `_ + (PDF). This is an assembly language and register reference for + the STM32 line. +* ARM Documentation: + * `Cortex-M3 Technical Reference Manual, Revision r1p1 + `_ + (PDF). This ARM manual specifies much of the the Cortex M3 + Architecture, including instruction timings. +* `newlib Documentation `_ 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 ` (along with the rest of :ref:`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 ` -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 + ` used to compile your programs is configured to link + against `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 `, the Maple -implementation uses :ref:`timers ` to drive the PWM directly. - -Consequently, **the Maple implementation only allows Servo instances -to** :ref:`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() ` documentation. - -RC Servos expect a pulse approximately every 20ms. In the Maple -implementation, :ref:`periods ` 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 ` to match up pins and timer -channels. +Servo +----- -Another difference: although it is not publicly documented to do so, -the Arduino implementation of `attach() -`_ 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 ` 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 `_. -**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 -`_. - -**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 ` 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 ` by choosing the Servo item under the Sketch > Import Library... menu. If you are using the :ref:`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() `. + +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 `, the Maple +implementation uses :ref:`timers ` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +to** :ref:`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() ` documentation. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods ` 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 +` to match up pins and timer channels. + +Another difference: although it is not publicly documented to do so, +the Arduino implementation of `attach() +`_ returns the timer +channel associated with the newly-attached pin, or 0 on failure (as of +Arduino 0021). The Maple implementation returns :ref:`true +` on success, and :ref:`false +` on failure (and this is its documented +behavior). + +We currently provide a soft (bit-banged) implementation of the +:ref:`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 ` by choosing the +Wire item under the Sketch > Import Library... menu. + +If you are using the :ref:`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 `_, a `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 ` 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 ` 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 ` for more information. - -Note that unlike the Arduino, the Maple does not have PWM -functionality on pin D10; all other pins are :ref:`compatible -`. - -The following table shows which timer can generate which PWM -outputs. See the :ref:`pin mapping 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 +` for more information. See your board's :ref:`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) `_ + * `Arduino reference on SPI `_ + * `Hardcore SPI on Arduino `_ by kik64 -* STMicro documentation for STM32F103RB microcontroller: - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) +* ST Documentation: + + * Reference Manual `RM0008 + `_ + (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 `. +* :ref:`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() `, +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 - ` before uploading a new - program to it (or somehow causing your program to re-enable serial - over USB using :ref:`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() `, 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 +` 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 ` 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 +` before uploading a new program +to it (or somehow causing your program to re-enable serial over USB +using :ref:`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() `, and +re-enabled using :ref:`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 ` 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 ` +* :ref:`Maple RET6 Edition ` + +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 +`, 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 ` 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 -` 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() `). A solution to the -second problem is the use of :ref:`perpetual bootloader mode -`. +The SerialUSB channel is used with the :ref:`Maple bootloader +` to reprogram the board: a :ref:`magic sequence of +control line toggles and transmitted data ` 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() `). A +solution to the second problem is the use of :ref:`perpetual +bootloader mode `. Recommended Reading ------------------- @@ -40,9 +38,11 @@ Recommended Reading * `Embedded USB - a brief tutorial `_ * `Wikipedia article on Universal Serial Bus (USB) `_ * Linux Kernel documentation for `USB ACM `_ and `USB Serial `_ -* STMicro documentation for STM32F103RB microcontroller: - - * `Datasheet `_ (pdf) - * `Reference Manual `_ (pdf) - * `Programming Manual `_ (pdf; assembly - language and register reference) +* ST documentation: + * Reference Manual `RM0008 + `_ + (PDF), Chapter 23, "Universal serial bus full-speed device + interface" + * `Programming Manual + `_ + (PDF; assembly language and register reference) -- cgit v1.2.3 From 6765e0eaf8da078195373e297acc9dff6dde7b9e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 5 May 2011 17:18:25 -0400 Subject: Putting updated HardwareTimer back into the build. HardwareTimer was removed from the build when the timer refactor was done; this redoes it in terms of the new timer.h interface. A variety of conflicting or badly designed bits were deprecated or removed. I'm still not satisfied with this interface, as it's going to make life difficult moving forward to high-density chips, where the addition of basic timers means that the capture/compare methods won't apply in some cases. However, we need to get 0.0.10 out the door, so it'll have to do for now. The docs are up to date, and contain a warning that the Wirish API isn't stable and a recommendation to use libmaple proper. --- docs/source/lang/api/analogwrite.rst | 24 +- docs/source/lang/api/hardwaretimer.rst | 579 +++++++++++++-------------------- docs/source/timers.rst | 10 + wirish/HardwareTimer.cpp | 217 ++++-------- wirish/HardwareTimer.h | 430 ++++++++++-------------- wirish/rules.mk | 1 + wirish/wirish.h | 1 + 7 files changed, 500 insertions(+), 762 deletions(-) (limited to 'docs/source/lang/api/hardwaretimer.rst') diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst index e789305..dd2192a 100644 --- a/docs/source/lang/api/analogwrite.rst +++ b/docs/source/lang/api/analogwrite.rst @@ -52,7 +52,7 @@ you much more precise control over the duty cycle of your PWM output. If you're porting code from the Arduino and want a quick-and-dirty fix, one solution is to :ref:`map ` the argument to -analogWrite into the right range:: +analogWrite() into the right range:: // Arduino code: analogWrite(pin, duty); @@ -71,8 +71,8 @@ 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 ` the timer controls) will -likely need to be modified as well. +:ref:`interrupts ` the timer controls) +will likely need to be modified as well. Difference 2: You must use pinMode() to set up PWM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -141,23 +141,27 @@ the steps are: 1. Figure out which :ref:`timer ` controls PWM output on your pin (\ :ref:`your board's Timer Pin Map - ` is your friend here). Let's say it's ``Timern``\ - , where ``n`` is some number 1, 2, 3, or 4. + ` is your friend here). -2. Call ``Timern.setPeriod(2041)``\ . This will set the timer's - period to approximately 2041 microseconds, which is a frequency of - approximately 490 Hz. +2. Let's say it's timer ``n``, where ``n`` is some number. You'll + then need to put "``HardwareTimer timer(n);``" with your variables, + as described in the :ref:`HardwareTimer + ` reference. + +3. In your :ref:`lang-setup`, put "``timer.setPeriod(2041);``". This + will set the timer's period to approximately 2041 microseconds, + which is a frequency of approximately 490 Hz. Be aware that this will change the period for the **entire timer**\ , and will affect anything else in your program that depends on that timer. The important examples are :ref:`timer interrupts -` and :ref:`PWM +` and :ref:`PWM `\ . See Also -------- -- :ref:`Maple PWM tutorial ` +- :ref:`pwm` .. rubric:: Footnotes diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst index 526beb6..09245f0 100644 --- a/docs/source/lang/api/hardwaretimer.rst +++ b/docs/source/lang/api/hardwaretimer.rst @@ -5,456 +5,341 @@ HardwareTimer ============= -This class defines the public API for interfacing with the STM32's -built-in timer peripherals. More information on these peripherals -(including code examples) is available in the :ref:`timers reference -`. +This page describes how to control the built-in timers. It does not +describe how the timers work on your board. For more information on +that, the :ref:`timers reference `. -.. FIXME [0.0.10] Updated HardwareTimer documentation, with deprecation +.. warning:: The timer interface is still taking shape, and is + expected to change significantly between releases. Because of + that, the functionality described in this page shouldn't be + considered stable. -.. warning:: This class has been deprecated. It is not available in - the current build. + If you want a timer API that will be consistent between releases of + the Maple IDE, your best bet for now is to use the low-level + support in :ref:`libmaple-timer`. -Library Documentation ---------------------- +.. contents:: Contents + :local: -HardwareTimer Class Reference -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. _lang-hardwaretimer-getting-started: -To interact with a particular timer, call one of the methods -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)``. +Getting Started +--------------- -.. TODO add tutorial-style examples +You'll first need to define a ``HardwareTimer`` variable, which you'll +use to control the timer. Do this by putting the line +"``HardwareTimer timer(number);``" with your variables, where +``number`` is the timer's number. -.. cpp:class:: HardwareTimer +Here's an example (we'll fill in :ref:`setup() ` and +:ref:`loop() ` later):: - Class for interacting with a timer. There are four predefined - instances available on the Maple: ``Timer1``, ``Timer2``, - ``Timer3``, and ``Timer4``. + // Use timer 1 + HardwareTimer timer(1); -.. _lang-hardwaretimer-attachinterrupt: + void setup() { + // Your setup code + } -.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler) + void loop() { + // ... + } - Attach an interrupt handler to the given ``channel``. This - interrupt handler will be called when the timer's counter reaches - the given channel :ref:`compare ` - value. +Configuring the Prescaler and Overflow +-------------------------------------- - ``handler`` should be a function which takes no arguments and has - :ref:`void ` value; i.e. it should have signature :: +After defining your ``timer`` variable, you'll probably want to +configure how fast your timer's counter changes (using the prescaler) +and when it gets reset to zero (using the overflow value). You can do +that with the ``setPrescaleFactor()`` and ``setOverflow()`` functions. - void handler(void); - - You can later detach the interrupt using :ref:`detachInterrupt() - `. - - .. note:: The function (often called an *interrupt service - routine*, or ISR) should attempt to return as quickly as - possible. :ref:`Blinking the LED `, some - logic, :ref:`PWM ` updates, and :ref:`Serial - ` writes are fine; writing to - :ref:`SerialUSB ` or :ref:`waiting - ` for user input can take a long - time and prevent other interrupts from firing on time. - - Tip: if you have a :ref:`delay() ` in your - ISR, you're probably doing it wrong. - -.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(1, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(2, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(3, handler)``. - -.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) - - Equivalent to :ref:`attachInterrupt - `\ ``(4, handler)``. - -.. _lang-hardwaretimer-setchannelmode: - -.. cpp:function:: void HardwareTimer::setChannelMode(int channel, TimerMode mode) - - Set the given channel of this timer to the given :ref:`mode - `. The parameter ``channel`` is one of - 1, 2, 3, and 4, and corresponds to the compare channel you would - like to set. Refer to your board's :ref:`master pin map - ` to match up timer channels and pin numbers. - -.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(1, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(2, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(3, mode)``. - -.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode) - - Equivalent to :ref:`setChannelMode `\ - ``(4, mode)``. - -.. _lang-hardwaretimer-getcompare: - -.. cpp:function:: uint16 HardwareTimer::getCompare(int channel) - - Gets the compare value for the given ``channel``, from 1 to 4. See - :ref:`setCompare() `. - -.. cpp:function:: uint16 HardwareTimer::getCompare1() - - Equivalent to :ref:`getCompare `\ - ``(1, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare2() - - Equivalent to :ref:`getCompare `\ - ``(2, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare3() - - Equivalent to :ref:`getCompare `\ - ``(3, mode)``. - -.. cpp:function:: uint16 HardwareTimer::getCompare4() +.. _lang-hardwaretimer-setprescalefactor: - Equivalent to :ref:`getCompare `\ - ``(4, mode)``. +.. doxygenfunction:: HardwareTimer::setPrescaleFactor + :no-link: -.. _lang-hardwaretimer-setcompare: +.. _lang-hardwaretimer-setoverflow: -.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare) +.. doxygenfunction:: HardwareTimer::setOverflow + :no-link: - Sets the compare value for the given ``channel`` to ``compare``. - If ``compare`` is greater than this timer's overflow value, it will - be truncated to the overflow value. The default compare value is - 65,535 (the largest unsigned 16-bit integer value). +For example:: - When the counter reaches this value the interrupt for this channel - will fire if the given ``channel`` :ref:`mode - ` is ``TIMER_OUTPUTCOMPARE`` and - an interrupt is :ref:`attached - `. + // Use timer 1 + HardwareTimer timer(1); - By default, this only changes the relative offsets between events - on a single timer ("phase"); they don't control the frequency with - which they occur. However, a common trick is to increment the - compare value manually in the interrupt handler so that the event - will fire again after the increment period. There can be a - different increment value for each channel, so this trick allows - events to be programmed at 4 different rates on a single - timer. Note that function call overheads mean that the smallest - increment rate is at least a few microseconds. + void setup() { + timer.setPrescaleFactor(5); + timer.setOverflow(255); + } -.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) + void loop() { + // ... + } - Equivalent to :ref:`setCompare `\ - ``(1, compare)``. +You may also find the ``setPeriod()`` function useful: -.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) +.. _lang-hardwaretimer-setperiod: - Equivalent to :ref:`setCompare `\ - ``(2, compare)``. +.. doxygenfunction:: HardwareTimer::setPeriod + :no-link: -.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) +For example:: - Equivalent to :ref:`setCompare `\ - ``(3, compare)``. + // Use timer 1 + HardwareTimer timer(1); -.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) + void setup() { + // Have the timer repeat every 20 milliseconds + int microseconds_per_millisecond = 1000; + timer.setPeriod(20 * microseconds_per_millisecond); + } - Equivalent to :ref:`setCompare `\ - ``(4, compare)``. + void loop() { + // ... + } -.. cpp:function:: uint16 HardwareTimer::getCount() +.. _lang-hardwaretimer-interrupts: - Gets the current timer count. Due to function call overhead, the - return value will be increasingly accurate with smaller prescale - values. Also see :ref:`setCount() `. +Using Timer Interrupts +---------------------- -.. _lang-hardwaretimer-setcount: +.. TODO [0.2.0] Improve the interrupts section, here or in timers.rst -.. cpp:function:: void HardwareTimer::setCount(uint16 val) +In order to use timer interrupts, we recommend the following sequence: - Set the timer's current count to ``val``. +* Pause the timer. +* Configure the prescaler and overflow. +* Pick a timer channel to handle the interrupt and set the channel's + :ref:`mode ` to ``TIMER_OUTPUT_COMPARE``. +* Set the channel compare value appropriately (this controls what counter value, + from 0 to overflow - 1). If you just want to make the interrupt fire once + every time the timer overflows, and you don't care what the timer count is, + the channel compare value can just be 1. +* Attach an interrupt handler to the channel. +* Refresh the timer. +* Resume the timer. - Note that there is some function call overhead associated with - calling this method, so using it is not a robust way to get - multiple timers to share a count value. +Here are two complete examples. - If ``val`` exceeds the timer's :ref:`overflow value - `, it is truncated to the overflow - value. +**LED blink**: This example blinks the built-in LED without doing +anything in ``loop()``. :: + #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles -.. _lang-hardwaretimer-detachinterrupt: - -.. cpp:function:: void HardwareTimer::detachInterrupt(int channel) + // We'll use timer 2 + HardwareTimer timer(2); - Remove the interrupt handler attached to the given ``channel``, if - any. The handler will no longer be called by this timer. + void setup() { + // Set up the LED to blink + pinMode(BOARD_LED_PIN, OUTPUT); -.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() + // Pause the timer while we're configuring it + timer.pause(); - Equivalent to :ref:`detachInterrupt - `\ ``(1)``. + // Set up period + timer.setPeriod(LED_RATE); // in microseconds -.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() + // Set up an interrupt on channel 1 + timer.setChannel1Mode(TIMER_OUTPUT_COMPARE); + timer.setCompare(TIMER_CH1, 1); // Interrupt 1 count after each update + timer.attachCompare1Interrupt(handler_led); - Equivalent to :ref:`detachInterrupt - `\ ``(2)``. + // Refresh the timer's count, prescale, and overflow + timer.refresh(); -.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() + // Start the timer counting + timer.resume(); + } - Equivalent to :ref:`detachInterrupt - `\ ``(3)``. + void loop() { + // Nothing! It's all in the handler_led() interrupt: + } -.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() + void handler_led(void) { + toggleLED(); + } - Equivalent to :ref:`detachInterrupt - `\ ``(4)``. +**Racing Counters**: This example shows how to use multiple timers at +the same time. :: -.. _lang-hardwaretimer-generateupdate: + int count3 = 0; + int count4 = 0; -.. cpp:function:: void HardwareTimer::generateUpdate() + // We'll use timers 3 and 4 + HardwareTimer timer3(3); + HardwareTimer timer4(4); - Re-initializes the counter (to 0 in upcounting mode, which is the - default), and generates an update of the prescale and overflow - registers. + void setup() { + // Set up the button for input + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); -.. _lang-hardwaretimer-getoverflow: + // Set up timers to add 1 to their counts each time + // their interrupts fire. + timer3.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); + timer4.setMode(TIMER_CH1, TIMER_OUTPUT_COMPARE); + timer3.pause(); + timer4.pause(); + timer3.setCount(0); + timer4.setCount(0); + timer3.setOverflow(30000); + timer4.setOverflow(30000); + timer3.setCompare(TIMER_CH1, 1000); // somewhere in the middle + timer4.setCompare(TIMER_CH1, 1000); + timer3.attachCompare1Interrupt(handler3); + timer4.attachCompare1Interrupt(handler4); + timer3.refresh(); + timer4.refresh(); + timer3.resume(); + timer4.resume(); + } -.. cpp:function:: uint16 HardwareTimer::getOverflow() + void loop() { + // Display the running counts + SerialUSB.print("Count 3: "); + SerialUSB.print(count3); + SerialUSB.print("\t\tCount 4: "); + SerialUSB.println(count4); + + // While the button is held down, pause timer 4 + for (int i = 0; i < 1000; i++) { + if (digitalRead(BOARD_BUTTON_PIN)) { + timer4.pause(); + } else { + timer4.resume(); + } + delay(1); + } + } - Gets the timer's overflow value. See :ref:`setOverflow() - `. + void handler3(void) { + count3++; + } -.. _lang-hardwaretimer-setoverflow: + void handler4(void) { + count4++; + } -.. cpp:function:: void HardwareTimer::setOverflow(uint16 val) +``HardwareTimer`` Class Reference +--------------------------------- - Sets the timer overflow (or "reload") value to ``val``. +This section gives a full listing of the capabilities of a +``HardwareTimer``. - When the timer's counter reaches this, value it resets to - zero. Its default value is 65535 (the largest unsigned 16-bit - integer); setting the overflow to anything lower will cause - interrupts to be called more frequently (see :ref:`setPeriod() - ` function for a shortcut). +.. doxygenclass:: HardwareTimer + :members: HardwareTimer, pause, resume, getPrescaleFactor, setPrescaleFactor, getOverflow, setOverflow, getCount, setCount, setPeriod, setMode, getCompare, setCompare, attachInterrupt, detachInterrupt, refresh - After the next :ref:`timer update - `, this number will be the - maximum value for the timer's channel compare values. +.. _lang-hardwaretimer-timermode: -.. _lang-hardwaretimer-pause: +.. doxygenenum:: timer_mode -.. cpp:function:: void HardwareTimer::pause() +Deprecated Functionality +------------------------ - Stop the timer's counter, without affecting its configuration. +The following functionality exists for now, but it has been +deprecated, and will be removed in a future Maple IDE release. You +shouldn't use it in new programs, and you should change any of your +programs which do use them to use the up-to-date features described +above. - The timer will no longer count or fire interrupts after this - function is called, until it is resumed. This function is useful - during timer setup periods, in order to prevent interrupts from - firing before the timer is fully configured. +The ``TimerMode`` type from previous releases has been renamed +``timer_mode``. The mode ``TIMER_OUTPUTCOMPARE`` is still present, +but will be removed in a future release. Use ``TIMER_OUTPUT_COMPARE`` +instead. - Note that there is some function call overhead associated with this - method, so using it in concert with :ref:`resume() - ` is not a robust way to align multiple - timers to the same count value. +.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) -.. _lang-hardwaretimer-setperiod: + Use ``attachInterrupt(1, handler)`` instead. -.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds) +.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) - Configure the :ref:`prescaler - ` and :ref:`overflow - ` values to generate a timer reload - with a period as close to the given number of ``microseconds`` as - possible. + Use ``attachInterrupt(2, handler)`` instead. - The return value is the new overflow value, which may be used to - set channel compare values. However, if a clock that fires an - interrupt every given number of microseconds is all that is - desired, and the relative "phases" are unimportant, channel compare - values may all be set to 1. +.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) -.. _lang-hardwaretimer-getprescalefactor: + Use ``attachInterrupt(3, handler)`` instead. -.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor() +.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) - Returns the timer's prescale factor. See - :ref:`setPrescaleFactor() `. + Use ``attachInterrupt(4, handler)`` instead. -.. _lang-hardwaretimer-setprescalefactor: +.. _lang-hardwaretimer-setchannelmode: -.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor) +.. cpp:function:: void HardwareTimer::setChannelMode(int channel, timer_mode mode) - Set the timer's prescale factor to ``factor``. + Use ``setMode(channel, mode)`` instead. - The prescaler acts as a clock divider to slow down the rate at - which the counter increments. +.. cpp:function:: void HardwareTimer::setChannel1Mode(timer_mode mode) - For example, the system clock rate is 72MHz, so the counter will - reach 65535 in (13.89 nanoseconds) × (65535 counts) = (910.22 - microseconds), or about a thousand times a second. If the - prescaler equals 1098, then the clock rate is effectively 72MHz / - 1098 = 65.56KHz, and the counter will reach 65536 in (15.25 - microseconds) × (65536 counts) = (0.999 seconds), or about once - per second. + Use ``setMode(1, mode)`` instead. - The :ref:`setPeriod() ` method may - also be used as a convenient alternative. +.. cpp:function:: void HardwareTimer::setChannel2Mode(timer_mode mode) -.. _lang-hardwaretimer-resume: + Use ``setMode(2, mode)`` instead. -.. cpp:function:: void HardwareTimer::resume() +.. cpp:function:: void HardwareTimer::setChannel3Mode(timer_mode mode) - Resume a paused timer, without affecting its configuration. + Use ``setMode(3, mode)`` instead. - The timer will resume counting and firing interrupts as - appropriate. +.. cpp:function:: void HardwareTimer::setChannel4Mode(timer_mode mode) - Note that there is some function call overhead associated with - using this method, so using it in concert with :ref:`pause() - ` is not a robust way to align multiple - timers to the same count value. + Use ``setMode(4, mode)`` instead. -.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum() +.. cpp:function:: uint16 HardwareTimer::getCompare1() - Returns the :ref:`timer device number - ` associated with the timer. For - example, ``Timer1.getTimerNum()`` would return ``TIMER1``. + Use ``getCompare(1, mode)`` instead. - In most cases, you should not need to use this function. If you do - use it, be careful; the constant ``TIMER1`` is *not equal* to the - number 1; similarly, ``TIMER2`` is *not* the number 2, etc. Be - sure to refer to the timer device number by name. +.. cpp:function:: uint16 HardwareTimer::getCompare2() -.. _lang-hardwaretimer-modes: + Use ``getCompare(2, mode)`` instead. -Timer Modes -^^^^^^^^^^^ -.. doxygenenum:: TimerMode +.. cpp:function:: uint16 HardwareTimer::getCompare3() -.. _lang-hardwaretimer-timer-dev-num: + Use ``getCompare(3, mode)`` instead. -Timer Device Numbers -^^^^^^^^^^^^^^^^^^^^ +.. cpp:function:: uint16 HardwareTimer::getCompare4() -These provide a lower-level interface for interacting with timers. -They are mostly useful in context with the :ref:`getTimer() -` function. **Be careful** when using -these not to confuse e.g. ``TIMER1`` with the number 1; they are -different. + Use ``getCompare(4, mode)`` instead. -.. doxygenenum:: timer_dev_num +.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) -.. _lang-hardwaretimer-convenience: + Use ``setCompare(1, compare)`` instead. -.. _lang-hardwaretimer-gettimer: +.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) -Other Functions -^^^^^^^^^^^^^^^ -.. doxygenfunction:: getTimer + Use ``setCompare(2, compare)`` instead. -Examples -^^^^^^^^ +.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) -**LED blink**:: + Use ``setCompare(3, compare)`` instead. - #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles +.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) - void handler_led(void); + Use ``setCompare(4, compare)`` instead. - void setup() - { - // Set up the LED to blink - pinMode(BOARD_LED_PIN, OUTPUT); +.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() - // Setup Timer - Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); - Timer2.setPeriod(LED_RATE); // in microseconds - Timer2.setCompare1(1); // overflow might be small - Timer2.attachCompare1Interrupt(handler_led); - } + Use ``detachInterrupt(1)`` instead. - void loop() { - // Nothing! It's all in the interrupts - } +.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() - void handler_led(void) { - toggleLED(); - } + Use ``detachInterrupt(2)`` instead. -**Racing Counters**:: +.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() - void handler_count1(void); - void handler_count2(void); + Use ``detachInterrupt(3)`` instead. - int count1 = 0; - int count2 = 0; +.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() - void setup() - { - // Set up BUT for input - pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); + Use ``detachInterrupt(4)`` instead. - // 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(); - } +.. cpp:function:: void HardwareTimer::generateUpdate() - 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); - } - } + Use ``refresh()`` instead. - void handler1(void) { - count1++; - } - void handler2(void) { - count2++; - } +In previous releases, to interact with a particular timers, you would +use one of the predefined ``HardwareTimer`` instances ``Timer1``, +``Timer2``, ``Timer3``, and ``Timer4``. These are still available for +now, but they are also deprecated, and will be removed in a future +release. As detailed in :ref:`lang-hardwaretimer-getting-started`, +you should define your own ``HardwareTimer`` variables. diff --git a/docs/source/timers.rst b/docs/source/timers.rst index cb30081..9163e69 100644 --- a/docs/source/timers.rst +++ b/docs/source/timers.rst @@ -45,6 +45,16 @@ 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. +By default, different compare values only change the relative offsets +between events on a single timer ("phase"). They don't control the +frequency with which they occur. However, a common trick is to +increment the compare value manually in the interrupt handler so that +the event will fire again after the increment period. There can be a +different increment value for each channel, so this trick allows +events to be programmed at 4 different rates on a single timer. Note +that function call overheads mean that the smallest increment rate is +at least a few microseconds. + Function Reference ------------------ diff --git a/wirish/HardwareTimer.cpp b/wirish/HardwareTimer.cpp index 04d1c76..d0e32c3 100644 --- a/wirish/HardwareTimer.cpp +++ b/wirish/HardwareTimer.cpp @@ -22,204 +22,125 @@ * THE SOFTWARE. *****************************************************************************/ -/* - * wirish timer class to manage the four 16-bit timer peripherals - */ - -#include "wirish.h" #include "HardwareTimer.h" +#include "boards.h" // for CYCLES_PER_MICROSECOND +#include "wirish_math.h" -HardwareTimer::HardwareTimer(timer_dev_num timerNum) { - ASSERT(timerNum != TIMER_INVALID); +// TODO [0.1.0] Remove deprecated pieces - this->timerNum = timerNum; -} +#ifdef STM32_MEDIUM_DENSITY +#define NR_TIMERS 4 +#elif defined(STM32_HIGH_DENSITY) +#define NR_TIMERS 8 +#else +#error "Unsupported density" +#endif -void HardwareTimer::resume(void) { - timer_resume(this->timerNum); +#define MAX_RELOAD ((1 << 16) - 1) + +HardwareTimer::HardwareTimer(uint8 timerNum) { + if (timerNum > NR_TIMERS) { + ASSERT(0); + } + timer_dev *devs[] = { + TIMER1, + TIMER2, + TIMER3, + TIMER4, +#ifdef STM32_HIGH_DENSITY + TIMER5, + TIMER6, + TIMER7, + TIMER8, +#endif + }; + this->dev = devs[timerNum - 1]; } void HardwareTimer::pause(void) { - timer_pause(this->timerNum); + timer_pause(this->dev); } -uint16 HardwareTimer::getPrescaleFactor(void) { - return timer_get_prescaler(this->timerNum) + 1; +void HardwareTimer::resume(void) { + timer_resume(this->dev); +} + +uint32 HardwareTimer::getPrescaleFactor(void) { + return timer_get_prescaler(this->dev) + 1; } -void HardwareTimer::setPrescaleFactor(uint16 factor) { - // The prescaler register is zero-indexed - timer_set_prescaler(this->timerNum, factor-1); +void HardwareTimer::setPrescaleFactor(uint32 factor) { + timer_set_prescaler(this->dev, (uint16)(factor - 1)); } uint16 HardwareTimer::getOverflow() { - return timer_get_reload(this->timerNum); + return timer_get_reload(this->dev); } void HardwareTimer::setOverflow(uint16 val) { - timer_set_reload(this->timerNum, val); + timer_set_reload(this->dev, val); } uint16 HardwareTimer::getCount(void) { - return timer_get_count(this->timerNum); + return timer_get_count(this->dev); } void HardwareTimer::setCount(uint16 val) { uint16 ovf = this->getOverflow(); - timer_set_count(this->timerNum, min(val, ovf)); + timer_set_count(this->dev, min(val, ovf)); } +// FIXME [0.0.10 beta] test! uint16 HardwareTimer::setPeriod(uint32 microseconds) { // Not the best way to handle this edge case? - if(!microseconds) { - setPrescaleFactor(1); - setOverflow(1); + if (!microseconds) { + this->setPrescaleFactor(1); + this->setOverflow(1); return this->getOverflow(); } - uint32 cycles = microseconds * CYCLES_PER_MICROSECOND; - - // With a prescale factor of 1, there are CYCLES_PER_MICROSECOND - // counts/ms - uint16 ps = (uint16)((cycles >> 16) + 1); - setPrescaleFactor(ps); - - // Finally, this overflow will always be less than 65536 - setOverflow((cycles/ps) - 1); - - return this->getOverflow(); -} -void HardwareTimer::setChannelMode(int channel, TimerMode mode) { - timer_set_mode(this->timerNum, channel, mode); + uint32 period_cyc = microseconds * CYCLES_PER_MICROSECOND; + uint16 prescaler = (uint16)(period_cyc / MAX_RELOAD); + uint16 overflow = (uint16)round(period_cyc / prescaler); + this->setPrescaleFactor(prescaler); + this->setOverflow(overflow); + return overflow; } -void HardwareTimer::setChannel1Mode(TimerMode mode) { - this->setChannelMode(1, mode); -} - -void HardwareTimer::setChannel2Mode(TimerMode mode) { - this->setChannelMode(2, mode); -} - -void HardwareTimer::setChannel3Mode(TimerMode mode) { - this->setChannelMode(3, mode); -} - -void HardwareTimer::setChannel4Mode(TimerMode mode) { - this->setChannelMode(4, mode); +void HardwareTimer::setMode(int channel, timer_mode mode) { + timer_set_mode(this->dev, (uint8)channel, (timer_mode)mode); } uint16 HardwareTimer::getCompare(int channel) { - return timer_get_compare_value(this->timerNum, channel); -} - -uint16 HardwareTimer::getCompare1() { - return this->getCompare(1); -} - -uint16 HardwareTimer::getCompare2() { - return this->getCompare(2); -} - -uint16 HardwareTimer::getCompare3() { - return this->getCompare(3); -} - -uint16 HardwareTimer::getCompare4() { - return this->getCompare(4); + return timer_get_compare(this->dev, (uint8)channel); } void HardwareTimer::setCompare(int channel, uint16 val) { uint16 ovf = this->getOverflow(); - timer_set_compare_value(this->timerNum, channel, min(val, ovf)); -} - -void HardwareTimer::setCompare1(uint16 val) { - this->setCompare(1, val); -} - -void HardwareTimer::setCompare2(uint16 val) { - this->setCompare(2, val); -} - -void HardwareTimer::setCompare3(uint16 val) { - this->setCompare(3, val); -} - -void HardwareTimer::setCompare4(uint16 val) { - this->setCompare(4, val); + timer_set_compare(this->dev, (uint8)channel, min(val, ovf)); } void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler) { - timer_attach_interrupt(this->timerNum, channel, handler); -} - -void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) { - this->attachInterrupt(1, handler); -} - -void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) { - this->attachInterrupt(2, handler); -} - -void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) { - this->attachInterrupt(3, handler); -} - -void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) { - this->attachInterrupt(4, handler); + timer_attach_interrupt(this->dev, (uint8)channel, handler); } void HardwareTimer::detachInterrupt(int channel) { - timer_detach_interrupt(this->timerNum, channel); -} - -void HardwareTimer::detachCompare1Interrupt(void) { - this->detachInterrupt(1); -} - -void HardwareTimer::detachCompare2Interrupt(void) { - this->detachInterrupt(2); -} - -void HardwareTimer::detachCompare3Interrupt(void) { - this->detachInterrupt(3); + timer_detach_interrupt(this->dev, (uint8)channel); } -void HardwareTimer::detachCompare4Interrupt(void) { - this->detachInterrupt(4); +void HardwareTimer::refresh(void) { + timer_generate_update(this->dev); } -void HardwareTimer::generateUpdate(void) { - timer_generate_update(this->timerNum); -} +/* -- Deprecated predefined instances -------------------------------------- */ -HardwareTimer Timer1(TIMER1); -HardwareTimer Timer2(TIMER2); -HardwareTimer Timer3(TIMER3); -HardwareTimer Timer4(TIMER4); +HardwareTimer Timer1(1); +HardwareTimer Timer2(2); +HardwareTimer Timer3(3); +HardwareTimer Timer4(4); #ifdef STM32_HIGH_DENSITY -HardwareTimer Timer5(TIMER5); // High-density devices only -HardwareTimer Timer8(TIMER8); // High-density devices only +HardwareTimer Timer5(5); +HardwareTimer Timer6(6); +HardwareTimer Timer7(7); +HardwareTimer Timer8(8); #endif - -HardwareTimer* getTimer(timer_dev_num timerNum) { - switch (timerNum) { - case TIMER1: - return &Timer1; - case TIMER2: - return &Timer2; - case TIMER3: - return &Timer3; - case TIMER4: - return &Timer4; -#ifdef STM32_HIGH_DENSITY - case TIMER5: - return &Timer5; - case TIMER8: - return &Timer8; -#endif - default: - return 0; - } -} diff --git a/wirish/HardwareTimer.h b/wirish/HardwareTimer.h index 4030adc..fd8ca9a 100644 --- a/wirish/HardwareTimer.h +++ b/wirish/HardwareTimer.h @@ -23,66 +23,45 @@ *****************************************************************************/ /** - * @brief wirish timer class to manage the four 16-bit timer peripherals + * @brief Wirish timer class. */ #ifndef _HARDWARETIMER_H_ #define _HARDWARETIMER_H_ -#include "timers.h" +// TODO [0.1.0] Remove deprecated pieces, pick a better API + +#include "timer.h" + +/** Timer mode. */ +typedef timer_mode TimerMode; + +/** @brief Deprecated; use TIMER_OUTPUT_COMPARE instead. */ +#define TIMER_OUTPUTCOMPARE TIMER_OUTPUT_COMPARE /** - * Interface to one of the 16-bit timer peripherals. - * - * User code should not instantiate this class directly; instead, use - * one of the predefined Timer instances (Timer1, Timer2, etc.). - * - * HardwareTimer instances can be configured to generate periodic or - * delayed events with minimal work done by the microcontroller. Each - * timer maintains a single 16-bit count that can be configured with a - * prescaler and overflow value. - * - * By default, a timer's counter is incremented once per clock cycle. - * The prescaler acts as a divider of the 72MHz Maple system clock; - * without prescaling, the timer's count would reach 65535 (2**16-1) - * and roll over over 1000 times per second. - * - * The overflow value is the maximum value the counter will reach. It - * defaults to 65535; smaller values will cause the counter to reset - * more frequently. + * @brief Interface to one of the 16-bit timer peripherals. */ class HardwareTimer { - private: - timer_dev_num timerNum; - - public: - HardwareTimer(timer_dev_num timer_num); +private: + timer_dev *dev; +public: /** - * Return this timer's device number. For example, - * Timer1.getTimerNum() == TIMER1 + * @brief Construct a new HardwareTimer instance. + * @param timerNum number of the timer to control. */ - timer_dev_num getTimerNum() { return timerNum; } + HardwareTimer(uint8 timerNum); /** - * Stop the counter, without affecting its configuration. - * - * The timer will no longer count or fire interrupts after this - * function is called, until it is resumed. This function is - * useful during timer setup periods, in order to prevent - * interrupts from firing before the timer is fully configured. - * - * Note that there is some function call overhead associated with - * this method, so using it in concert with - * HardwareTimer::resume() is not a robust way to align multiple - * timers to the same count value. + * @brief Stop the counter, without affecting its configuration. * * @see HardwareTimer::resume() */ void pause(void); /** - * Resume a paused timer, without affecting its configuration. + * @brief Resume a paused timer, without affecting its configuration. * * The timer will resume counting and firing interrupts as * appropriate. @@ -97,66 +76,51 @@ class HardwareTimer { void resume(void); /** - * Returns the timer's prescale factor. + * @brief Get the timer's prescale factor. + * @return Timer prescaler, from 1 to 65,536. * @see HardwareTimer::setPrescaleFactor() */ - uint16 getPrescaleFactor(); + uint32 getPrescaleFactor(); /** - * Set the timer's prescale factor. + * @brief Set the timer's prescale factor. * - * The prescaler acts as a clock divider to slow down the rate at - * which the counter increments. + * The new value won't take effect until the next time the counter + * overflows. You can force the counter to reset using + * HardwareTimer::refresh(). * - * For example, the system clock rate is 72MHz, so the counter - * will reach 65535 in (13.89 nanoseconds) * (65535 counts) = - * (910.22 microseconds), or about a thousand times a second. If - * the prescaler equals 1098, then the clock rate is effectively - * 65.56KHz, and the counter will reach 65536 in (15.25 - * microseconds) * (65536 counts) = (0.999 seconds), or about once - * per second. - * - * The HardwareTimer::setPeriod() method may also be used as a - * convenient alternative. - * - * @param factor The new prescale value to set. - * @see HardwareTimer::setPeriod() + * @param factor The new prescale value to set, from 1 to 65,536. + * @see HardwareTimer::refresh() */ - void setPrescaleFactor(uint16 factor); + void setPrescaleFactor(uint32 factor); /** - * Gets the timer overflow value. + * @brief Get the timer overflow value. * @see HardwareTimer::setOverflow() */ uint16 getOverflow(); /** - * Sets the timer overflow (or "reload") value. + * @brief Set the timer overflow (or "reload") value. * - * When the timer's counter reaches this, value it resets to - * zero. Its default value is 65535 (the largest unsigned 16-bit - * integer); setting the overflow to anything lower will cause - * interrupts to be called more frequently (see the setPeriod() - * function below for a shortcut). This number sets the maximum - * value for the channel compare values. + * The new value won't take effect until the next time the counter + * overflows. You can force the counter to reset using + * HardwareTimer::refresh(). * * @param val The new overflow value to set + * @see HardwareTimer::refresh() */ void setOverflow(uint16 val); /** - * Retrieve the current timer count. + * @brief Get the current timer count. * * @return The timer's current count value */ uint16 getCount(void); /** - * Set the current timer count. - * - * Note that there is some function call overhead associated with - * calling this method, so using it is not a robust way to get - * multiple timers to share a count value. + * @brief Set the current timer count. * * @param val The new count value to set. If this value exceeds * the timer's overflow value, it is truncated to the @@ -165,143 +129,50 @@ class HardwareTimer { void setCount(uint16 val); /** - * Configure the prescaler and overflow values to generate a timer + * @brief Set the timer's period in microseconds. + * + * Configures the prescaler and overflow values to generate a timer * reload with a period as close to the given number of * microseconds as possible. * - * The return value is the overflow, which may be used to set - * channel compare values. However, if a clock that fires an - * interrupt every given number of microseconds is all that is - * desired, and the relative "phases" are unimportant, channel - * compare values may all be set to 1. - * - * @param microseconds the desired period of the timer. - * @return the overflow value (and thus, the largest value that can be - * set as a compare). + * @param microseconds The desired period of the timer. This must be + * greater than zero. + * @return The new overflow value. */ uint16 setPeriod(uint32 microseconds); /** - * Set the given channel of this timer to the given mode. - * + * @brief Configure a timer channel's mode. * @param channel Timer channel, from 1 to 4 * @param mode Mode to set */ - void setChannelMode(int channel, TimerMode mode); - - /** - * Set channel 1 of this timer to the given mode. - * - * Note: Timer1.setChannel1Mode(TIMER_PWM) may not work as - * expected; if you want PWM functionality on a channel make sure - * you don't set it to something else! - * - * @see TimerMode - */ - void setChannel1Mode(TimerMode mode); - - /** - * Set channel 2 of this timer to the given mode. - * @see TimerMode - */ - void setChannel2Mode(TimerMode mode); - - /** - * Set channel 3 of this timer to the given mode. - * @see TimerMode - */ - void setChannel3Mode(TimerMode mode); - - /** - * Set channel 4 of this timer to the given mode. - * @see TimerMode - */ - void setChannel4Mode(TimerMode mode); + void setMode(int channel, timer_mode mode); /** - * Gets the compare value for the given channel. + * @brief Get the compare value for the given channel. * @see HardwareTimer::setCompare() */ uint16 getCompare(int channel); - /** Equivalent to getCompare(1) */ - uint16 getCompare1(); - - /** Equivalent to getCompare(2) */ - uint16 getCompare2(); - - /** Equivalent to getCompare(3) */ - uint16 getCompare3(); - - /** Equivalent to getCompare(4) */ - uint16 getCompare4(); - /** - * Sets the compare value for the given channel. - * - * When the counter reaches this value the interrupt for this - * channel will fire if the channel mode is TIMER_OUTPUTCOMPARE - * and an interrupt is attached. - * - * By default, this only changes the relative offsets between - * events on a single timer ("phase"); they don't control the - * frequency with which they occur. However, a common trick is to - * increment the compare value manually in the interrupt handler - * so that the event will fire again after the increment - * period. There can be a different increment value for each - * channel, so this trick allows events to be programmed at 4 - * different rates on a single timer. Note that function call - * overheads mean that the smallest increment rate is at least a - * few microseconds. + * @brief Set the compare value for the given channel. * * @param channel the channel whose compare to set, from 1 to 4. * @param compare The compare value to set. If greater than this * timer's overflow value, it will be truncated to * the overflow value. * - * @see TimerMode - * @see HardwareTimer::setChannelMode() + * @see timer_mode + * @see HardwareTimer::setMode() * @see HardwareTimer::attachInterrupt() */ void setCompare(int channel, uint16 compare); /** - * Equivalent to setCompare(1, compare). - */ - void setCompare1(uint16 compare); - - /** - * Equivalent to setCompare(2, compare). - */ - void setCompare2(uint16 compare); - - /** - * Equivalent to setCompare(3, compare). - */ - void setCompare3(uint16 compare); - - /** - * Equivalent to setCompare(4, compare). - */ - void setCompare4(uint16 compare); - - /** - * Attach an interrupt handler to the given channel. This - * interrupt handler will be called when the timer's counter - * reaches the given channel compare value. - * - * The argument should be a function which takes no arguments and - * has no return value; i.e. it should have signature + * @brief Attach an interrupt handler to the given channel. * - * void (*handler)(void); - * - * Note: The function (often called an interrupt service routine, - * or ISR) should attempt to return as quickly as possible. - * Blinking the LED, some logic, PWM updates, and Serial writes - * are fine; writing to SerialUSB or waiting for user input can - * take a long time and other compare interrupts won't fire. Tip: - * if you have a delay() in your interrupt routine, you're probably - * doing it wrong. + * This interrupt handler will be called when the timer's counter + * reaches the given channel compare value. * * @param channel the channel to attach the ISR to, from 1 to 4. * @param handler The ISR to attach to the given channel. @@ -310,32 +181,10 @@ class HardwareTimer { void attachInterrupt(int channel, voidFuncPtr handler); /** - * Equivalent to attachCompareInterrupt(1, handler). - * @see HardwareTimer::attachCompareInterrupt() - */ - void attachCompare1Interrupt(voidFuncPtr handler); - - /** - * Equivalent to attachCompareInterrupt(2, handler). - * @see HardwareTimer::attachCompareInterrupt() - */ - void attachCompare2Interrupt(voidFuncPtr handler); - - /** - * Equivalent to attachCompareInterrupt(3, handler). - * @see HardwareTimer::attachCompareInterrupt() - */ - void attachCompare3Interrupt(voidFuncPtr handler); - - /** - * Equivalent to attachCompareInterrupt(4, handler). - * @see HardwareTimer::attachCompareInterrupt() - */ - void attachCompare4Interrupt(voidFuncPtr handler); - - /** - * Remove the interrupt handler attached to the given channel, if - * any. The handler will no longer be called by this timer. + * @brief Remove the interrupt handler attached to the given + * channel, if any. + * + * The handler will no longer be called by this timer. * * @param channel the channel whose interrupt to detach, from 1 to 4. * @see HardwareTimer::attachInterrupt() @@ -343,71 +192,138 @@ class HardwareTimer { void detachInterrupt(int channel); /** - * Equivalent to detachInterrupt(1). - * @see HardwareTimer::detachInterrupt() + * @brief Reset the counter, and update the prescaler and overflow + * values. + * + * This will reset the counter to 0 in upcounting mode (the + * default). It will also update the timer's prescaler and + * overflow, if you have set them up to be changed using + * HardwareTimer::setPrescaleFactor() or + * HardwareTimer::setOverflow(). + * + * @see HardwareTimer::setPrescaleFactor() + * @see HardwareTimer::setOverflow() */ - void detachCompare1Interrupt(void); + void refresh(void); - /** - * Equivalent to detachInterrupt(2). - * @see HardwareTimer::detachInterrupt() - */ - void detachCompare2Interrupt(void); + /* -- Deprecated methods ----------------------------------------------- */ - /** - * Equivalent to detachInterrupt(3). - * @see HardwareTimer::detachInterrupt() - */ - void detachCompare3Interrupt(void); + /** @brief Deprecated; use setMode(channel, mode) instead. */ + void setChannelMode(int channel, timer_mode mode) { + setMode(channel, mode); + } - /** - * Equivalent to detachInterrupt(4). - * @see HardwareTimer::detachInterrupt() - */ - void detachCompare4Interrupt(void); + /** @brief Deprecated; use setMode(TIMER_CH1, mode) instead. */ + void setChannel1Mode(timer_mode mode) { setMode(TIMER_CH1, mode); } - /** - * Re-initializes the counter (to 0 in upcounting mode, which is - * the default), and generates an update of the prescale and - * overflow registers. - */ - void generateUpdate(void); + /** @brief Deprecated; use setMode(TIMER_CH2, mode) instead. */ + void setChannel2Mode(timer_mode mode) { setMode(TIMER_CH2, mode); } + + /** @brief Deprecated; use setMode(TIMER_CH3, mode) instead. */ + void setChannel3Mode(timer_mode mode) { setMode(TIMER_CH3, mode); } + + /** @brief Deprecated; use setMode(TIMER_CH4, mode) instead. */ + void setChannel4Mode(timer_mode mode) { setMode(TIMER_CH4, mode); } + + /** @brief Deprecated; use return getCompare(TIMER_CH1) instead. */ + uint16 getCompare1() { return getCompare(TIMER_CH1); } + + /** @brief Deprecated; use return getCompare(TIMER_CH2) instead. */ + uint16 getCompare2() { return getCompare(TIMER_CH2); } + + /** @brief Deprecated; use return getCompare(TIMER_CH3) instead. */ + uint16 getCompare3() { return getCompare(TIMER_CH3); } + + /** @brief Deprecated; use return getCompare(TIMER_CH4) instead. */ + uint16 getCompare4() { return getCompare(TIMER_CH4); } + + /** @brief Deprecated; use setCompare(TIMER_CH1, compare) instead. */ + void setCompare1(uint16 compare) { setCompare(TIMER_CH1, compare); } + + /** @brief Deprecated; use setCompare(TIMER_CH2, compare) instead. */ + void setCompare2(uint16 compare) { setCompare(TIMER_CH2, compare); } + + /** @brief Deprecated; use setCompare(TIMER_CH3, compare) instead. */ + void setCompare3(uint16 compare) { setCompare(TIMER_CH3, compare); } + + /** @brief Deprecated; use setCompare(TIMER_CH4, compare) instead. */ + void setCompare4(uint16 compare) { setCompare(TIMER_CH4, compare); } + + /** @brief Deprecated; use attachInterrupt(TIMER_CH1, handler) instead. */ + void attachCompare1Interrupt(voidFuncPtr handler) { + attachInterrupt(TIMER_CH1, handler); + } + + /** @brief Deprecated; use attachInterrupt(TIMER_CH2, handler) instead. */ + void attachCompare2Interrupt(voidFuncPtr handler) { + attachInterrupt(TIMER_CH2, handler); + } + + /** @brief Deprecated; use attachInterrupt(TIMER_CH3, handler) instead. */ + void attachCompare3Interrupt(voidFuncPtr handler) { + attachInterrupt(TIMER_CH3, handler); + } + + /** @brief Deprecated; use attachInterrupt(TIMER_CH4, handler) instead. */ + void attachCompare4Interrupt(voidFuncPtr handler) { + attachInterrupt(TIMER_CH4, handler); + } + + /** @brief Deprecated; use detachInterrupt(TIMER_CH1) instead. */ + void detachCompare1Interrupt(void) { detachInterrupt(TIMER_CH1); } + + /** @brief Deprecated; use detachInterrupt(TIMER_CH2) instead. */ + void detachCompare2Interrupt(void) { detachInterrupt(TIMER_CH2); } + + /** @brief Deprecated; use detachInterrupt(TIMER_CH3) instead. */ + void detachCompare3Interrupt(void) { detachInterrupt(TIMER_CH3); } + + /** @brief Deprecated; use detachInterrupt(TIMER_CH4) instead. */ + void detachCompare4Interrupt(void) { detachInterrupt(TIMER_CH4); } + + /** @brief Deprecated; use refresh() instead. */ + void generateUpdate(void) { refresh(); } }; -/** Pre-instantiated timer for use by user code. */ +/* -- The rest of this file is deprecated. --------------------------------- */ + +/** + * @brief Deprecated. + * + * Pre-instantiated timer. + */ extern HardwareTimer Timer1; -/** Pre-instantiated timer for use by user code. */ +/** + * @brief Deprecated. + * + * Pre-instantiated timer. + */ extern HardwareTimer Timer2; -/** Pre-instantiated timer for use by user code. */ +/** + * @brief Deprecated. + * + * Pre-instantiated timer. + */ extern HardwareTimer Timer3; -/** Pre-instantiated timer for use by user code. */ +/** + * @brief Deprecated. + * + * Pre-instantiated timer. + */ extern HardwareTimer Timer4; #ifdef STM32_HIGH_DENSITY -/** Pre-instantiated timer for use by user code, on devices with - more than four timers (this does not include the Maple). */ -extern HardwareTimer Timer5; -/** Pre-instantiated timer for use by user code, on devices with - more than four timers (this does not include the Maple). */ -extern HardwareTimer Timer8; -#endif - /** - * Get one of the pre-instantiated HardwareTimer instances, given a - * timer device number. - * - * Be careful not to pass an actual number to this function. For - * example, getTimer(1) will not return Timer1. Use a real - * timer_dev_num, e.g. TIMER1, TIMER2, etc. + * @brief Deprecated. * - * @param timerNum the timer device number, e.g. TIMER1. - * - * @return Pointer to the HardwareTimer instance corresponding to the - * given timer device number. If timerNum is TIMER_INVALID, returns a - * null pointer. + * Pre-instantiated timer. + */ +extern HardwareTimer Timer5; +/** + * @brief Deprecated. * - * @see timer_dev_num + * Pre-instantiated timer. */ -HardwareTimer* getTimer(timer_dev_num timerNum); - +extern HardwareTimer Timer8; #endif +#endif diff --git a/wirish/rules.mk b/wirish/rules.mk index c3608e3..6999288 100644 --- a/wirish/rules.mk +++ b/wirish/rules.mk @@ -23,6 +23,7 @@ cppSRCS_$(d) := wirish_math.cpp \ boards/maple_RET6.cpp \ comm/HardwareSerial.cpp \ comm/HardwareSPI.cpp \ + HardwareTimer.cpp \ usb_serial.cpp \ cxxabi-compat.cpp \ wirish_shift.cpp \ diff --git a/wirish/wirish.h b/wirish/wirish.h index d30ad20..82a9897 100644 --- a/wirish/wirish.h +++ b/wirish/wirish.h @@ -44,6 +44,7 @@ #include "wirish_time.h" #include "HardwareSPI.h" #include "HardwareSerial.h" +#include "HardwareTimer.h" #include "usb_serial.h" /* Arduino wiring macros and bit defines */ -- cgit v1.2.3