diff options
Diffstat (limited to 'docs/source')
19 files changed, 1109 insertions, 27 deletions
diff --git a/docs/source/_static/img/blinky-to-flash.png b/docs/source/_static/img/blinky-to-flash.png Binary files differnew file mode 100755 index 0000000..0320c5b --- /dev/null +++ b/docs/source/_static/img/blinky-to-flash.png diff --git a/docs/source/_static/img/blinky.png b/docs/source/_static/img/blinky.png Binary files differnew file mode 100755 index 0000000..bda4cee --- /dev/null +++ b/docs/source/_static/img/blinky.png diff --git a/docs/source/_static/img/codeblocks_build.png b/docs/source/_static/img/codeblocks_build.png Binary files differnew file mode 100644 index 0000000..c98bcdc --- /dev/null +++ b/docs/source/_static/img/codeblocks_build.png diff --git a/docs/source/_static/img/codeblocks_makefile.png b/docs/source/_static/img/codeblocks_makefile.png Binary files differnew file mode 100644 index 0000000..a0ef21f --- /dev/null +++ b/docs/source/_static/img/codeblocks_makefile.png diff --git a/docs/source/_static/img/codeblocks_maketargets.png b/docs/source/_static/img/codeblocks_maketargets.png Binary files differnew file mode 100644 index 0000000..bbb68cb --- /dev/null +++ b/docs/source/_static/img/codeblocks_maketargets.png diff --git a/docs/source/_static/img/codeblocks_newproject.png b/docs/source/_static/img/codeblocks_newproject.png Binary files differnew file mode 100644 index 0000000..8d08d1f --- /dev/null +++ b/docs/source/_static/img/codeblocks_newproject.png diff --git a/docs/source/_static/img/libmaple-screenshot-small.png b/docs/source/_static/img/libmaple-screenshot-small.png Binary files differnew file mode 100644 index 0000000..f2be783 --- /dev/null +++ b/docs/source/_static/img/libmaple-screenshot-small.png diff --git a/docs/source/_static/img/verify-success.png b/docs/source/_static/img/verify-success.png Binary files differnew file mode 100755 index 0000000..6928674 --- /dev/null +++ b/docs/source/_static/img/verify-success.png diff --git a/docs/source/_static/img/verify_button.png b/docs/source/_static/img/verify_button.png Binary files differnew file mode 100644 index 0000000..37100db --- /dev/null +++ b/docs/source/_static/img/verify_button.png diff --git a/docs/source/conf.py b/docs/source/conf.py index e9c55b2..7f2b3b4 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,7 +44,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'libmaple' +project = u'Maple' copyright = u'2010, LeafLabs, LLC' # The version info for the project you're documenting, acts as replacement for @@ -169,7 +169,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'libmapledoc' +htmlhelp_basename = 'mapledoc' # -- Options for LaTeX output ------------------------------------------------- @@ -183,7 +183,7 @@ htmlhelp_basename = 'libmapledoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target file, title, author, documentclass [howto/manual]) latex_documents = [ - ('index', 'libmaple.tex', u'libmaple Documentation', + ('index', 'maple.tex', u'Maple Documentation', u'LeafLabs, LLC', 'manual'), ] @@ -216,7 +216,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'libmaple', u'libmaple Documentation', + ('index', 'maple', u'Maple Documentation', [u'LeafLabs, LLC'], 1) ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 92b2d5d..ec7313d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,25 +3,29 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _index: + Maple Documentation Index ========================= Welcome! This is the documentation index for programming your Maple. -It contains technical documentation, as well as some getting started -guides and example projects. +It contains tutorials, quickstarts, and technical documentation. -.. TODO add projects +If you just got a new Maple, you probably want the :ref:`Maple +quickstart <maple-quickstart>`. -Parts of the documentation: +Table of contents: .. toctree:: :maxdepth: 2 - Language reference <language> - Library reference <libraries> - Unix toolchain <unix-toolchain> - libmaple (C library) API <libmaple> + Maple Quickstart Guide <maple-quickstart> + Maple IDE Installation Guide <maple-ide-install> + Wiring/Arduino Language Reference <language> + Wiring/Arduino Library Reference <libraries> + libmaple Documentation and APIs <libmaple> Maple bootloader <bootloader> + Troubleshooting <troubleshooting> Indices and tables ================== diff --git a/docs/source/language.rst b/docs/source/language.rst index 3772872..6634f9d 100644 --- a/docs/source/language.rst +++ b/docs/source/language.rst @@ -1,25 +1,31 @@ +.. highlight:: c++ + .. _language: ========================== Maple Language Reference ========================== -The Maple can be programmed in a mostly-complete subset of the 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 +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 <http://arduino.cc/en/Reference/HomePage>`_ on the Arduino webpage for more information, or follow a direct link below. +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`. + Unique Maple Additions ---------------------- ``ASSERT(...)`` The ``ASSERT()`` function can be very useful for basic program - debugging. The function accepts a boolean; for example: + debugging. The function accepts a boolean; for example:: - ``ASSERT(state == WAIT);`` + ASSERT(state == WAIT); zero is false and any other number is true. If the boolean is true the assertion passes and the program continues as usual. If it is @@ -31,9 +37,9 @@ Unique Maple Additions Including assertions in a program increases the program size. When using libmaple **from the command line only**, they can be - disabled by making the definition + disabled by making the definition :: - ``#define DEBUG_LEVEL DEBUG_NONE`` + #define DEBUG_LEVEL DEBUG_NONE before including either wirish or libmaple. In this case, all assertions will pass without any lost clock cycles. Note that @@ -326,6 +332,163 @@ Arduino Documentation Links .. _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 +-------------------------- + +This is a note for programmers comfortable with C or C++ (although, +you C programmers should remember that `C++ is not a superset of C +<http://en.wikipedia.org/wiki/Compatibility_of_C_and_C%2B%2B>`_) who +want a better understanding of the differences between C++ and the +Wiring language. The good news is that the differences are relatively +few. + +A *sketch* is the IDE's notion of a project; it consists of one or +more files written in the Wiring language, which is mostly the same as +C++. The major difference between the two is that in Wiring, it's not +necessary to declare global functions before they are used. That is, +the following is valid Wiring, and ``f()`` returns ``5``:: + + int f() { + return g(); + } + + int g() { + return 5; + } + +All of the files in a sketch share the same (global) namespace. That +is, the behavior is as if all of a sketch's files were part of the +same translation unit, so they don't have to include one another in +order to access each other's definitions. The only other major +difference between Wiring and C++ is that Wiring doesn't support +dynamically allocated memory -- that is, ``new`` and ``delete`` won't +work. As of |today|, Maple only has 20 KB RAM, anyway, so it's +doubtful that static allocation is not what you want. + +The Wiring language also does not require you to define your own +``main`` method (in fact, it forbids you from doing so). Instead, you +are required to define two functions, ``setup`` and ``loop``, with +type signatures :: + + void setup(void) + void loop(void) + +Once a sketch is uploaded to a Maple and begins to run, ``setup()`` is +called once, and then ``loop()`` is called repeatedly. The IDE +compilation process proceeds via a source-to-source translation from +the files in a sketch to C++. + +This translation process first concatenates the sketch files, then +parses the result to produce a list of all functions defined in the +global scope. (We borrow this stage from the Arduino IDE, which in +turn borrows it from Wiring. It uses regular expressions to parse +C++, which is, of course, `Bad and Wrong +<http://www.retrologic.com/jargon/B/Bad-and-Wrong.html>`_. An +upcoming rewrite of the IDE performs this preprocessing step +correctly, using a real parser. Until then, you have our apologies.) +The order in which the individual sketch files are concatenated is not +defined; it is unwise to write code that depends on a particular +ordering. + +The concatenated sketch files are then appended onto a file which +includes `WProgram.h +<http://github.com/leaflabs/libmaple/blob/master/wirish/WProgram.h>`_ +(which includes the wirish and libmaple libraries, and declares +``setup()`` and ``loop()``), and then provides declarations for all +the function definitions found in the previous step. At this point, +we have a file that is a valid C++ translation unit, but lacks a +``main()`` method. The final step of compilation provides this +method, which behaves roughly like:: + + int main(void) { + setup(); + while (true) loop(); + } + +(The truth is a little bit more complicated, but not by much). + +As an example, consider a sketch with two files. The first file +contains ``setup()`` and ``loop()``:: + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + +The second file contains the (not very useful) implementation for +``choose_a_pin()``:: + + int choose_a_pin() { + return random(5, 15); + } + +Then the results of the concatenation process might be :: + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + + int choose_a_pin(void); + + int choose_a_pin() { + return random(5, 15); + } + +Which could plausibly be turned into the final source file :: + + #include "WProgram.h" + + void setup(void); + void loop(void); + int choose_a_pin(void); + + int the_pin; + + void setup() { + the_pin = choose_a_pin(); + pinMode(the_pin, OUTPUT); + } + + void loop() { + static int toggle = 0; + toggle ^= 1; + digitalWrite(the_pin, toggle); + } + + int choose_a_pin(void); + + int choose_a_pin() { + return random(5, 15); + } + + int main() { + setup(); + while (true) loop(); + } + +(Recall that it's legal C++ for a function to be declared multiple +times, as long as it's defined exactly once). + + Recommended Reading ------------------- diff --git a/docs/source/libmaple-api.rst b/docs/source/libmaple-api.rst new file mode 100644 index 0000000..df9a4d9 --- /dev/null +++ b/docs/source/libmaple-api.rst @@ -0,0 +1,7 @@ +.. _libmaple_api: + +======================== + libmaple API reference +======================== + +Stub. diff --git a/docs/source/libmaple.rst b/docs/source/libmaple.rst index c7e5c83..620fdfa 100644 --- a/docs/source/libmaple.rst +++ b/docs/source/libmaple.rst @@ -1,5 +1,37 @@ +.. highlight:: sh + +.. _libmaple: + ==================== libmaple Reference ==================== -Stub. +.. image:: /_static/img/libmaple-screenshot-small.png + :align: center + :alt: libmaple screenshot + +`LeafLabs libmaple <libmaple-libmaple>`_ is the low level library we have developed for for the ARM +Cortex-M3 chips manufactured by STMicroelectronics used in the Maple +boards (the `STM32F103x`_ series). We found the generic peripheral +libraries too painful to build on top of, and reimplemented the +functionality we needed in a simpler (and less general) form. + +.. _libmaple-libmaple: http://github.com/leaflabs/libmaple +.. _STM32F103x: http://www.st.com/stonline/stappl/productcatalog/app?path=/pages/stcom/PcStComPartNumberSearch.searchPartNumber&search=stm32f103 + +This library is transparently included in the `Maple IDE +<http://leaflabs.com/docs/maple-ide/>`_, but we develop it separately +using good old Unix command line tools and release it for advanced +users who might chafe at the “sketch” programming model of the +IDE. Included are some examples, a Makefile, and the compatibility +wrappers and code to imitate the Arduino programming library. + +**Check out the latest source**:: + + git clone git://github.com/leaflabs/libmaple.git + +.. toctree:: + :maxdepth: 2 + + Unix Toolchain Quickstart <unix-toolchain> + libmaple API reference <libmaple-api> diff --git a/docs/source/libraries.rst b/docs/source/libraries.rst index 374b71c..1f298fa 100644 --- a/docs/source/libraries.rst +++ b/docs/source/libraries.rst @@ -1,7 +1,119 @@ +.. highlight:: c++ +.. default-domain:: cpp + .. _libraries: ========================= Maple Library Reference ========================= -Stub +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. + +* :ref:`LiquidCrystal <liquid_crystal>` +* :ref:`Wire <wire>` + +.. _liquid_crystal: + +LiquidCrystal +------------- + +The LiquidCrystal library allows Maple to control LCD screens. For more information, see the Arduino LiquidCrystal documentation. +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: + +Wire +---- + +We provide a soft (bit-banged) implementation of the `Wire I2C library +<http://arduino.cc/en/Reference/WireBegin>`_. + +Compatibility Note +^^^^^^^^^^^^^^^^^^ + +This implementation is synchronous, and thus supports only a subset of +the full Wire interface (however, the functionality which is supported +is fully compatible with Arduino). For now, please use the function +reference which follows when developing projects using our +implementation. + +Please note that the current implementation only supports master mode +using a bit-banged (software) protocol. Future enhancements will use +the hardware i2c peripheral on the stm32 as well as the DMA for +performance. Support for slave, smBUS, and multimaster modes are also +slated for inclusion in the enhanced Wire port. + +Function Reference +^^^^^^^^^^^^^^^^^^ + +``Wire.begin()`` + Joins the i2c bus as master, using pin 20 as SDA and pin 21 as SCL + (this is compatible with the pin settings on the Arduino Mega). + +``Wire.begin(sda, scl)`` + Like ``Wire.begin()``, but with the given pins as SDA and + SCL. + +``Wire.beginTransmission(slave_address)`` + Set up a transmission to a slave device with the given (7-bit) + address. Bytes subsequently queued for transmission (using + ``Wire.send``) will be sent to ``slave_address`` when ``void + Wire.endTransmission()`` is called. + +``void Wire.send(byte)`` + Queues the given byte (``uint8`` or ``int``) to the slave address + previously specified by a call to ``Wire.beginTransmission``. At + most 32 bytes may be queued in a single transmission. + +``Wire.send(string)`` + Queues a given string (``char*``) for transmission. The characters + of the string are individually queued for transmission as + bytes. At most 32 bytes may be queued in a single transmission. + +``Wire.send(buffer, length)`` + Queues a byte buffer ``buffer`` (``uint8*`` or ``int*``), with + ``length`` elements, for transmission. At most 32 bytes may be + queued in a single transmission. + +``Wire.endTransmission()`` + Ends a transmission (begun by ``Wire.beginTransmission(uint8)``), + and actually sends the bytes queued by calls to Wire.send. + + The return value is one of the following status codes: + + * ``SUCCESS``: All bytes were transmitted successfully. + + * ``EDATA``: More than 32 bytes were queued for transmission. No + bytes are actually sent when this happens. + + * ``ENACKADDR``: Did not receive ACK on transmit of address. No + bytes are actually sent when this happens. + + * ``ENACKTRNS``: Did not receive ACK during transmit of data. Some + bytes may have been sent when this happens; however, the + transmission is aborted after the first byte of data which is + not ACKed by the slave device. + + * ``EOTHER``: Other error occurred. + +``Wire.requestFrom(address, num_bytes)`` + Requests ``num_bytes`` bytes from 7-bit slave address + address. Returns the actual number of bytes read. These bytes may + subsequently be read one at a time using ``Wire.receive()``. + + Note: if ``num_bytes`` exceeds the size of the transmit/receive + buffer (currently 32), it will be truncated to 32. + +``Wire.receive()`` + Get and return the next byte read during the previous call to + ``Wire.requestFrom(uint8, int)``. You can check how many bytes are + left to read using ``uint8 Wire.available()``. + +``Wire.available()`` + Returns the number of bytes which are still available for reading + (with ``Wire.receive()``) from the last call to + ``Wire.requestFrom(uint8, int)``. diff --git a/docs/source/maple-ide-install.rst b/docs/source/maple-ide-install.rst new file mode 100644 index 0000000..b84df76 --- /dev/null +++ b/docs/source/maple-ide-install.rst @@ -0,0 +1,10 @@ +.. _maple-ide-install: + +======================== + Maple IDE Installation +======================== + +.. _maple-ide-install-java: +.. _maple-ide-install-windows-drivers: + +Stub. diff --git a/docs/source/maple-quickstart.rst b/docs/source/maple-quickstart.rst new file mode 100644 index 0000000..8184772 --- /dev/null +++ b/docs/source/maple-quickstart.rst @@ -0,0 +1,256 @@ +.. highlight:: sh + +.. _maple-quickstart: + +======================== + Maple Quickstart Guide +======================== + +You'll need a `Maple board <http://leaflabs.com/store/>`_, a `mini-b +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 +<http://leaflabs.com/contact>`_! + +The major steps are: + +* :ref:`Download and install the IDE <maple-quickstart-download>` + +* :ref:`(Windows) Resolve driver issues <maple-ide-install-windows-drivers>` + +* :ref:`Run the IDE <maple-quickstart-run-ide>`, then :ref:`compile + and upload a simple Blink program <maple-quickstart-compile-blinky>` + +* Test the USB serial connection with a HelloWorld + +.. _maple-quickstart-download: + +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:** + +Double-click the :command:`Maple IDE` application you dragged into +your computer's :file:`Applications` folder. + +.. _maple-quickstart-compile-blinky: + +4. Compile a program! +--------------------- + +Let's load up a simple example program that blinks the status LED. +From the File menu, select Examples > Digital > Blink: + +.. image:: /_static/img/blinky.png + :align: center + :alt: Click "Blink" + +Next, select Tools > Board > "LeafLabs Maple ... to FLASH": + +.. image:: /_static/img/blinky-to-flash.png + :align: center + :alt: Upload to FLASH + +.. note:: + + You have the option between RAM and FLASH programming: FLASH saves + the program into permanent memory so the program will be run every + time the Maple is reset, while RAM simply injects the compiled + program into the processor's memory. + + Programming to RAM is faster to upload and a buggy program can be + wiped away with a simple reset, while FLASH memory is larger and is + the only option for permanently uploading a program. + +.. image:: /_static/img/verify_button.png + :align: left + :alt: Verify button + +Now press the "verify" button (furthest to the left with a "play" +arrow) to compile the code. Some output should scroll by in the +bottom window, and then a confirmation message will appear: + +.. image:: /_static/img/verify-success.png + :align: center + :alt: Code verified successfully. + +5. 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. + +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. + +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. + +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. + +.. warning:: + + This 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 + it back in, using :ref:`perpetual bootloader mode + <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! + +6. 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. + +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 +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! +------------------------ + +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. + +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! diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst new file mode 100644 index 0000000..0aba027 --- /dev/null +++ b/docs/source/troubleshooting.rst @@ -0,0 +1,9 @@ +.. _troubleshooting: + +======================= + Maple Troubleshooting +======================= + +.. _troubleshooting-perpetual-bootloader: + +Stub. diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index 8f7ce7c..9939979 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -1,5 +1,494 @@ -================ - Unix Toolchain -================ +.. highlight:: sh -Stub +.. _unix-toolchain: + +=========================== + Unix Toolchain Quickstart +=========================== + +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 +comfortable with the Unix command line; some previous experience with +editing your shell startup script (.bashrc, .tcshrc, etc.) and using +`make <http://www.gnu.org/software/make/>`_ is recommended. For +generic installation/setup issues, the `IDE install +<http://leaflabs.com/docs/libmaple/install/>`_ and +:ref:`troubleshooting` pages may be helpful. If all else fails, try +our `forum`_, or `contact us directly <http://leaflabs.com/contact>`_! + +.. _forum: http://forums.leaflabs.com + +We currently have instructions for 32- and 64-bit Linux and OS X Snow +Leopard. If you're on another Unix platform, Windows, or an earlier +version of OS X, we're guessing that you can translate/port these +directions on your own. As a jumping off point, you might want to +begin with these `stripped down distributions +<http://static.leaflabs.com/pub/codesourcery/>`_ of the `CodeSourcery +GCC compiler tools <http://www.codesourcery.com/sgpp/features.html>`_ +(including win32 versions). If you do have success on other platforms, +please post in the forums, so we can fold your tips into this +document! + +* :ref:`Linux setup <toolchain-linux-setup>` +* :ref:`OS X setup <toolchain-osx-setup>` +* :ref:`Test compilation <toolchain-test>` +* :ref:`Upload a program <toolchain-upload>` +* :ref:`Communicate over USB-serial interface <toolchain-serialusb>` +* :ref:`Starting your own projects <toolchain-projects>` +* :ref:`Debug with OpenOCD <toolchain-openocd>` +* :ref:`Do it all with Code::Blocks <toolchain-codeblocks>` +* :ref:`Go forth exuberantly! <toolchain-exuberantly>` + +.. _toolchain-linux-setup: + +Linux Setup +----------- + +These instructions are oriented towards Linux users using a +contemporary Debian-based distribution. + +**1. Collect and Install Tools** + +First I'll give the commands to run, then explain:: + + $ sudo aptitude install build-essential git-core wget screen dfu-util \ + openocd python python-serial + +You'll want to install a bunch of developer "basics" like +:command:`make`, :command:`tar`, etc. A good catch-all for these +tools is the "build-essential" meta-package on most debian platforms: +installing this fake package will pull in dozens of useful tools +without bogging your system down too much. ``git-core`` is the name of +the git package; `Git <http://git-scm.com/>`_ is a distributed code +versioning system we use to track changes in our source +code. :command:`wget` is a simple tool to download files over http +from the command line, and is optional (you could pull in the required +downloads using a browser). :command:`screen` is a really cool virtual +terminal program; in the context of Maple, we use it to connect to +serial port devices. + +:command:`dfu-util` is a tool from the `OpenMoko`_ project that we use +to upload programs to the Maple over USB. + +.. _OpenMoko: http://openmoko.com/ + +:command:`openocd` is a `JTAG +<http://en.wikipedia.org/wiki/Joint_Test_Action_Group>`_ control +program used in conjunction with an ARM JTAG device to do in circuit +debugging (pause/resume program execution, upload and download code, +read out register status, etc). (optional) + +Lastly, our reset script (which sends control signals over the +USB-serial connection to restart and enter the bootloader) is written +in Python and requires the `PySerial +<http://pyserial.sourceforge.net/>`_ library (the ``python-serial`` +package; this could also be installed with `easy_install +<http://peak.telecommunity.com/DevCenter/EasyInstall>`_). + +**2. Fetch libmaple and Compiler Toolchain** :: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + $ cd libmaple + $ wget http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-linux32.tar.gz + $ tar xvf arm-*-linux32.tar.gz + $ export PATH=$PATH:~/libmaple/arm/bin # or wherever these tools ended up + +This step is fairly straightforward: do a git clone of the `libmaple +repository <http://github.com/leaflabs/libmaple>`_ to some directory, +then download and extract the ARM compiler toolchain. + +The :file:`arm/bin/` directory will need to be added to +:envvar:`PATH`; you can check that this worked by entering +``arm-none-`` and hitting tab to auto-complete (bash should show a +bunch of results). Regardless of where you put the toolchain, make +sure to preserve its internal directory layout, as the binaries make +relative path calls and references. + +.. _toolchain-udev: + +**3. Install udev Rules** + +From the libmaple directory, :: + + $ groups # make sure it includes plugdev; if not add, yourself to it + $ sudo cp support/scripts/45-maple.rules /etc/udev/rules.d/45-maple.rules + $ sudo /etc/init.d/udev restart + +As a security precaution on linux, unknown USB devices can only be +accessed by the superuser. This udev script identifies the Maple based +on its vendor and product IDs, mounts it to :file:`/dev/maple`, and +grants read/write permissions to the ``plugdev`` group. After +restarting :command:`udev` you'll need to fully unplug or power cycle +any Maples connected to the computer. + +**So far, so good?** + +Great! Test your setup by :ref:`compiling a sample program +<toolchain-test>`. + +.. _toolchain-osx-setup: + +OS X Setup +---------- + +These instructions have been tested successfully on OS X 10.6.4. As +stated previously, this document assumes a general level of Unix +aptitude on the part of the reader; if you're uncomfortable using +Terminal (or if you don't know what that means), then you should +probably stick with using the `Maple IDE +<http://leaflabs.com/docs/maple-ide/>`_ to develop programs. Some of +these software packages might be available on `MacPorts +<http://www.macports.org/>`_. The author had some bad experiences with +MacPorts a few years ago, though, and hasn't touched it since. Of +course, your mileage may vary. + +**1. Collect and Install Tools** + +You will need the following tools to get started: + + 1. `XCode <http://developer.apple.com/technologies/xcode.html>`_: If + you're reading this, you've probably already got this. Provides + compilers and other basic tools of the trade. It's a free download, + but requires registration (gross, we know). + + 2. `Git <http://git-scm.com/>`_: All of our code is tracked by a + distributed versioning system called git. A `Mac installer + <http://code.google.com/p/git-osx-installer/downloads/list?can=3>`_ + is available. + + 3. :command:`dfu-util`: A tool from `OpenMoko`_ that we use to upload + programs to the Maple over USB. If you're feeling masochistic, there + are instructions for `building dfu-util from source + <http://wiki.openmoko.org/wiki/Dfu-util#Mac>`_. + + However, if you've got better things to do, you can steal a dfu-util + binary from a program called `Openmoko Flasher + <http://www.handheld-linux.com/wiki.php?page=Openmoko%20Flasher>`_. To + do this, first `download Openmoko Flasher + <http://projects.goldelico.com/p/omflasher/downloads/>`_, then copy + the .app into your :file:`/Applications` folder (or wherever you + like). Let's pretend you saved the .app to the directory + + :file:`/Applications/OpenMoko Flasher.app` + + Then the :command:`dfu-util` binary resides in + + :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` + + To get access to it from the command line, just make a symbolic link + to the binary from some place on your :envvar:`PATH`:: + + $ ln -s /Applications/OpenMoko\ Flasher.app/Contents/Mac\ OS/dfu-util \ + /somewhere/on/your/PATH/dfu-util + + .. note:: + Just copying the binary somewhere doesn't work, as it relies on + dynamically linked libraries found elsewhere in the .app + bundle. It's possible to pull just the relevant pieces out of the + .app, but you're on your own. + + To make sure this worked, try plugging in your Maple, making sure + it's in bootloader mode (you can do this by pressing RESET, then + quickly pressing BUT and holding it for several seconds), then + running :: + + $ dfu-util -l + + If you see some lines that look like :: + + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=0, name="DFU Program RAM 0x20000C00" + Found DFU: [0x1eaf:0x0003] devnum=0, cfg=0, intf=0, alt=1, name="DFU Program FLASH 0x08005000" + + then you're all set. + + 4. PySerial: our reset script (which sends control signals over the + USB-serial connection to restart and enter the bootloader) is written + in Python and requires the `PySerial + <http://pyserial.sourceforge.net/>`_ library. Download the `latest + version <http://pypi.python.org/pypi/pyserial>`_. After you download + and untar, install it with :: + + $ cd /path/to/pyserial-x.y + $ python setup.py build + $ sudo python setup.py install + + The package is also available via :command:`easy_install`, so if + you're comfortable using that, you could also install it with :: + + $ easy_install pyserial + +**2. Fetch libmaple and Compiler Toolchain** + +You first need to clone libmaple:: + + $ cd ~ + $ git clone git://github.com/leaflabs/libmaple.git libmaple + +Then you need to get the cross-compilers we use to build a +project. These are just modified versions of GCC; you can `download +them for OS X here +<http://static.leaflabs.com/pub/codesourcery/gcc-arm-none-eabi-latest-osx32.tar.gz>`_. Assuming +you saved this file to + + :file:`~/Downloads/gcc-blah-blah-osx32.tar.gz` + +you can then unpack the archive and let OS X know where the compilers +live with :: + + $ cd ~/Downloads + $ tar -xvzf gcc-blah-blah-macosx32.tar.gz + $ mv arm ~/libmaple/arm + +After that's done, you'll probably want to update your shell startup +script to stick :file:`~/libmaple/arm/bin` into your :envvar:`PATH`. + +**So far, so good?** + +Great! Go on to the next section, where you test everything out. + +.. _toolchain-test: + +Test compilation +---------------- + +Get back into the libmaple directory (this tutorial assumes you put it +in :file:`~/libmaple`) and test that you've installed all the compilation +tools correctly:: + + $ cd ~/libmaple + $ cp main.cpp.example main.cpp + $ make clean + $ make + +If it all works out, you should end up seeing something like this:: + + find build -iname *.o | xargs arm-none-eabi-size -t + text data bss dec hex filename + 482 4 24 510 1fe build/wirish/comm/HardwareSerial.o + 260 0 0 260 104 build/wirish/comm/HardwareSPI.o + 60 0 0 60 3c build/wirish/wirish.o + + [...] + + 2196 0 1 2197 895 build/libmaple/usb/usb_lib/usb_core.o + 1904 0 0 1904 770 build/libmaple/usb/usb_lib/usb_regs.o + 56 0 0 56 38 build/libmaple/usb/usb_lib/usb_init.o + 344 0 0 344 158 build/libmaple/usb/usb_hardware.o + 6637 0 58 6695 1a27 build/main.o + 21499 201 391 22091 564b (TOTALS) + + Final Size: + arm-none-eabi-size build/maple.out + text data bss dec hex filename + 21824 200 552 22576 5830 build/maple.out + Flash build + +Woo! It worked. The ``dec`` field at the end gives the total program +size in bytes. The long listing of object files above the ``Final +Size`` helps to identify bloated code. As you write larger projects, +you may find that they use too much space. If that happens, the +file-by-file listing will help you track down the fatties porking up +your program. + +.. _toolchain-upload: + +Upload a program +---------------- + +Ok, let's blow away the little example program and upload the +interactive test session to your Maple. This will let you interact +textually with the Maple via USB-serial. If you're on Linux, then +before executing :command:`make install`, you'll want to have the udev +rules setup :ref:`as described above <toolchain-udev>`. Plug in your Maple +using the mini-b USB cable; then run :: + + $ cd ~/libmaple + $ cp examples/test-session.cpp main.cpp + $ make clean + $ make + $ make install + +A number of things can go wrong at this stage. Simple debugging steps +include using :ref:`perpetual bootloader mode +<troubleshooting-perpetual-bootloader>`, restarting the Maple a couple +times, :command:`make clean`, etc. If nothing works, the `forum`_ is +your friend. + +.. _toolchain-serialusb: + +Communicate over USB-serial interface +------------------------------------- + +Okay, now that we've flashed the interactive test session to the +Maple, let's test it out. The device for the maple should look +something like :file:`/dev/ttyACMXXX` on Linux or +:file:`/dev/tty.usbmodemXXX` on OS X, but it might have a slightly +different name on your system. To open up a session, run :: + + $ screen /dev/tty-whatever-it-is + +If the interactive test program built and uploaded correctly, you +should be able to connect without any errors reported by +:command:`screen`. Type ``h`` or hit the space bar to get a response; +there are a number of commands which demonstrate Maple peripheral +features. As of October 2010, the HardwareSerial library is blocking, +so using any commands which would write to the USART Serial ports will +cause the program to hang. To exit the screen session, type :kbd:`C-a +C-\\` (control-a, followed by control-backslash), and type ``y`` when +prompted if you're sure. + +Using :command:`screen` in this way sometimes messes up your session. +If your shell starts acting up after you exit screen, you should be +able to fix it with :: + + $ reset && clear + +.. _toolchain-projects: + +Starting your own projects +-------------------------- + +So everything worked, and you want to start your own project? Great! +It's easy. Just set the environment variable :envvar:`LIB_MAPLE_HOME` +in your shell startup script to point to the libmaple repository you +cloned (this tutorial assumes you put it in :file:`~/libmaple`). For +example, if you use bash as your shell, just put this line in your +:file:`~/.bashrc` or :file:`~/.bash_profile`:: + + export LIB_MAPLE_HOME=~/libmaple + +Now, in order to start your own projects, just grab a copy of the +:file:`Makefile` and skeleton :file:`main.cpp` we provided in the +libmaple repository, and you're good to go:: + + $ cd + $ mkdir my-awesome-project + $ cp ~/libmaple/Makefile ~/libmaple/build-targets.mk my-awesome-project + $ cp ~/libmaple/main.cpp.example my-awesome-project/main.cpp + +(TEMPORARY: The file :file:`build-targets.mk` is where the rule to +build the object file for :file:`main.cpp` lives. If you have multiple +source files, you'll probably need to look at it and edit as +appropriate. We're sorry about that and will update the Makefile +structure later to remove this pain point.) Then hack away! You can +:command:`make`, :command:`make clean`, and :command:`make install` +from your new directory :file:`my-awesome-project` just like you did +in the libmaple repository. + +.. note:: + + We update the libmaple repository fairly frequently with bugfixes + and other improvements. In order get access to these in your local + copy of the repository, you should periodically update it with:: + + $ cd $LIB_MAPLE_HOME + $ git pull + + The `commits page + <http://github.com/leaflabs/libmaple/commits/master>`_ for the + github repository is a good place to watch for bleeding-edge + updates; our `blog <http://leaflabs.com/blog/>`_ is the place to + watch for major releases. We keep releases of libmaple and the + Maple IDE in lockstep, so any IDE updates will have corresponding + library updates. + +.. _toolchain-openocd: + +Debug with OpenOCD +------------------ + +TODO. For now see `this great guide +<http://fun-tech.se/stm32/OpenOCD/index.php>`_ from fun-tech.se. + +.. _toolchain-codeblocks: + +Do it all with Code::Blocks +--------------------------- + +.. TODO this really should reflect the new, more pleasant build system + +Optional. `Code::Blocks <http://www.codeblocks.org/>`_ is a generic +cross platform IDE. We don't personally use it for development, so we +haven't worked out all the kinks (e.g., debugging isn't integrated), +but it might be helpful for people who are allergic to `vim +<http://www.vim.org/>`_ and/or `Emacs +<http://www.gnu.org/software/emacs/>`_. The simple configuration +described here just calls down to the :file:`Makefile`, so follow the +above directions to get the command line tools configured (you'll +definitely need the arm-none-eabi-* tools on your :envvar:`PATH`), +then `install Code::Blocks +<http://www.codeblocks.org/downloads/26>`_. You can do this on Linux +with:: + + $ sudo aptitude install codeblocks + +The first time it runs you'll maybe want to disable all the glitzy +"Getting Started" crap (when will they learn?). We've added a .cbp +"projects" file to the libmaple repository: you can try using that one +by copying it from :file:`support/codeblocks/libmaple.cbp` to the top +level directory, but no promises (it might be missing new source files +etc). It's probably worth reading through these instructions as well +to get a feel for how it all works. + +To create your own "libmaple" project, start with an "Empty Project" +with the "Folder to create project in" set to your +:envvar:`LIB_MAPLE_HOME`. Make sure that the "Resulting filename" is +in the top level directory as well. + +.. image:: /_static/img/codeblocks_newproject.png + :align: center + :alt: Code::Blocks new project wizard + +Select the "GNU GCC Compiler" (it won't be used, anyway) and disable +the "Debug" configuration in the next window. Now you should have a +project with no files; add files by right clicking on the project in +the left panel file hierarchy and "Add files recursively". Import both +the :file:`wirish` and :file:`libmaple` directories recursively, then +add :file:`main.cpp` separately. + +.. image:: /_static/img/codeblocks_makefile.png + :align: center + :alt: Code::Blocks targets options + +Next we have to configure the Makefile targets. Go to the +"Properties..." menu under "Project" and check the "This is a custom +Makefile" box. Then go to the "Build targets" tab and create "ram" and +"flash" targets, both of type "Console application" and without the +Auto-generated filename prefixes or extensions. Set the Output +filename to :file:`support/codeblocks/program_flash.sh` and +:file:`support/codeblocks/program_ram.sh` respectively; these scripts +just call the program_ram/program_flash make targets and are a hack to +get the "run" button to upload code to the Maple. The IDE will warn +that these files will be overwritten, but they won't be. For both the +"flash" and "ram" targets, click the "Build options..." button (below +"Virtual targets..." etc) and go to the far right tab ("'Make' +commands"). Edit the Clean project/target line so it's just "clean" +(not "clean$target"), and set the "Build project/target" and "Compile +single file" commands to ``$make -f $makefile MAPLE_TARGET=$target`` +and ``$make -f $makefile MAPLE_TARGET=$target $file``, respectively. + +.. image:: /_static/img/codeblocks_maketargets.png + :align: center + :alt: Code::Blocks make targets + +Save all these changes, go back to the main IDE window, and try to +build/run. "Build" will compile everything, "Run" will run the upload +script in a terminal window (if there are problems they will flash by +very quickly; you can start Code::Blocks in a terminal window and +check the output in that base window if necessary), and "Rebuild" will +clean before rebuilding. + +.. image:: /_static/img/codeblocks_build.png + :align: center + :alt: Success! + +.. _toolchain-exuberantly: + +Go forth exuberantly! +--------------------- + +Let us know what you come up with! Use #leaflabs on Twitter, post in +the `forum`_, track us down in the real world, whatever. We love +projects! |
