diff options
Diffstat (limited to 'docs/source/troubleshooting.rst')
| -rw-r--r-- | docs/source/troubleshooting.rst | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..4d7cbb0 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,258 @@ +.. highlight:: sh + +.. _troubleshooting: + +Troubleshooting +=============== + +This page documents common problems and their solutions. + +.. contents:: Contents + :local: + +=================== + Hardware problems +=================== + +.. _troubleshooting-throb: + +The LED is throbbing and my program is stopped! +----------------------------------------------- + +The LED throbs when there has been a failed software :ref:`ASSERT() +<lang-assert>` or some other error. + +In the case of a failed assertion, a first debugging step you can take +is to find out the file and line where the failed assertion took place +(for instructions on this, see the ``ASSERT()`` documentation linked +to above). This may give you some clue about the source of the error. + +:ref:`libmaple` often uses ``ASSERT()`` to halt immediately when it +detects that something has gone wrong, so if you're not using +assertions, then what's probably happening is that some bug is causing +the failed ``ASSERT()`` lower down. + +If it's not a failed assertion, then you're likely looking at +something like a `hard fault +<http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0337e/ch05s12s01.html>`_. + +There are a few issues with the bootloader which mean you might not be +able to upload your program when this happens. You can still +reprogram by using :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>`. + +My board is bricked! I can't upload via the bootloader no matter what! +---------------------------------------------------------------------- + +Don't panic. First, make sure that the board is plugged in correctly +for program upload, using the instructions given in the +:ref:`quickstart <maple-quickstart-upload>`. If that doesn't work, +try using :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>`. + +If that doesn't work, then you've got a problem. All is not lost, +however! You can always try to :ref:`re-flash the bootloader +<bootloader-reflashing>` over serial (or :ref:`JTAG <jtag>`). + +If your board 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:`Arduino Compatibility +<arduino-compatibility>`, :ref:`GPIO <gpio>`, or other :ref:`hardware +specific documentation <index-hardware>` for more information. + +The reset and D38/serial buttons don't seem to work reliably! +------------------------------------------------------------- + +A few Maple Rev3 boards shipped in May-June 2010 may have had +unreliable buttons; see the :ref:`Maple Errata +<maple-rev3-bad-buttons>` for details. `We're happy to replace these +for you <http://leaflabs.com/contact>`_\ ! + +.. _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. + +.. 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. + +.. TODO: be more helpful + +.. _troubleshooting-ide-usage: + +============== + IDE problems +============== + +[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! + +.. _troubleshooting-compilation: + +========================== + Common compiler problems +========================== + +``NullPointerException`` +------------------------ + +A classic! Make sure you have selected a board from the pulldown menu. + +``undefined reference to setup()/loop()`` +----------------------------------------- + +Your sketch/program either does not include one of the :ref:`setup() +<lang-setup>` or :ref:`loop() <lang-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. + +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>`. + +``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. + +.. _troubleshooting-upload: + +====================== +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. + +``No DFU capable USB device found`` +----------------------------------- + +This probably means the Maple isn't plugged in or powered on. Try +unplugging and plugging back in, 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 boards plugged in; how do I know which one will get programmed? +------------------------------------------------------------------------------- + +Because the Maple IDE uses DFU to upload programs, you can't select a +particular board to upload to. There's no solution to this problem +for now: you'll have to just plug in your boards 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; our Makefile isn't smart enough to rebuild everything for the +new target. + +My code uploads, but it doesn't work! +------------------------------------- + +Are you sure you have the right board selected? (Maple vs. Maple Mini, +etc.) + +.. _troubleshooting-shell: + +=================== +Command-Line Issues +=================== + +[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. + +The usual cause is using a serial port monitor and not closing it +before restarting the board or uploading a new program. The operating +system doesn't like that, and locks up that device. After reset, the +board 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 hacker solution is to restart your cdc_acm kernel module. On +Ubuntu 9.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 + +.. _troubleshooting-tips-tricks: + +=============== +Tips and Tricks +=============== + +.. _troubleshooting-perpetual-bootloader: + +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 +will be available for reprogramming. + +To put your Maple (or other Maple board) into perpetual bootloader mode: + +#. Plug your board into the USB port. + +#. Hit the reset button (it's the button labeled RESET). Notice that + your board blinks quickly 6 times, then blinks slowly a few more + times. + +#. Hit reset again, and this time push and hold the other button + during the 6 fast blinks (the normal button is labeled BUT). You + can release it once the slow blinks start. |