summaryrefslogtreecommitdiff
path: root/Host/libnxt-0.3/README
diff options
context:
space:
mode:
Diffstat (limited to 'Host/libnxt-0.3/README')
-rw-r--r--Host/libnxt-0.3/README129
1 files changed, 129 insertions, 0 deletions
diff --git a/Host/libnxt-0.3/README b/Host/libnxt-0.3/README
new file mode 100644
index 0000000..5b54bd3
--- /dev/null
+++ b/Host/libnxt-0.3/README
@@ -0,0 +1,129 @@
+ 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.