LibNXT and FwFlash
                        v0.4.2
                 ====================

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 1.0 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 (https://lejos.sourceforge.io/). 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?
====

Original author is 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.

Fourteen years after the last release, Nicolas Schodet took over the
project to make it live for another decade or more. First goal is to
update it to use new libusb versions, then next goals will be to add
new features and make it easier to use, while still staying true to
the original design.

How?
====

To compile all of this you'll need a copy of libusb 1.0 on your
system, as well as an ARM compiler and the Meson build system.

If you are running a debian based system, you can install them using:

    sudo apt install build-essential libusb-1.0-0-dev meson gcc-arm-none-eabi

To build the optional manual pages, you also need scdoc:

    sudo apt install scdoc

When you have all that, build with:

    meson build
    cd build
    meson compile

Once you're done, you can try fwflash out by resetting your NXT (see
bellow) and running:

    ./fwflash firmware.bin

How to flash a NXT firmware?
============================

Make sure you have a firmware to flash. This is usually a .rfw or .bin
file of size 262144 byte. You can find one:

- on your current installation of the Minstorms software,
- on the NXT Improved Firmware website:
  https://nxt-firmware.ni.fr.eu.org/releases/
- or on the Enhanced NBC/NXC Firmware website:
  http://bricxcc.sourceforge.net/firmware.html

Connect the NXT using a USB cable. You can check in your operating
system logs that the NXT is detected. On linux, you can also check
that the NXT is connected using lsusb. Make sure that the cable is
good as it was reported that bad cable make the procedure fail.

Then press and hold, for at least five seconds, the reset button which
is hidden in the pin hole under the USB port. The brick should make a
clicking noise and you can check in your operating system logs that
the NXT is detected in SAM-BA mode, with a different identification.

Then run fwflash:

    ./fwflash firmware.bin

Where firmware.bin is the path to your firmware file.

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.