diff options
| author | Marti Bolivar <mbolivar@mit.edu> | 2010-12-15 01:50:56 -0500 |
|---|---|---|
| committer | Marti Bolivar <mbolivar@mit.edu> | 2010-12-15 16:16:31 -0500 |
| commit | d744fb826f4a6d6ce560f3b78f2e63a1f9666d9e (patch) | |
| tree | 35d0939c959cec372e1a6ce2f4bdf95dbe977918 | |
| parent | 74c8937446e1be4e0d21f69a8c098e2caf7814d5 (diff) | |
| download | librambutan-d744fb826f4a6d6ce560f3b78f2e63a1f9666d9e.tar.gz librambutan-d744fb826f4a6d6ce560f3b78f2e63a1f9666d9e.zip | |
Finalized 0.0.9 documentation.
50 files changed, 1714 insertions, 1225 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile index 88b8764..3290843 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -318,7 +318,7 @@ EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = NO +EXTRACT_STATIC = YES # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -1335,13 +1335,13 @@ ENABLE_PREPROCESSING = YES # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. @@ -1369,7 +1369,8 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = __cplusplus +PREDEFINED = ALWAYS_INLINE= \ + __cplusplus # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1462,7 +1463,7 @@ HIDE_UNDOC_RELATIONS = YES # toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) -HAVE_DOT = YES +HAVE_DOT = NO # The DOT_NUM_THREADS specifies the number of dot invocations doxygen is # allowed to run in parallel. When set to 0 (the default) doxygen will diff --git a/docs/source/_static/img/jtag-wiring.png b/docs/source/_static/img/jtag-wiring.png Binary files differindex 9c63e82..8f31f99 100644 --- a/docs/source/_static/img/jtag-wiring.png +++ b/docs/source/_static/img/jtag-wiring.png diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index d42c050..57833ed 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -138,447 +138,447 @@ This time, however, no DFU transaction is initiated, and the bootloader gives way to user code, closing down the DFU pipe and bringing up the USB serial. -.. _bootloader-rev6: - -Maple Rev6 - The Serial Bootloader (Tentative) ----------------------------------------------- - -.. note:: This section documents an in-progress version of the Maple - bootloader. **No Maples yet sold use this bootloader protocol**. - It has not been yet been publicly released, and its interface is - not stable. - -The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, -but was unsatisfactory on Windows. Unlike the other operating systems, -Windows needed to be manually pointed to both the driver to use for -programming (DFU, via `libusb <http://www.libusb.org/>`_) and the -driver to use for serial communication (usbser.sys, built in to -Windows). Since Maple operates in only one of these modes at a time, -driver installation was unnecessarily complicated. It was necessary to -bring Maple into the correct mode before installing each of the -drivers. Furthermore, because libusb is not bundled with Windows, and -its driver is not signed, Windows 7 users have been forced to -laboriously disable driver signing checks. Finally, Windows hates the -constant switching of the device between Serial and DFU modes (during -programming), and often prompts users to install drivers that are -already installed. We have therefore decided to abandon DFU. - -In our new bootloader scheme, Maple is simply a serial device. -Windows comes bundled with usbser.sys, so no driver signing is -required. The IDE installation process is greatly simplified, there -is no more switching back and forth between "modes", and we can build -in new functionality outside the DFU spec. - -The first incarnation of this serial-only bootloader leaves libmaple -and user code untouched. However, during programming, instead of -calling :command:`dfu-util` to upload code we will now call a newly -written utility script similar to `avr-dude -<http://savannah.nongnu.org/projects/avrdude/>`_. The high level -operation of the bootloader will remain the same - come on at startup, -wait for an upload operation or timeout, and jump to user code. - -The second version of this bootloader will eliminate this dependence -on resetting and timing out by having the bootloader run in the -background. It will additionally own the serial port. In this scheme, -sending data over the COM port while DTR is pulled low results in that -packet being captured by the bootloader and interpreted as a -bootloader command. When the user uploads a new program, the -bootloader will overwrite the old one, reset the various peripheral -registers, and jump to user code. All of this will occur without -resetting the chip and thus causing Maple to connect and disconnect -from your computer (which seems to cause many problems). - -The final version of this bootloader scheme will involve a separate -microcontroller, whose responsibilities are to drive the USB port, -program the main processor, and offer some amount of debugging -capability. This will allow user sketches to run on the bare metal of -the main processor, without any bootloader hiding underneath. This -approach is similar to the approaches taken by mbed and the Arduino -Uno. - -Regardless of which generation of the new serial bootloader you are -working with, the command interface is the same. The low level -communication protocol is inspired by STK-500, the protocol used to -program many AVR-based development boards. The protocol is a -packetized query-response scheme. The host PC initiates every -transaction, and for every query sent to the bootloader, a single -response will be returned (or the system times out). Data is -transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity -bit. Every query or response follows the same packet format that looks -like this: - -.. _bootloader-packet-structure: - -Packet Structure -^^^^^^^^^^^^^^^^ - -A bootloader packet is composed of a sequence of fields, as follows. - -.. list-table:: - :header-rows: 1 - - * - Field - - Length (bytes) - - Value - - Description - - * - START - - 1 - - 0x1B - - Magic constant, indicates bootloader packet - - * - SEQUENCE_NUM - - 1 - - 0--0xFF - - Queries and responses must have the same sequence number; rolls - over to 0 after 0xFF - - * - MESSAGE_SIZE - - 2 - - 0--0xFFFF - - Size of message body, currently limited to a 1024B=1KB maximum - - * - TOKEN - - 1 - - 0x7F - - Differs from STK500 value of 0x0E - - * - MESSAGE_BODY - - Variable, determined by MESSAGE_SIZE field - - Command query or response - - See :ref:`next section <bootloader-commands>` - - * - CHECKSUM - - 4 - - XOR of all other 32-bit words in packet - - See :ref:`below <bootloader-checksum>` - -.. _bootloader-checksum: - -.. highlight:: cpp - -.. note:: When computing the checksum, the words in a packet are - interpreted big-endian (as if the packet were a sequence of 32-bit, - big-endian unsigned integers). If the end of the MESSAGE_BODY is - not aligned with a four-byte boundary, then the checksum will treat - it as if it was padded with zero bytes to a four-byte boundary. - - As a concrete example, an entire GET_INFO query (see :ref:`below - <bootloader-get-info>`), including the packet structure, is - comprised of the byte sequence :: - - {0x1B, 0x7F, 0x00, 0x01, 0x7F, 0x00, 0x64, 0x7F, 0x00, 0x01} - - The SEQUENCE_NUM of this query is 0x7F. +.. .. _bootloader-rev6: + +.. Maple Rev6 - The Serial Bootloader (Tentative) +.. ---------------------------------------------- + +.. .. note:: This section documents an in-progress version of the Maple +.. bootloader. **No Maples yet sold use this bootloader protocol**. +.. It has not been yet been publicly released, and its interface is +.. not stable. + +.. The bootloader in Rev3/Rev5 works well on Linux, acceptably on Mac, +.. but was unsatisfactory on Windows. Unlike the other operating systems, +.. Windows needed to be manually pointed to both the driver to use for +.. programming (DFU, via `libusb <http://www.libusb.org/>`_) and the +.. driver to use for serial communication (usbser.sys, built in to +.. Windows). Since Maple operates in only one of these modes at a time, +.. driver installation was unnecessarily complicated. It was necessary to +.. bring Maple into the correct mode before installing each of the +.. drivers. Furthermore, because libusb is not bundled with Windows, and +.. its driver is not signed, Windows 7 users have been forced to +.. laboriously disable driver signing checks. Finally, Windows hates the +.. constant switching of the device between Serial and DFU modes (during +.. programming), and often prompts users to install drivers that are +.. already installed. We have therefore decided to abandon DFU. + +.. In our new bootloader scheme, Maple is simply a serial device. +.. Windows comes bundled with usbser.sys, so no driver signing is +.. required. The IDE installation process is greatly simplified, there +.. is no more switching back and forth between "modes", and we can build +.. in new functionality outside the DFU spec. + +.. The first incarnation of this serial-only bootloader leaves libmaple +.. and user code untouched. However, during programming, instead of +.. calling :command:`dfu-util` to upload code we will now call a newly +.. written utility script similar to `avr-dude +.. <http://savannah.nongnu.org/projects/avrdude/>`_. The high level +.. operation of the bootloader will remain the same - come on at startup, +.. wait for an upload operation or timeout, and jump to user code. + +.. The second version of this bootloader will eliminate this dependence +.. on resetting and timing out by having the bootloader run in the +.. background. It will additionally own the serial port. In this scheme, +.. sending data over the COM port while DTR is pulled low results in that +.. packet being captured by the bootloader and interpreted as a +.. bootloader command. When the user uploads a new program, the +.. bootloader will overwrite the old one, reset the various peripheral +.. registers, and jump to user code. All of this will occur without +.. resetting the chip and thus causing Maple to connect and disconnect +.. from your computer (which seems to cause many problems). + +.. The final version of this bootloader scheme will involve a separate +.. microcontroller, whose responsibilities are to drive the USB port, +.. program the main processor, and offer some amount of debugging +.. capability. This will allow user sketches to run on the bare metal of +.. the main processor, without any bootloader hiding underneath. This +.. approach is similar to the approaches taken by mbed and the Arduino +.. Uno. + +.. Regardless of which generation of the new serial bootloader you are +.. working with, the command interface is the same. The low level +.. communication protocol is inspired by STK-500, the protocol used to +.. program many AVR-based development boards. The protocol is a +.. packetized query-response scheme. The host PC initiates every +.. transaction, and for every query sent to the bootloader, a single +.. response will be returned (or the system times out). Data is +.. transmitted over 115.2kbps, 8 data bits, 1 stop bit, no parity +.. bit. Every query or response follows the same packet format that looks +.. like this: + +.. .. _bootloader-packet-structure: + +.. Packet Structure +.. ^^^^^^^^^^^^^^^^ + +.. A bootloader packet is composed of a sequence of fields, as follows. + +.. .. list-table:: +.. :header-rows: 1 + +.. * - Field +.. - Length (bytes) +.. - Value +.. - Description + +.. * - START +.. - 1 +.. - 0x1B +.. - Magic constant, indicates bootloader packet + +.. * - SEQUENCE_NUM +.. - 1 +.. - 0--0xFF +.. - Queries and responses must have the same sequence number; rolls +.. over to 0 after 0xFF + +.. * - MESSAGE_SIZE +.. - 2 +.. - 0--0xFFFF +.. - Size of message body, currently limited to a 1024B=1KB maximum + +.. * - TOKEN +.. - 1 +.. - 0x7F +.. - Differs from STK500 value of 0x0E + +.. * - MESSAGE_BODY +.. - Variable, determined by MESSAGE_SIZE field +.. - Command query or response +.. - See :ref:`next section <bootloader-commands>` + +.. * - CHECKSUM +.. - 4 +.. - XOR of all other 32-bit words in packet +.. - See :ref:`below <bootloader-checksum>` + +.. .. _bootloader-checksum: + +.. .. highlight:: cpp + +.. .. note:: When computing the checksum, the words in a packet are +.. interpreted big-endian (as if the packet were a sequence of 32-bit, +.. big-endian unsigned integers). If the end of the MESSAGE_BODY is +.. not aligned with a four-byte boundary, then the checksum will treat +.. it as if it was padded with zero bytes to a four-byte boundary. -.. highlight:: sh +.. As a concrete example, an entire GET_INFO query (see :ref:`below +.. <bootloader-get-info>`), including the packet structure, is +.. comprised of the byte sequence :: + +.. {0x1B, 0x7F, 0x00, 0x01, 0x7F, 0x00, 0x64, 0x7F, 0x00, 0x01} + +.. The SEQUENCE_NUM of this query is 0x7F. + +.. .. highlight:: sh -.. _bootloader-commands: +.. .. _bootloader-commands: -Commands -^^^^^^^^ +.. Commands +.. ^^^^^^^^ -The packet structure overhead is for reliability. The actual queries -and responses are transacted inside of the message body. Following -the STK-500 protocol, each query or response begins with the single -byte command field. For each query, the resultant response must begin -with the same CMD byte. For each type of command, the structure of -queries and responses is of fixed size. +.. The packet structure overhead is for reliability. The actual queries +.. and responses are transacted inside of the message body. Following +.. the STK-500 protocol, each query or response begins with the single +.. byte command field. For each query, the resultant response must begin +.. with the same CMD byte. For each type of command, the structure of +.. queries and responses is of fixed size. -Also following STK-500, fields longer than 1 byte are transmitted MSB -first (big-endian). However, READ and WRITE commands operate byte-wise -(not word-wise); it is up to the host PC to ensure that alignment and -ordering issues are handled appropriately. +.. Also following STK-500, fields longer than 1 byte are transmitted MSB +.. first (big-endian). However, READ and WRITE commands operate byte-wise +.. (not word-wise); it is up to the host PC to ensure that alignment and +.. ordering issues are handled appropriately. -.. _bootloader-get-info: +.. .. _bootloader-get-info: -GET_INFO -"""""""" +.. GET_INFO +.. """""""" -Used to query device characteristics. +.. Used to query device characteristics. -GET_INFO Query: +.. GET_INFO Query: -.. list-table:: - :header-rows: 1 +.. .. list-table:: +.. :header-rows: 1 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - GET_INFO - - 1 - - Value 0 +.. * - GET_INFO +.. - 1 +.. - Value 0 -GET_INFO Response: +.. GET_INFO Response: -.. list-table:: - :header-rows: 1 - :widths: 4 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - GET_INFO - - 1 - - Value 0 +.. * - GET_INFO +.. - 1 +.. - Value 0 - * - Endianness - - 1 - - 0 indicates little-endian, 1 indicates big-endian. - (Currently returns 0; this field allows for future - expansion). +.. * - Endianness +.. - 1 +.. - 0 indicates little-endian, 1 indicates big-endian. +.. (Currently returns 0; this field allows for future +.. expansion). - * - Available Ram - - 4 - - In bytes +.. * - Available Ram +.. - 4 +.. - In bytes - * - Available Flash - - 4 - - In bytes +.. * - Available Flash +.. - 4 +.. - In bytes - * - Flash Page Size - - 2 - - In bytes +.. * - Flash Page Size +.. - 2 +.. - In bytes - * - Starting Address (FLASH) - - 4 - - Usually 0x08005000 +.. * - Starting Address (FLASH) +.. - 4 +.. - Usually 0x08005000 - * - Starting Address (RAM) - - 4 - - Usually 0x200000C0 +.. * - Starting Address (RAM) +.. - 4 +.. - Usually 0x200000C0 - * - Bootloader Version - - 4 - - Current version 0x00060000 (MAJ,MIN) +.. * - Bootloader Version +.. - 4 +.. - Current version 0x00060000 (MAJ,MIN) -.. _bootloader-erase-page: +.. .. _bootloader-erase-page: -ERASE_PAGE -"""""""""" +.. ERASE_PAGE +.. """""""""" -Used to erase flash pages. +.. Used to erase flash pages. -ERASE_PAGE query: +.. ERASE_PAGE query: -.. list-table:: - :header-rows: 1 - :widths: 4 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - ERASE_PAGE - - 1 - - Value 1 +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 - * - ADDRESS - - 4 - - Will erase whichever page contains ADDRESS +.. * - ADDRESS +.. - 4 +.. - Will erase whichever page contains ADDRESS -ERASE_PAGE response: +.. ERASE_PAGE response: -.. list-table:: - :header-rows: 1 - :widths: 3 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 3 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - ERASE_PAGE - - 1 - - Value 1 +.. * - ERASE_PAGE +.. - 1 +.. - Value 1 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success) +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success) -WRITE_BYTES -""""""""""" +.. WRITE_BYTES +.. """"""""""" -Used to write to RAM or flash. +.. Used to write to RAM or flash. -WRITE_BYTES query: +.. WRITE_BYTES query: -.. list-table:: - :header-rows: 1 - :widths: 4 4 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 4 4 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - WRITE_BYTES - - 1 - - Value 2 +.. * - WRITE_BYTES +.. - 1 +.. - Value 2 - * - Starting Address - - 4 - - Can address arbitrary RAM, or :ref:`cleared - <bootloader-erase-page>` flash pages. +.. * - Starting Address +.. - 4 +.. - Can address arbitrary RAM, or :ref:`cleared +.. <bootloader-erase-page>` flash pages. - * - DATA - - MESSAGE_SIZE - 5 - - See :ref:`Packet Structure <bootloader-packet-structure>` +.. * - DATA +.. - MESSAGE_SIZE - 5 +.. - See :ref:`Packet Structure <bootloader-packet-structure>` -WRITE_BYTES response: +.. WRITE_BYTES response: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - WRITE_BYTES - - 1 - - Value 2 +.. * - WRITE_BYTES +.. - 1 +.. - Value 2 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success). Will fail if writes were - made to uncleared pages. Does not clean up failed writes - (memory will be left in an undefined state). +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success). Will fail if writes were +.. made to uncleared pages. Does not clean up failed writes +.. (memory will be left in an undefined state). -READ_BYTES -"""""""""" +.. READ_BYTES +.. """""""""" -Used to read from RAM or flash. +.. Used to read from RAM or flash. -READ_BYTES query: +.. READ_BYTES query: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - READ_BYTES - - 1 - - Value 3 +.. * - READ_BYTES +.. - 1 +.. - Value 3 - * - ADDRESS - - 4 - - Start of block to read. Must be a multiple of 4. +.. * - ADDRESS +.. - 4 +.. - Start of block to read. Must be a multiple of 4. - * - LENGTH - - 2 - - Maximum number of bytes to read (currently, this may be at most - 1024 = 1KB). Must be a multiple of 4. +.. * - LENGTH +.. - 2 +.. - Maximum number of bytes to read (currently, this may be at most +.. 1024 = 1KB). Must be a multiple of 4. -READ_BYTES response: +.. READ_BYTES response: -.. list-table:: - :header-rows: 1 - :widths: 2 2 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 2 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - READ_BYTES - - 1 - - Value 3 +.. * - READ_BYTES +.. - 1 +.. - Value 3 - * - DATA - - MESSAGE_SIZE - 1 - - Contains read bytes. The actual number of bytes read may be - less than the LENGTH field of the corresponding READ_BYTES - query. If this section is of length 0, this should be - interpreted as a read failure. See - :ref:`bootloader-packet-structure`. +.. * - DATA +.. - MESSAGE_SIZE - 1 +.. - Contains read bytes. The actual number of bytes read may be +.. less than the LENGTH field of the corresponding READ_BYTES +.. query. If this section is of length 0, this should be +.. interpreted as a read failure. See +.. :ref:`bootloader-packet-structure`. -JUMP_TO_USER -"""""""""""" +.. JUMP_TO_USER +.. """""""""""" -Causes the bootloader to jump to user code's starting address. +.. Causes the bootloader to jump to user code's starting address. -JUMP_TO_USER query: +.. JUMP_TO_USER query: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - JUMP_TO_USER - - 1 - - Value 4 +.. * - JUMP_TO_USER +.. - 1 +.. - Value 4 - * - Location - - 1 - - 0 means jump to flash starting address, 1 means jump to RAM - starting address. See the :ref:`bootloader-get-info` command - for more information. +.. * - Location +.. - 1 +.. - 0 means jump to flash starting address, 1 means jump to RAM +.. starting address. See the :ref:`bootloader-get-info` command +.. for more information. -JUMP_TO_USER response: +.. JUMP_TO_USER response: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - JUMP_TO_USER - - 1 - - Value 4 +.. * - JUMP_TO_USER +.. - 1 +.. - Value 4 - * - SUCCESS - - 1 - - Either 0 (failure) or 1 (success). If successful, after the - response is sent, the bootloader ends this session and jumps to - the user code in flash or RAM as specified in the query's - Location field. +.. * - SUCCESS +.. - 1 +.. - Either 0 (failure) or 1 (success). If successful, after the +.. response is sent, the bootloader ends this session and jumps to +.. the user code in flash or RAM as specified in the query's +.. Location field. -SOFT_RESET -"""""""""" +.. SOFT_RESET +.. """""""""" -Engages a full software reset. +.. Engages a full software reset. -SOFT_RESET query: +.. SOFT_RESET query: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - SOFT_RESET - - 1 - - Value 5 +.. * - SOFT_RESET +.. - 1 +.. - Value 5 -SOFT_RESET response: +.. SOFT_RESET response: -.. list-table:: - :header-rows: 1 - :widths: 2 1 10 +.. .. list-table:: +.. :header-rows: 1 +.. :widths: 2 1 10 - * - Field - - Bytes - - Comments +.. * - Field +.. - Bytes +.. - Comments - * - SOFT_RESET - - 1 - - Value 5 +.. * - SOFT_RESET +.. - 1 +.. - Value 5 - * - SUCCESS - - 1 - - Either 0 or 1 (FAILED and OK, respectively). Will end this - bootloader session and reset the processor. +.. * - SUCCESS +.. - 1 +.. - Either 0 or 1 (FAILED and OK, respectively). Will end this +.. bootloader session and reset the processor. .. _bootloader-reflashing: diff --git a/docs/source/compatibility.rst b/docs/source/compatibility.rst index a070b42..848a3d3 100644 --- a/docs/source/compatibility.rst +++ b/docs/source/compatibility.rst @@ -119,8 +119,6 @@ differences, most of which are improvements: Shield and Device Compatibility ------------------------------- -.. TODO update for 0.0.9 - .. list-table:: :header-rows: 1 @@ -134,7 +132,7 @@ Shield and Device Compatibility * - WiFi Shield - Yes! - - Tested; no library yet (expected for 0.0.9) + - Tested; preliminary library support * - MIDI shield - Yes! @@ -146,7 +144,8 @@ Shield and Device Compatibility * - Bluetooth shield - Unknown - - + - Some Bluetooth <-> UART boards have been tested and are known + to work. * - Cellular shield - Unknown @@ -158,11 +157,12 @@ Library Porting Status The state of currently ported Arduino libraries is the :ref:`libraries`. -.. TODO update for 0.0.9; update as libraries are ported. +.. TODO Update as libraries are ported. .. list-table:: :header-rows: 1 + * - Library - Ported? - Notes @@ -180,9 +180,11 @@ The state of currently ported Arduino libraries is the - Planned * - EEPROM - - No - - The Maple doesn't have EEPROM; use flash instead. Perhaps this - library could be emulated? + - (Unsupported) third-party emulation + - The Maple doesn't have EEPROM; it uses flash instead. There is + an `EEPROM emulation library + <http://akb77.com/g/mcu/maple-eeprom-emulation-library/>`_ by + `x893 <http://akb77.com/g/>`_, but we haven't tested it. * - Firmata - Not yet @@ -192,6 +194,10 @@ The state of currently ported Arduino libraries is the - Not yet - Planned + * - Servo + - **Yes** + - :ref:`Included since IDE 0.0.9 <libraries-servo>` + * - SoftwareSerial - Not yet - Planned diff --git a/docs/source/cpp.rst b/docs/source/cpp.rst deleted file mode 100644 index a20578e..0000000 --- a/docs/source/cpp.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _cpp: - -============== -C++ for Maple -============== - -.. _index-language-index-cpp-index: - -.. toctree:: - :maxdepth: 1 - :glob: - - lang/cpp/*
\ No newline at end of file diff --git a/docs/source/external-interrupts.rst b/docs/source/external-interrupts.rst index 79492ef..5187ca4 100644 --- a/docs/source/external-interrupts.rst +++ b/docs/source/external-interrupts.rst @@ -121,6 +121,5 @@ Recommended Reading * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst index ee2b6eb..4017862 100644 --- a/docs/source/gpio.rst +++ b/docs/source/gpio.rst @@ -14,9 +14,9 @@ peripheral functions. This page documents those capabilities, by pin. The current and voltage limitations have not been copied over from the STM32 datasheet (see the :ref:`Recommended Reading <gpio-recommended-reading>` for a link). In particular, a number of -GPIO pins are 5v tolerant (which means that applying 5v to a pin and -reading it as input or allowing it to drain to ground will not damage -that pin), while some are not. +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. .. contents:: Contents :local: @@ -26,11 +26,10 @@ that pin), while some are not. Pin Mapping Mega Table ---------------------- -This huge reference 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 5v tolerant (see -above). +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). .. csv-table:: :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?" @@ -99,6 +98,5 @@ Recommended Reading STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/home.rst b/docs/source/home.rst deleted file mode 100644 index db5b56e..0000000 --- a/docs/source/home.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _home: - -======================== -Maple Documentation Home -======================== - - -Welcome! - -Maple is a user-friendly prototyping platform developed by LeafLabs in Cambridge, MA. Using Maple, creators with any level of experience can implement beautiful ideas that require the power of a 32-bit processor. For more details about Maple's hardware, please see its :ref:`technical specifications <specs>`. To start using your Maple, keep reading - -.. _home-Getting-Started: - -Getting Started -^^^^^^^^^^^^^^^ - -:ref:`Quickstart <maple-quickstart>` - -:ref:`IDE Anatomy <ide>` - -:ref:`Basic Language Reference <language>` - -:ref:`Tech Specs<specs>` - -.. _home-Problem-Solving: - -Problem Solving -^^^^^^^^^^^^^^^ - -Check out our :ref:`troubleshooting <troubleshooting>` and :ref:`known problems<errata>` pages. - -If you don't find what you're looking for, hit the `forums <http://forums.leaflabs.com/>`_ to ask the LeafLabs team and other Maple users questions. Good luck, and have fun! diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst index 6e5b946..b4a996b 100644 --- a/docs/source/i2c.rst +++ b/docs/source/i2c.rst @@ -80,7 +80,6 @@ Recommended Reading * `Arduino i2c/TWI reference <http://www.arduino.cc/playground/Learning/I2C>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) * `Application Note on Advanced I2C Usage diff --git a/docs/source/index.rst b/docs/source/index.rst index c552dd4..825ec81 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,15 @@ .. _index: Maple Documentation Contents -============================= +============================ + +Welcome! This is the Maple documentation index. If you just bought a +Maple, you probably want to head to the :ref:`quickstart +<maple-quickstart>`. If you're having problems, check out the +:ref:`troubleshooting <troubleshooting>` and :ref:`known problems +<errata>` pages. + +Have fun! .. _index-usage: @@ -15,7 +23,7 @@ Maple Documentation Contents IDE Anatomy <ide> .. _index-maple-programming: - + **Maple Programming:** .. toctree:: @@ -29,7 +37,7 @@ Maple Documentation Contents Bootloader <bootloader> - Troubleshooting <troubleshooting> + Troubleshooting <troubleshooting> Known Problems <errata> .. _index-hardware: @@ -38,7 +46,7 @@ Maple Documentation Contents .. toctree:: :maxdepth: 1 - + i2c pwm gpio @@ -55,8 +63,8 @@ Maple Documentation Contents .. toctree:: :maxdepth: 1 - + Technical Specifications <specs> Complete Language Index <language-index> - + diff --git a/docs/source/jtag.rst b/docs/source/jtag.rst index 7cfba5f..e3c8111 100644 --- a/docs/source/jtag.rst +++ b/docs/source/jtag.rst @@ -15,24 +15,24 @@ and hardware peripherals (we use it when working on :ref:`libmaple Note that the STM32 on the Maple has a built-in low level serial debugger which could also be used to flash bootloaders, and that the :ref:`ASSERT <language-assert>` framework allows basic debugging over -a USART serial channel. We expect only advanced users to use this -feature. +a USART serial channel. We expect only fairly advanced users to use +this feature. .. contents:: Contents :local: - Wiring Diagram -------------- .. figure:: /_static/img/jtag-wiring.png :align: center :alt: JTAG wiring diagram + :width: 7.4in - JTAG wiring diagram to connect a standard 20-pin ARM JTAG device to - the 8-pin JTAG port on the Maple. - -.. FIXME jtag wiring diagram (above) looks terrible; replace it + JTAG wiring diagram (`large version + <http://leaflabs.com/wp-content/uploads/2010/11/maple-jtagadapter.png>`_) + to connect a standard 20-pin ARM JTAG device to the 8-pin JTAG port + on the Maple. The Maple has holes for a 8-pin JTAG header but that header is not soldered on by default. If you know ahead of time that you'll be @@ -42,14 +42,7 @@ probably solder one on for no charge. Otherwise, you can simply attach standard 0.1" pitch male header pins (either the exact 4x2 block or two 4-pin pieces of breakaway straight header). For a one-off usage hack, the header can be jammed in the holes and twisted to -ensure electrical contact; this is what we do to flash our bootloader. - -The above schematic assumes that the header has been soldered on to -the *bottom* of the board, not the top; most ribbon cable connectors -will interfere with the power header. If you don't want a header -coming off the bottom, you can use a slim connector and invert this -diagram appropriately. - +ensure electrical contact. Compatible Devices ------------------ @@ -65,6 +58,8 @@ Recommended Reading * `STM32/gdb/OpenOCD HOWTO <http://fun-tech.se/stm32/OpenOCD/gdb.php>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) +* There's a `thread on JTAG + <http://forums.leaflabs.com/topic.php?id=536>`_ in our `forum`_ + which you may find useful. diff --git a/docs/source/lang/api/analogread.rst b/docs/source/lang/api/analogread.rst index c614aca..35c6fbc 100644 --- a/docs/source/lang/api/analogread.rst +++ b/docs/source/lang/api/analogread.rst @@ -32,11 +32,6 @@ 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`\ ). -It takes about 0.8 microseconds (.0000008 seconds) to read an analog -input, so the maximum sample rate using this function is approximately -1.3 million samples per second\ [#fsamp]_. - - Parameter Discussion -------------------- @@ -115,40 +110,10 @@ Some basic tools to accomplish this are `resistor dividers . However, opamps and other powered components can also be used if greater precision is required. -Finally, On the Arduino, it takes significantly longer to read analog -input: about 100 microseconds (0.0001 s), so the maximum reading rate -is 10,000 times a second. - - See also -------- - :ref:`ADC note <adc>` - `(Arduino) Tutorial: Analog Input Pins <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ - -.. rubric:: Footnotes - -.. [#fsamp] This is based on the current configuration of a 55.5 cycle - sample time, at 72 MHz. However, the minimum sample time *possible* - is 1.5 cycles, leading to a theoretical maximum of approximately 48 - million samples per second (of course, doing anything with the - readings also consumes cycles, so this maximum can't be reached in - practice). - - See the `STM32 Reference Manual <full-manual>`_, §§11.12.4--5 - (pp. 225--226), for more information on the low-level bit twiddling - currently necessary to change the sample time. For examples of how - the ADCs are configured in libmaple, see `adc.h - <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.h>`_ - and `adc.c - <http://github.com/leaflabs/libmaple/blob/master/libmaple/adc.c>`_\ - . Be aware that changing the sample time has important - consequences related to the impedance of the device connected to - the input pin. If you want to make changes, as a minimum, you - should first read ST's application notes on `ADC modes - <stm32-adc-modes>`_ and `ADC oversampling - <stm32-adc-oversampling>`_. - - .. include:: cc-attribution.txt diff --git a/docs/source/lang/api/analogwrite.rst b/docs/source/lang/api/analogwrite.rst index 01820ef..9147b96 100644 --- a/docs/source/lang/api/analogwrite.rst +++ b/docs/source/lang/api/analogwrite.rst @@ -11,19 +11,18 @@ analogWrite() .. note:: On the Maple, calling analogWrite() is the same as calling - :ref:`lang-pwmwrite`\ ; see that function's documentation for more - information. + :ref:`lang-pwmwrite`\ ; we recommend using that function directly + instead. This is because PWM is not true analog output (i.e., is not the output of a `DAC <http://en.wikipedia.org/wiki/Digital-to-analog_converter>`_\ ), so - the function is badly named. For instance, **analogWrite() has + the function is badly named. For instance, analogWrite() **has absolutely nothing to do with** :ref:`lang-analogread`\ , which is potentially confusing. - The alias of analogWrite() to pwmWrite() is provided (sigh) for the - sake of compatibility with Arduino, but we recommend using - :ref:`lang-pwmwrite` when writing new software, for clarity. + The alias of analogWrite() to pwmWrite() is provided for the sake + of compatibility with Arduino only. .. contents:: Contents :local: @@ -97,23 +96,21 @@ Difference 3: No PWM on pin 10 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ On the Maple, the pins which support PWM are: 0, 1, 2, 3, 5, 6, 7, 8, -9, 11, 12, and 14, or twelve pins in total. That is at least as -*many* PWM pins as any Arduino board, but there are differences in -*which* pins support it. +9, 11, 12, 14, 24, 27, and 28 or fifteen pins in total. That's *more* +PWM-capable pins as any Arduino board, but there are differences in +*which* pins support PWM. * On **most Arduino boards** (those with the ATmega168 or ATmega328; this includes the **Arduino Uno**), this function works on pins 3, 5, 6, 9, 10, and 11, or six pins total. Note that these boards support PWM on pin 10, while Maple does not. -* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve pins - total. Note that this board supports PWM on pins 4, 10, and 13, - while the Maple does not. Maple supports PWM on pins 0, 1, and 14, - which the Mega does not, making the total number of pins supporting - PWM equal on these boards. +* On the **Arduino Mega**, PWM works on pins 2 through 13, or twelve + pins total. Note that this board supports PWM on pins 4, 10, and + 13, while the Maple does not. -* **Older Arduino boards** with an ATmega8 only support analogWrite() on - pins 9, 10, and 11. Maple does not support PWM on pin 10. +* **Older Arduino boards** with an ATmega8 only support analogWrite() + on pins 9, 10, and 11. Maple does not support PWM on pin 10. In all cases, Arduino boards support PWM on pin 10, unlike Maple. We did our best to make PWM as pin-compatible as possible; however, @@ -125,7 +122,8 @@ work on any Arduino board and on Maple. The "safe" pins, which work on most recent Arduino boards, the Arduino Mega and the Maple, are pins 3, 5, 6, 9, and 11. Thus, if you want your project to be as portable as possible between Maple and Arduino, we recommend using the -"safest" pins first, then the "safe" pins, as necessary. +"safest" pins first, then the "safe" pins, then any other pins, as +necessary. Difference 4: PWM frequency ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -138,17 +136,23 @@ Hz, or 1.1 KHz. This is because the PWM frequency is the frequency of the timer which controls PWM output on the particular pin (\ :ref:`the PWM tutorial has the details <pwm>`\ ). -If your application absolutely requires Arduino's PWM frequency (it -probably doesn't), then the steps are: +If your application definitely requires Arduino's PWM frequency, then +the steps are: -1. Figure out which timer controls PWM output on your pin (\ :ref:`this table <pwm-timer-table>` is your friend here). Let's say it's ``Timern``\ , where ``n`` is some number 1, 2, 3, or 4. +1. Figure out which :ref:`timer <lang-hardwaretimer>` controls PWM + output on your pin (\ :ref:`this table <pwm-timer-table>` is your + friend here). Let's say it's ``Timern``\ , where ``n`` is some + number 1, 2, 3, or 4. -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. Call ``Timern.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. One example is :ref:`interrupts <timers-attachinterrupt>`\ . -You've been :ref:`warned <timers-pwm-conflicts>`\ . +timer. The important examples are :ref:`timer interrupts +<lang-hardwaretimer-attachinterrupt>` and :ref:`PWM +<timers-pwm-conflicts>`\ . See also -------- diff --git a/docs/source/lang/api/constants.rst b/docs/source/lang/api/constants.rst index bc5c894..4426293 100644 --- a/docs/source/lang/api/constants.rst +++ b/docs/source/lang/api/constants.rst @@ -288,6 +288,29 @@ exponent indicators. Some examples are given in the following table: - 67.0×10\ :sup:`-12` - ``0.000000000067`` +.. _lang-constants-board: + +Board-Specific Constants +------------------------ + +This section documents constants whose value might change across +different LeafLabs boards. You can use these constants to help ensure +that your code will be portable across different boards. + +.. TODO replace "upcoming" when Mini, Native come out + +.. _lang-constants-led: + +- ``BOARD_LED_PIN``: the number of the pin which connects to the + built-in LED. On the Maple, this is pin 13, but it's not guaranteed + to be the same in upcoming boards like the Maple Mini. + +.. _lang-constants-but: + +- ``BOARD_BUTTON_PIN``: the number of the pin which connects to the + built-in button (labeled "BUT"). On the Maple, this is pin 38, but + it's not guaranteed to be the same in other boards. + See Also -------- diff --git a/docs/source/lang/api/hardwarespi.rst b/docs/source/lang/api/hardwarespi.rst new file mode 100644 index 0000000..c71b2c3 --- /dev/null +++ b/docs/source/lang/api/hardwarespi.rst @@ -0,0 +1,152 @@ +.. highlight:: cpp + +.. _lang-hardwarespi: + +HardwareSPI +=========== + +This class is used for creating objects to manage the Maple's built-in +SPI ports. The Maple has two SPI ports. The relevant pins +corresponding to each port's logic signals are documented in the +following table (and on the Maple silkscreen): + +.. _lang-hardwarespi-pinout: + +.. list-table:: + :header-rows: 1 + + * - Port number + - NSS + - MOSI + - MISO + - SCK + + * - 1 + - 10 + - 11 + - 12 + - 13 + + * - 2 + - 31 + - 32 + - 33 + - 34 + +If you use a SPI port, you cannot simultaneously use its associated +pins for other purposes. + +Library Documentation +--------------------- + +HardwareSPI Class Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can use the SPI interface by including a declaration ``HardwareSPI +Spi(number);`` at the start of the sketch or program. The ``number`` +must be either 1 or 2 and specifies which port to use. Once this is +done, you can call any of the methods documented here using +``Spi.method(arguments)``; for example, ``Spi.send(0x13)`` would send +the value ``0x13`` into the port buffer to be transmitted as soon as +possible. + +.. cpp:class:: HardwareSPI + + Class for interacting with SPI. + +.. cpp:function:: HardwareSPI::HardwareSPI(uint32 spi_num) + + Construct an object for managing a SPI peripheral. ``spi_num`` + must be 1 or 2; see the :ref:`table above + <lang-hardwarespi-pinout>` for pinout information. + +.. cpp:function:: void HardwareSPI::begin(SPIFrequency freq, uint32 endianness, uint32 mode) + + Configure the baudrate of the given SPI port and set up the header + pins appropriately. + + Parameters: + + - ``freq``: one of the ``SPIFrequency`` values, given :ref:`below + <lang-hardwarespi-spifrequency>`. + + - ``endianness``: either ``LSBFIRST`` (little-endian) or + ``MSBFIRST`` (big-endian). + + - ``mode``: one of 0, 1, 2, or 3, and specifies which SPI mode is + used. The mode number determines a combination of polarity and + phase according to the following table: + + .. list-table:: + :header-rows: 1 + + * - Mode + - Polarity + - Phase + + * - 0 + - 0 + - 0 + + * - 1 + - 0 + - 1 + + * - 2 + - 1 + - 0 + + * - 3 + - 1 + - 1 + + For more information on polarity and phase, see the + :ref:`external references, below <lang-hardwarespi-seealso>`. + +.. cpp:function:: void HardwareSPI::begin() + + A convenience ``begin()``, equivalent to ``begin(SPI_1_125MHZ, + MSBFIRST, 0)``. + +.. cpp:function:: uint8 HardwareSpi::send(uint8 *data, uint32 length) + + Writes ``data`` into the port buffer to be transmitted as soon as + possible, where ``length`` is the number of bytes to send from + ``data``. Returns the last byte shifted back from slave. + +.. cpp:function:: uint8 HardwareSpi::send(uint8 data) + + Writes the single byte ``data`` into the port buffer to be + transmitted as soon as possible. Returns the data byte shifted + back from the slave. + +.. cpp:function:: uint8 HardwareSpi::recv() + + Reads a byte from the peripheral. Returns the next byte in the + buffer. + +SPI Speeds +^^^^^^^^^^ + +.. _lang-hardwarespi-spifrequency: + +The possible SPI speeds are configured using the ``SPIFrequency`` enum: + +.. doxygenenum:: SPIFrequency + +.. _lang-hardwarespi-seealso: + +See Also +-------- + +* `Wikipedia Article on Serial Peripheral Interface Bus (SPI) + <http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus>`_ +* `Arduino reference on SPI + <http://www.arduino.cc/playground/Code/Spi>`_ +* `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64 +* STMicro documentation for STM32F103RB microcontroller: + + * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) + * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) + + diff --git a/docs/source/lang/api/hardwaretimer.rst b/docs/source/lang/api/hardwaretimer.rst new file mode 100644 index 0000000..258471b --- /dev/null +++ b/docs/source/lang/api/hardwaretimer.rst @@ -0,0 +1,368 @@ +.. highlight:: cpp + +.. _lang-hardwaretimer: + +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 +<timers>`. + +Library Documentation +--------------------- + +HardwareTimer Class Reference +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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)``. + +.. cpp:class:: HardwareTimer + + Class for interacting with a timer. There are four predefined + instances available on the Maple: ``Timer1``, ``Timer2``, + ``Timer3``, and ``Timer4``. + +.. _lang-hardwaretimer-attachinterrupt: + +.. cpp:function:: void HardwareTimer::attachInterrupt(int channel, voidFuncPtr handler) + + 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 <lang-hardwaretimer-setcompare>` + value. + + ``handler`` should be a function which takes no arguments and has + :ref:`void <lang-void>` value; i.e. it should have signature :: + + void handler(void); + + You can later detach the interrupt using :ref:`detachInterrupt() + <lang-hardwaretimer-detachinterrupt>`. + + .. note:: The function (often called an *interrupt service + routine*, or ISR) should attempt to return as quickly as + possible. :ref:`Blinking the LED <lang-toggleled>`, some + logic, :ref:`PWM <pwm>` updates, and :ref:`Serial + <lang-serial>` writes are fine; writing to + :ref:`SerialUSB <lang-serialusb>` or :ref:`waiting + <lang-waitforbuttonpress>` for user input can take a long + time and prevent other interrupts from firing on time. + + Tip: if you have a :ref:`delay() <lang-delay>` in your + ISR, you're probably doing it wrong. + +.. cpp:function:: void HardwareTimer::attachCompare1Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + <lang-hardwaretimer-attachinterrupt>`\ ``(1, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare2Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + <lang-hardwaretimer-attachinterrupt>`\ ``(2, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare3Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + <lang-hardwaretimer-attachinterrupt>`\ ``(3, handler)``. + +.. cpp:function:: void HardwareTimer::attachCompare4Interrupt(voidFuncPtr handler) + + Equivalent to :ref:`attachInterrupt + <lang-hardwaretimer-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 + <lang-hardwaretimer-modes>`. The parameter ``channel`` is one of + 1, 2, 3, and 4, and corresponds to the compare channel you would + like to set. Refer to the full :ref:`pin mapping table + <pin-mapping-mega-table>` to match up timer channels and pin + numbers. + +.. cpp:function:: void HardwareTimer::setChannel1Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\ + ``(1, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel2Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\ + ``(2, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel3Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode <lang-hardwaretimer-setchannelmode>`\ + ``(3, mode)``. + +.. cpp:function:: void HardwareTimer::setChannel4Mode(TimerMode mode) + + Equivalent to :ref:`setChannelMode <lang-hardwaretimer-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() <lang-hardwaretimer-setcompare>`. + +.. cpp:function:: uint16 HardwareTimer::getCompare1() + + Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\ + ``(1, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare2() + + Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\ + ``(2, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare3() + + Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\ + ``(3, mode)``. + +.. cpp:function:: uint16 HardwareTimer::getCompare4() + + Equivalent to :ref:`getCompare <lang-hardwaretimer-getcompare>`\ + ``(4, mode)``. + +.. _lang-hardwaretimer-setcompare: + +.. cpp:function:: void HardwareTimer::setCompare(int channel, uint16 compare) + + 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). + + When the counter reaches this value the interrupt for this channel + will fire if the given ``channel`` :ref:`mode + <lang-hardwaretimer-setchannelmode>` is ``TIMER_OUTPUTCOMPARE`` and + an interrupt is :ref:`attached + <lang-hardwaretimer-attachinterrupt>`. + + 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. + +.. cpp:function:: void HardwareTimer::setCompare1(uint16 compare) + + Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\ + ``(1, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare2(uint16 compare) + + Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\ + ``(2, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare3(uint16 compare) + + Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\ + ``(3, compare)``. + +.. cpp:function:: void HardwareTimer::setCompare4(uint16 compare) + + Equivalent to :ref:`setCompare <lang-hardwaretimer-setcompare>`\ + ``(4, compare)``. + +.. cpp:function:: uint16 HardwareTimer::getCount() + + 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() <lang-hardwaretimer-setcount>`. + +.. _lang-hardwaretimer-setcount: + +.. cpp:function:: void HardwareTimer::setCount(uint16 val) + + Set the timer's current count to ``val``. + + 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. + + If ``val`` exceeds the timer's :ref:`overflow value + <lang-hardwaretimer-getoverflow>`, it is truncated to the overflow + value. + + +.. _lang-hardwaretimer-detachinterrupt: + +.. cpp:function:: void HardwareTimer::detachInterrupt(int channel) + + Remove the interrupt handler attached to the given ``channel``, if + any. The handler will no longer be called by this timer. + +.. cpp:function:: void HardwareTimer::detachCompare1Interrupt() + + Equivalent to :ref:`detachInterrupt + <lang-hardwaretimer-detachinterrupt>`\ ``(1)``. + +.. cpp:function:: void HardwareTimer::detachCompare2Interrupt() + + Equivalent to :ref:`detachInterrupt + <lang-hardwaretimer-detachinterrupt>`\ ``(2)``. + +.. cpp:function:: void HardwareTimer::detachCompare3Interrupt() + + Equivalent to :ref:`detachInterrupt + <lang-hardwaretimer-detachinterrupt>`\ ``(3)``. + +.. cpp:function:: void HardwareTimer::detachCompare4Interrupt() + + Equivalent to :ref:`detachInterrupt + <lang-hardwaretimer-detachinterrupt>`\ ``(4)``. + +.. _lang-hardwaretimer-generateupdate: + +.. cpp:function:: void HardwareTimer::generateUpdate() + + Re-initializes the counter (to 0 in upcounting mode, which is the + default), and generates an update of the prescale and overflow + registers. + +.. _lang-hardwaretimer-getoverflow: + +.. cpp:function:: uint16 HardwareTimer::getOverflow() + + Gets the timer's overflow value. See :ref:`setOverflow() + <lang-hardwaretimer-setoverflow>`. + +.. _lang-hardwaretimer-setoverflow: + +.. cpp:function:: void HardwareTimer::setOverflow(uint16 val) + + Sets the timer overflow (or "reload") value to ``val``. + + 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() + <lang-hardwaretimer-setperiod>` function for a shortcut). + + After the next :ref:`timer update + <lang-hardwaretimer-generateupdate>`, this number will be the + maximum value for the timer's channel compare values. + +.. _lang-hardwaretimer-pause: + +.. cpp:function:: void HardwareTimer::pause() + + Stop the timer's 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 :ref:`resume() + <lang-hardwaretimer-resume>` is not a robust way to align multiple + timers to the same count value. + +.. _lang-hardwaretimer-setperiod: + +.. cpp:function:: uint16 HardwareTimer::setPeriod(uint32 microseconds) + + Configure the :ref:`prescaler + <lang-hardwaretimer-getprescalefactor>` and :ref:`overflow + <lang-hardwaretimer-getoverflow>` values to generate a timer reload + with a period as close to the given number of ``microseconds`` as + possible. + + 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. + +.. _lang-hardwaretimer-getprescalefactor: + +.. cpp:function:: uint16 HardwareTimer::getPrescaleFactor() + + Returns the timer's prescale factor. See + :ref:`setPrescaleFactor() <lang-hardwaretimer-setprescalefactor>`. + +.. _lang-hardwaretimer-setprescalefactor: + +.. cpp:function:: void HardwareTimer::setPrescaleFactor(uint16 factor) + + Set the timer's prescale factor to ``factor``. + + The prescaler acts as a clock divider to slow down the rate at + which the counter increments. + + 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. + + The :ref:`setPeriod() <lang-hardwaretimer-setperiod>` method may + also be used as a convenient alternative. + +.. cpp:function:: void HardwareTimer::resume() + + Resume a paused timer, without affecting its configuration. + + The timer will resume counting and firing interrupts as + appropriate. + + Note that there is some function call overhead associated with + using this method, so using it in concert with :ref:`pause() + <lang-hardwaretimer-pause>` is not a robust way to align multiple + timers to the same count value. + +.. cpp:function:: timer_dev_num HardwareTimer::getTimerNum() + + Returns the :ref:`timer device number + <lang-hardwaretimer-timer-dev-num>` associated with the timer. For + example, ``Timer1.getTimerNum()`` would return ``TIMER1``. + + 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. + +.. _lang-hardwaretimer-modes: + +Timer Modes +^^^^^^^^^^^ +.. doxygenenum:: TimerMode + +.. _lang-hardwaretimer-timer-dev-num: + +Timer Device Numbers +^^^^^^^^^^^^^^^^^^^^ + +These provide a lower-level interface for interacting with timers. +They are mostly useful in context with the :ref:`getTimer() +<lang-hardwaretimer-gettimer>` function. **Be careful** when using +these not to confuse e.g. ``TIMER1`` with the number 1; they are +different. + +.. doxygenenum:: timer_dev_num + +.. _lang-hardwaretimer-convenience: + +.. _lang-hardwaretimer-gettimer: + +Other Functions +^^^^^^^^^^^^^^^ +.. doxygenfunction:: getTimer diff --git a/docs/source/lang/api/interrupts.rst b/docs/source/lang/api/interrupts.rst new file mode 100644 index 0000000..58fd2cc --- /dev/null +++ b/docs/source/lang/api/interrupts.rst @@ -0,0 +1,47 @@ +.. highlight:: cpp + +.. _lang-interrupts: + +interrupts() +============ + +Re-enables interrupts (after they've been disabled by +:ref:`noInterrupts() <lang-nointerrupts>`). Interrupts allow certain +important tasks to happen in the background, and certain interrupts +are enabled by default. + +Some functions will not work while interrupts are disabled, and both +incoming and outgoing communication may be ignored. Interrupts can +slightly disrupt the timing of code, however, and may be disabled for +particularly critical sections of code. + +Library Documentation +--------------------- + +.. doxygenfunction:: interrupts + +Example +------- + +:: + + void setup() {} + + void loop() { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + +See Also +-------- + +- :ref:`noInterrupts() <lang-nointerrupts>` +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` +- :ref:`Timers reference <timers>` +- :ref:`Timer API <lang-hardwaretimer>` +- :ref:`External interrupts <external-interrupts>` + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/api/isbuttonpressed.rst b/docs/source/lang/api/isbuttonpressed.rst new file mode 100644 index 0000000..dbff0c9 --- /dev/null +++ b/docs/source/lang/api/isbuttonpressed.rst @@ -0,0 +1,17 @@ +.. _lang-isbuttonpressed: + +isButtonPressed() +================= + +Check whether the board's built-in button (labeled BUT on the +silkscreen) is pressed. + +Library Documentation +--------------------- + +.. doxygenfunction:: isButtonPressed + +See Also +-------- + +- :ref:`lang-waitforbuttonpress` diff --git a/docs/source/lang/api/nointerrupts.rst b/docs/source/lang/api/nointerrupts.rst new file mode 100644 index 0000000..68f0498 --- /dev/null +++ b/docs/source/lang/api/nointerrupts.rst @@ -0,0 +1,47 @@ +.. highlight:: cpp + +.. _lang-nointerrupts: + +noInterrupts() +============== + +Description +----------- + +Disables interrupts. Interrupts allow certain important tasks to +happen in the background and are enabled by default. Some functions +will not work while interrupts are disabled, and incoming +communication may be ignored. Interrupts can slightly disrupt the +timing of code, however, and may be disabled for particularly critical +sections of code. + +Library Documentation +--------------------- + +.. doxygenfunction:: noInterrupts + +Example +------- + +:: + + void setup() {} + + void loop() { + noInterrupts(); + // critical, time-sensitive code here + interrupts(); + // other code here + } + +See Also +-------- + +- :ref:`interrupts() <lang-interrupts>` +- :ref:`attachInterrupt() <lang-attachinterrupt>` +- :ref:`detachInterrupt() <lang-detachinterrupt>` +- :ref:`Timers reference <timers>` +- :ref:`Timer API <lang-hardwaretimer>` +- :ref:`External interrupts <external-interrupts>` + +.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/api/pinmode.rst b/docs/source/lang/api/pinmode.rst index b9095da..03cbcfa 100644 --- a/docs/source/lang/api/pinmode.rst +++ b/docs/source/lang/api/pinmode.rst @@ -13,6 +13,8 @@ Library Documentation .. doxygenfunction:: pinMode +.. _lang-pinmode-wiringpinmode: + .. doxygenenum:: WiringPinMode Discussion diff --git a/docs/source/lang/api/pwmwrite.rst b/docs/source/lang/api/pwmwrite.rst index 7a1d51f..2c858ab 100644 --- a/docs/source/lang/api/pwmwrite.rst +++ b/docs/source/lang/api/pwmwrite.rst @@ -11,6 +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. +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 Arduino function :ref:`analogWrite() <lang-analogwrite>` is an +alias for ``pwmWrite()``, but it is badly named, and its use is +discouraged. + .. contents:: Contents :local: @@ -25,12 +32,11 @@ Example Sets the output to the LED proportional to the value read from the potentiometer:: - int ledPin = 13; // LED connected to pin 13 (Maple) int analogPin = 3; // potentiometer connected to analog pin 3 int val = 0; // variable to store the read value void setup() { - pinMode(ledPin, OUTPUT); // sets the LED pin as output + pinMode(BOARD_LED_PIN, OUTPUT); // sets the LED pin as output pinMode(analogPin, PWM); // sets the potentiometer pin as PWM // output @@ -39,8 +45,9 @@ potentiometer:: void loop() { val = analogRead(analogPin); // read the input pin - analogWrite(ledPin, val / 16); // analogRead values go from 0 to 4095, - // analogWrite values from 0 to 65535 + analogWrite(BOARD_LED_PIN, val / 16); // analogRead values go from 0 + // to 4095, analogWrite values + // from 0 to 65535 } See Also diff --git a/docs/source/lang/api/serialusb.rst b/docs/source/lang/api/serialusb.rst index af3a7e0..e1d12bf 100644 --- a/docs/source/lang/api/serialusb.rst +++ b/docs/source/lang/api/serialusb.rst @@ -52,7 +52,9 @@ world!")``. .. cpp:class:: USBSerial Emulated serial-over-USB class. ``SerialUSB`` is the predefined - instance. + (singleton) instance. + +.. _lang-serialusb-begin: .. cpp:function:: USBSerial::begin() @@ -65,7 +67,12 @@ world!")``. .. cpp:function:: USBSerial::end() - Disables the USB peripheral. + Disables the USB peripheral. Note that using this function will + terminate all USB communications between the Maple and the USB + host; in particular, it implies that you won't be able to upload + any new programs without resetting the board or using + :ref:`perpetual bootloader mode + <troubleshooting-perpetual-bootloader>`. .. cpp:function:: unsigned int USBSerial::available() diff --git a/docs/source/lang/api/toggleled.rst b/docs/source/lang/api/toggleled.rst new file mode 100644 index 0000000..0cc20c2 --- /dev/null +++ b/docs/source/lang/api/toggleled.rst @@ -0,0 +1,17 @@ +.. _lang-toggleled: + +toggleLED() +=========== + +Switches the LED from off to on, or on to off. + +Library Documentation +--------------------- + +.. doxygenfunction:: toggleLED + +See Also +-------- + +- :ref:`BOARD_LED_PIN <lang-constants-led>` +- :ref:`togglePin() <lang-togglepin>` diff --git a/docs/source/lang/api/togglepin.rst b/docs/source/lang/api/togglepin.rst new file mode 100644 index 0000000..290718d --- /dev/null +++ b/docs/source/lang/api/togglepin.rst @@ -0,0 +1,17 @@ +.. _lang-togglepin: + +togglePin() +=========== + +Switches a digital output pin from :ref:`HIGH <lang-constants-high>` +to :ref:`LOW <lang-constants-low>`, or from LOW to HIGH. + +Library Documentation +--------------------- + +.. doxygenfunction:: togglePin + +See Also +-------- + +- :ref:`toggleLED() <lang-toggleled>` diff --git a/docs/source/lang/api/waitforbuttonpress.rst b/docs/source/lang/api/waitforbuttonpress.rst new file mode 100644 index 0000000..34c5066 --- /dev/null +++ b/docs/source/lang/api/waitforbuttonpress.rst @@ -0,0 +1,17 @@ +.. _lang-waitforbuttonpress: + +waitForButtonPress() +==================== + +Wait for the board's built-in button (labeled BUT on the silkscreen) +to be pressed, possibly with timeout. + +Library Documentation +--------------------- + +.. doxygenfunction:: waitForButtonPress + +See Also +-------- + +- :ref:`lang-isbuttonpressed` diff --git a/docs/source/lang/cpp/numeric-types.rst b/docs/source/lang/cpp/built-in-types.rst index 9d2be48..1323db8 100644 --- a/docs/source/lang/cpp/numeric-types.rst +++ b/docs/source/lang/cpp/built-in-types.rst @@ -1,16 +1,20 @@ -.. _lang-numeric-types: +.. highlight:: cpp -Numeric types -============= +.. _lang-built-in-types: -This document serves as a reference for all of the built-in numeric -types which are available when programming in the IDE. Programmers -using the :ref:`command-line tools <unix-toolchain>` will have access -to these types as long as they have imported ``wirish.h``; several are -defined in in `libmaple_types.h +================ + Built-in Types +================ + +This document serves as a reference for many of the built-in types +which are available when programming in the IDE. Programmers using +the :ref:`command-line tools <unix-toolchain>` will have access to +these types as long as they have imported `wirish.h +<https://github.com/leaflabs/libmaple/blob/master/wirish/wirish.h>`_; +several are defined in in `libmaple_types.h <https://github.com/leaflabs/libmaple/blob/master/libmaple/libmaple_types.h>`_. -.. _lang-numeric-types-integral: +.. _lang-built-in-types-integral: Integral types -------------- @@ -77,3 +81,15 @@ Floating-Point Types .. cpp:type:: double 64-bit, IEEE 754 double-precision floating-point type. + +Other Types +----------- + +.. cpp:type:: voidFuncPtr + + Pointer to a function that takes no arguments and returns nothing, i.e. + + :: + + typedef void (*voidFuncPtr)(void); + diff --git a/docs/source/lang/cpp/keywords.rst b/docs/source/lang/cpp/keywords.rst index e4ebe99..e3bc20d 100644 --- a/docs/source/lang/cpp/keywords.rst +++ b/docs/source/lang/cpp/keywords.rst @@ -94,7 +94,7 @@ The following keywords are used for built-in types. - :ref:`lang-float` - :ref:`lang-int` - :ref:`lang-long` -- :ref:`short <lang-numeric-types-integral>` +- :ref:`short <lang-built-in-types-integral>` - :ref:`void <lang-void>` (not really a type, but used in the absence of one) diff --git a/docs/source/lang/cpp/variables.rst b/docs/source/lang/cpp/variables.rst index 9094cd5..e6da0c9 100644 --- a/docs/source/lang/cpp/variables.rst +++ b/docs/source/lang/cpp/variables.rst @@ -37,7 +37,7 @@ named ``inputVariable2``, with an initial value of ``0``:: int inputVariable2 = 0; The Maple environment comes ready to use with many useful types of -variables. See the :ref:`built-in types <lang-numeric-types>` page +variables. See the :ref:`built-in types <lang-built-in-types>` page for more information. Here are a few examples of declaring variables of different types:: @@ -116,7 +116,7 @@ he goes past the left side of the screen, he reappears on the right:: x = x + 1; // x now contains -2,147,483,648; rolled over "right to left" Each numeric type's reference page includes its range. See the -:ref:`built-in types <lang-numeric-types>` reference for links to each +:ref:`built-in types <lang-built-in-types>` reference for links to each type's reference page. Using Variables @@ -149,7 +149,7 @@ See Also -------- - :ref:`lang-scope` -- :ref:`lang-numeric-types` +- :ref:`lang-built-in-types` .. rubric:: Footnotes diff --git a/docs/source/lang/cpp/void.rst b/docs/source/lang/cpp/void.rst index 88bd448..88c9c64 100644 --- a/docs/source/lang/cpp/void.rst +++ b/docs/source/lang/cpp/void.rst @@ -5,10 +5,12 @@ ``void`` ======== -The ``void`` keyword is used only in function declarations. It -indicates that the function is expected to return no information to -the function from which it was called, or that it expects no arguments -from its caller. +.. cpp:type:: void + + The ``void`` keyword is used in function declarations. It indicates + that the function is expected to return no information to the + function from which it was called, or that it expects no arguments + from its caller. Example ------- diff --git a/docs/source/lang/unimplemented/interrupts.rst b/docs/source/lang/unimplemented/interrupts.rst deleted file mode 100644 index 55b8e93..0000000 --- a/docs/source/lang/unimplemented/interrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _lang-interrupts: - -interrupts() -============ - -Re-enables interrupts (after they've been disabled by -`noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ ()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None - - - -Returns -------- - -None - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `noInterrupts <http://arduino.cc/en/Reference/NoInterrupts>`_\ () -- `attachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_\ () -- `detachInterrupt <http://arduino.cc/en/Reference/DetachInterrupt>`_\ () - - - - -.. include:: /lang/cc-attribution.txt diff --git a/docs/source/lang/unimplemented/nointerrupts.rst b/docs/source/lang/unimplemented/nointerrupts.rst deleted file mode 100644 index fb2e5f9..0000000 --- a/docs/source/lang/unimplemented/nointerrupts.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. _lang-nointerrupts: - -noInterrupts() -============== - -Description ------------ - -Disables interrupts (you can re-enable them with interrupts()). -Interrupts allow certain important tasks to happen in the -background and are enabled by default. Some functions will not work -while interrupts are disabled, and incoming communication may be -ignored. Interrupts can slightly disrupt the timing of code, -however, and may be disabled for particularly critical sections of -code. - - - -Parameters ----------- - -None. - - - -Returns -------- - -None. - - - -Example -------- - -:: - - void setup() {} - - void loop() - { - noInterrupts(); - // critical, time-sensitive code here - interrupts(); - // other code here - } - - - -See Also --------- - - -- `interrupts <http://arduino.cc/en/Reference/Interrupts>`_\ () - - - - -.. include:: /lang/cc-attribution.txt diff --git a/docs/source/language-index.rst b/docs/source/language-index.rst index 7843cb0..e160e2b 100644 --- a/docs/source/language-index.rst +++ b/docs/source/language-index.rst @@ -4,37 +4,37 @@ Complete Language Index ======================= -This is the index of Maple's :ref:`language reference <language-lang-docs>` documentation. The 'Maple API' column includes language specific to Maple as a microcontroller development platform, while the language in 'C++ for Maple' is more generally applied. - -# Fix above explanation +This is the index of Maple's :ref:`language reference +<language-lang-docs>` documentation. The "Maple API" column provides +API references for documented libmaple functionality. The "C++ for +Maple".. pages are adaptations of the Arduino C++ documentation to the +.. Maple, and are intended as a minimal reference/refresher for +.. programmers familiar with the Arduino language. .. _index-language-index-cpp: .. _index-language-index-api: -+--------------------------------------------+----------------------------------------------+ -| Maple API | :ref:`C++ for Maple <cpp>` | -| | | -+============================================+==============================================+ -| | | -| .. toctree:: | .. toctree:: | -| :maxdepth: 1 | :maxdepth: 1 | -| :glob: | :glob: | -| | | -| lang/api/* | lang/cpp/* | -| | | -+--------------------------------------------+----------------------------------------------+ - -.. Unfinished, unimplemented in libmaple: ++----------------------------------+------------------------------------+ +| Maple API | C++ for Maple | +| | | ++==================================+====================================+ +| | | +| .. toctree:: | .. toctree:: | +| :maxdepth: 1 | :maxdepth: 1 | +| :glob: | :glob: | +| | | +| lang/api/* | lang/cpp/* | +| | | ++----------------------------------+------------------------------------+ + +.. Unimplemented in libmaple or not part of current release: .. toctree:: :hidden: - lang/unimplemented/interrupts.rst - lang/unimplemented/nointerrupts.rst lang/unimplemented/notone.rst lang/unimplemented/pulsein.rst lang/unimplemented/shiftout.rst lang/unimplemented/stringclass.rst lang/unimplemented/stringobject.rst lang/unimplemented/tone.rst - diff --git a/docs/source/language.rst b/docs/source/language.rst index 8e5d454..018eb8c 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -52,8 +52,8 @@ Unique Maple Additions Maple Language Reference ------------------------ -The following table summarizes the available language features. A -more exhaustive index is available at the :ref:`language-index`. +The following table summarizes the available core language features. +A more exhaustive index is available at the :ref:`language-index`. +--------------------------------------------+----------------------------------------------+---------------------------------------------------+ | Structure | Variables | Functions | @@ -67,129 +67,129 @@ more exhaustive index is available at the :ref:`language-index`. |**Control Structures** |* :ref:`INPUT <lang-constants-input>` | | | | | :ref:`OUTPUT <lang-constants-output>` |* :ref:`digitalRead() <lang-digitalread>` | |* :ref:`if/else <lang-if>` | | | -| |* :ref:`true <lang-constants-true>` | | | -|* :ref:`for <lang-for>` | :ref:`false <lang-constants-false>` |**Analog I/O** | +| |* :ref:`true <lang-constants-true>` | |* :ref:`togglePin() <lang-togglepin>` | +|* :ref:`for <lang-for>` | :ref:`false <lang-constants-false>` | | +| | |* :ref:`toggleLED() <lang-toggleled>` | +|* :ref:`switch/case <lang-switchcase>` |* :ref:`BOARD_LED_PIN <lang-constants-led>` | | | +| | :ref:`BOARD_BUTTON_PIN <lang-constants-but>`|* :ref:`isButtonPressed() <lang-isbuttonpressed>` | +|* :ref:`while <lang-while>` | | | +| |* :ref:`Constants |* :ref:`waitForButtonPress() | +|* :ref:`do...while <lang-dowhile>` | <lang-constants>` (:ref:`integers | <lang-waitforbuttonpress>` | +| | <lang-constants-integers>`, :ref:`floating | | +|* :ref:`break <lang-break>` | point <lang-constants-fp>`) |**Analog I/O** | | | | | -|* :ref:`switch/case <lang-switchcase>` |* :ref:`Constants |* :ref:`analogRead() <lang-analogread>` | -| | <lang-constants>` (:ref:`integers | | -|* :ref:`while <lang-while>` | <lang-constants-integers>`, :ref:`floating |* :ref:`pwmWrite() <lang-pwmwrite>` | -| | point <lang-constants-fp>`) | (:ref:`analogWrite() <lang-analogwrite>` is | -|* :ref:`do...while <lang-dowhile>` | | also available, though its use is discouraged) | -| |**Data Types** | | -|* :ref:`break <lang-break>` | | | -| | The size of each datatype, in bytes, is |**Advanced I/O** | -|* :ref:`continue <lang-continue>` | given in parentheses where appropriate. | | -| | |* tone(): TODO | -|* :ref:`return <lang-return>` | *Note*: The ``word`` type is (deliberately) | | -| | :ref:`not supported <language-no-word>`. |* noTone(): TODO | -|* :ref:`goto <lang-goto>` | | | -| |* :ref:`void <lang-void>` |* shiftOut(): TODO | +|* :ref:`continue <lang-continue>` |**Data Types** |* :ref:`analogRead() <lang-analogread>` | | | | | -|**Further syntax** |* :ref:`boolean <lang-boolean>` (1 byte) |* pulseIn(): TODO | +|* :ref:`return <lang-return>` | The size of each datatype, in bytes, is |* :ref:`pwmWrite() <lang-pwmwrite>` | +| | given in parentheses where appropriate. | (:ref:`analogWrite() <lang-analogwrite>` is | +|* :ref:`goto <lang-goto>` | | also available, though its use is discouraged) | +| | *Note*: The ``word`` type is (deliberately) | | +| | :ref:`not supported <language-no-word>`. | | +|**Further syntax** | |**Advanced I/O** | +| |* :ref:`void <lang-void>` | | +|* :ref:`; (semicolon) <lang-semicolon>` | |* tone(): TODO | +| |* :ref:`boolean <lang-boolean>` (1 byte) | | +|* :ref:`{} (curly braces) | |* noTone(): TODO | +| <lang-curly-braces>` |* :ref:`char <lang-char>` (1 byte) | | +| | |* shiftOut(): TODO | +|* :ref:`// (single-line comment) |* :ref:`unsigned char | | +| <lang-comments-singleline>` | <lang-unsignedchar>` (1 byte) |* pulseIn(): TODO | | | | | -|* :ref:`; (semicolon) <lang-semicolon>` |* :ref:`char <lang-char>` (1 byte) | | -| | |**Time** | -|* :ref:`{} (curly braces) |* :ref:`unsigned char | | -| <lang-curly-braces>` | <lang-unsignedchar>` (1 byte) |* :ref:`millis() <lang-millis>` | +|* :ref:`/\* \*/ (multi-line comment) |* :ref:`byte <lang-byte>` (1 byte) | | +| <lang-comments-multiline>` | |**Time** | +| |* :ref:`int <lang-int>` (4 bytes) | | +|* :ref:`#define <lang-define>` | |* :ref:`millis() <lang-millis>` | +| |* :ref:`unsigned int <lang-unsignedint>` | | +|* :ref:`#include <lang-include>` | (4 bytes) |* :ref:`micros() <lang-micros>` | | | | | -|* :ref:`// (single-line comment) |* :ref:`byte <lang-byte>` (1 byte) |* :ref:`micros() <lang-micros>` | -| <lang-comments-singleline>` | | | -| |* :ref:`int <lang-int>` (4 bytes) |* :ref:`delay() <lang-delay>` | -|* :ref:`/\* \*/ (multi-line comment) | | | -| <lang-comments-multiline>` |* :ref:`unsigned int <lang-unsignedint>` |* :ref:`delayMicroseconds() | -| | (4 bytes) | <lang-delaymicroseconds>` | -|* :ref:`#define <lang-define>` | | | -| |* :ref:`long <lang-long>` (8 bytes) | | -|* :ref:`#include <lang-include>` | |**Math** | -| |* :ref:`unsigned long <lang-unsignedlong>` | | -| | (8 bytes) |* :ref:`min() <lang-min>` | +| |* :ref:`long <lang-long>` (8 bytes) |* :ref:`delay() <lang-delay>` | |**Arithmetic Operators** | | | -| |* :ref:`float <lang-float>` (4 bytes) |* :ref:`max() <lang-max>` | -|* :ref:`= <lang-assignment>` | | | -| (assignment operator) |* :ref:`double <lang-double>` (8 bytes) |* :ref:`abs() <lang-abs>` | +| |* :ref:`unsigned long <lang-unsignedlong>` |* :ref:`delayMicroseconds() | +|* :ref:`= <lang-assignment>` | (8 bytes) | <lang-delaymicroseconds>` | +| (assignment operator) | | | +| |* :ref:`float <lang-float>` (4 bytes) | | +|* :ref:`+ <lang-arithmetic>` (addition) | |**Math** | +| |* :ref:`double <lang-double>` (8 bytes) | | +|* :ref:`- <lang-arithmetic>` | |* :ref:`min() <lang-min>` | +| (subtraction) |* :ref:`Strings <lang-string>` | | +| | |* :ref:`max() <lang-max>` | +|* :ref:`* <lang-arithmetic>` |* :ref:`Arrays <lang-array>` | | +| (multiplication) | |* :ref:`abs() <lang-abs>` | +| |* :ref:`enum <lang-enum>` | | +|* :ref:`/ <lang-arithmetic>` (division) | |* :ref:`constrain() <lang-constrain>` | +| |* :ref:`Numeric types <lang-built-in-types>` | | +|* :ref:`% <lang-modulo>` (modulo) | |* :ref:`map() <lang-map>` | +| |**Conversion** | | +| | |* :ref:`pow() <lang-pow>` | +|**Comparison Operators** |* :ref:`char() <lang-charcast>` | | +| | |* :ref:`sqrt() <lang-sqrt>` | +|* :ref:`== <lang-comparison>` (equal to) |* :ref:`byte() <lang-bytecast>` | | | | | | -|* :ref:`+ <lang-arithmetic>` (addition) |* :ref:`Strings <lang-string>` |* :ref:`constrain() <lang-constrain>` | +|* :ref:`\!= <lang-comparison>` |* :ref:`int() <lang-intcast>` |**Trigonometry** | +| (not equal to) | | | +| |* :ref:`long() <lang-longcast>` |* :ref:`sin() <lang-sin>` | +|* :ref:`< <lang-comparison>` (less than) | | | +| |* :ref:`float() <lang-floatcast>` |* :ref:`cos() <lang-cos>` | +|* :ref:`> <lang-comparison>` | | | +| (greater than) |* :ref:`double() <lang-doublecast>` |* :ref:`tan() <lang-tan>` | | | | | -|* :ref:`- <lang-arithmetic>` |* :ref:`Arrays <lang-array>` |* :ref:`map() <lang-map>` | -| (subtraction) | | | -| |* :ref:`enum <lang-enum>` |* :ref:`pow() <lang-pow>` | -|* :ref:`* <lang-arithmetic>` | | | -| (multiplication) |* :ref:`Numeric types <lang-numeric-types>` |* :ref:`sqrt() <lang-sqrt>` | +|* :ref:`<= <lang-comparison>` | | | +| (less than or equal to) |**Variable Scope & Qualifiers** |**Random Numbers** | | | | | -|* :ref:`/ <lang-arithmetic>` (division) |**Conversion** | | -| | |**Trigonometry** | -|* :ref:`% <lang-modulo>` (modulo) |* :ref:`char() <lang-charcast>` | | -| | |* :ref:`sin() <lang-sin>` | -| |* :ref:`byte() <lang-bytecast>` | | -|**Comparison Operators** | |* :ref:`cos() <lang-cos>` | -| |* :ref:`int() <lang-intcast>` | | -|* :ref:`== <lang-comparison>` (equal to) | |* :ref:`tan() <lang-tan>` | -| |* :ref:`long() <lang-longcast>` | | -|* :ref:`\!= <lang-comparison>` | | | -| (not equal to) |* :ref:`float() <lang-floatcast>` |**Random Numbers** | +|* :ref:`>= <lang-comparison>` |* :ref:`variables <lang-variables>`, |* :ref:`randomSeed() <lang-randomseed>` | +| (greater than or equal to) | :ref:`scope <lang-variables-scope>` | | +| | |* :ref:`random() <lang-random>` | +| |* :ref:`static <lang-static>` | | +|**Boolean Operators** | | | +| |* :ref:`volatile <lang-volatile>` |**Bits and Bytes** | +|* :ref:`&& <lang-boolean-and>` (and) | | | +| |* :ref:`const <lang-const>` |* :ref:`lowByte() <lang-lowbyte>` | +|* :ref:`|| <lang-boolean-or>` (or) | | | +| | |* :ref:`highByte() <lang-highbyte>` is | +|* :ref:`\! <lang-boolean-not>` (not) |**Utilities** | provided, though its use is discouraged. | | | | | -|* :ref:`< <lang-comparison>` (less than) |* :ref:`double() <lang-doublecast>` |* :ref:`randomSeed() <lang-randomseed>` | -| | | | -|* :ref:`> <lang-comparison>` | |* :ref:`random() <lang-random>` | -| (greater than) |**Variable Scope & Qualifiers** | | -| | | | -|* :ref:`<= <lang-comparison>` |* :ref:`variables <lang-variables>`, |**Bits and Bytes** | -| (less than or equal to) | :ref:`scope <lang-variables-scope>` | | -| | |* :ref:`lowByte() <lang-lowbyte>` | -|* :ref:`>= <lang-comparison>` |* :ref:`static <lang-static>` | | -| (greater than or equal to) | |* :ref:`highByte() <lang-highbyte>` is | -| |* :ref:`volatile <lang-volatile>` | provided, though its use is discouraged. | -| | | | -|**Boolean Operators** |* :ref:`const <lang-const>` |* :ref:`bitRead() <lang-bitread>` | -| | | | -|* :ref:`&& <lang-boolean-and>` (and) | |* :ref:`bitWrite() <lang-bitwrite>` | -| |**Utilities** | | -|* :ref:`|| <lang-boolean-or>` (or) | |* :ref:`bitSet() <lang-bitset>` | -| |* :ref:`sizeof() <lang-sizeof>` | | -|* :ref:`\! <lang-boolean-not>` (not) | |* :ref:`bitClear() <lang-bitclear>` | -| | | | -| | |* :ref:`bit() <lang-bit>` | +| |* :ref:`sizeof() <lang-sizeof>` |* :ref:`bitRead() <lang-bitread>` | |**Pointer Operators** | | | +| | |* :ref:`bitWrite() <lang-bitwrite>` | +|* :ref:`* dereference operator | | | +| <lang-pointer>` | |* :ref:`bitSet() <lang-bitset>` | | | | | -|* :ref:`* dereference operator | |**External Interrupts** | +|* :ref:`& reference operator | |* :ref:`bitClear() <lang-bitclear>` | | <lang-pointer>` | | | -| | |* :ref:`Reference Page <external-interrupts>` | -|* :ref:`& reference operator | | | -| <lang-pointer>` | |* :ref:`attachInterrupt() | -| | | <lang-attachinterrupt>` | +| | |* :ref:`bit() <lang-bit>` | | | | | -|**Bitwise Operators** | |* :ref:`detachInterrupt() | -| | | <lang-detachinterrupt>` | +|**Bitwise Operators** | | | +| | |**External Interrupts** | |* :ref:`& <lang-bitwisemath-and>` | | | -| (bitwise and) | | | -| | |**Interrupts** | -|* :ref:`| <lang-bitwisemath-or>` | | | -| (bitwise or) | |* interrupts(): TODO | +| (bitwise and) | |* :ref:`Reference Page <external-interrupts>` | | | | | -|* :ref:`^ <lang-bitwisemath-xor>` | |* noInterrupts(): TODO | -| (bitwise xor) | | | +|* :ref:`| <lang-bitwisemath-or>` | |* :ref:`attachInterrupt() | +| (bitwise or) | | <lang-attachinterrupt>` | | | | | -|* :ref:`~ <lang-bitwisemath-not>` | |**Communication** | -| (bitwise not) | | | -| | |* :ref:`SerialUSB <lang-serialusb>` | -|* :ref:`\<\< <lang-bitshift>` | | | -| (shift left) | |* :ref:`Serial <lang-serial>` | +|* :ref:`^ <lang-bitwisemath-xor>` | |* :ref:`detachInterrupt() | +| (bitwise xor) | | <lang-detachinterrupt>` | | | | | -|* :ref:`>> <lang-bitshift>` | |**Looking for something else?** | -| (shift right) | | | -| | | See the :ref:`libraries` page for interfacing with| -| | | particular types of hardware. Maple links | -|**Compound Operators** | | against `newlib <http://sourceware.org/newlib/>`_ | -| | | and allows the use of any of its functions; see | -|* :ref:`++ <lang-increment>` | | its documentation for more details. | -| (increment) | | | +|* :ref:`~ <lang-bitwisemath-not>` | | | +| (bitwise not) | |**Interrupts** | | | | | -|* :ref:`- - <lang-increment>` | | | -| (decrement) | | | +|* :ref:`\<\< <lang-bitshift>` | |* :ref:`interrupts() <lang-interrupts>` | +| (shift left) | | | +| | |* :ref:`noInterrupts() <lang-nointerrupts>` | +|* :ref:`>> <lang-bitshift>` | | | +| (shift right) | | | +| | |**Communication** | | | | | -|* :ref:`+= <lang-compoundarithmetic>` | | | -| (compound add) | | | +|**Compound Operators** | |* :ref:`SerialUSB <lang-serialusb>` | | | | | +|* :ref:`++ <lang-increment>` | |* :ref:`Serial <lang-serial>` | +| (increment) | | | +| | |**Looking for something else?** | +|* :ref:`- - <lang-increment>` | | | +| (decrement) | | See the :ref:`libraries` page for interfacing with| +| | | particular types of hardware. Maple links | +|* :ref:`+= <lang-compoundarithmetic>` | | against `newlib <http://sourceware.org/newlib/>`_ | +| (compound add) | | and allows the use of any of its functions; see | +| | | its documentation for more details. | |* :ref:`-= | | | | <lang-compoundarithmetic>` (compound | | | | subtract) | | | @@ -222,6 +222,8 @@ more exhaustive index is available at the :ref:`language-index`. Missing Arduino Features ------------------------ +.. _langage-missing-analogreference: + **analogReference()** It is not possible to implement this function on the Maple @@ -256,8 +258,6 @@ Unimplemented Arduino Features The following Wiring/Arduino features are currently unimplemented on the Maple. However, they will be present in future versions: -- `interrupts() <http://arduino.cc/en/Reference/Interrupts>`_ -- `noInterrupts() <http://www.arduino.cc/en/Reference/NoInterrupts>`_ - `noTone() <http://www.arduino.cc/en/Reference/NoTone>`_ - `pulseIn() <http://www.arduino.cc/en/Reference/PulseIn>`_ - `shiftOut() <http://www.arduino.cc/en/Reference/ShiftOut>`_ @@ -272,7 +272,11 @@ the Maple. However, they will be present in future versions: C++ for Maple -------------- -If you haven't programmed in C++, or if you just need to jog your memory, you may want to check out our :ref:`C++ for Maple Index<cpp>`. It covers programming ideas and C++ that will definitely come in handy. + +If you haven't programmed in C++, or if you just need to jog your +memory, you may want to check out our :ref:`Language Index +<language-index>`. It provides some introductory coverage of +programming ideas and C++. .. _arduino_c_for_c_hackers: @@ -366,9 +370,7 @@ contains ``setup()`` and ``loop()``:: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } The second file contains the (not very useful) implementation for @@ -388,9 +390,7 @@ Then the results of the concatenation process might be :: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } int choose_a_pin(void); @@ -415,9 +415,7 @@ Which could plausibly be turned into the final source file :: } void loop() { - static int toggle = 0; - toggle ^= 1; - digitalWrite(the_pin, toggle); + togglePin(the_pin); } int choose_a_pin(void); @@ -441,7 +439,6 @@ Recommended Reading * `newlib Documentation <http://sourceware.org/newlib/>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (assembly language and register reference) diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 567aec8..7623963 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -21,13 +21,69 @@ in the description of the library. .. contents:: Contents :local: +.. toctree:: + :hidden: + + libs/servo.rst + +.. _libraries-servo: + +Servo +----- + +The Servo library is provided for convenient control of RC +servomotors. For more information, see the :ref:`Servo <libs-servo>` +reference. + +**Compatibility Note** + +The Servo class provides a public interface identical to the Arduino +version's documented functionality (as of Arduino 0021), so in most +cases, this library will be a drop-in replacement. + +However, there are some differences, essentially at the level of +implementation details. + +The major difference is that while the Arduino implementation drives +the servos with "bit-banged" :ref:`PWM <pwm>`, the Maple +implementation uses :ref:`timers <timers>` to drive the PWM directly. + +Consequently, **the Maple implementation only allows Servo instances +to** :ref:`attach <libs-servo-attach>` **to pins that support PWM**. + +To determine if a pin supports PWM (15 Maple pins do), you can either +check if "PWM" appears next to its number on the Maple silkscreen, or +consult the :ref:`pwmWrite() <lang-pwmwrite>` documentation. + +RC Servos expect a pulse approximately every 20ms. In the Maple +implementation, :ref:`periods <lang-hardwaretimer-setperiod>` are set +for entire timers, rather than individual channels. Thus, +``attach()``\ ing a Servo to a pin can interfere with other pins +associated with the same timer\ [#fard-servo]_. + +Because of this, we recommend connecting multiple servomotors to pins +which share a timer, in order to keep as many timers free for other +purposes as possible. Consult the :ref:`table provided in the timers +reference <timers-pin-channel-map>` to match up pins and timer +channels. + +Another difference: although it is not publicly documented to do so, +the Arduino implementation of `attach() +<http://arduino.cc/en/Reference/ServoAttach>`_ returns the timer +channel associated with the newly-attached pin, or 0 on failure (as of +Arduino 0021). The Maple implementation returns true on success, and +false on failure (and this is its documented behavior). + .. _libraries-liquid-crystal: LiquidCrystal ------------- +.. TODO 0.0.10 make our own LiquidCrystal docs + The LiquidCrystal library allows Maple to control LCD screens. For -more information, see the Arduino LiquidCrystal documentation. +more information, see the `Arduino LiquidCrystal documentation +<http://www.arduino.cc/en/Reference/LiquidCrystal>`_. **Compatibility Note** @@ -57,6 +113,8 @@ 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 ^^^^^^^^^^^^^^^^^^^^^^^ @@ -127,3 +185,10 @@ Wire Function Reference 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 + +.. [#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/servo.rst b/docs/source/libs/servo.rst new file mode 100644 index 0000000..f92fd91 --- /dev/null +++ b/docs/source/libs/servo.rst @@ -0,0 +1,108 @@ +.. highlight:: cpp + +.. _libs-servo: + +======= + Servo +======= + +This documents the Servo library for controlling RC servomotors. It +is implemented as a thin layer over the built-in :ref:`timer +peripherals <timers>`. + +You can use this library in the :ref:`IDE <ide>` by choosing the Servo +item under the Sketch > Import Library... menu. + +If you are using the :ref:`Unix toolchain <unix-toolchain>`, the +library is located in ``$LIB_MAPLE_HOME/libraries/Servo/``. + +Servo Class Reference +--------------------- + +You can construct a Servo object by including the declaration :: + + Servo servo; + +in your sketch. This will create a Servo object called ``servo``. +You can then use any of its methods; for instance, to control a +servomotor attached to pin 9, you could write :: + + servo.attach(9); + +.. cpp:class:: Servo + + Class for controlling RC servomotors via :ref:`timers <timers>`. + +.. _libs-servo-attach: + +.. cpp:function:: bool Servo::attach(uint8 pin, uint16 min, uint16 max) + + Attach this Servo object to the given ``pin``. The pin must be + capable of PWM. You can check this by seeing if "PWM" is written + next to its number on the Maple silkscreen, or by consulting the + :ref:`pwmWrite() <lang-pwmwrite>` documentation. + + Sets this pin's :ref:`mode <lang-pinmode>` to :ref:`PWM + <lang-pinmode-wiringpinmode>`, and returns true if successful. + Does nothing and returns false if the pin doesn't support PWM. + + Parameter ``min`` is the pulse width corresponding to 0 degrees; + ``max`` is the pulse width corresponding to 180 degrees (both are + in microseconds). + +.. cpp:function:: bool Servo::attach(uint8 pin) + + Equivalent to :ref:`attach(pin, 544, 2400) <libs-servo-attach>`. + +.. _libs-servo-attached: + +.. cpp:function:: int Servo::attached() const + + If currently attached (via :ref:`attach() <libs-servo-attach>`) to + a pin, returns that pin's number. Returns ``NOT_ATTACHED`` + otherwise. + +.. cpp:function:: bool Servo::detach() + + If this Servo object is currently attached to pin, stops driving + the servo by setting a zero pulse width (this is accomplished by + setting the associated :ref:`channel mode + <lang-hardwaretimer-setchannelmode>` to ``TIMER_DISABLED``). + + Subsequently, calling :ref:`attached() <libs-servo-attached>` will + return ``NOT_ATTACHED``. + +.. cpp:function:: void Servo::write(unsigned int value) + + If ``value`` is less than ``SERVO_MAX_WRITE_ANGLE`` (which, for + Arduino compatibility, is 200), it's interpreted as an angle in + degrees. Otherwise, it's treated as a pulse width in microseconds. + + Drives the servo to target the given angle, based on a linear + interpolation of the ``min`` and ``max`` pulse widths determined + when :ref:`attach() <libs-servo-attach>` was called. + + Be aware that some (especially lower-cost) servos have fairly + non-linear maps between pulse width and target angle. Make sure to + test your motor before relying on this method. + +.. cpp:function:: void Servo::writeMicroseconds(uint16 pulseWidth) + + Drives the servo using a ``pulseWidth``-microsecond pulse. + + If ``pulseWidth`` is outside of the [``min``, ``max``\ ] pulse + width range set during :ref:`attach() <libs-servo-attach>`, it will + be clamped to lie in this range. + +.. cpp:function:: int Servo::read() const + + Returns the servo's target angle, in degrees. This will be clamped + to lie between 0 (when the pulse width is at most ``min``) and 180 + (when the pulse width is at least ``max``). + +.. cpp:function:: uint16 Servo::readMicroseconds() const + + Returns the pulse width of the wave currently driving the servo, in + microseconds. This will be clamped to lie in the [``min``, + ``max``\ ] pulse width range set during :ref:`attach() + <libs-servo-attach>`. diff --git a/docs/source/pwm.rst b/docs/source/pwm.rst index fd72842..1a8f4df 100644 --- a/docs/source/pwm.rst +++ b/docs/source/pwm.rst @@ -28,9 +28,9 @@ Note that unlike the Arduino, the Maple does not have PWM functionality on pin D10; all other pins are :ref:`compatible <compatibility>`. -The following table shows which :ref:`timer <timers>` generates which -PWM outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` -to track down exactly which timer *channel* corresponds to each pin. +The following table shows which timer can generate which PWM +outputs. See the :ref:`pin mapping table <pin-mapping-mega-table>` to +track down exactly which timer *channel* corresponds to each pin. .. _pwm-timer-table: @@ -65,12 +65,13 @@ The Maple has 16-bit PWM resolution, which means that the counter and variables can be as large as 65535, as opposed to 255 with 8-bit resolution. With a 72MHz clock rate, a PWM output could have maximum period of about one millisecond; using a :ref:`prescaler -<pwm-prescaler>` (clock divider) in front of the counter can increase -this maximum period. Setting the :ref:`period <pwm-overflow>` to -something other than the maximum value gives further control over the -total length of the waveform. However, this effectively limits the -resolution with which the duty can be modified: the duty must be less -than or equal to the period. +<lang-hardwaretimer-setprescalefactor>` (clock divider) in front of +the counter can increase this maximum period. Setting the +:ref:`period <lang-hardwaretimer-setperiod>` to something other than +the maximum value gives further control over the total length of the +waveform. However, this effectively limits the resolution with which +the duty can be modified: the duty must be less than or equal to the +period. Here are some commonly used PWM configurations (note that servos are notoriously variable, especially the lower cost models): @@ -93,82 +94,13 @@ notoriously variable, especially the lower cost models): Function Reference ------------------ -``pinMode(pin_num, PWM)`` - - This command is usually called from :ref:`setup() <lang-setup>` to - tell the microcontroller that pin_num should be configured to PWM - output. ``PWM`` implies regular driven OUTPUT; ``PWM_OPEN_DRAIN`` - is also available (see the list of :ref:`GPIO modes <gpio-modes>` - for more information). - -.. _pwm-pwmwrite: - -``pwmWrite(pin_num, value)`` - - This command sets the PWM duty. User code is expected to determine - and honor the maximum value (based on the configured period). As a - convenience, ``analogWrite`` is an alias for ``pwmWrite`` to ease - porting Arduino code, though period and duty will have to be - recalibrated (see :ref:`compatibility <compatibility>`). - -.. _pwm-overflow: - -``Timer[1,2,3,4].setOverflow(overflow)`` - - This function sets the period ("reload" or "overflow") value for - an entire PWM timer bank. The value is 16bit (0 to 65535) and - determines the maximum value that can be written with - :ref:`pwmWrite() <pwm-pwmwrite>` corresponding to 100% duty - cycle. This also affects the PWM frequency: the higher reload is, - the lower the PWM frequency will be. - - The PWM output pin starts HIGH, then the timer begins counting up - from zero (with frequency equal to 72MHz/:ref:`prescaler - <pwm-prescaler>`) until it hits the duty value, at which point it - drops to LOW. The timer then continues counting up until it hits - the total period (set with this function), at which point the - cycle starts again. - -.. _pwm-prescaler: - -``Timer[1,2,3,4].setPrescaleFactor(prescale)`` - - Find the appropriate timer for a given PWM header using the table - :ref:`above <pwm-timer-table>`, then set the prescaler. A - prescaler is a clock divider. The timer will normally count with - frequency equal to the STM32's normal clock (72MHz); this - corresponds to setting ``prescale`` to 1 (which is the default). - - If a longer frequency is desired, use a larger ``prescale`` value. - For instance, an 8MHz frequency can be achieved by setting - ``prescale`` to 9, since 72MHz / 9 = 8MHz. - - This function is normally called once from, :ref:`lang-setup`, but - the timer can be reconfigured with a new prescaler at any time. - - * Configure 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. - -``Timer[1,2,3,4].setPeriod(period_in_microseconds)`` - - Configure 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. - - +- :ref:`lang-pinmode` +- :ref:`lang-pwmwrite` +- :ref:`Timer API<lang-hardwaretimer>` (especially :ref:`setOverflow() + <lang-hardwaretimer-setoverflow>`, :ref:`setPrescaleFactor() + <lang-hardwaretimer-setprescalefactor>`, and :ref:`setPeriod() + <lang-hardwaretimer-setperiod>`). +- :ref:`Timers reference <timers>`. Recommended Reading ------------------- @@ -182,6 +114,5 @@ Recommended Reading * `So You Want To Use PWM, Eh? <http://www.arcfn.com/2009/07/secrets-of-arduino-pwm.html>`_ at Non-Lexical Vocables * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/spi.rst b/docs/source/spi.rst index ca9415c..ba43eef 100644 --- a/docs/source/spi.rst +++ b/docs/source/spi.rst @@ -4,54 +4,16 @@ SPI ===== -The Maple has two SPI ports. The first has NSS on D10, MOSI on D11, -MISO on D12, and SCK on D13. The second has NSS on D31, SCK on D32, -MISO on D33, and MOSI on D34. +The Serial Peripheral Interface Bus (SPI) is a serial data transfer +protocol useful for interacting with a wide variety of hardware +peripherals. -.. _spi-speeds: +The Maple has two SPI ports. The first has NSS on D10, MOSI on +D11, MISO on D12, and SCK on D13. The second has NSS on D31, SCK on +D32, MISO on D33, and MOSI on D34. -Each port can be configured at one of the following speeds: - -* ``SPI_18MHZ``: 18 MHz -* ``SPI_9MHZ``: 9 MHz -* ``SPI_4_5MHZ``: 4.5 MHz -* ``SPI_2_25MHZ``: 2.25 MHz -* ``SPI_1_125MHZ``: 1.124 MHz -* ``SPI_562_500KHZ``: 562.500 KHz -* ``SPI_281_250KHZ``: 281.250 KHz -* ``SPI_140_625KHZ``: 140.625 KHz - -.. contents:: Contents - :local: - -Function Reference ------------------- - -``HardwareSPI Spi(number);`` - - This declaration must be included at the start of any sketch or - program that uses the SPI interface. The argument number is either - 1 or 2 and specifies which port to use. - -``Spi.begin(freq, endianness, mode)`` - - ``begin`` is usually called in :ref:`lang-setup` to configure the - baudrate of the given SPI port and to set up the header pins - appropriately. ``freq`` is one of the set listed :ref:`above - <spi-speeds>`; ``endianness`` is either ``LSBFIRST`` or - ``MSBFIRST``; mode is one of 0, 1, 2, 3, and specifies which "SPI - Mode" is used (see specification docs linked below). - -``Spi.begin()`` - - A default ``begin`` with no arguments is provided for the lazy; it - is equivalent to ``Spi.begin(SPI_1_125MHZ, MSBFIRST, 0)``. - -``Spi.send(data, size)`` - - Writes data into the port buffer to be transmitted as soon as - possible. ``data`` should be an array of type ``byte*``; ``size`` - should be the number of elements in ``data``. +The public libmaple API for managing the SPI ports is the +:ref:`HardwareSpi <lang-hardwarespi>` class. Recommended Reading ------------------- @@ -63,7 +25,6 @@ Recommended Reading * `Hardcore SPI on Arduino <http://klk64.com/arduino-spi/>`_ by kik64 * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/timers.rst b/docs/source/timers.rst index 948805b..56dd686 100644 --- a/docs/source/timers.rst +++ b/docs/source/timers.rst @@ -8,25 +8,46 @@ Timers 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 -<pwm>` channels, once enabled, generate regular square-wave signals on -specific output pins that will continue even if the microcontroller is -busy crunching numbers or handling communications interrupts. By -attaching interrupt handlers to these channels (instead of just -changing the voltage on an external pin), more complex events like -printing to a serial port, updating a variable, or emitting a whale -mating call can be scheduled. You can even modify the configuration of -the timer itself at a regular interval; the possibilities are endless! - -The four timers each have four separate compare channels. Each timer -is a single 16-bit counter that can be configured with both a -prescaler and an overflow value. The prescaler acts as a divider of -the 72MHz system clock; without prescaling the counter would get up to -65536 (2 to the 16th power) and roll over more than a thousand times a -second; even with the full prescaler it rolls over about once a -minute. The overflow value is the maximum value the counter will go up -to. It defaults to the full 65535; smaller values will cause the -counter to reset to zero more frequently. +<pwm>` channels can generate regular square-wave signals on specific +output pins without consuming extra clock cycles. By attaching +interrupt handlers to these channels (instead of just changing the +voltage on an external pin), more complex events can be scheduled. + +.. contents:: Contents + :local: + +Introduction +------------ + +.. _timers-prescale: + +The four timers each have four separate compare channels. Each channel +has an associated 16-bit counter that can be configured with a 16-bit +prescaler and a 16-bit overflow value. The prescaler determines how +fast the counter changes, while the overflow value determines when it +gets reset. + +The prescaler acts as a divider of the 72MHz system clock. That is, +with a prescaler of 1, the channel's counter increments with a +frequency of 72MHz, rolling over (passing the maximum 16-bit unsigned +integer value of 65,535) more than a thousand times a second. With a +prescaler of 7200, it has a frequency of (72/7200) MHz = 10 KHz, +rolling over approximately every 6.55 seconds. + +The overflow value is the maximum value the counter will go up to. It +defaults to the full 65,535; smaller values will cause the counter to +reset to zero more frequently. + +Whenever a channel's counter reaches its overflow value, an "update +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 +------------------ +The libmaple API for interacting with timers is documented at the +:ref:`HardwareTimer reference <lang-hardwaretimer>`. Caveats ------- @@ -36,9 +57,18 @@ Caveats **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 full :ref:`pin mapping table -<pin-mapping-mega-table>` to match up timer channels and Maple header -pin numbers. +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, @@ -59,7 +89,8 @@ configuration being the same. auto-reset and communications functionality. This will require that you put your Maple into :ref:`perpetual bootloader mode <troubleshooting-perpetual-bootloader>` before uploading a new - program to it. + program to it (or somehow causing your program to re-enable serial + over USB using :ref:`SerialUSB.begin() <lang-serialusb-begin>`). Disabling SysTick with ``systick_disable()`` helps as well. However, calling this function will break the ``micros()`` and @@ -73,33 +104,6 @@ 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. -.. _timers-modes: - -General Timer Modes -------------------- - -``TIMER_DISABLED`` - - Exactly what it sounds like: the timer stops counting, interrupts - are not called, and no state changes are output. - -``TIMER_PWM`` - - This is the default mode for pins after initialization. See the - :ref:`PWM docs <pwm>` for more information on this 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. - -``TIMER_OUTPUTCOMPARE`` - - In this mode, the timer counts from 0 to the overflow value - repeatedly; every time the counter value reaches one of the - channel compare values, the corresponding interrupt is fired. - SysTick Peripheral ------------------ @@ -111,136 +115,22 @@ 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()``. -Function Reference ------------------- - -For all of these functions, ``Timer1`` can be replaced with -``Timer2``, ``Timer3``, or ``Timer4``; the channel numbers also range -from 1 to 4. - -``Timer1.pause()``/\ ``Timer1.resume()`` - - These functions start and stop the counter without affecting the - rest of the configuration. These functions can be used during the - setup period to prevent interrupts from firing before they are - completely configured. Note that there is some function call - overhead with these functions, so they are not a perfect way to - align multiple timers to the same count value. - -``Timer1.setOverflow(val)`` - - Sets the overflow (or "reload") value for the whole timer; when - the counter reaches this value it resets to zero. Defaults to - 65535 (the largest unsigned 16bit integer); setting it 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. - -``Timer1.setPrescaleFactor(val)`` - - The prescaler acts as a clock divider to slow down the rate at - which the counter increments. 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 you set the prescaler to 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 just about - once a second. Use the :ref:`setPeriod <timers-set-period>` - function below if you are allergic to math! - -.. _timers-set-period: - -``Timer1.setPeriod(val)`` - - This tricky trick will configure the prescaler and overflow values - to generate a timer reload with a period as close to val - microseconds as possible. It returns the chosen overflow value, - which you can then use to set the channel compare values - appropriately: if you just want the interrupts to fire when the - clock rolls over and you don't care about the relative "phase", - you can always set the channel compare values to 1. - - Remember: a microsecond is 1/1,000,000th of a second, or 1/1,000 - of a millisecond. The prescaler itself is 16bit, so the longest - period that can be configured is 1/(72MHz) * (2^32) = (59.65 - seconds) or about a minute. You can get around this by creating an - interrupt that increments a 32-bit variable, by using the - ``millis()`` function, or by interfacing with an external - real-time-clock chip. - -``Timer1.setCount(val)``/\ ``Timer1.getCount()`` - - These functions let you mess with the counter's brains - directly. You can probably make it not work if you try! The timer - is 16bit, so ``val`` and the return value of ``getCount`` are - ``uint16``. - -``Timer1.setChannel1Mode(MODE)`` - - This sets the given channel (here 1) of the given timer (here 1) - to the given mode. See the :ref:`list above <timers-modes>` for - possible values; for interrupts you want ``TIMER_OUTPUTCOMPARE``. - -``Timer1.setCompare1(val)`` - - Sets the compare value for the given channel; when the counter - reaches this value the interrupt for this channel will fire if the - channel is in output compare mode 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 overhead means that the smallest increment - rate is a couple microseconds. - -.. _timers-attachinterrupt: -.. _timers-detachinterrupt: - -``Timer1.attachCompare1Interrupt(function)``/\ ``Timer1.detachCompare1Interrupt()`` - - This is how to attach or disable an interrupt handlers to timer - channels; this what will get called when the counter reaches the - compare value set with ``setCompareN(val)``. ``function`` - (sometimes referred to as an ISR: "interrupt service routine") - should be of a type that does not accept or return any values - (C/C++ programmers: ``void (function*)(void)``). They are just - like any other function in your sketch/program and must be - initialized at the top of the file and defined below. - - ``function`` should try to do what it has to do as fast 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 ISR, you're probably doing it - wrong. - - Stay vigilant here... function pointers are serious business, and - once you go down that path you'll find yourself in a `forest of - parentheses <http://mitpress.mit.edu/sicp/>`_ before you know it. - Code Examples ------------- LED blink ^^^^^^^^^ -\ :: +:: - #define LED_PIN 13 #define LED_RATE 500000 // in microseconds; should give 0.5Hz toggles void handler_led(void); - int toggle = 0; - void setup() { // Set up the LED to blink - pinMode(LED_PIN, OUTPUT); + pinMode(BOARD_LED_PIN, OUTPUT); // Setup Timer Timer2.setChannel1Mode(TIMER_OUTPUTCOMPARE); @@ -254,16 +144,13 @@ LED blink } void handler_led(void) { - toggle ^= 1; - digitalWrite(LED_PIN, toggle); + toggleLED(); } Racing Counters ^^^^^^^^^^^^^^^ -\ :: - - #define BUTTON_PIN 38 +:: void handler_count1(void); void handler_count2(void); @@ -274,7 +161,7 @@ Racing Counters void setup() { // Set up BUT for input - pinMode(BUTTON_PIN, INPUT_PULLUP); + pinMode(BOARD_BUTTON_PIN, INPUT_PULLUP); // Setup Counting Timers Timer3.setChannel1Mode(TIMER_OUTPUTCOMPARE); @@ -302,7 +189,7 @@ Racing Counters // Run... while BUT is held, pause Count2 for(int i = 0; i<1000; i++) { - if(digitalRead(BUTTON_PIN)) { + if(digitalRead(BOARD_BUTTON_PIN)) { Timer4.pause(); } else { Timer4.resume(); diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 0c10d01..f3052d9 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -150,7 +150,11 @@ is several times more FLASH memory available for user programs. ``No DFU capable USB device found`` ----------------------------------- -This probably means you don't have a Maple plugged in or powered on! +This probably means you don't have a Maple plugged in or powered on. +Try unplugging and plugging your Maple or pressing the RESET button. + +This can also happen if you disable the USB peripheral, e.g. using +:ref:`SerialUSB.end() <lang-serialusb-end>`. I have multiple Maples installed; how do I know which one will get flashed? --------------------------------------------------------------------------- @@ -161,19 +165,26 @@ board. There's no solution to this problem for now: you'll have to just plug in the Maples one at a time. If this is a real problem let us know and we'll see if we can come up with a better solution. +My flash programs don't seem to stick; they behave like they are RAM! +--------------------------------------------------------------------- + +If you have uploaded a program to RAM, this will take priority over +any program subsequently uploaded to flash. We'll be removing this +bug in a later version of the bootloader. For now, you can fix this +by unplugging your Maple to clear the contents of RAM, then plugging +it back in. + +If you are using the :ref:`Unix toolchain <unix-toolchain>`, Make sure +you :command:`make clean` when switching between FLASH and RAM +targets; :command:`make` isn't smart enough to rebuild everything that +needs to be for the new target. + .. _troubleshooting-shell: ===================== Command-line issues ===================== -My flash programs don't seem to stick; they behave like they are RAM! ---------------------------------------------------------------------- - -Make sure you :command:`make clean` when switching between FLASH and -RAM targets; :command:`make` isn't smart enough to rebuild everything -that needs to be for the new target. - [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` ----------------------------------------------------- diff --git a/docs/source/usart.rst b/docs/source/usart.rst index c0334a9..3beb3fc 100644 --- a/docs/source/usart.rst +++ b/docs/source/usart.rst @@ -30,6 +30,5 @@ Recommended Reading * `Arduino reference on Serial <http://arduino.cc/en/Reference/Serial>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) diff --git a/docs/source/usb.rst b/docs/source/usb.rst index 5494b06..f502f31 100644 --- a/docs/source/usb.rst +++ b/docs/source/usb.rst @@ -39,7 +39,6 @@ Recommended Reading * Linux Kernel documentation for `USB ACM <http://www.kernel.org/doc/Documentation/usb/acm.txt>`_ and `USB Serial <http://www.kernel.org/doc/Documentation/usb/usb-serial.txt>`_ * STMicro documentation for STM32F103RB microcontroller: - * `All documents <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ * `Datasheet <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ (pdf) * `Reference Manual <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ (pdf) * `Programming Manual <http://www.st.com/stonline/products/literature/pm/15491.pdf>`_ (pdf; assembly diff --git a/libmaple/libmaple_types.h b/libmaple/libmaple_types.h index a976a9e..8d216a8 100644 --- a/libmaple/libmaple_types.h +++ b/libmaple/libmaple_types.h @@ -45,6 +45,8 @@ typedef void (*voidFuncPtr)(void); #define __io volatile +#define ALWAYS_INLINE inline __attribute__((always_inline)) + #ifndef NULL #define NULL 0 #endif diff --git a/libmaple/timers.h b/libmaple/timers.h index 7589283..8d28f60 100644 --- a/libmaple/timers.h +++ b/libmaple/timers.h @@ -228,16 +228,16 @@ extern struct timer_dev timer_dev_table[]; /** * Initializes timer with prescale as the clock divisor. * - * @param timer Timer number. Valid values are TIMER1, TIMER2, - * TIMER3, TIMER4, and (on high-density devices) TIMER5, TIMER8. + * @param timer_num Timer number. * * @param prescale value in the range 1--65535 to use as a prescaler * for timer counter increment frequency. * + * @see timer_dev_num * @see timer_set_prescaler() * @see timer_set_mode() */ -void timer_init(timer_dev_num, uint16); +void timer_init(timer_dev_num timer_num, uint16 prescale); /** * Quickly disable all timers. Calling this function is faster than, @@ -250,34 +250,34 @@ void timer_disable_all(void); * this value is likely to be inaccurate if the counter is running * with a low prescaler. * - * @param timer the timer whose counter to return. + * @param timer_num the timer whose counter to return. * * @pre Timer has been initialized. */ -uint16 timer_get_count(timer_dev_num); +uint16 timer_get_count(timer_dev_num timer_num); /** * Sets the counter value for the given timer. * - * @param timer the timer whose counter to set. + * @param timer_num the timer whose counter to set. * * @param value the new counter value. * * @pre Timer has been initialized. */ -void timer_set_count(timer_dev_num,uint16); +void timer_set_count(timer_dev_num timer_num, uint16 value); /** * Stops the timer's counter from incrementing. Does not modify the * timer's mode or settings. * - * @param timer the timer to pause. + * @param timer_num the timer to pause. * * @see timer_resume() * * @pre Timer has been initialized. */ -void timer_pause(timer_dev_num); +void timer_pause(timer_dev_num timer_num); /** * Starts the counter for the given timer. Does not modify the @@ -285,17 +285,19 @@ void timer_pause(timer_dev_num); * first rising clock cycle after it has been re-enabled using this * function. * - * @param timer the timer to resume. + * @param timer_num the timer to resume. * * @see timer_pause() * * @pre Timer has been initialized. */ -void timer_resume(timer_dev_num); +void timer_resume(timer_dev_num timer_num); /** * Returns the prescaler for the given timer. * + * @param timer_num the timer whose prescaler to return. + * * @see timer_set_prescaler() * * @pre Timer has been initialized. @@ -308,7 +310,7 @@ uint16 timer_get_prescaler(timer_dev_num timer_num); * per clock cycle). This prescale does not take effect until the * next update event. * - * @param timer the timer whose prescaler to set. + * @param timer_num the timer whose prescaler to set. * * @param prescale the new prescaler. * @@ -331,10 +333,6 @@ uint16 timer_get_reload(timer_dev_num timer_num); * After this function returns, the timer's counter will reset to 0 * after it has reached the value max_reload. * - * @param timer the timer whose reload to set. - * - * @param max_reload the new reload value. - * * @pre Timer has been initialized. */ void timer_set_reload(timer_dev_num timer_num, uint16 max_reload); @@ -344,52 +342,32 @@ void timer_set_reload(timer_dev_num timer_num, uint16 max_reload); /** * Set the mode of an individual timer channel. * - * @param timer the timer whose channel mode to set. - * - * @param channel the channel whose mode to set (1 <= channel <= 4). - * - * @param mode the new mode value. Currently acceptable values - * include TIMER_DISABLED, TIMER_PWM, and TIMER_OUTPUTCOMPARE. Note - * that timer_disable_all() will disable all timers and all channels - * much more quickly than repeated calls to this function with mode - * TIMER_DISABLED. - * - * @see TimerMode - * * @see timer_disable_all() - * + * @see TimerMode + * @see timer_dev_num * @pre Timer has been initialized. */ -void timer_set_mode(timer_dev_num timer_num, uint8 channel_num, uint8 mode); +void timer_set_mode(timer_dev_num timer_num, uint8 channel, TimerMode mode); /** * Get the compare value for the given timer channel. * @see timer_set_compare_value() - * + * @see timer_dev_num * @pre Timer has been initialized. */ -uint16 timer_get_compare_value(timer_dev_num timer_num, uint8 channel_num); +uint16 timer_get_compare_value(timer_dev_num timer_num, uint8 channel); /** * Sets the compare value for a given timer channel. Useful for * scheduling when interrupt handlers will be called. * - * @param timer the timer whose channel compare to set. - * - * @param channel the channel whose compare to set (1 <= channel <= 4). - * - * @param compare the new compare value. This new value must be less - * than or equal to the timer's reload value. - * * @see timer_attach_interrupt() - * * @see timer_detach_interrupt() - * * @see timer_set_reload() - * + * @see timer_dev_num * @pre Timer has been initialized. */ -void timer_set_compare_value(timer_dev_num timer_num, uint8 channel_num, +void timer_set_compare_value(timer_dev_num timer_num, uint8 channel, uint16 value); /** @@ -397,44 +375,27 @@ void timer_set_compare_value(timer_dev_num timer_num, uint8 channel_num, * After this function returns, any handler attached to the given * channel will no longer be called. * - * @param timer the timer whose channel to detach the interrupt - * handler from. - * - * @param channel the channel from which to detach the interrupt handler. - * * @see timer_attach_interrupt() - * * @pre Timer has been initialized. + * @see timer_dev_num */ -void timer_detach_interrupt(timer_dev_num timer_num, uint8 channel_num); +void timer_detach_interrupt(timer_dev_num timer_num, uint8 channel); /** * Attach an interrupt handler for the given timer and channel. The - * handler will be called whenever the timer's counter reaches the - * compare value for the given timer and channel. - * - * @param timer the timer whose channel to register with an interrupt handler. - * - * @param channel the channel with which the new handler will be - * associated. timer_set_compare_value() can be used to set the value - * which the timer's counter must reach before handler is called (1 <= - * channel <= 4). - * - * @param handler the interrupt handler to call once the timer reaches - * the given channel's compare value. - * - * @pre The channel's mode must be set to TIMER_OUTPUTCOMPARE, or the - * interrupt handler will not get called. + * given ISR, handler, will be called whenever the timer's counter + * reaches the compare value for the given timer and channel. * * @see timer_set_compare_value() - * * @see timer_detach_interrupt() - * * @see timer_set_mode() - * + * @see timer_dev_num + * @see voidFuncPtr * @pre Timer has been initialized. + * @pre The channel's mode must be set to TIMER_OUTPUTCOMPARE, or the + * interrupt handler will not get called. */ -void timer_attach_interrupt(timer_dev_num timer_num, uint8 channel_num, +void timer_attach_interrupt(timer_dev_num timer_num, uint8 channel, voidFuncPtr handler); /** @@ -449,18 +410,18 @@ void timer_generate_update(timer_dev_num timer_num); /** * Turn on PWM with duty_cycle. * - * @param channel TIMERx_CHn_CCR, where x goes from 1 to NR_TIMERS, + * @param ccr TIMERx_CHn_CCR, where x goes from 1 to NR_TIMERS, * and n goes from 1 to 4. * - * @param duty_cycle 0--65535. duty_cycle=0 means always off; - * duty_cycle=65535 means always on. + * @param duty_cycle: A number between 0 and + * timer_get_compare_value(TIMERx, y), where x and y are as above. * * @pre Pin has been set to alternate function output. * * @pre Timer has been initialized. */ -static inline void timer_pwm_write_ccr(TimerCCR CCR, uint16 duty_cycle) { - *CCR = duty_cycle; +static inline void timer_pwm_write_ccr(TimerCCR ccr, uint16 duty_cycle) { + *ccr = duty_cycle; } #ifdef __cplusplus diff --git a/support/scripts/copy-to-ide b/support/scripts/copy-to-ide index 5bf52a4..c6b4c16 100755 --- a/support/scripts/copy-to-ide +++ b/support/scripts/copy-to-ide @@ -4,9 +4,7 @@ # repository. # Change this -DEST=`pwd`/../maple-ide/hardware/leaflabs/cores/maple/ - -ARCH=`uname -a` +DEST=`pwd`/../maple-ide-java/hardware/leaflabs/cores/maple FILES="LICENSE ./libmaple/*.h @@ -21,8 +19,8 @@ FILES="LICENSE ./wirish/*.cpp ./wirish/comm/*.cpp ./wirish/comm/*.h - ./support/ld/maple/ - ./support/ld/maple_native/ + ./support/ld/maple + ./support/ld/maple_native ./support/ld/libcs3-lanchon-stm32.a ./support/ld/names.inc" @@ -34,9 +32,9 @@ then exit -1 fi -echo "Then delete the old files..." -rm -r $DEST/*.c $DEST/*.cpp $DEST/*.h $DEST/*.cxx $DEST/*.ld $DEST/*.inc $DEST/*.a $DEST/maple/ $DEST/maple_native/ +echo "\nThen delete the old files..." +rm -r $DEST/*.c $DEST/*.cpp $DEST/*.h $DEST/*.cxx $DEST/*.inc $DEST/*.a $DEST/maple $DEST/maple_native -echo "Finally copy the new source files!" -cp -r $FILES $DEST +echo "\nFinally copy the new source files!" +cp -R $FILES $DEST echo "Done." diff --git a/wirish/HardwareTimer.cpp b/wirish/HardwareTimer.cpp index 92c6adf..354663e 100644 --- a/wirish/HardwareTimer.cpp +++ b/wirish/HardwareTimer.cpp @@ -221,7 +221,6 @@ HardwareTimer* getTimer(timer_dev_num timerNum) { return &Timer8; #endif default: - ASSERT(0); return 0; } } diff --git a/wirish/HardwareTimer.h b/wirish/HardwareTimer.h index c72175f..4034b1f 100644 --- a/wirish/HardwareTimer.h +++ b/wirish/HardwareTimer.h @@ -89,7 +89,7 @@ class HardwareTimer { * * Note that there is some function call overhead associated with * using this method, so using it in concert with - * HardwareTimer::resume() is not a robust way to align multiple + * HardwareTimer::pause() is not a robust way to align multiple * timers to the same count value. * * @see HardwareTimer::pause() @@ -103,7 +103,7 @@ class HardwareTimer { uint16 getPrescaleFactor(); /** - * Set the timer prescale. + * Set the timer's prescale factor. * * The prescaler acts as a clock divider to slow down the rate at * which the counter increments. @@ -155,7 +155,7 @@ class HardwareTimer { * Set the current timer count. * * Note that there is some function call overhead associated with - * callign this method, so using it is not a robust way to get + * calling this method, so using it is not a robust way to get * multiple timers to share a count value. * * @param val The new count value to set. If this value exceeds @@ -184,10 +184,6 @@ class HardwareTimer { /** * Set the given channel 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! - * * @param channel Timer channel, from 1 to 4 * @param mode Mode to set */ @@ -228,24 +224,24 @@ class HardwareTimer { */ uint16 getCompare(int channel); - /** Like getCompare(1) */ + /** Equivalent to getCompare(1) */ uint16 getCompare1(); - /** Like getCompare(2) */ + /** Equivalent to getCompare(2) */ uint16 getCompare2(); - /** Like getCompare(3) */ + /** Equivalent to getCompare(3) */ uint16 getCompare3(); - /** Like getCompare(4) */ + /** 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 channel 1 mode is TIMER_OUTPUTCOMPARE and - * an interrupt is attached. + * 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 @@ -259,32 +255,33 @@ class HardwareTimer { * few microseconds. * * @param channel the channel whose compare to set, from 1 to 4. - * @param val The compare value to set. If greater than this - * timer's overflow value, it will be truncated to the - * overflow value. + * @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 HardwareTimer::attachInterrupt() */ void setCompare(int channel, uint16 compare); /** - * Like setCompare(1, compare). + * Equivalent to setCompare(1, compare). */ void setCompare1(uint16 compare); /** - * Like setCompare(2, compare). + * Equivalent to setCompare(2, compare). */ void setCompare2(uint16 compare); /** - * Like setCompare(3, compare). + * Equivalent to setCompare(3, compare). */ void setCompare3(uint16 compare); /** - * Like setCompare(4, compare). + * Equivalent to setCompare(4, compare). */ void setCompare4(uint16 compare); @@ -313,25 +310,25 @@ class HardwareTimer { void attachInterrupt(int channel, voidFuncPtr handler); /** - * Like attachCompareInterrupt(1, handler). + * Equivalent to attachCompareInterrupt(1, handler). * @see HardwareTimer::attachCompareInterrupt() */ void attachCompare1Interrupt(voidFuncPtr handler); /** - * Like attachCompareInterrupt(2, handler). + * Equivalent to attachCompareInterrupt(2, handler). * @see HardwareTimer::attachCompareInterrupt() */ void attachCompare2Interrupt(voidFuncPtr handler); /** - * Like attachCompareInterrupt(3, handler). + * Equivalent to attachCompareInterrupt(3, handler). * @see HardwareTimer::attachCompareInterrupt() */ void attachCompare3Interrupt(voidFuncPtr handler); /** - * Like attachCompareInterrupt(4, handler). + * Equivalent to attachCompareInterrupt(4, handler). * @see HardwareTimer::attachCompareInterrupt() */ void attachCompare4Interrupt(voidFuncPtr handler); @@ -346,25 +343,25 @@ class HardwareTimer { void detachInterrupt(int channel); /** - * Like detachInterrupt(1). + * Equivalent to detachInterrupt(1). * @see HardwareTimer::detachInterrupt() */ void detachCompare1Interrupt(void); /** - * Like detachInterrupt(2). + * Equivalent to detachInterrupt(2). * @see HardwareTimer::detachInterrupt() */ void detachCompare2Interrupt(void); /** - * Like detachInterrupt(3). + * Equivalent to detachInterrupt(3). * @see HardwareTimer::detachInterrupt() */ void detachCompare3Interrupt(void); /** - * Like detachInterrupt(4). + * Equivalent to detachInterrupt(4). * @see HardwareTimer::detachInterrupt() */ void detachCompare4Interrupt(void); @@ -394,6 +391,22 @@ extern HardwareTimer Timer5; 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. + * + * @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. + * + * @see timer_dev_num + */ HardwareTimer* getTimer(timer_dev_num timerNum); #endif diff --git a/wirish/comm/HardwareSPI.h b/wirish/comm/HardwareSPI.h index 03d1ea1..7241d0b 100644 --- a/wirish/comm/HardwareSPI.h +++ b/wirish/comm/HardwareSPI.h @@ -29,18 +29,23 @@ #ifndef _HARDWARESPI_H_ #define _HARDWARESPI_H_ +/** + * Defines the possible SPI communication speeds. + */ typedef enum SPIFrequency { - SPI_18MHZ = 0, - SPI_9MHZ = 1, - SPI_4_5MHZ = 2, - SPI_2_25MHZ = 3, - SPI_1_125MHZ = 4, - SPI_562_500KHZ = 5, - SPI_281_250KHZ = 6, - SPI_140_625KHZ = 7, - MAX_SPI_FREQS = 8, + SPI_18MHZ = 0, /**< 18 MHz */ + SPI_9MHZ = 1, /**< 9 MHz */ + SPI_4_5MHZ = 2, /**< 4.5 MHz */ + SPI_2_25MHZ = 3, /**< 2.25 MHZ */ + SPI_1_125MHZ = 4, /**< 1.125 MHz */ + SPI_562_500KHZ = 5, /**< 562.500 KHz */ + SPI_281_250KHZ = 6, /**< 281.250 KHz */ + SPI_140_625KHZ = 7, /**< 140.625 KHz */ + MAX_SPI_FREQS = 8, /**< The number of SPI frequencies. */ } SPIFrequency; +/* Documented by hand in docs/source/lang/api/hardwarespi.rst; if you + make any changes, make sure to update this document. */ class HardwareSPI { private: uint32 spi_num; diff --git a/wirish/ext_interrupts.h b/wirish/ext_interrupts.h index 057c0d3..304e267 100644 --- a/wirish/ext_interrupts.h +++ b/wirish/ext_interrupts.h @@ -86,7 +86,7 @@ void detachInterrupt(uint8 pin); * * @see noInterrupts() */ -static inline __attribute__((always_inline)) void interrupts() { +static ALWAYS_INLINE void interrupts() { nvic_globalirq_enable(); } @@ -100,7 +100,7 @@ static inline __attribute__((always_inline)) void interrupts() { * * @see interrupts() */ -static inline __attribute__((always_inline)) void noInterrupts() { +static ALWAYS_INLINE void noInterrupts() { nvic_globalirq_disable(); } diff --git a/wirish/io.h b/wirish/io.h index 547dc8e..2d22dcd 100644 --- a/wirish/io.h +++ b/wirish/io.h @@ -145,7 +145,7 @@ void digitalWrite(uint8 pin, uint8 value); * @return LOW or HIGH. * @see pinMode() */ -uint32 digitalRead(uint8); +uint32 digitalRead(uint8 pin); /** * Read an analog value from pin. This function blocks during ADC diff --git a/wirish/wirish_math.h b/wirish/wirish_math.h index 4156722..14614ba 100644 --- a/wirish/wirish_math.h +++ b/wirish/wirish_math.h @@ -79,8 +79,10 @@ long random(long min, long max); * @return the mapped value. */ /* TODO: profile code bloat due to inlining this */ -inline long map(long x, long in_min, long in_max, long out_min, long out_max) { - return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; +inline long map(long value, long fromStart, long fromEnd, + long toStart, long toEnd) { + return (value - fromStart) * (toEnd - toStart) / (fromEnd - fromStart) + + toStart; } #define PI 3.1415926535897932384626433832795 |
