From 80b8f6d28f23a45a0c37275c5df775bd2e989e5e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 11 Mar 2011 16:46:33 -0500 Subject: Cleanups; new support/gdb/gpio.gdb. --- README | 157 ++++++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 102 insertions(+), 55 deletions(-) (limited to 'README') diff --git a/README b/README index b7dd521..f37999b 100644 --- a/README +++ b/README @@ -1,80 +1,127 @@ - _ _ _ _ - | (_) |__ _ __ ___ __ _ _ __ | | ___ + _ _ _ _ + | (_) |__ _ __ ___ __ _ _ __ | | ___ | | | '_ \| '_ ` _ \ / _` | '_ \| |/ _ \ | | | |_) | | | | | | (_| | |_) | | __/ |_|_|_.__/|_| |_| |_|\__,_| .__/|_|\___| - |_| by leaflabs! + |_| by LeafLabs! -The latest version of this repository can be found at: -http://github.com/leaflabs/libmaple +The latest version of this repository can be found here: -libmaple Repo Layout + http://github.com/leaflabs/libmaple + +Instructions to Compile for ARM Targets ------------------------------------------------------------------------------ -/LICENSE - Licensing and copyright information -/main.cpp.example - main.cpp is required for a successful build but is non-existant by default; - use this file as a template for building your program. By default just - blinks an LED. +A HOWTO is available in the "Unix Toolchain Quickstart" guide at: + + http://leaflabs.com/docs/unix-toolchain.html + +HTML documentation for this repository is automatically generated from +the source code and the files under the top-level /docs/ directory. +It is available online at: + + http://leaflabs.com/docs/ + +(For more information on how this documentation is generated, see +/docs/README). + +Instructions to Create a Library +------------------------------------------------------------------------------ + +TODO: fold this section into the Unix Toolchain Quickstart. + +If you have a complicated project with its own Makefile and multiple +source files, or you're using an IDE that creates its own Makefile, +you'll probably want to load libmaple from an archive (a build-time +library, not a DLL). + +To create an archive, use the "make library" target, and install +build/libmaple.a and the appropriate headers in your project's +directory. At a minimum, the header set will include libmaple.h, +util.h, and libmaple_types.h. + +Repository Layout +------------------------------------------------------------------------------ /build/ - Binary output -/libmaple/ - Lowest level definitions, routines, macros, and functions. This is the meat - of the library. + Compiler output -/wirish/ - Extra wrappers and functionality around the lower level code which is - useful for programming in the IDE. Files in here implement the "Wirish" - language, an Arduino "Wiring"-like language. +/contrib/ + + Community-contributed resources. LeafLabs doesn't maintain the + contents of this directory, so it may get stale. + +/docs/ + + Source code and build scripts for Doxygen and Sphinx + documentation. The libmaple HTML documentation is generated from + these files. It is available under http://leaflabs.com/docs/. /examples/ - What it sounds like. Copy these to /main.cpp to compile them. - -/support/ld/ - Linker scripts -/support/notes/ - Unstructured text notes that may be useful. The 45-maple.rules udev file - can be placed in /etc/udev/rules.d/ on compatible linux machines to allow - non-root access to the Maple USB device for uploading. + Example code and test programs. Copy these to /main.cpp to compile them. -Instructions to Compile for ARM Targets ------------------------------------------------------------------------------- -The best HOWTO for developing with this code is the "libmaple Unix Toolchain -Quickstart" guide at http://leaflabs.com/docs/libmaple/unix-toolchain/. +/libmaple/ -The Codesourcery g++ compiler for arm platforms is required. It is based on gcc -(they push changes into gcc a couple times a year), get the latest EABI version -from: + Lowest level definitions, routines, macros, and functions. This is + the meat of the library. The Arduino-like compatibility layer is + in /wirish/. - http://www.codesourcery.com/sgpp/lite/arm +/libraries/ -Note: grab the linux binaries for targeting the EABI platform (not to be -confused with the linux binaries /tageting/ the linux platform). + Special-purpose libraries that don't merit inclusion in the + /libmaple/ and /wirish/ directories, which are intended for + general use. Arduino-compatible libraries go here. -I unzip the archive ("TAR") version into a directory such as -~/bin/arm-gcc-codesourcery and then add the bin/ directory within that to my -$PATH in ~/.profile, resource that, then check that arm-none-eabi-gcc and -others are in my path. +/LICENSE -You will also need to have dfu-util installed and on your path (on Linux) or -compiled and placed in a folder "dfu-util/" at the same level as the -maple-library folder (macosx and windows). + Licensing and copyright information. -Write your program using /main.cpp as the entry point. Then just 'make help' -and follow the directions! +/main.cpp.example -Instructions to create a library ------------------------------------------------------------------------------- -If you have a complicated project with its own Makefile and multiple .c files, -or you're using an IDE that creates its own Makefile, you'll probably want to -load libmaple from an archive (a build-time library, not a DLL). Use the -"make library" target, and install build/libmaple.a and the appropriate headers -in your project's directory. At a minimum, the header set will include -libmaple.h, util.h, and libmaple_types.h + main.cpp is required for a successful build but is non-existent by + default; use this file as a template for building your program. By + default, just blinks an LED. + +/Makefile + + libmaple build instructions for GNU Make. + +/notes/ + + Unstructured text notes that may be useful. The 45-maple.rules + udev file can be placed in /etc/udev/rules.d/ on compatible Linux + machines to allow non-root access to the Maple USB device for + uploading. + +/README/ + + This file. + +/support/ + + Support files and scripts for various purposes. + + codeblocks/ [OBSOLETE] Config files for the Code::Blocks IDE. + gdb/ GDB scripts. + ld/ Linker scripts. + make/ Additional scripts used by the top-level Makefile. + openocd/ OpenOCD scripts for JTAG debugging. + scripts/ Miscellany. + stm32loader.py Script for uploading via the built-in USART bootloader. + +TODO + + Various undone tasks. Also see our bugtracker at + + http://code.google.com/p/leaflabs/issues/list + +/wirish/ + + Extra wrappers and functionality around the lower level code in + /libmaple/. These files implement an Arduino "Wiring"-like + library. -- cgit v1.2.3 From 351f9a097fb8e005e9465a8a883b2f063e5c5160 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 14 Apr 2011 14:28:23 -0400 Subject: Ancillary file cleanups. --- README | 32 ++-- TODO | 56 +------ support/codeblocks/libmaple.cbp | 300 ------------------------------------ support/codeblocks/program_flash.sh | 4 - support/codeblocks/program_ram.sh | 4 - support/gdb/gpio.gdb | 12 -- support/gdb/gpio/gpio.gdb | 12 ++ support/gdb/i2c/test.gdb | 112 ++++++++++++++ test.gdb | 112 -------------- 9 files changed, 141 insertions(+), 503 deletions(-) delete mode 100644 support/codeblocks/libmaple.cbp delete mode 100755 support/codeblocks/program_flash.sh delete mode 100755 support/codeblocks/program_ram.sh delete mode 100644 support/gdb/gpio.gdb create mode 100644 support/gdb/gpio/gpio.gdb create mode 100644 support/gdb/i2c/test.gdb delete mode 100644 test.gdb (limited to 'README') diff --git a/README b/README index f37999b..6e4c400 100644 --- a/README +++ b/README @@ -12,21 +12,25 @@ The latest version of this repository can be found here: http://github.com/leaflabs/libmaple -Instructions to Compile for ARM Targets +General information ------------------------------------------------------------------------------ -A HOWTO is available in the "Unix Toolchain Quickstart" guide at: +A HOWTO on setting up this library for use in a Unix environment is +available in our online HTML documentation: http://leaflabs.com/docs/unix-toolchain.html -HTML documentation for this repository is automatically generated from -the source code and the files under the top-level /docs/ directory. -It is available online at: +The HTML docs for this repository are automatically generated from the +source code and the files under the top-level /docs/ directory. For +more information, see /docs/README. - http://leaflabs.com/docs/ +Our bugtracker is available at: -(For more information on how this documentation is generated, see -/docs/README). + http://code.google.com/p/leaflabs/issues/list + +For changes that block official releases, see our wiki: + + http://wiki.leaflabs.com/index.php?title=Blocking_Changes Instructions to Create a Library ------------------------------------------------------------------------------ @@ -93,10 +97,7 @@ Repository Layout /notes/ - Unstructured text notes that may be useful. The 45-maple.rules - udev file can be placed in /etc/udev/rules.d/ on compatible Linux - machines to allow non-root access to the Maple USB device for - uploading. + Unstructured text notes that may be useful. /README/ @@ -106,7 +107,6 @@ Repository Layout Support files and scripts for various purposes. - codeblocks/ [OBSOLETE] Config files for the Code::Blocks IDE. gdb/ GDB scripts. ld/ Linker scripts. make/ Additional scripts used by the top-level Makefile. @@ -114,12 +114,6 @@ Repository Layout scripts/ Miscellany. stm32loader.py Script for uploading via the built-in USART bootloader. -TODO - - Various undone tasks. Also see our bugtracker at - - http://code.google.com/p/leaflabs/issues/list - /wirish/ Extra wrappers and functionality around the lower level code in diff --git a/TODO b/TODO index af8ef80..7c2f6e8 100644 --- a/TODO +++ b/TODO @@ -1,55 +1,7 @@ -Quick TODO -------------------------------------------------------------------- +Bugtracker: -- write language unit test -- more maple-specific example programs -- maple mini serial bootloader HOWTO -- maple and mini jtag HOWTO +http://code.google.com/p/leaflabs/issues/list -Peripherals ------------------------------------------------------------------- - -- I2C wrap up -- SPI wrap up - -Arduino Library functions to port (these are LGPL) ---------------------------- - -EEPROM: - functions: - uint8 read(int) - void write(int, uint8) - -Firmata: - edit Firmata.h for capabilities - -Matrix: - soft spi port stuff - -SoftwareSerial: - clockCyclesToMicroseconds(int) - -Sprite: - all good? - -LiquidCrystal: - timing on soft serial send() commands - -Stepper: - requires millis() - -Wire: - reimplementation of the utility/twi.{c/h} code: - void twi_init(void); - void twi_setAddress(uint8_t); - uint8_t twi_readFrom(uint8_t, uint8_t*, uint8_t); - uint8_t twi_writeTo(uint8_t, uint8_t*, uint8_t, uint8_t); - uint8_t twi_transmit(uint8_t*, uint8_t); - void twi_attachSlaveRxEvent( void (*)(uint8_t*, int) ); - void twi_attachSlaveTxEvent( void (*)(void) ); - void twi_reply(uint8_t); - void twi_stop(void); - void twi_releaseBus(void); - -Ethernet: - ho baby... - uses avr/interrupt.h - reimplement utility/spi stuff +Blocking changes for official releases: +http://wiki.leaflabs.com/index.php?title=Blocking_Changes diff --git a/support/codeblocks/libmaple.cbp b/support/codeblocks/libmaple.cbp deleted file mode 100644 index 4766275..0000000 --- a/support/codeblocks/libmaple.cbp +++ /dev/null @@ -1,300 +0,0 @@ - - - - - - diff --git a/support/codeblocks/program_flash.sh b/support/codeblocks/program_flash.sh deleted file mode 100755 index 9dfe9f1..0000000 --- a/support/codeblocks/program_flash.sh +++ /dev/null @@ -1,4 +0,0 @@ -#/usr/bin/env sh - -cd ../.. -make MAPLE_TARGET=flash install diff --git a/support/codeblocks/program_ram.sh b/support/codeblocks/program_ram.sh deleted file mode 100755 index 55fe73d..0000000 --- a/support/codeblocks/program_ram.sh +++ /dev/null @@ -1,4 +0,0 @@ -#/usr/bin/env sh - -cd ../.. -make MAPLE_TARGET=ram install diff --git a/support/gdb/gpio.gdb b/support/gdb/gpio.gdb deleted file mode 100644 index 4376cfd..0000000 --- a/support/gdb/gpio.gdb +++ /dev/null @@ -1,12 +0,0 @@ -set print pretty on - -print "GPIOA registers:" -p/x *GPIOA->regs -print "GPIOB registers:" -p/x *GPIOB->regs -print "GPIOC registers:" -p/x *GPIOC->regs -print "GPIOD registers:" -p/x *GPIOD->regs -print "AFIO registers:" -p/x *(struct afio_reg_map*)0x40010000 diff --git a/support/gdb/gpio/gpio.gdb b/support/gdb/gpio/gpio.gdb new file mode 100644 index 0000000..4376cfd --- /dev/null +++ b/support/gdb/gpio/gpio.gdb @@ -0,0 +1,12 @@ +set print pretty on + +print "GPIOA registers:" +p/x *GPIOA->regs +print "GPIOB registers:" +p/x *GPIOB->regs +print "GPIOC registers:" +p/x *GPIOC->regs +print "GPIOD registers:" +p/x *GPIOD->regs +print "AFIO registers:" +p/x *(struct afio_reg_map*)0x40010000 diff --git a/support/gdb/i2c/test.gdb b/support/gdb/i2c/test.gdb new file mode 100644 index 0000000..8b71320 --- /dev/null +++ b/support/gdb/i2c/test.gdb @@ -0,0 +1,112 @@ +define i2c_sr1_flags +set $s = $arg0 +printf "SR1: " + +if (($s & (1 << 15))) + printf "SMBALERT " +end + +if (($s & (1 << 14))) + printf "TIMEOUT " +end + +if (($s & (1 << 12))) + printf "PECERR " +end + +if (($s & (1 << 11))) + printf "OVR " +end + +if (($s & (1 << 10))) + printf "AF " +end + +if (($s & (1 << 9))) + printf "ARLO " +end + +if (($s & (1 << 8))) + printf "BERR " +end + +if (($s & (1 << 7))) + printf "TXE " +end + +if (($s & (1 << 6))) + printf "RXNE " +end + +if (($s & (1 << 4))) + printf "STOPF " +end + +if (($s & (1 << 3))) + printf "ADD10 " +end + +if (($s & (1 << 2))) + printf "BTF " +end + +if (($s & (1 << 1))) + printf "ADDR " +end + +if (($s & (1 << 0))) + printf "SB " +end +end + +define i2c_sr2_flags +set $s = $arg0 +printf "SR2: " + +if (($s & (1 << 7))) + printf "DUALF " +end + +if (($s & (1 << 6))) + printf "SMBHOST " +end + +if (($s & (1 << 5))) + printf "SMBDEFAULT " +end + +if (($s & (1 << 4))) + printf "GENCALL " +end + + +if (($s & (1 << 2))) + printf "TRA " +end + +if (($s & (1 << 1))) + printf "BUSY " +end + +if (($s & (1 << 0))) + printf "MSL " +end + +end + +define pbc +set $c = crumbs +while ($c->event) + if ($c->event != 0) + printf "Event: %d ", $c->event + if ($c->event == 1) + i2c_sr1_flags $c->sr1 + printf "\t" + i2c_sr2_flags $c->sr2 + end + printf "\n" + end + set $c = $c + 1 +end + + diff --git a/test.gdb b/test.gdb deleted file mode 100644 index 8b71320..0000000 --- a/test.gdb +++ /dev/null @@ -1,112 +0,0 @@ -define i2c_sr1_flags -set $s = $arg0 -printf "SR1: " - -if (($s & (1 << 15))) - printf "SMBALERT " -end - -if (($s & (1 << 14))) - printf "TIMEOUT " -end - -if (($s & (1 << 12))) - printf "PECERR " -end - -if (($s & (1 << 11))) - printf "OVR " -end - -if (($s & (1 << 10))) - printf "AF " -end - -if (($s & (1 << 9))) - printf "ARLO " -end - -if (($s & (1 << 8))) - printf "BERR " -end - -if (($s & (1 << 7))) - printf "TXE " -end - -if (($s & (1 << 6))) - printf "RXNE " -end - -if (($s & (1 << 4))) - printf "STOPF " -end - -if (($s & (1 << 3))) - printf "ADD10 " -end - -if (($s & (1 << 2))) - printf "BTF " -end - -if (($s & (1 << 1))) - printf "ADDR " -end - -if (($s & (1 << 0))) - printf "SB " -end -end - -define i2c_sr2_flags -set $s = $arg0 -printf "SR2: " - -if (($s & (1 << 7))) - printf "DUALF " -end - -if (($s & (1 << 6))) - printf "SMBHOST " -end - -if (($s & (1 << 5))) - printf "SMBDEFAULT " -end - -if (($s & (1 << 4))) - printf "GENCALL " -end - - -if (($s & (1 << 2))) - printf "TRA " -end - -if (($s & (1 << 1))) - printf "BUSY " -end - -if (($s & (1 << 0))) - printf "MSL " -end - -end - -define pbc -set $c = crumbs -while ($c->event) - if ($c->event != 0) - printf "Event: %d ", $c->event - if ($c->event == 1) - i2c_sr1_flags $c->sr1 - printf "\t" - i2c_sr2_flags $c->sr2 - end - printf "\n" - end - set $c = $c + 1 -end - - -- cgit v1.2.3 From 7e1b03e701291e887dadcc0bef4c9221e30e1049 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 14 Apr 2011 16:00:39 -0400 Subject: Unix toolchain docs improvements. Folded information in the README about the library Makefile target into docs/source/unix-toolchain.rst. Added a pointer to the JTAG HOWTO page on the wiki. Made some other miscellaneous cleanups, updates and improvements. --- README | 17 +-- docs/source/unix-toolchain.rst | 306 ++++++++++++++++++++++------------------- 2 files changed, 168 insertions(+), 155 deletions(-) (limited to 'README') diff --git a/README b/README index 6e4c400..456ea2f 100644 --- a/README +++ b/README @@ -32,21 +32,6 @@ For changes that block official releases, see our wiki: http://wiki.leaflabs.com/index.php?title=Blocking_Changes -Instructions to Create a Library ------------------------------------------------------------------------------- - -TODO: fold this section into the Unix Toolchain Quickstart. - -If you have a complicated project with its own Makefile and multiple -source files, or you're using an IDE that creates its own Makefile, -you'll probably want to load libmaple from an archive (a build-time -library, not a DLL). - -To create an archive, use the "make library" target, and install -build/libmaple.a and the appropriate headers in your project's -directory. At a minimum, the header set will include libmaple.h, -util.h, and libmaple_types.h. - Repository Layout ------------------------------------------------------------------------------ @@ -99,7 +84,7 @@ Repository Layout Unstructured text notes that may be useful. -/README/ +/README This file. diff --git a/docs/source/unix-toolchain.rst b/docs/source/unix-toolchain.rst index d49b642..a173146 100644 --- a/docs/source/unix-toolchain.rst +++ b/docs/source/unix-toolchain.rst @@ -7,20 +7,21 @@ =========================== This is a tutorial for using the Maple with a standard Unix toolchain -(make, gcc, etc.). It's not necessary to do this in order to program -the Maple; you can always :ref:`install the Maple IDE +(``make``, ``gcc``, etc.). It's not necessary to do this in order to +program the Maple; you can always :ref:`install the Maple IDE ` 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 -comfortable with the Unix command line; some previous experience with -editing your shell startup script (.bashrc, .tcshrc, etc.) and using -`make `_ is recommended. For -generic installation/setup issues, the :ref:`IDE installation -` and :ref:`troubleshooting` pages may be -helpful. If all else fails, try our `forum`_, or `contact us -directly`_\ ! +and root (or Administrator) 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 `GCC `_ and `make +`_ is recommended. + +For generic installation and setup issues, see the :ref:`IDE +installation ` and :ref:`troubleshooting` pages. If +all else fails, try our `forum`_, or `contact us directly`_\ ! 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 @@ -54,36 +55,40 @@ 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 `_ 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. +You'll want to install a bunch of developer "basics" like ``make``, +``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 `_ is a distributed code versioning system +we use to track changes in our source code; ``git-core`` is the +corresponding package. + +``wget`` is a simple tool to download files over http from the command +line; installing it is optional (you could pull in the required +downloads using a browser). + +``screen`` is a screen manager; in the context of Maple, we use it to +connect to serial port devices. + +``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 +``openocd`` is a `JTAG `_ 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) +read out register status, etc). It's also 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 -`_ library (the ``python-serial`` -package; this could also be installed with `easy_install -`_). +in `Python `_, and requires the `PySerial +`_ library available in the +``python-serial`` package. This can also be installed with +`easy_install `_. **2. Fetch libmaple and Compiler Toolchain** :: @@ -100,10 +105,10 @@ then download and extract the ARM compiler toolchain. The :file:`arm/bin/` directory will need to be added to ``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. +to auto-complete (your shell 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. After you're done, you'll probably want to update your shell startup script so :file:`~/libmaple/arm/bin` stays in your ``PATH``. @@ -118,12 +123,12 @@ From the libmaple directory, :: $ 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. +As a security precaution on Linux, unknown USB devices can only be +accessed by root. 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 +``udev`` you'll need to fully unplug or power cycle any Maples +connected to the computer. **So far, so good?** @@ -140,38 +145,40 @@ 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 -`_ to develop programs. +`_ to write programs. **1. Collect and Install Tools** -You will need the following tools\ [#fmacports]_ to get started: +You will need the following tools\ [#fpackman]_ to get started: 1. `XCode `_: 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). + compilers and other basic tools of the trade. While XCode was once + free of charge, Apple has since begun charging for it; if you'd + rather not pay, you can probably get by with just a `make + `_ binary. 2. `Git `_: All of our code is tracked by a - distributed versioning system called git. A `Mac installer + distributed versioning system called Git. A `Mac installer `_ 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 + 3. ``dfu-util``: A tool from `OpenMoko`_ that we use to upload + programs to the Maple over USB. If you prefer to compile from + source, OpenMoko provides instructions for `building dfu-util `_. - However, if you've got better things to do, you can steal a dfu-util - binary from a program called `Openmoko Flasher + If you're in a hurry, you can steal a dfu-util binary from a program + called `Openmoko Flasher `_. To do this, first `download Openmoko Flasher `_, then copy - the .app into your :file:`/Applications` folder (or wherever you - like). Let's pretend you saved the .app to the directory + the OpenMoko application 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 + Then the ``dfu-util`` binary resides in :file:`/Applications/OpenMoko Flasher.app/Contents/Mac OS/dfu-util` @@ -188,8 +195,9 @@ You will need the following tools\ [#fmacports]_ to get started: .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 + it's in :ref:`perpetual bootloader mode + ` (do this by pressing RESET, + then quickly pressing BUT and holding it for several seconds), then running :: $ dfu-util -l @@ -212,8 +220,8 @@ You will need the following tools\ [#fmacports]_ to get started: $ 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 :: + The package is also available via ``easy_install``, so if you're + comfortable using that, you could also install it with :: $ easy_install pyserial @@ -288,20 +296,20 @@ 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. +file-by-file listing will help you track down the culprits. .. _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 `. Plug in your Maple -using the mini-b USB cable; then run :: +Let's blow away the little example program and upload the interactive +test session to your Maple. This will let you interact with the Maple +over a :ref:`USB serial port `. If you're on Linux, then before +executing ``make install``, you'll want to have the udev rules setup +:ref:`as described above `. + +Plug in your Maple using the Mini-B USB cable; then run :: $ cd ~/libmaple $ cp examples/test-session.cpp main.cpp @@ -312,91 +320,106 @@ using the mini-b USB cable; then run :: A number of things can go wrong at this stage. Simple debugging steps include using :ref:`perpetual bootloader mode `, restarting the Maple a couple -times, :command:`make clean`, etc. If nothing works, the `forum`_ is -your friend. +times, ``make clean``, etc. If nothing works, the `forum`_ is your +friend. .. _toolchain-serialusb: -Communicate over USB-serial interface +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 :: +Now let's try out the interactive test session. The serial port +device file should look something like :file:`/dev/ttyACMXXX` on Linux +or :file:`/dev/tty.usbmodemXXX` on OS X, but ``XXX`` will vary +depending on your system. Try using one of these to find out which it +is:: + + # Linux + $ ls /dev/ttyACM* + + # OS X + $ ls /dev/tty.usbmodem* + +To open up a session, run :: $ screen /dev/ttyXXX -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) on Mac, or :kbd:`C-a -k` (control-a k) on Linux, and type ``y`` when prompted if you're -sure. +If the interactive test program built and uploaded correctly, +``screen`` won't report any errors, and will present you an empty +terminal. Your board is now waiting for you to send it a command. +Type ``h`` to print a list of commands which demonstrate various +features; type any command's letter to run it. + +To exit the screen session, type :kbd:`C-a C-\\` (control-a, followed +by control-backslash) on Mac, or :kbd:`C-a k` (control-a k) on Linux, +and type ``y`` when prompted if you're sure. .. note:: - Using :command:`screen` in this way sometimes messes up your - terminal session on OS X. If your shell starts acting up after you - exit screen, you should be able to fix it with :: + Using ``screen`` sometimes messes up your terminal session on OS X. + If your shell starts acting funny after you exit ``screen``, you + should be able to fix it with :: $ reset && clear + If that doesn't work, just close the Terminal window and open up a + new one. + .. _toolchain-projects: Starting your own projects -------------------------- -.. TODO fix the build-targets.mk mess, note the "library" target - So everything worked, and you want to start your own project? Great! -It's easy. Just set the environment variable ``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 - `_ for the - github repository is a good place to watch for bleeding-edge - updates; our `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. +There are two ways to go about it. + +If your project is small, all you have to do is replace +:file:`~/libmaple/main.cpp` with your own code, and you're free to use +``make`` and ``make install`` in the same way you did when you first +:ref:`uploaded a program `. + +If you have a more complicated project, with its own Makefile and +multiple source files, or if you're using an IDE that creates its own +Makefile, you'll probably want to load libmaple from an archive (a +build-time library, not a DLL). + +To create an archive, use the ``library`` Makefile target:: + + $ cd ~/libmaple + $ make library + +This will produce a build-time library in the file +:file:`~/libmaple/build/libmaple.a`. To use it, make sure that you +link against that library, and that the libmaple sources are in your +include path. + +At a minimum, your include path should contain the directories +:file:`~/libmaple/libmaple` and :file:`~/libmaple/wirish/`. If you +want to use one of the officially supported :ref:`libraries +`, those live under :file:`~/libmaple/libraries/`. The +main include file for the Wirish library is +:file:`~/libmaple/wirish/wirish.h`. + +Getting Updates +--------------- + +We update libmaple 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 ~/libmaple + $ git pull + +We keep releases of libmaple and the Maple IDE in lockstep, so any +IDE updates will have corresponding library updates. Our `blog +`_ is the place to watch for major +releases; an `RSS feed `_ is +available. + +You can sign up for a free `Github `_ +account and `watch libmaple +`_ to receive +notifications about bleeding-edge development. .. _toolchain-openocd: @@ -405,20 +428,25 @@ Debug with OpenOCD TODO. For now see `this great guide `_ from fun-tech.se, and -the ``jtag`` Makefile target. +the ``jtag`` Makefile target. There is also a `JTAG How-To +`_ page on +our `wiki `_ which you may find useful. .. _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! +Let us know what you come up with! Use #leaflabs on `Twitter +`_, post in the `forum`_, join the the +#leafblowers IRC channel on `freenode +`_, whatever. We love projects! .. rubric:: Footnotes -.. [#fmacports] Some of these software packages might be available on - `MacPorts `_. The author had some bad +.. [#fpackman] Some of these software packages might be available on + `MacPorts `_ or `Homebrew + `_. 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. + touched a package manager on OS X since. Of course, your mileage + may vary. -- cgit v1.2.3