diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/adc.rst | 70 | ||||
| -rw-r--r-- | docs/source/bootloader.rst | 3 | ||||
| -rw-r--r-- | docs/source/compatibility.rst | 129 | ||||
| -rw-r--r-- | docs/source/conf.py | 22 | ||||
| -rw-r--r-- | docs/source/epilog.rst | 51 | ||||
| -rw-r--r-- | docs/source/errata.rst | 11 | ||||
| -rw-r--r-- | docs/source/gpio.rst | 89 | ||||
| -rw-r--r-- | docs/source/i2c.rst | 2 | ||||
| -rw-r--r-- | docs/source/language.rst | 53 | ||||
| -rw-r--r-- | docs/source/libmaple-api.rst | 1 | ||||
| -rw-r--r-- | docs/source/libmaple.rst | 2 | ||||
| -rw-r--r-- | docs/source/libraries.rst | 4 | ||||
| -rw-r--r-- | docs/source/maple-ide-install.rst | 3 | ||||
| -rw-r--r-- | docs/source/maple-quickstart.rst | 9 | ||||
| -rw-r--r-- | docs/source/prolog.rst | 7 | ||||
| -rw-r--r-- | docs/source/troubleshooting.rst | 275 |
16 files changed, 520 insertions, 211 deletions
diff --git a/docs/source/adc.rst b/docs/source/adc.rst index 17c672d..4e118aa 100644 --- a/docs/source/adc.rst +++ b/docs/source/adc.rst @@ -4,4 +4,72 @@ ADC ===== -Stub. +Analog-Digital Conversion is the process of reading a physical voltage +as a number. The Maple has a large number of pins which are capable of +taking 12-bit ADC measurements, which means that voltages from ground +to +3.3v are read as numbers from 0 to 4095; this corresponds to a +theoretical sensitivity of just under 1 millivolt. In reality, a +number of factors introduce noise and bias into this reading and a +number of techniques must be used to get good precision and accuracy. + +.. compound:: + + The header pins with ADC functionality (marked as "AIN" on the + silkscreen) are: + + D0, D1, D2, D3, D10, D11, D12, D13, D15, D16, D17, D18, D19, D20, D27, D28 + +.. contents:: Contents + :local: + +.. _adc-noise-bias: + +Noise and Bias +-------------- + +The biggest issues with analog-digital conversion are noise and bias. +With the Maple, we have tried to isolate the ADC pins and traces from +strong noise sources but there are always trade--offs between noise, +additional functionality, cost, and package size. + +The 6 ADC pins in a bank (D15--D20) generally have the least +noise and should be used for fine measurements. If the input voltage +changes relatively slowly, a number of samples can be taken in +succession and averaged together, or the same voltage can even be +sampled by multiple ADC pins at the same time. + +An important factor when taking a voltage reading is the reference +voltages that the sample is being compared against. In the case of the +Maple, the high reference is |vcc| and the low reference is ground. +This means that noise or fluctuations on either |vcc| or ground will +affect the measurement. It also means that the voltage you are trying +to sample must be between ground and 3.3V. In the case of a variable +reading, it is best if the voltage varies over the entire range of +0--3.3V; otherwise, only a fraction of the sensitivity is being +leveraged. Resistor dividers and constant voltage diodes are basic +tools which can help bring a given voltage signal into the appropriate +range; opamps and other powered components can also be used. + +.. _adc-function-reference: + +Function Reference +------------------ + +.. TODO function reference (figure out Doxygen first) + +.. _adc-recommended-reading: + +Recommended Reading +------------------- + +* `Wikipedia article on Analog-to-digital converter <http://en.wikipedia.org/wiki/Analog-to-digital_converter>`_ +* `Arduino Analog Input Tutorial <http://arduino.cc/en/Tutorial/AnalogInputPins>`_ +* STMicro documentation for STM32F103RB microcontroller: + + * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ + * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ + * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ + * `Application Note on ADC Modes (pdf) <http://www.st.com/stonline/products/literature/an/16840.pdf>`_ + * `Application Note on ADC Oversampling (pdf) <http://www.st.com/stonline/products/literature/an/14183.pdf>`_ + + diff --git a/docs/source/bootloader.rst b/docs/source/bootloader.rst index 9280c68..c4c5da2 100644 --- a/docs/source/bootloader.rst +++ b/docs/source/bootloader.rst @@ -15,6 +15,9 @@ Flash memory and only runs when the chip is reset). **Visit the github development project**: http://github.com/leaflabs/maple-bootloader +.. contents:: Contents + :local: + Bootloader Schemes Explained! ----------------------------- diff --git a/docs/source/compatibility.rst b/docs/source/compatibility.rst index aeed36b..6166ec5 100644 --- a/docs/source/compatibility.rst +++ b/docs/source/compatibility.rst @@ -1,7 +1,136 @@ +.. highlight:: cpp + .. _compatibility: ============================= Maple-Arduino Compatibility ============================= +.. contents:: Contents + :local: + +Overview +-------- + +The biggest difference between the Maple and most Arduino boards is +that the Maple uses a 32-bit ARM Cortex-M3 architecture chip while the +Arduinos have 8-bit Atmel AVR chips. The different instruction set +means that machine code (executable binary programs) is incompatible +between the two, and a different compiler (actually just a different +version of `gcc <http://gcc.gnu.org/>`_) is required. The compiler for +the regular Arduino IDE is the popular :command:`avr-gcc` package; the +compiler for the Maple version of the IDE is CodeSourcery's edition of +gcc for the ARM EABI target (:command:`arm-non-eabi-gcc`). + +The bitwidth of the processor means that the Maple can process 32-bit +operations (like adding two 32-bit integers) in a single instruction, +while an Arduino processor would have to split up large operations +into several smaller ones. In a lot of cases 8-bit operations are +plenty (integers 0-255, single characters of text, etc.), but if +you're dealing with higher resolution data, the speed up could be +significant. A trade-off is that code could be larger as well; program +instructions and memory locations can be up to 32-bits each, which in +the worst case would quadruple program size. In reality, the removal +of extra instructions and fancy packing together of simple +instructions means that programs aren't much larger (or are even +smaller). + +Header Numbering and Incompatibilities +-------------------------------------- + +The numbering of headers is different; on the Maple each GPIO has a +unique number: D0, D1, D2, all the way up to D37 (actually, there are +:ref:`a few more <jtag>`...). On the Arduino, the analog pins are +numbered separately (A0-A5) from the digital pins (D0\ -D13). + +The incompatible hardware differences are: + +* |i2c| port: on most Arduinos, the |i2c| port is Analog Input + 4 (SDA) and Analog Input 5 (SCL); on the Maple, |i2c| port 1 is D5 + (SCL) and D9 (SDA), and |i2c| port 2 is D29 (SCL) and D30 (SDA). + + It should be possible to skywire, sacrificing signal quality (due to + increased capacitance). Alternatively, |i2c| can be bit-banged + reasonably well in software. This peripheral could potentially be + rerouted internally, but we haven't looked into it. + +* :ref:`PWM <pwm>` on D10: all the other standard Arduino PWM headers have PWM + functionality on the Maple (D2,D3,D6,D9,D11), but not D10. We did + our best! It may be possible to reroute this peripheral internally + using low level configuration, but we haven't looked in to it. + +* No External Voltage Reference: The Arduino has an Aref pin which + allows the use of an external ADC voltage reference; the Maple has + an extra GPIO pin (14) with PWM capability in this spot, and does + not allow an external voltage reference to be configured. + +* EEPROM: the Maple does not have any internal EEPROM. This + functionality can be emulated with regular persistent flash memory, + or with an external EEPROM chip. + +* ISP Programming: the Maple does not use an ISP/ICSP bus for + debugging; it uses :ref:`JTAG <jtag>`. + + +Software Language/Library Changes +--------------------------------- + +With :ref:`one notable exception <language-no-word>`, the entire +Arduino language is supported. However, there are some subtle +differences, most of which are improvements: + +* 32-bit integers: many standard functions either expect or return + full 32-bit (4 byte) integer values instead of the regular 16-bit (2 + byte) Arduino values. + +* `pinMode()`_ types: any :ref:`GPIO <gpio>` (including analog pins) + can be configured into one of the following modes with a single call + to `pinMode()`_: ``OUTPUT``, ``OUTPUT_OPEN_DRAIN``, + ``INPUT_FLOATING``, ``INPUT_PULLUP``, + ``INPUT_PULLDOWN``. Additionally, the PWM and Analog Input pins can + be configured as ``INPUT_ANALOG`` and ``PWM`` respectively. See the + :ref:`GPIO documentation <gpio>` for more information. + + .. TODO: reference libmaple docs above when they're done + +* Serial1 syntax: like the `Arduino Mega + <http://arduino.cc/en/Main/ArduinoBoardMega>`_, the Maple has + multiple USART ports. By default, Serial is not mapped to any of + them, use ``Serial1`` through ``Serial3`` instead. + + .. TODO: reference libmaple docs for Serial[n] above when they're done + +* 16-bit :ref:`PWM <pwm>`: Arduino boards support 8-bit PWM, which + means that calls to `analogWrite()`_ take values between 0 (always + off) and 255 (always on). The Maple supports 16-bit PWM, so the + corresponding values should be between 0 (always off) and 65535 + (always on). + +* 12-bit :ref:`ADC <adc>`: Arduino boards support 10-bit ADC, which + means that calls to `analogRead()`_ will return values between 0 and + 1023. The Maple supports 12-bit ADC, so the same call will instead + return values between 0 and 4095. + + +.. class:: ported-feature + +I am supported! + +This should be ordinary + +.. class:: non-ported-feature + +I can't do it :( + +Also ordinary + +.. class:: partly-ported-feature + +I sorta work + +And I am also ordinary + Stub. + +(not finished) + diff --git a/docs/source/conf.py b/docs/source/conf.py index 5fcb939..26147fd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,7 +17,11 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +# +# We rely on Michael Jones's breathe as a Doxygen-to-Sphinx bridge. +# See libmaple/docs/README for information on obtaining it and letting +# Sphinx know where it is. +sys.path.append(os.environ['BREATHE_HOME']) # -- General configuration ---------------------------------------------------- @@ -29,7 +33,7 @@ import sys, os # ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', - 'sphinx.ext.coverage'] + 'sphinx.ext.coverage', 'breathe'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -68,12 +72,16 @@ release = '0.0.7' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['epilog.rst'] +exclude_patterns = ['epilog.rst', 'prolog.rst'] # Included at the end of every source file that is read. with open('epilog.rst', 'r') as ep: rst_epilog = ep.read() +# Included at the beginning of every source file that is read. +with open('prolog.rst', 'r') as pr: + rst_prolog = pr.read() + # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None @@ -229,3 +237,11 @@ man_pages = [ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} + + +# -- Options for breathe integration ------------------------------------------ + +breathe_projects = {'libmaple' : os.path.join(os.environ['LIB_MAPLE_HOME'], + 'docs', 'doxygen', 'xml')} + +breathe_default_project = 'libmaple' diff --git a/docs/source/epilog.rst b/docs/source/epilog.rst index 0e430c8..7805362 100644 --- a/docs/source/epilog.rst +++ b/docs/source/epilog.rst @@ -4,5 +4,56 @@ .. Common URL references .. _forum: http://forums.leaflabs.com .. _contact: http://leaflabs.com/contact/ + + +.. Arduino built-in functions .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop + +.. _pinMode(): http://arduino.cc/en/Reference/PinMode +.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite +.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead + +.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference +.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead +.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite + +.. _tone(): http://arduino.cc/en/Reference/Tone +.. _noTone(): http://arduino.cc/en/Reference/NoTone +.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut +.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn + +.. _millis(): http://arduino.cc/en/Reference/Millis +.. _micros(): http://arduino.cc/en/Reference/Micros +.. _delay(): http://arduino.cc/en/Reference/Delay +.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds + +.. _min(): http://arduino.cc/en/Reference/Min +.. _max(): http://arduino.cc/en/Reference/Max +.. _abs(): http://arduino.cc/en/Reference/Abs +.. _constrain(): http://arduino.cc/en/Reference/Constrain + +.. _map(): http://arduino.cc/en/Reference/Map +.. _pow(): http://arduino.cc/en/Reference/Pow +.. _sqrt(): http://arduino.cc/en/Reference/Sqrt + +.. _sin(): http://arduino.cc/en/Reference/Sin +.. _cos(): http://arduino.cc/en/Reference/Cos +.. _tan(): http://arduino.cc/en/Reference/Tan + +.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed +.. _random(): http://arduino.cc/en/Reference/Random + +.. _lowByte(): http://arduino.cc/en/Reference/LowByte +.. _highByte(): http://arduino.cc/en/Reference/HighByte +.. _bitRead(): http://arduino.cc/en/Reference/BitRead +.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite +.. _bitSet(): http://arduino.cc/en/Reference/BitSet +.. _bitClear(): http://arduino.cc/en/Reference/BitClear +.. _bit(): http://arduino.cc/en/Reference/Bit + +.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt +.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt + +.. _interrupts(): http://arduino.cc/en/Reference/Interrupts +.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts diff --git a/docs/source/errata.rst b/docs/source/errata.rst index b702bd1..09b2ad1 100644 --- a/docs/source/errata.rst +++ b/docs/source/errata.rst @@ -4,4 +4,15 @@ Errata ======== +This page is a collection of known issues and warnings for each +revision of the Maple board. The failure modes aren't design errors, +but are easy ways to break or damage your board permanently. For a +list of differences between the Maple and Arduinos, see the page on +:ref:`compatibility <compatibility>`. + +.. contents:: Contents + :local: + Stub. + +(not finished) diff --git a/docs/source/gpio.rst b/docs/source/gpio.rst index f608a61..2567221 100644 --- a/docs/source/gpio.rst +++ b/docs/source/gpio.rst @@ -4,4 +4,91 @@ GPIO ====== -Stub. +The Maple features 38 ready-to-use general purpose input/output (GPIO) +pins for digital input/output, numbered D0 through D37. These numbers +correspond to the numeric values next to each header on the Maple +silkscreen. + +Many of these pins may additionally be used for special features or +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. + +.. contents:: Contents + :local: + +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). + +.. csv-table:: + :header: "Pin", "STM32", ":ref:`ADC <adc>`", ":ref:`Timer <timers>`", ":ref:`I2C <i2c>`", ":ref:`UART <usart>`", ":ref:`SPI <spi>`", "5v?" + + "D0", "PA3", "ADC3", "TIM2_CH4", "-", "USART2_RX", "-", "No" + "D1", "PA2", "ADC2", "TIM2_CH3", "-", "USART2_TX", "-", "No" + "D2", "PA0", "ADC0", "TIM2_CH1_ETR", "-", "USART2_CTS", "-", "No" + "D3", "PA1", "ADC1", "TIM2_CH2", "-", "USART2_RTS", "-", "No" + "D4", "PB5", "-", "-", "ISC1_SMBA", "-", "-", "No" + "D5", "PB6", "-", "TIM4_CH1", "I2C1_SCL", "-", "-", "Yes" + "D6", "PA8", "-", "TIM1_CH1", "-", "USART1_CK", "-", "Yes" + "D7", "PA9", "-", "TIM1_CH2", "-", "USART1_TX", "-", "Yes" + "D8", "PA10", "-", "TIM1_CH3", "-", "USART1_RX", "-", "Yes" + "D9", "PB7", "-", "TIM4_CH2", "I2C1_SDA", "-", "-", "Yes" + "D10", "PA4", "ADC4", "-", "-", "USART2_CK", "SPI1_NSS", "No" + "D11", "PA7", "ADC7", "TIM3_CH2", "-", "-", "SPI1_MOSI", "No" + "D12", "PA6", "ADC6", "TIM3_CH1", - - SPI1_MISO No + D13 PA5 ADC5 - - - SPI1_SCK No + D14 PB8 - TIM4_CH3 - - - Yes + + Analog header + + D15 PC0 ADC10 - - - - No + D16 PC1 ADC11 - - - - No + D17 PC2 ADC12 - - - - No + D18 PC3 ADC13 - - - - No + D19 PC4 ADC14 - - - - No + D20 PC5 ADC15 - - - - No + + External header + + D21 PC13 - - - - - No + D22 PC14 - - - - - No + D23 PC15 - - - - - No + D24 PB9 - TIM4_CH4 - - - Yes + D25 PD2 - TIM3_ETR - - - Yes + D26 PC10 - - - - - Yes + D27 PB0 ADC8 TIM3_CH3 - - - No + D28 PB1 ADC9 TIM3_CH4 - - - No + D29 PB10 - - I2C2_SCL USART3_TX - Yes + D30 PB11 - - I2C2_SDA USART3_RX - Yes + D31 PB12 - TIM1_BKIN I2C2_SMBAL USART3_CK SPI2_NSS Yes + D32 PB13 - TIM1_CH1N - USART3_CTS SPI2_SCK Yes + D33 PB14 - TIM1_CH2N - USART3_RTS SPI2_MISO Yes + D34 PB15 - TIM1_CH3N - - SPI2_MOSI Yes + D35 PC6 - - - - - Yes + D36 PC7 - - - - - Yes + D37 PC8 - - - - - + + +Stub (unfinished). + +.. _gpio-recommended-reading: + +Recommended Reading +------------------- + +STMicro documentation for STM32F103RB microcontroller: + + * `All <http://www.st.com/mcu/devicedocs-STM32F103RB-110.html>`_ + * `Datasheet (pdf) <http://www.st.com/stonline/products/literature/ds/13587.pdf>`_ + * `Reference Manual (pdf) <http://www.st.com/stonline/products/literature/rm/13902.pdf>`_ diff --git a/docs/source/i2c.rst b/docs/source/i2c.rst index e0444eb..34bd57c 100644 --- a/docs/source/i2c.rst +++ b/docs/source/i2c.rst @@ -4,6 +4,4 @@ |i2c| ===== -.. |i2c| replace:: I\ :sup:`2`\ C - Stub. diff --git a/docs/source/language.rst b/docs/source/language.rst index 8115d6b..6eb5bc7 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -24,6 +24,9 @@ C or C++ programmers curious about the differences between the Wiring language and C++ may wish to skip to the :ref:`arduino_c_for_c_hackers`. +.. contents:: Contents + :local: + Unique Maple Additions ---------------------- @@ -308,59 +311,15 @@ Arduino Documentation Links .. _const: http://arduino.cc/en/Reference/Const .. _sizeof(): http://arduino.cc/en/Reference/Sizeof -.. _pinMode(): http://arduino.cc/en/Reference/PinMode -.. _digitalWrite(): http://arduino.cc/en/Reference/DigitalWrite -.. _digitalRead(): http://arduino.cc/en/Reference/DigitalRead - -.. _analogReference(): http://arduino.cc/en/Reference/AnalogReference -.. _analogRead(): http://arduino.cc/en/Reference/AnalogRead -.. _analogWrite(): http://arduino.cc/en/Reference/AnalogWrite - -.. _tone(): http://arduino.cc/en/Reference/Tone -.. _noTone(): http://arduino.cc/en/Reference/NoTone -.. _shiftOut(): http://arduino.cc/en/Reference/ShiftOut -.. _pulseIn(): http://arduino.cc/en/Reference/PulseIn - -.. _millis(): http://arduino.cc/en/Reference/Millis -.. _micros(): http://arduino.cc/en/Reference/Micros -.. _delay(): http://arduino.cc/en/Reference/Delay -.. _delayMicroseconds(): http://arduino.cc/en/Reference/DelayMicroseconds - -.. _min(): http://arduino.cc/en/Reference/Min -.. _max(): http://arduino.cc/en/Reference/Max -.. _abs(): http://arduino.cc/en/Reference/Abs -.. _constrain(): http://arduino.cc/en/Reference/Constrain - -.. _map(): http://arduino.cc/en/Reference/Map -.. _pow(): http://arduino.cc/en/Reference/Pow -.. _sqrt(): http://arduino.cc/en/Reference/Sqrt - -.. _sin(): http://arduino.cc/en/Reference/Sin -.. _cos(): http://arduino.cc/en/Reference/Cos -.. _tan(): http://arduino.cc/en/Reference/Tan - -.. _randomSeed(): http://arduino.cc/en/Reference/RandomSeed -.. _random(): http://arduino.cc/en/Reference/Random - -.. _lowByte(): http://arduino.cc/en/Reference/LowByte -.. _highByte(): http://arduino.cc/en/Reference/HighByte -.. _bitRead(): http://arduino.cc/en/Reference/BitRead -.. _bitWrite(): http://arduino.cc/en/Reference/BitWrite -.. _bitSet(): http://arduino.cc/en/Reference/BitSet -.. _bitClear(): http://arduino.cc/en/Reference/BitClear -.. _bit(): http://arduino.cc/en/Reference/Bit - +.. Links for the standard Arduino built-in functions are included as +.. part of the standard epilog. .. _our reference page: http://leaflabs.com/docs/external-interrupts/ -.. _attachInterrupt(): http://arduino.cc/en/Reference/AttachInterrupt -.. _detachInterrupt(): http://arduino.cc/en/Reference/DetachInterrupt - -.. _interrupts(): http://arduino.cc/en/Reference/Interrupts -.. _noInterrupts(): http://arduino.cc/en/Reference/NoInterrupts .. _Serial: http://arduino.cc/en/Reference/Serial .. _community-contributed code: http://www.arduino.cc/playground/Main/GeneralCodeLibrary .. _newlib: http://sourceware.org/newlib/ + .. _arduino_c_for_c_hackers: Note for C/C++ Programmers diff --git a/docs/source/libmaple-api.rst b/docs/source/libmaple-api.rst index af283cb..d5b90b6 100644 --- a/docs/source/libmaple-api.rst +++ b/docs/source/libmaple-api.rst @@ -8,3 +8,4 @@ This page documents the lower-level features of libmaple, which may be of use to programmers who don't wish to use the Arduino-style environment provided by the `Maple IDE <maple-ide-install>`_. +Stub. diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst index 620fdfa..a018cd7 100644 --- a/docs/source/libmaple.rst +++ b/docs/source/libmaple.rst @@ -30,6 +30,8 @@ wrappers and code to imitate the Arduino programming library. git clone git://github.com/leaflabs/libmaple.git +**Table of contents:** + .. toctree:: :maxdepth: 2 diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index c2d5cb0..6a97b0e 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -15,8 +15,8 @@ library you want. Any incompatibilities between the Maple and Arduino versions are noted in the description of the library. -* :ref:`LiquidCrystal <liquid_crystal>` -* :ref:`Wire <wire>` +.. contents:: Contents + :local: .. _liquid_crystal: diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst index 46c903b..3c3fffe 100644 --- a/docs/source/maple-ide-install.rst +++ b/docs/source/maple-ide-install.rst @@ -11,7 +11,8 @@ check the :ref:`troubleshooting page <troubleshooting>` for help with some common problems. If all else fails, try our `forum`_, or `contact us directly <http://leaflabs.com/contact>`_! -.. _forum: http://forums.leaflabs.com +.. contents:: Contents + :local: Download -------- diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst index 20d84a0..4d646d7 100644 --- a/docs/source/maple-quickstart.rst +++ b/docs/source/maple-quickstart.rst @@ -15,13 +15,8 @@ If you have trouble along the way, try the :ref:`troubleshooting page <troubleshooting>` for help with some common problems. If all else fails, try our `forum`_, or `contact us directly <contact>`_! -The steps are: - -* :ref:`Install and run the IDE <maple-quickstart-get-ide>` - -* :ref:`Compile and upload a program <maple-quickstart-compile-blinky>` - -* :ref:`Test the USB serial connection <maple-quickstart-serial-port>` +.. contents:: Contents + :local: .. _maple-quickstart-get-ide: diff --git a/docs/source/prolog.rst b/docs/source/prolog.rst new file mode 100644 index 0000000..2823947 --- /dev/null +++ b/docs/source/prolog.rst @@ -0,0 +1,7 @@ +.. Additions to this file will be included at the beginning of every +.. .rst file. DO NOT USE IT to insert a header; this is not +.. recommended by the Sphinx people, who have other ways of doing it. + +.. Common substitutions +.. |vcc| replace:: V\ :sub:`cc` +.. |i2c| replace:: I\ :sup:`2`\ C diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index b878ae4..9d452d1 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -2,231 +2,212 @@ .. _troubleshooting: -======================= - Maple Troubleshooting -======================= - -* :ref:`Hardware Problems <troubleshooting-hardware>` - - * The status LED is throbbing and I can't upload my program! - * My board is bricked! I can't upload via the bootloader no matter what! - * My 5v peripheral doesn't work! (I2C, SPI, USART, etc) - * The reset and D38/serial buttons don't seem to work reliably! - -* :ref:`IDE installation problems <troubleshooting-ide-install>` - - * I don't have root/administrator access! - * [Linux] I don't use udev! - -* :ref:`IDE usage problems <troubleshooting-ide-usage>` - - * [Mac OSX] The "Board" and "Serial Port" menu items are missing! - -* :ref:`Common compiler problems <troubleshooting-compilation>` - - * ``NullPointerException`` - * ``undefined reference to setup()/loop()`` - * ``error: 'Serial' was not declared in this scope`` - * ``File(s) not found`` - -* :ref:`Common upload problems <troubleshooting-upload>` - - * My program is too large! - * ``No DFU capable USB device found`` - * I have multiple Maples installed; how do I know which one will get flashed? +Troubleshooting +=============== -* :ref:`Command-line issues <troubleshooting-shell>` +This page documents common problems and their solutions. - * My flash programs don't seem to stick; they behave like they are RAM! - * [Linux] ``cdc_acm 3-1:1.0: no more free acm devices`` +.. contents:: Contents + :local: -* :ref:`Tips and tricks <troubleshooting-tips-tricks>` - - * Perpetual bootloader mode - -.. _troubleshooting-hardware: - -Hardware problems ------------------ +=================== + Hardware problems +=================== The status LED is throbbing and I can't upload my program! +---------------------------------------------------------- - The LED throbs when there has been a failed software - :ref:`assertion <language-assert>`. +The LED throbs when there has been a failed software :ref:`assertion +<language-assert>`. - You can still reprogram by resetting the board and uploading - during the short window when the bootloader waits for a - program. +You can still reprogram by resetting the board and uploading during +the short window when the bootloader waits for a program. - To make this window longer (it can be hard to get the timing - right), use :ref:`perpetual bootloader mode - <troubleshooting-perpetual-bootloader>`. +To make this window longer (it can be hard to get the timing right), +use :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>`. My board is bricked! I can't upload via the bootloader no matter what! +---------------------------------------------------------------------- - Use the hardcoded serial STM32 serial bootloader to re-flash the - bootloader. +Use the hardcoded serial STM32 serial bootloader to re-flash the +bootloader. - .. TODO insert docs on reflashing the bootloader +.. TODO insert docs on reflashing the bootloader - If it really is bricked, and you think it's our fault, - `contact us <http://leaflabs.com/contact>`_\ ! +If it really is bricked, and you think it's our fault, `contact us +<http://leaflabs.com/contact>`_\ ! My 5v peripheral doesn't work! (I2C, SPI, USART, etc) +----------------------------------------------------- - Yup, the Maple is a 3.3v board. You may need to use a level - converter. See the :ref:`compatibility <compatibility>`, - :ref:`GPIO <gpio>`, or other :ref:`hardware specific documentation - <hardware>` for more information. +Yup, the Maple is a 3.3v board. You may need to use a level +converter. See the :ref:`compatibility <compatibility>`, :ref:`GPIO +<gpio>`, or other :ref:`hardware specific documentation <hardware>` +for more information. The reset and D38/serial buttons don't seem to work reliably! +------------------------------------------------------------- - A few rev3 boards shipped in May-June 2010 may have had unreliable - buttons; see the :ref:`errata page <errata>` for details. `We're - happy to replace these for you <http://leaflabs.com/contact>`_\ ! +A few rev3 boards shipped in May-June 2010 may have had unreliable +buttons; see the :ref:`errata page <errata>` for details. `We're +happy to replace these for you <http://leaflabs.com/contact>`_\ ! -.. _troubleshooting-ide-install: -Installation problems ---------------------- +.. _troubleshooting-ide-install: +======================= + Installation problems +======================= I don't have root/administrator access! +--------------------------------------- - There are probably hacks or work-arounds to getting programs - uploaded without higher level system permissions. If you can - access USB character devices (ACM or ttyUSB style), you should be - able to communicate with the Maple and reprogram using an FTDI - converter and the serial bootloader, but we haven't tried. +There are probably hacks or work-arounds to getting programs uploaded +without higher level system permissions. If you can access USB +character devices (ACM or ttyUSB style), you should be able to +communicate with the Maple and reprogram using an FTDI converter and +the serial bootloader, but we haven't tried. - .. TODO: be more helpful +.. TODO: be more helpful [Linux] I don't use udev! +------------------------- - There is probably a simple way to get autoconfiguration working - with devfs; in the meantime, you could try running the entire IDE - as root. +There is probably a simple way to get autoconfiguration working with +devfs; in the meantime, you could try running the entire IDE as root. - .. TODO: be more helpful +.. TODO: be more helpful .. _troubleshooting-ide-usage: -IDE problems ------------- +============== + IDE problems +============== -[Mac OSX] The "Board" and "Serial Port" menu items are missing! +[Mac OS X] The "Board" and "Serial Port" menu items are missing! +---------------------------------------------------------------- - Sometimes this happens if you try to compile or upload without - having a board selected. The work-around is to restart the - IDE. Mysterious! +Sometimes this happens if you try to compile or upload without having +a board selected. The work-around is to restart the IDE. Mysterious! .. _troubleshooting-compilation: -Common compiler problems ------------------------- +========================== + Common compiler problems +========================== ``NullPointerException`` +------------------------ - A classic! Make sure you have selected a board from the pulldown menu. +A classic! Make sure you have selected a board from the pulldown menu. - .. TODO: remove when Python version is released +.. TODO: remove when Python version is released ``undefined reference to setup()/loop()`` +----------------------------------------- - Your sketch/program either does not include one of the `setup - <setup()>`_ or `loop <loop()>`_ functions, or it was not found by - the compiler. Your program must include both ``void setup()`` and - ``void loop()`` functions; they don't have to do anything, but - they **must** be there. +Your sketch/program either does not include one of the `setup +<setup()>`_ or `loop <loop()>`_ functions, or it was not found by the +compiler. Your program must include both ``void setup()`` and ``void +loop()`` functions; they don't have to do anything, but they **must** +be there. - You can start with an example program (to see one in the IDE, - click on File > Examples > Stubs > BareMinimum) to get the basic - structure. See also the :ref:`language <language>` documentation. +You can start with an example program (to see one in the IDE, click on +File > Examples > Stubs > BareMinimum) to get the basic structure. +See also the :ref:`language <language>` documentation. - This is a common error when your entire sketch is blank. +This is a common error when your entire sketch is blank. ``error: 'Serial' was not declared in this scope`` +-------------------------------------------------- - The classic Arduino has only one USART device and uses the unique - name "Serial" to control it. Larger devices like the Arduino Mega - and the Maple have multiple USARTS referred to as ``Serial1``, - ``Serial2``, etc. You probably want ``Serial2`` on the Maple; - that's the one connected to pins D0 and D1. See also the - :ref:`USART docs <usart>`. +The classic Arduino has only one USART device and uses the unique name +"Serial" to control it. Larger devices like the Arduino Mega and the +Maple have multiple USARTS referred to as ``Serial1``, ``Serial2``, +etc. You probably want ``Serial2`` on the Maple; that's the one +connected to pins D0 and D1. See also the :ref:`USART docs <usart>`. ``File(s) not found`` +--------------------- - There is an intermittent bug with the temporary directory build - system that on occasion will lose many of the ``#include``\ d - libmaple files. If you recompile everything, it should be fine. +There is an intermittent bug with the temporary directory build system +that on occasion will lose many of the ``#include``\ d libmaple +files. If you recompile everything, it should be fine. - .. TODO remove when the Python version is released +.. TODO remove when the Python version is released .. _troubleshooting-upload: -Common upload problems ----------------------- +======================== + Common upload problems +======================== My program is too large! +------------------------ - First, make sure you're using the FLASH target instead of RAM; - there is several times more FLASH memory available for user - programs. +First, make sure you're using the FLASH target instead of RAM; there +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! I have multiple Maples installed; how do I know which one will get flashed? +--------------------------------------------------------------------------- - Because the Maple IDE uses DFU to upload programs, you can't - select a particular Maple from the Serial Port menu to upload to a - particular 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. +Because the Maple IDE uses DFU to upload programs, you can't select a +particular Maple from the Serial Port menu to upload to a particular +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. .. _troubleshooting-shell: -Command-line issues -------------------- +===================== + 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. +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`` +----------------------------------------------------- - This is a nasty one! It means that all 32 possible CDC_ACM serial - devices (:file:`/dev/ttyACM25`, etc.) have been used up. +This is a nasty one! It means that all 32 possible CDC_ACM serial +devices (:file:`/dev/ttyACM25`, etc.) have been used up. - The usual cause is using a serial port monitor and not closing it - before restarting the Maple or uploading a new program. The - operating system doesn't like that, and locks up that - device. After reset the Maple comes back up as a new device. If - you develop heavily and don't restart you'll blow right through - all 32 devices. +The usual cause is using a serial port monitor and not closing it +before restarting the Maple or uploading a new program. The operating +system doesn't like that, and locks up that device. After reset the +Maple comes back up as a new device. If you develop heavily and don't +restart you'll blow right through all 32 devices. - The lazy solution is to always close the monitor before - restarting, and if you get this error in :file:`dmesg` after a - dfu-util "Not Found" error, restart you machine. +The lazy solution is to always close the monitor before restarting, +and if you get this error in :file:`dmesg` after a dfu-util "Not +Found" error, restart you machine. - The hacker solution is to restart your cdc_acm kernel module. On - Ubuntu 09.10, this goes a little something like:: +The hacker solution is to restart your cdc_acm kernel module. On +Ubuntu 09.10, this goes a little something like:: - $ sudo rmmod cdc-acm - $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko + $ sudo rmmod cdc-acm + $ sudo insmod /lib/modules/2.6.31-20-generic/kernel/drivers/usb/class/cdc-acm.ko .. _troubleshooting-tips-tricks: -Tips and Tricks ---------------- +================= + Tips and Tricks +================= .. _troubleshooting-perpetual-bootloader: -**Perpetual Bootloader Mode** +Perpetual Bootloader Mode +------------------------- In this mode, Maple stays a DFU device and does not jump to user code until the next reset. This is useful for guaranteeing that your Maple @@ -234,13 +215,13 @@ will be available for reprogramming. To put your Maple into perpetual bootloader mode: -1. Plug your Maple into the USB port. +#. Plug your Maple into the USB port. -2. Hit the reset button on your Maple (it's the small button at the -bottom left, labeled RESET). Notice that it blinks quickly 6 times, -then blinks slowly a few more times. +#. Hit the reset button on your Maple (it's the small button at the + bottom left, labeled RESET). Notice that it blinks quickly 6 + times, then blinks slowly a few more times. -3. Hit reset again, and this time push and hold the other button -during the 6 fast blinks (the button is on the top right; it is -labeled BUT). You can release it once the slow blinks start. +#. Hit reset again, and this time push and hold the other button + during the 6 fast blinks (the button is on the top right; it is + labeled BUT). You can release it once the slow blinks start. |