aboutsummaryrefslogtreecommitdiffstats
path: root/source/troubleshooting.rst
blob: 7fdfe17f97a3e341729d95cc84738f41088c0538 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
.. highlight:: sh

.. _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?

* :ref:`Command-line issues <troubleshooting-shell>`

  * 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``

* :ref:`Tips and tricks <troubleshooting-tips-tricks>`

  * Perpetual bootloader mode

.. _troubleshooting-hardware:

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>`.

    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>`.

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.

    .. 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>`_\ !

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.

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>`_\ !

.. _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 OSX] 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. 

    .. TODO: remove when Python version is released

``undefined reference to setup()/loop()``

    Your sketch/program either does not include one of the :ref:`setup
    <setup()>` or :ref:`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.

    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.

    .. TODO remove when the Python version is released

.. _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 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.

.. _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``

    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 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::

      $ 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 into perpetual bootloader mode:

1. 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.

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.