aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 9e8f9bd5bb35b06fc20d66a7f549a6b2150690ad (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
                  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 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?
====

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 1.0 on your system,
as well as the Meson build system.

 - Libusb 1.0: https://libusb.info/
 - Meson: https://mesonbuild.com/

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
your user manual for details on this) and running:

    ./fwflash firmware.bin

firmware.bin is a Lego Mindstorms NXT firmware. You can find this on
your current installation of the Mindstorms software, on LEGO's website,
on the NXT Improved Firwmare website, or on the Enhanced NBC/NXC
Firmware 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.