LibNXT and FwFlash v0.3 David Anderson ==================== What? ===== LibNXT is an utility library for talking to the LEGO Mindstorms NXT intelligent brick at a relatively low level. It currently does: - Handling USB communication and locating the NXT in the USB tree. - Interaction with the Atmel AT91SAM boot assistant. - Flashing of a firmware image to the NXT. - Execution of code directly in RAM. (If you have ideas of other stuff it should do, please suggest!) LibNXT is targetted at the platforms that the official Lego Minstorms NXT software overlooks. Specifically, it will work on any POSIX-compliant operating system where libusb 0.1 (http://libusb.sf.net/) is supported. The design of LibNXT is layered, meaning you can plug into it at any level of complexity or abstraction you desire, from the lowest level USB bulk bit-pushing interface, to an API exposing the SAM-BA commandset, right up to just calling nxt_firmware_flash() and having everything taken care of! `fwflash` is the first utility program that uses LibNXT. As its name hints, its purpose is to take a NXT firmware image file and flash it to a connected NXT device. `fwexec` is another cool utility, originally written by the folks of the Lejos project (http://lejos.sourceforge.net/). It takes a specially compiled firmware image, uploads it to the NXT's RAM, and executes it directly from there. While this firmware will only last until the brick is powered down, it is a great tool for testing firmwares during development without wearing down the flash memory. Who? ==== Uh, that would be me. David Anderson, linux/open source developer and enthusiast, and fan of embedded stuff in general. As mentionned above, the `fwexec` utility was originally written by Lawrie Griffiths, over at Lejos. When? ===== Started the day after receiving the NXT kit, I started by working out the firmware flashing procedure from the specs and a USB dump of the windows software at work. Since then, after obtaining a proof-of-concept application, I've been implementing this library to abstract the horrors of low-level USB chatter into a nice, clean library. - Release 0.3 (22/04/2007) : more than a year later, there are a few changes, and it can't hurt to push them out in an actual release. This release includes a more intelligent build system that handles a missing flash driver elegantly, and the `fwexec` utility program. Unless people have specific itches that need scratching, or bugs that should be fixed, this will probably be the final release of libnxt. My personal itch is scratched, and I've moved on to using libnxt to write firmware code :-). - Release 0.2 (17/03/2006) : firmware flashing is now done entirely with open source code. The flash driver routine has been replaced with open source code implementing the flashing procedure. - Release 0.1.1 (10/03/2006) : add big-endian host arch support, and make the firmware image reading process a little less linux-centric (use of the posix open/read/close API instead of mmap). - Release 0.1 (10/03/2006) : featuring the FwFlash utility and a LibNXT with just enough API in it to get FwFlash working :-) How? ==== To compile all of this you'll need a copy of libusb 0.1 on your system, as well as the scons project manager. - Libusb 0.1: http://libusb.sf.net/ - Scons: http://www.scons.org/ When you have all that, just run 'scons' in the libnxt directory, and compilation should follow. Once you're done, you can try fwflash out by resetting your NXT (see your user manual for details on this) and running: ./fwflash nxtos.bin nxtos.bin is the official Lego Mindstorms NXT firmware. You can find this on your current installation of the Mindstorms software, or on LEGO's website. If all goes well, fwflash should inform you that it has found the NXT on your USB device bus, and that flashing has started. After a few seconds, it should announce successful flashing, and say that it has booted the new firmware, which should be answered by the greeting sound of the LEGO firmware as the brick starts up :-). If it doesn't, well it's either a problem with your USB device permissions (if fwflash can't find the NXT), or it's a bug (if the brick doesn't reboot properly, or if some weird error is reported by fwflash and it bombs out. The release tarball comes with a 'flash.bin'. This file is the compiled version of the embedded flash driver, which is uploaded to the NXT's RAM and required to write data into flash memory. If you do not have a release tarball, or accidentally deleted your copy of flash.bin, there are several options. If you have an ARM7 cross-compiler toolchain, you can simply type 'make' in the 'flash_write' subdirectory to rebuild the flash driver. If you don't have a suitable cross-compiler, you can just run 'scons' as usual. The build system will see that the flash driver is missing, and offer to download a binary copy from the LibNXT website and use that.