diff options
| author | Marti Bolivar <mbolivar@mit.edu> | 2010-10-08 22:07:53 -0400 |
|---|---|---|
| committer | Marti Bolivar <mbolivar@mit.edu> | 2010-10-08 22:07:53 -0400 |
| commit | 20b3718c015db98433da121485fa6bb7ab88faa7 (patch) | |
| tree | 6a75283ab9d705e6309bdcce2c7487c612b1ea87 | |
| parent | 2eb7dee002654d645a84cbb5c1e88aad7c45528d (diff) | |
| download | librambutan-20b3718c015db98433da121485fa6bb7ab88faa7.tar.gz librambutan-20b3718c015db98433da121485fa6bb7ab88faa7.zip | |
current Maple documentation either rewritten or stubbed out in Sphinx
29 files changed, 832 insertions, 224 deletions
diff --git a/source/_static/img/blinky-to-flash.png b/source/_static/img/blinky-to-flash.png Binary files differindex 0320c5b..0320c5b 100755..100644 --- a/source/_static/img/blinky-to-flash.png +++ b/source/_static/img/blinky-to-flash.png diff --git a/source/_static/img/blinky.png b/source/_static/img/blinky.png Binary files differindex bda4cee..bda4cee 100755..100644 --- a/source/_static/img/blinky.png +++ b/source/_static/img/blinky.png diff --git a/source/_static/img/osx-network-prefs-unconfigured.png b/source/_static/img/osx-network-prefs-unconfigured.png Binary files differnew file mode 100644 index 0000000..70d2fa0 --- /dev/null +++ b/source/_static/img/osx-network-prefs-unconfigured.png diff --git a/source/_static/img/osx-unconfigured-popup.png b/source/_static/img/osx-unconfigured-popup.png Binary files differnew file mode 100644 index 0000000..a43ad57 --- /dev/null +++ b/source/_static/img/osx-unconfigured-popup.png diff --git a/source/_static/img/serial-port-mac.png b/source/_static/img/serial-port-mac.png Binary files differnew file mode 100644 index 0000000..b3a1989 --- /dev/null +++ b/source/_static/img/serial-port-mac.png diff --git a/source/_static/img/serial-port-ubuntu.png b/source/_static/img/serial-port-ubuntu.png Binary files differnew file mode 100644 index 0000000..8038e41 --- /dev/null +++ b/source/_static/img/serial-port-ubuntu.png diff --git a/source/_static/img/serial-port-win.png b/source/_static/img/serial-port-win.png Binary files differnew file mode 100644 index 0000000..90dc1c4 --- /dev/null +++ b/source/_static/img/serial-port-win.png diff --git a/source/_static/img/upload-button.png b/source/_static/img/upload-button.png Binary files differnew file mode 100644 index 0000000..20a663f --- /dev/null +++ b/source/_static/img/upload-button.png diff --git a/source/_static/img/verify-success.png b/source/_static/img/verify-success.png Binary files differindex 6928674..6928674 100755..100644 --- a/source/_static/img/verify-success.png +++ b/source/_static/img/verify-success.png diff --git a/source/adc.rst b/source/adc.rst new file mode 100644 index 0000000..17c672d --- /dev/null +++ b/source/adc.rst @@ -0,0 +1,7 @@ +.. _adc: + +===== + ADC +===== + +Stub. diff --git a/source/bootloader.rst b/source/bootloader.rst index f893e1e..17cd34b 100644 --- a/source/bootloader.rst +++ b/source/bootloader.rst @@ -1,5 +1,129 @@ +.. highlight:: sh + ================== Maple Bootloader ================== -stub +The firmware which allows the Maple to be reprogrammed via a USB +connection. Every Maple board comes programmed with this by default, +and it is not overwritten by regular programs (it lives lower in the +Flash memory and only runs when the chip is reset). + +**Check out the latest source code version:** :: + + git clone git://github.com/leaflabs/maple-bootloader.git + +**Visit the github development project**: http://github.com/leaflabs/maple-bootloader + +Bootloader Schemes Explained! +----------------------------- + +Maple Rev 3 (the version currently shipping) represents a drastic +remake of the core library as well as the upload process. Some of +these changes are aesthetic, refactoring and reorganization. Some are +performance minded. The changes to the bootloader, however, were +implemented to solve some really gritty cross platform issues. Before +delving in to how the Rev1 bootloader worked and how the Rev 3 +bootloader works now, lets look at the features common to both of them +and touch a bit on the Arduino setup. This is a fairly involved +explanation, with a lot of details that are likely only interesting to +a few. If you just want to get the rough idea, skim this article. If +you want to start hacking on the bootloader, get in touch with us to +get even more info on how this all works. Of course, you can always +checkout the code at github! + +Arduino +^^^^^^^ + +Arduino is based off of AVR series micro controllers, most of which +lack USB support. Thus, boards like the Duemilanove add USB capability +via an FTDI USB to Serial converter chip. This chip interfaces with +the AVR over…serial. When you plug an Arduino into a computer only an +FTDI driver is needed. Since the FTDI chip is separate from the AVR, +you can reset the Arduino without closing this USB connection with the +FTDI chip. To program an Arduino, the host machine sends a command +over the USB pipe (reset DTR) which in turn resets the AVR. The AVR +will boot into a bootloader, which waits for a second for any upload +commands over serial. The host machine can either send those commands, +or do nothing. In which case the AVR will quickly jump to user code +and off you go. The whole process is quick, the bootloader doesn’t +live for very long, and will exit almost immediately if no upload +commands are received. + +Maple Rev1: The Horror... +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Maple is based off the STM32 (ARM cortex M3) series chips, which do +have embedded USB support. Thus, Maple doesn’t need the extra FTDI +chip. Firmware is uploaded via the standard DFU protocol (also used by +iPhone and openMoko). Since DFU is a standard, there is no need for +custom software running on the host to upload the firmware. Any DFU +compliant program will work. The maple ide is based around +:command:`dfu-util`, openMoko’s DFU utility. Using DFU came at a cost, +however. The USB port must additionally implement a separate serial +port at the same time (we use the CDC ACM class for serial +functionality). + +Maple Rev 1 attempted to run both DFU and CDC ACM devices +simultaneously on the USB peripheral. On Linux, this worked great. The +OS would service the DFU driver during uploads, and the CDC ACM for +serial port transactions. There was no reset necessary for uploads. No +waiting. The bootloader was always running the background, ready to +receive commands. + +The problem was that ONLY Linux did this. Windows refused to attach +more than one driver to a single USB device without repackaging the +DFU and CDC ACM into a single IAD Compound Device. It's not terribly +important what this means, except for two things. + +1. Four drivers were necessary to make everything work. +2. IAD is not supported by OS X. + +Mac, on the other hand, only supported Compound USB, a different trick +that is not supported by Windows. While a perpetual background +bootloader was attractive, it became clear, after much toiling, we +were going to have to write some custom drivers across several +platforms to make everything work this way. + +Maple Rev3 +^^^^^^^^^^ + +Maple Rev 3 takes a completely different tack, more along the lines of +Arduino. In Rev 3, the device resets into bootloader mode, which +stays alive for a few moments to receive commands and then jumps to +user code. The bootloader is implemented as a DFU device – just a DFU +device, no serial port. This requires one driver for windows +(:file:`drivers/mapleDrv/dfu`). As part of the :ref:`libmaple` +library, user code is automatically supplied with serial support via +some behind the scenes work that happens automatically when you +compile (``setupUSB()`` is appended to ``setup()``). This user mode +code only implements a CDC ACM class USB device, giving you functions +like ``Usb.print()``. Separating these two modes fixed the driver +issue, there are no complicated compound usb device nonsense, and the +scheme works well across platforms, requiring only two drivers (serial +and DFU) on Windows. + +However, it is no longer possible to upload code at will, since there +is no bootloader quietly listening in the background. Instead you have +to reset the board, then initiate a DFU transaction. This reset is +performed automatically by the IDE by sending a command over the USB +serial port. You can generate this reset on your own using a python +script or some other scheme. All you need do is: + +1. Pulse DTR (high and then low, so that youve created a negative + edge) +2. Write “1EAF” in ASCII over the serial pipe. This will cause Maple + to reset. Only the first 4 bytes after a negative edge of DTR are + checked for this command, so its important you actually create a + negative edge, rather than just ensuring DTR is low. + +After the reset, the host OS takes a few moments (.5-2 seconds) to +re-enumerate the device as DFU. This delay is unpredictable, and its +the reason the bootloader on Maple Rev3 stays alive for so +long. Sometimes the bootloader was exiting before the OS had even +enumerated the device! Once in bootloader mode, however, +:command:`dfu-util` uploads your sketch into either flash or ram (dfu +alternate setting 0 or 1 respectively) and resets the board again. +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. diff --git a/source/compatibility.rst b/source/compatibility.rst new file mode 100644 index 0000000..aeed36b --- /dev/null +++ b/source/compatibility.rst @@ -0,0 +1,7 @@ +.. _compatibility: + +============================= + Maple-Arduino Compatibility +============================= + +Stub. diff --git a/source/errata.rst b/source/errata.rst new file mode 100644 index 0000000..b702bd1 --- /dev/null +++ b/source/errata.rst @@ -0,0 +1,7 @@ +.. _errata: + +======== + Errata +======== + +Stub. diff --git a/source/gpio.rst b/source/gpio.rst new file mode 100644 index 0000000..f608a61 --- /dev/null +++ b/source/gpio.rst @@ -0,0 +1,7 @@ +.. _gpio: + +====== + GPIO +====== + +Stub. diff --git a/source/hardware.rst b/source/hardware.rst new file mode 100644 index 0000000..1fa3554 --- /dev/null +++ b/source/hardware.rst @@ -0,0 +1,24 @@ +.. _hardware: + +================================= + Hardware-Specific Documentation +================================= + +This page indexes the Maple's capabilities for interacting with +external hardware peripherals. For information about a particular +device or protocol, see its individual reference page. + +Individual reference pages: + +.. toctree:: + :maxdepth: 2 + + i2c + pwm + gpio + usb + jtag + adc + spi + usart + timers diff --git a/source/i2c.rst b/source/i2c.rst new file mode 100644 index 0000000..e0444eb --- /dev/null +++ b/source/i2c.rst @@ -0,0 +1,9 @@ +.. _i2c: + +===== +|i2c| +===== + +.. |i2c| replace:: I\ :sup:`2`\ C + +Stub. diff --git a/source/index.rst b/source/index.rst index ec7313d..cdf151d 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,21 +11,27 @@ Maple Documentation Index Welcome! This is the documentation index for programming your Maple. It contains tutorials, quickstarts, and technical documentation. -If you just got a new Maple, you probably want the :ref:`Maple -quickstart <maple-quickstart>`. +If you just got a new Maple, you probably want to begin with the +:ref:`quickstart <maple-quickstart>`. You can then move on to reading +about the programming language you use with the Maple at the +:ref:`language reference <language>`. Good luck, and have fun! Table of contents: +.. TODO: be more Pythonic with a "parts of the documentation" thing .. toctree:: :maxdepth: 2 Maple Quickstart Guide <maple-quickstart> Maple IDE Installation Guide <maple-ide-install> - Wiring/Arduino Language Reference <language> - Wiring/Arduino Library Reference <libraries> + Maple/Arduino Compatibility Reference <compatibility> + Maple Language Reference <language> + Maple Library Reference <libraries> libmaple Documentation and APIs <libmaple> Maple bootloader <bootloader> Troubleshooting <troubleshooting> + Hardware-Specific Documentation <hardware> + Known Problems <errata> Indices and tables ================== diff --git a/source/jtag.rst b/source/jtag.rst new file mode 100644 index 0000000..e94229f --- /dev/null +++ b/source/jtag.rst @@ -0,0 +1,7 @@ +.. _jtag: + +====== + JTAG +====== + +Stub. diff --git a/source/language.rst b/source/language.rst index 6634f9d..7bf71c6 100644 --- a/source/language.rst +++ b/source/language.rst @@ -9,11 +9,17 @@ The Maple can be programmed in the `Wiring <http://www.wiring.org.co/reference/>`_ language, which is the same language used to program the `Arduino <http://arduino.cc/>`_ boards. -The entire language will be supported in a future release. Please see -the extensive `language reference +Please see the extensive `language reference <http://arduino.cc/en/Reference/HomePage>`_ on the Arduino webpage for more information, or follow a direct link below. +.. warning:: + + The Arduino boards have different sizes for data types, so don't + trust their documentation for how many bytes an ``int``, ``long``, + etc. take up. The sizes of each data type on the Maple are given + in the :ref:`table below <language-arduino-docs>`. + 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`. @@ -21,6 +27,8 @@ language and C++ may wish to skip to the Unique Maple Additions ---------------------- +.. _language-assert: + ``ASSERT(...)`` The ``ASSERT()`` function can be very useful for basic program debugging. The function accepts a boolean; for example:: @@ -46,6 +54,8 @@ Unique Maple Additions this will **not work in the IDE**; even with this definition, assertions will still be enabled. +.. _language-arduino-docs: + Arduino Documentation Links --------------------------- @@ -70,73 +80,73 @@ Arduino Documentation Links |* `for`_ | | | | |**Data Types** |* `analogRead()`_ | |* `switch/case`_ | | | -| |* `void`_ |* `analogWrite()`_ - PWM | -|* `while`_ | | | -| |* `boolean`_ | | -|* `do...while`_ | |**Advanced I/O** | -| |* `char`_ | | -|* `break`_ | |* `tone()`_ | -| |* `unsigned char`_ | | -|* `continue`_ | |* `noTone()`_ | -| |* `byte`_ | | -|* `return`_ | |* `shiftOut()`_ | -| |* `int`_ | | -|* `goto`_ | |* `pulseIn()`_ | -| |* `unsigned int`_ | | -| | | | -|**Further syntax** |* `word`_ |**Time** | -| | | | -|* `;`_ (semicolon) |* `long`_ |* `millis()`_ | -| | | | -|* `{}`_ (curly braces) |* `unsigned long`_ |* `micros()`_ | -| | | | -|* `//`_ (single line comment) |* `float`_ |* `delay()`_ | +| |Primitive data types on the Maple |* `analogWrite()`_ - PWM | +|* `while`_ |have different sizes than on the | | +| |Arduino, since the Maple has a full | | +|* `do...while`_ |32-bit processor. The size of each |**Advanced I/O** | +| |such type on the Maple is given | | +|* `break`_ |below. |* `tone()`_ | | | | | -|* `/\* \*/`_ (multi-line comment) |* `double`_ |* `delayMicroseconds()`_ | +|* `continue`_ |The ``word`` type is (deliberately) |* `noTone()`_ | +| |:ref:`not supported | | +|* `return`_ |<language-no-word>`. |* `shiftOut()`_ | | | | | -|* `#define`_ |* `string`_ | | -| | |**Math** | -|* `#include`_ |* `array`_ | | -| | |* `min()`_ | +|* `goto`_ |* `void`_ |* `pulseIn()`_ | | | | | -|**Arithmetic Operators** |**Conversion** |* `max()`_ | +| |* `boolean`_ (1 byte) | | +|**Further syntax** | |**Time** | +| |* `char`_ (1 byte) | | +|* `;`_ (semicolon) | |* `millis()`_ | +| |* `unsigned char`_ (1 byte) | | +|* `{}`_ (curly braces) | |* `micros()`_ | +| |* `byte`_ (1 byte) | | +|* `//`_ (single line comment) | |* `delay()`_ | +| |* `int`_ (4 bytes) | | +|* `/\* \*/`_ (multi-line comment) | |* `delayMicroseconds()`_ | +| |* `unsigned int`_ (4 bytes) | | +|* `#define`_ | | | +| |* `long`_ (8 bytes) |**Math** | +|* `#include`_ | | | +| |* `unsigned long`_ (8 bytes) |* `min()`_ | | | | | -|* `=`_ (assignment operator) |* `char()`_ |* `abs()`_ | +|**Arithmetic Operators** |* `float`_ (4 bytes) |* `max()`_ | | | | | -|* `+`_ (addition) |* `byte()`_ |* `constrain()`_ | +|* `=`_ (assignment operator) |* `double`_ (8 bytes) |* `abs()`_ | | | | | -|* `-`_ (subtraction) |* `int()`_ |* `map()`_ | +|* `+`_ (addition) |* `string`_ |* `constrain()`_ | | | | | -|* `*`_ (multiplication) |* `word()`_ |* `pow()`_ | +|* `-`_ (subtraction) |* `array`_ |* `map()`_ | | | | | -|* `/`_ (division) |* `long()`_ |* `sqrt()`_ | +|* `*`_ (multiplication) | |* `pow()`_ | +| |**Conversion** | | +|* `/`_ (division) | |* `sqrt()`_ | +| |* `char()`_ | | +|* `%`_ (modulo) | | | +| |* `byte()`_ |**Trigonometry** | | | | | -|* `%`_ (modulo) |* `float()`_ | | -| | |**Trigonometry** | +|**Comparison Operators** |* `int()`_ |* `sin()`_ | | | | | -|**Comparison Operators** |**Variable Scope & Qualifiers** |* `sin()`_ | +|* `==`_ (equal to) |* `word()`_ |* `cos()`_ | | | | | -|* `==`_ (equal to) |* `variable scope`_ |* `cos()`_ | +|* `!=`_ (not equal to) |* `long()`_ |* `tan()`_ | | | | | -|* `!=`_ (not equal to) |* `static`_ |* `tan()`_ | -| | | | -|* `<`_ (less than) |* `volatile`_ | | +|* `<`_ (less than) |* `float()`_ | | | | |**Random Numbers** | -|* `>`_ (greater than) |* `const`_ | | -| | |* `randomSeed()`_ | +|* `>`_ (greater than) | | | +| |**Variable Scope & Qualifiers** |* `randomSeed()`_ | |* `<=`_ (less than or equal to) | | | -| |**Utilities** |* `random()`_ | +| |* `variable scope`_ |* `random()`_ | |* `>=`_ (greater than or equal to) | | | -| |* `sizeof()`_ (sizeof operator) | | +| |* `static`_ | | | | |**Bits and Bytes** | -|**Boolean Operators** | | | +|**Boolean Operators** |* `volatile`_ | | | | |* `lowByte()`_ | -|* `&&`_ (and) | | | +|* `&&`_ (and) |* `const`_ | | | | |* `highByte()`_ | |* `||`_ (or) | | | -| | |* `bitRead()`_ | +| |**Utilities** |* `bitRead()`_ | |* `!`_ (not) | | | -| | |* `bitWrite()`_ | +| |* `sizeof()`_ (sizeof operator) |* `bitWrite()`_ | | | | | |**Pointer Access Operators** | |* `bitSet()`_ | | | | | @@ -180,6 +190,27 @@ Arduino Documentation Links | | | | +------------------------------------+------------------------------------+-----------------------------------------+ +.. _language-no-word: + +.. note:: + + The ``word`` data type is not supported on the Maple. This is by + choice. + + We decided not to include it because, while the Maple has 32-bit + words, the word size on an Arduino board is only 16 bits, and code + that uses the ``word`` type is likely to rely on that fact. + + By not supporting ``word``, you'll get a compile error when porting + Arduino code to your Maple instead of potentially weird, + hard-to-debug runtime behavior. + + If you're porting over Arduino code and really want ``word``, you + can put the following at the top of the file you're porting:: + + typedef uint16 word; + + .. _setup(): http://arduino.cc/en/Reference/Setup .. _loop(): http://arduino.cc/en/Reference/Loop .. _if: http://arduino.cc/en/Reference/If diff --git a/source/libraries.rst b/source/libraries.rst index 1f298fa..c2d5cb0 100644 --- a/source/libraries.rst +++ b/source/libraries.rst @@ -7,9 +7,13 @@ Maple Library Reference ========================= -This page briefly summarizes the Arduino libraries that have been ported to Maple. You can use a library from within a sketch by going to Sketch > Import Library... from within the IDE, then choosing the library you want. +This page briefly summarizes the Arduino libraries that have been +ported to Maple. You can use a library from within a sketch by going +to Sketch > Import Library... from within the IDE, then choosing the +library you want. -Any incompatibilities between the Maple and Arduino versions are noted in the description of the library. +Any incompatibilities between the Maple and Arduino versions are noted +in the description of the library. * :ref:`LiquidCrystal <liquid_crystal>` * :ref:`Wire <wire>` @@ -19,10 +23,14 @@ Any incompatibilities between the Maple and Arduino versions are noted in the de LiquidCrystal ------------- -The LiquidCrystal library allows Maple to control LCD screens. For more information, see the Arduino LiquidCrystal documentation. -Compatibility Note +The LiquidCrystal library allows Maple to control LCD screens. For +more information, see the Arduino LiquidCrystal documentation. -At this time, no incompatibilities between the Maple and Arduino versions are known. Any observed differences should be considered bugs, and reported on the forums. +**Compatibility Note** + +At this time, no incompatibilities between the Maple and Arduino +versions are known. Any observed differences should be considered +bugs, and reported on the forums. .. _wire: @@ -32,8 +40,7 @@ Wire We provide a soft (bit-banged) implementation of the `Wire I2C library <http://arduino.cc/en/Reference/WireBegin>`_. -Compatibility Note -^^^^^^^^^^^^^^^^^^ +**Compatibility Note** This implementation is synchronous, and thus supports only a subset of the full Wire interface (however, the functionality which is supported diff --git a/source/maple-ide-install.rst b/source/maple-ide-install.rst index b84df76..46c903b 100644 --- a/source/maple-ide-install.rst +++ b/source/maple-ide-install.rst @@ -1,10 +1,154 @@ +.. highlight:: c++ + .. _maple-ide-install: ======================== Maple IDE Installation ======================== +If you still can't get the IDE installed after reading this page, +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 + +Download +-------- + +Choose the correct version for your operating system: + +.. list-table:: + :widths: 15 30 50 + :header-rows: 1 + + * - Platform + - Status + - IDE Package + * - Windows + - Tested on 32bit Windows XP + - `maple-ide-LATEST-windowsxp32.zip <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-windowsxp32.zip>`_ (about 75mb) + * - Linux + - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) + - `maple-ide-LATEST-linux32.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux32.tgz>`_ (about 30mb) + + `maple-ide-LATEST-linux64.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux64.tgz>`_ (about 30mb) + * - Mac OSX + - Tested on Snow Leopard 10.6 (64bit and 32bit) + - `maple-ide-LATEST-macosx-10_6.dmg <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-macosx-10_6.dmg>`_ (about 40mb) + +The package bundles together a compiler, an upload utility, a software +library, and a simple GUI text editor. All this software is `free and +open <http://fsf.org/>`_; we are grateful to the `Arduino +<http://arduino.cc/>`_, `CodeSourcery +<http://www.codesourcery.com/>`_, `GNU <http://gnu.org/>`_, and +`OpenMoko <http://openmoko.com/>`_ developers, as well as many others, +who allow us to reuse their software. + +Installation +------------ + +* :ref:`Windows <maple-ide-install-windows>` +* :ref:`Linux <maple-ide-install-linux>` +* :ref:`OS X <maple-ide-install-osx>` + +.. _maple-ide-install-windows: + +Windows +^^^^^^^ +First, extract all the files in the ZIP file to a suitable location on +your system (like your Desktop folder). Next, you have to install +some drivers. Sorry! + +First, install DFU drivers (for uploading code to your Maple) using +the following steps. + +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. + +4. Your Maple is now in :ref:`perpetual bootloader mode + <troubleshooting-perpetual-bootloader>`. This should give you a + chance to install the DFU drivers. + +5. Windows should now prompt you for some drivers. In the top level + directory of the Maple IDE, point Windows to + :file:`drivers/mapleDrv/dfu/`. + +Next, install serial drivers (for communicating with your Maple using +serial over USB). + +1. Reset your Maple and allow it to exit the bootloader (wait for the + slow blinking to stop). The Maple will next start running whatever + program was uploaded to it last. (New Maples will start running the + test program we upload to them before shipping them to you). + +2. Once Maple is running some user code, Windows should prompt you for + more drivers. Point windows to :file:`driver/mapleDrv/serial`. + +You can now run the Maple IDE by double-clicking on the +:command:`maple-ide` program from within the extracted IDE directory. + +.. _maple-ide-install-linux: + +Linux +^^^^^ + .. _maple-ide-install-java: -.. _maple-ide-install-windows-drivers: +.. note:: + + The IDE is written in Java and requires a compatible runtime (JRE). + + If you don't have one, they're usually pretty easy to install. Sun + Java 1.6 and OpenJDK 1.6 are known to work, and runtimes mostly + compatible with Sun Java 1.5+ should probably get the job done. + + To install Java, try using your distribution's software packaging + tool and search for "JRE" or "java". On Debian-based systems + (including Ubuntu) you can try to install the OpenJDK 1.6 JRE + with:: + + $ sudo aptitude install openjdk-6-jre + +Extract the tarball to an appropriate location (like your home +directory or desktop). + +Make sure you have a Java runtime (JRE) installed; if you can run +:command:`java` from the shell, you should be fine. + +Next, run the script :file:`install-udev-rules.sh` in the extracted +IDE directory. It will ask for root permissions. You now need to +restart udev:: + + sudo /etc/init.d/udev restart + +This will grant members of the group ``plugdev`` read/write access to +Maple devices over USB. Make sure that you are in that group. (For +more information on why this is part of the install process, see the +:ref:`Unix toolchain quickstart <toolchain-udev>`). + +To run the Maple IDE, run :command:`maple-ide` from the shell, or +double-click on it if your window system supports it. + +Feel free to put the IDE directory wherever you want. As long as you +leave its internal structure unchanged, things should be fine. + +.. _maple-ide-install-osx: + +OS X +^^^^ + +Double-click on the :file:`.dmg` file you downloaded to mount the disk +image. From the mounted image, drag and drop the Maple IDE icon into +your computer's Applications folder. + +To run the Maple IDE, double-click the :command:`Maple IDE` +application you dragged into your computer's :file:`Applications` +folder. -Stub. diff --git a/source/maple-quickstart.rst b/source/maple-quickstart.rst index 8184772..9337611 100644 --- a/source/maple-quickstart.rst +++ b/source/maple-quickstart.rst @@ -11,130 +11,32 @@ USB cable <http://www.google.com/products?q=mini-b+usb+cable>`_, a functional computer, and possibly root (or "administrator") access to that computer. -If you have trouble along the way try the :ref:`install page -<maple-ide-install>` for more detailed download and installation -instructions, and the :ref:`troubleshooting page <troubleshooting>` -for help with some common problems. If all else fails, try our `forum -<http://forums.leaflabs.com>`_, or `contact us directly +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 <http://leaflabs.com/contact>`_! -The major steps are: +.. _forum: http://forums.leaflabs.com -* :ref:`Download and install the IDE <maple-quickstart-download>` +The steps are: -* :ref:`(Windows) Resolve driver issues <maple-ide-install-windows-drivers>` +* :ref:`Install and run the IDE <maple-quickstart-get-ide>` -* :ref:`Run the IDE <maple-quickstart-run-ide>`, then :ref:`compile - and upload a simple Blink program <maple-quickstart-compile-blinky>` +* :ref:`Compile and upload a program <maple-quickstart-compile-blinky>` -* Test the USB serial connection with a HelloWorld +* :ref:`Test the USB serial connection <maple-quickstart-serial-port>` -.. _maple-quickstart-download: +.. _maple-quickstart-get-ide: -1. Download the IDE -------------------- - -Choose the correct version for your operating system: - -.. list-table:: - :widths: 15 30 50 - :header-rows: 1 - - * - Platform - - Status - - IDE Package - * - Windows - - Tested on 32bit Windows XP - - `maple-ide-LATEST-windowsxp32.zip <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-windowsxp32.zip>`_ (about 75mb) - * - Linux - - Tested on Ubuntu 9.10 (64bit) and 10.04 (32bit) - - `maple-ide-LATEST-linux32.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux32.tgz>`_ (about 30mb) - - `maple-ide-LATEST-linux64.tgz <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-linux64.tgz>`_ (about 30mb) - * - Mac OSX - - Tested on Snow Leopard 10.6 (64bit and 32bit) - - `maple-ide-LATEST-macosx-10_6.dmg <http://static.leaflabs.com/pub/leaflabs/maple-ide/maple-ide-LATEST-macosx-10_6.dmg>`_ (about 40mb) - -.. note:: - - The Linux release requires that you have a Java runtime (JRE) - installed. If you're on Linux, don't have a JRE, and don't know how - to install one, see the :ref:`installation page - <maple-ide-install-java>`. - -The package bundles together a compiler, an upload utility, a software -library, and a simple GUI text editor. All this software is `free and -open <http://fsf.org/>`_; we are grateful to the `Arduino -<http://arduino.cc/>`_, `CodeSourcery -<http://www.codesourcery.com/>`_, `GNU <http://gnu.org/>`_, and -`OpenMoko <http://openmoko.com/>`_ developers, as well as many others, -who allow us to reuse their software. - -2. Install the IDE ------------------- - -**Windows:** - -First, extract all the files in the ZIP file to a suitable location on -your system (like your Desktop folder). - -Next, you'll have to install drivers; see the :ref:`installation page -<maple-ide-install-windows-drivers>` for more details. Sorry! - -**Linux:** - -Extract the tarball to an appropriate location (like your -home directory or desktop). - -Make sure you have a Java runtime (JRE) installed; if you can run -:command:`java` from the shell, you should be fine. For instructions -on installing a JRE, try the :ref:`installation page -<maple-ide-install-java>` or searching the package manager for your -distribution. - -Next, run the script :file:`install-udev-rules.sh` in the extracted -IDE directory. It will ask for root permissions. You now need to -restart udev:: - - sudo /etc/init.d/udev restart - -This will grant members of the group ``plugdev`` read/write access to -Maple devices over USB. Make sure that you are in that group. (For -more information on why this is part of the install process, see the -:ref:`Unix toolchain quickstart <toolchain-udev>`). - -**OS X:** - -Double-click on the :file:`.dmg` file you downloaded in :ref:`Step 1 -<maple-quickstart-download>`. - -Next, drag and drop the Maple IDE icon into your computer's -Applications folder. - -.. _maple-quickstart-run-ide: - -3. Run the IDE --------------- - -**Windows:** - -Double-click on the :command:`maple-ide` program from within the -extracted IDE directory. - -**Linux:** - -Run :file:`maple-ide` from the shell, or double click on it if your -window system supports it. - -**OS X:** +Install and run the IDE +----------------------- -Double-click the :command:`Maple IDE` application you dragged into -your computer's :file:`Applications` folder. +See the :ref:`IDE installation page <maple-ide-install>` for instructions. .. _maple-quickstart-compile-blinky: -4. Compile a program! ---------------------- +Compile a program! +------------------ Let's load up a simple example program that blinks the status LED. From the File menu, select Examples > Digital > Blink: @@ -172,42 +74,89 @@ bottom window, and then a confirmation message will appear: :align: center :alt: Code verified successfully. -5. Upload that program! ------------------------ +Upload that program! +-------------------- Now it's (finally!) time to plug in your Maple. Use a mini-b cable, -making sure that the power source jumper is on the USB header -first. +making sure that the power source jumper is on the USB header first. +We ship Maples with the power source jumper configured that way, so +you shouldn't have to do anything. For reference, it should look like +this: + +.. image:: /_static/img/plugged-in-maple.png + :align: center + :alt: Correctly plugged in Maple + +.. note:: + + On OS X, a network interface dialog will pop up every time you plug in + the Maple. + + .. image:: /_static/img/osx-unconfigured-popup.png + :align: center + :alt: Unconfigured modem popup + + If you click "Network Preferences..." and accept the default ("Not + Configured"), the dialog won't pop up and everything will work fine. + That is, from this window, click "Apply": + + .. image:: /_static/img/osx-network-prefs-unconfigured.png + :align: center + :scale: 75% + :alt: Click "Apply" The Maple should blink a short pattern on the blue status LED every time it is plugged in, reset, or reprogrammed, just to let you know -it's there. If it ever starts throbbing in a slow, smooth pattern that -means you've got a problem: see the troubleshooting page. - -On OS X, a modem setup dialog will pop up every time you plug in the -Maple. If you go to System Preferences Network Settings and accept -the default ("unconfigured") settings, the dialog won't pop up and -everything will work fine. +it's there. If it ever starts throbbing in a slow, smooth pattern, +then you've got a problem: see the :ref:`troubleshooting +<troubleshooting>` page for help. If all systems are go, select the Board type and Serial Port -(something like /dev/ttyACM0, /dev/cu.usbmodem5d21, or COM3 depending -on your platform) from the Tools menu. Then press the "upload" button -(right arrow to a bunch of dots) to upload your program to the -Maple. You should see some text and a progress bar flash by in the -status window of the IDE, then some blinky patterns on the Maple, and -then a constant blink with whatever time period you programmed in -above. +(something like :file:`COM3`, :file:`/dev/ttyACM0`, or +:file:`/dev/tty.usbmodemfa221`, depending on your platform, from the +Tools menu: + +Windows XP: + +.. image:: /_static/img/serial-port-win.png + :align: center + :alt: Board type and serial port for Windows XP + +Linux: + +.. image:: /_static/img/serial-port-ubuntu.png + :align: center + :alt: Board type and serial port for Linux + +OS X: + +.. image:: /_static/img/serial-port-mac.png + :align: center + :alt: Board type and serial port for the OS X + +Then press the "Upload" button to upload your program to the +Maple. + +.. image:: /_static/img/upload-button.png + :align: center + :alt: Click the "Upload" button + +You should see some text and a progress bar flash by in the status +window of the IDE, then some blinky patterns on the Maple, and then a +constant blinking on and off. Go ahead and modify the file a little bit: if you change the 'delay(1000);' numbers to a different value the speed of the blink will change. The value is a time in milliseconds to pause before continuing with the program, so by default the LED will be on for 1 -second, then off for 1 second, etc. +second, then off for 1 second, etc. Any time you make any changes, go +through the same Verify and Upload process to upload the new version +of your program to your Maple. .. warning:: - This step is the most common source of problems, especially on - Windows. + The uploading step is the most common source of problems, + especially on Windows. The situation is much improved over the past, but if you have trouble, try doing things again, unplugging your Maple and plugging @@ -215,42 +164,43 @@ second, then off for 1 second, etc. <troubleshooting-perpetual-bootloader>`, or restarting the IDE. - Please report any problems in the forums. If we don't know it's - broken, we can't fix it! + If nothing works, please report the problem in the `forum`_. + +.. _maple-quickstart-serial-port: -6. Use the serial port monitor! -------------------------------- +Use the serial port monitor! +---------------------------- As a last step to make sure everything has been configured correctly, let's upload a hello world program that will send text from the Maple -back to the IDE over the USB connection. From File select Examples, -Stubs, HelloWorld, and make sure the correct board and serial port -targets are selected from the Tools pull-down. And of course you could -change the text to be printed out; make sure you leave the double -quotes around it though or you'll get a compile error. +back to the IDE over the USB connection. From the File menu, select +Examples > Stubs > HelloWorld (similarly to when you selected the +Blink program), and make sure the correct board and serial port +targets are selected from the Tools pull-down. Open the serial monitor window (button on the far right) and make sure the 9600 baud speed is selected. Then go back to the code editing -window and upload your program (upload will recompile your code -automatically if there's been any change since the last "verify"). You +window and upload your program (Upload will recompile your code +automatically if there's been any change since the last Verify). You should get text spit at you over the serial monitor right after the program is uploaded. Shout back! We can hear you! -7. Go forth exuberantly! ------------------------- +Go forth exuberantly! +--------------------- We really hope you got this far and didn't frown or make a bitter -lemon face too often getting here. Where you go now is up to you: -perhaps you've got some crazy project cooking, or a longer tutorial to -work through, or maybe now is a good time for a trip to the kitchen -for a delicious sandwich. +lemon face getting here. Where you go now is up to you: perhaps you've +got some crazy project cooking, or a longer tutorial to work through, +or maybe now is a good time for a trip to the kitchen for a delicious +`sandwich <http://everything2.com/title/Velvet+Elvis>`_. If you blew through this guide and are the kind of person who drinks -their coffee straight and has more than a 100 lines of vim or emacs -customization and doesn't even have a mouse plugged into your computer -you may want to look at the Unix Toolchain quickstart guide to getting -working with your old friends make, jtag, and gcc. - -Let us know what you come up with! Tag internet content with -#leaflabs, post in the forums, track us down in the real world, -whatever. We love projects! +their coffee straight, has more than a 100 lines of vim or emacs +customization, and doesn't even have a mouse plugged into their +computer, you may want to look at the :ref:`Unix Toolchain quickstart +<unix-toolchain>` guide. It's the tutorial for getting working with +your old friends :command:`make`, :command:`jtag`, and :command:`gcc`. + +Let us know what you come up with! Tag us with #leaflabs on Twitter, +post in the `forum`_, track us down in the real world, whatever. We +love projects! diff --git a/source/pwm.rst b/source/pwm.rst new file mode 100644 index 0000000..c01e415 --- /dev/null +++ b/source/pwm.rst @@ -0,0 +1,7 @@ +.. _pwm: + +============================== + Pulse-Width Modulation (PWM) +============================== + +Stub. diff --git a/source/spi.rst b/source/spi.rst new file mode 100644 index 0000000..8518f3c --- /dev/null +++ b/source/spi.rst @@ -0,0 +1,7 @@ +.. _spi: + +===== + SPI +===== + +Stub. diff --git a/source/timers.rst b/source/timers.rst new file mode 100644 index 0000000..c156d4f --- /dev/null +++ b/source/timers.rst @@ -0,0 +1,7 @@ +.. _timers: + +======== + Timers +======== + +Stub. diff --git a/source/troubleshooting.rst b/source/troubleshooting.rst index 0aba027..7fdfe17 100644 --- a/source/troubleshooting.rst +++ b/source/troubleshooting.rst @@ -1,9 +1,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: -Stub. +**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. + diff --git a/source/unix-toolchain.rst b/source/unix-toolchain.rst index 9939979..0328a5c 100644 --- a/source/unix-toolchain.rst +++ b/source/unix-toolchain.rst @@ -6,6 +6,10 @@ Unix Toolchain Quickstart =========================== +This is a tutorial for using the Maple with a standard Unix toolchain. +It's not necessary to do this in order to program the Maple; you can +always use our `IDE <maple-ide-install>`_ instead. + You'll need a Maple board, a mini-b USB cable, a functional computer, and root access to that computer. This guide assumes you've had success with the IDE on your machine and that you are fairly @@ -240,9 +244,10 @@ live with :: $ cd ~/Downloads $ tar -xvzf gcc-blah-blah-macosx32.tar.gz $ mv arm ~/libmaple/arm + $ export PATH=$PATH:~/libmaple/arm/bin After that's done, you'll probably want to update your shell startup -script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`. +script so :file:`~/libmaple/arm/bin` stays in your :envvar:`PATH`. **So far, so good?** @@ -400,7 +405,8 @@ Debug with OpenOCD ------------------ TODO. For now see `this great guide -<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se. +<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se, and +the ``jtag`` Makefile target. .. _toolchain-codeblocks: diff --git a/source/usart.rst b/source/usart.rst new file mode 100644 index 0000000..30c953a --- /dev/null +++ b/source/usart.rst @@ -0,0 +1,7 @@ +.. _usart: + +======= + USART +======= + +Stub. diff --git a/source/usb.rst b/source/usb.rst new file mode 100644 index 0000000..2460df5 --- /dev/null +++ b/source/usb.rst @@ -0,0 +1,7 @@ +.. _usb: + +===== + USB +===== + +Stub. |
