Unix Toolchain Quickstart¶
This is a tutorial for using a standard Unix toolchain (make
,
gcc
, etc.) with Maple. It’s intended for C and C++ programmers
who want to use libmaple directly.
Contents
Requirements¶
For Windows, you will somehow need to install drivers.
At a minimum, you need:
- Maple board
- Mini-B USB cable
- root (or Administrator) access to your computer.
On Linux and OS X, you need to know how to use bash, and how to edit your .bashrc. Some experience using GCC and make is recommended, but is not required.
Setup¶
You first need to set up your computer by installing and configuring various things. Don’t fret! We’ve got detailed instructions, just for you.
Come back when you’re ready. We’ll wait.
Test compilation¶
Test that you’ve installed all the compilation tools correctly by running the following commands in your shell.
Windows users:
- Don’t type the
$
‘s, just the parts that come after.- First get to libmaple by opening a Git Shell, then running
cd libmaple
.- Always type
cs-make
instead ofmake
.
Linux and OS X users:
- Run these from the top-level libmaple directory.
$ cp main.cpp.example main.cpp
$ make clean
$ make
If all goes well, you should see a bunch of output, then something like this:
Final Size:
text data bss dec hex filename
13164 1704 552 15420 3c3c build/maple.elf
Hurray! You’ve just compiled your first program for Maple.
Important: if you’re not using Maple (Maple Mini, etc.), make sure to read the following note before moving on.
You can now move on to uploading a program, or take a quick detour to learn more about the build output.
Note
This tutorial assumes you’re using a Maple. If you’re
compiling for another board, you’ll need to set a BOARD
environment variable appropriately.
To get a list of values for BOARD
, run
$ make list-boards
For example, to compile for Maple Mini:
On OS X or Linux, run:
$ export BOARD=maple_mini $ make
On Windows, set a new environment variable named
BOARD
to valuemaple_mini
, then open a new Git Shell, and runcd libmaple
followed bycs-make
as explained above.
You can check that this worked by making sure that the final
program file is named build/maple_mini.elf
instead of
maple.elf
:
Final Size:
text data bss dec hex filename
16848 2696 704 20248 4f18 build/maple_mini.elf
Other notes for OS X and Linux:
You can also use the following, but you’ll need to write the
BOARD=maple_mini
part every time you callmake
(formake install
, etc.):$ BOARD=maple_mini make
To make the board setting permanent, add this line to your .bashrc:
export BOARD=maple_mini
Warning
You must start from a clean build after each time you
change BOARD
(advanced users: or MEMORY_TARGET
). For
example, if you compile a program for Maple, then you want to
compile another program for Maple Mini, you must run $ make
clean
before you compile the second program. If you do not,
you will experience strange errors.
Notes about the libmaple
build¶
These are just some miscellaneous notes that are good to know. Feel free to skip reading this section.
- The
dec
field at the end of the build output underFinal Size:
gives the total program size in bytes. Thetext
,data
, andbss
fields respectively break down the size of the program into code, initialized data, and zero-valued data. - The long list of object files above the
Final Size
shows similar information on a per-file basis. You can use it to help slim down programs that use too much space. build/$BOARD.elf
is the final build result (whereBOARD
ismaple
,maple_mini
, etc. depending on your build).- There are other files under
build
you may be interested in, like disassembly and map files. - If you want quicker build times, you should check out our blog post, Making libmaple compile faster.
Upload a program¶
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 USB serial port.
- Linux: you need udev rules set up as described in the setup doc.
- Windows: you need to somehow install drivers.
- OS X: everything Just Works for you. Aren’t you special?
Plug in your Maple using a Mini-B USB cable, then run
# Window users: as usual, use cs-make instead of make.
$ 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 perpetual bootloader mode, restarting the Maple a couple
times, make clean
, etc. If nothing works, the forum is your
friend.
Communicate over USB-Serial¶
Now let’s try out the interactive test session. You need to connect to the board’s serial port device file.
- Linux: this looks like
/dev/ttyACM*
. - OS X: it looks like
/dev/tty.usbmodem*
. - Windows: it will be
COMx
, wherex
is some number.
Try using one of these to find out which it is:
# Linux
$ ls /dev/ttyACM*
# OS X
$ ls /dev/tty.usbmodem*
# Windows, works from libmaple directory
$ python support/scripts/win-list-com-ports.py
To open up a session on Linux or OS X, run
$ screen /dev/ttyXYZ
(On Windows, you will need to use a separate program, such as PuTTY.)
screen
will present you an empty terminal. Your board is waiting
for you to send it a command. Type h
to print a list of commands;
type any command’s letter to run it.
Example output (for Maple):
> u
Hello World!
> b
Board information
=================
* Clock speed (MHz): 72
* BOARD_LED_PIN: 13
* BOARD_BUTTON_PIN: 38
* GPIO information (BOARD_NR_GPIO_PINS = 44):
ADC pins (15): 0, 1, 2, 3, 10, 11, 12, 15, 16, 17, 18, 19, 20, 27, 28
PWM pins (15): 0, 1, 2, 3, 5, 6, 7, 8, 9, 11, 12, 14, 24, 27, 28
Used pins (7): 13, 38, 39, 40, 41, 42, 43``
To exit the screen session, type C-a k
(control-a k) on Linux,
or C-a C-\
(Control-a, followed by Control-backslash) on OS X,
and type y
when prompted if you’re sure.
Note
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.
Start your own project¶
So everything worked, and you want to start your own project? Great! There are two ways to go about it.
If your project is small, all you have to do is replace
~/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
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
~/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.
There is also a page on starting a project with the Unix toolchain on the LeafLabs wiki that you may find useful.
Get 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 do our best to keep the master libmaple branch on GitHub free from broken or half-finished code, so don’t be too scared running the latest and greatest. If you do, please report any bugs or regressions!
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.
(Optional) Upload/Debug with JTAG/SWD¶
Advanced users will wish to use a JTAG (or SWD) dongle for uploading and debugging their programs. A big advantage to this approach is that it lets you use GDB to single-step through your code, inspect variables, etc.
You can build your projects for JTAG or SWD upload with the jtag
Makefile target. That is, instead of compiling with make
, compile
with
# (This is equivalent to $ MEMORY_TARGET=jtag make)
$ make jtag
Then use your favorite JTAG/SWD dongle and driver software to upload
the resulting program. An ELF
suitable for upload is in build/$BOARD.elf
; the raw binary you
can copy directly to address 0x0 is build/$BOARD.bin
.
Warning
Uploading code built with the jtag
target will
overwrite the bootloader. This is a good thing
– since you’re using another upload method, this lets you use the
Flash and RAM the bootloader ordinarily reserves for itself. You
can always reflash the bootloader
later.
While LeafLabs doesn’t officially support any particular way of using JTAG with Maple, there is a JTAG How-To on the LeafLabs wiki that you may find useful.
Go forth exuberantly!¶
Let us know what you come up with! Mention @leaflabs on Twitter, post in the forum, join the the #leafblowers IRC channel on freenode, whatever. We love projects!