aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/troubleshooting.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/troubleshooting.rst')
-rw-r--r--docs/source/troubleshooting.rst275
1 files changed, 128 insertions, 147 deletions
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.