Last night I installed the NuttX RTOS on
a new
STM32F4 Discovery
board I bought
at Mauser
a couple of days ago for $15. Of course, I was working from
Debian Linux. This would not have been possible without
extensive help from the Interwebs. I used too many different
references to list most of them here. Instead, I'm just
going to tell you how I would do it if I had it to do
over. Got to give something back, y'know. Here goes…
Hardware Needed
Software Needed
The latest NuttX tarball and NuttX apps tarball from their
website. I used version 6.32. Unpack the tarballs
according to the instructions in the top-level NuttX
README.
A "toolchain" for compiling, loading and debugging
code. I used Keith Packard's
Debian package for stlink, but he has upstreamed the other packages to Debian.
I then ran apt-get update
to refresh the cache. "I
may have also added Keith's GPG key somehow so that it
didn't whine? You'll likely also need to make sure you
have a Debian unstable feed enabled.
I used apt-get -t unstable install
to install needed
packages.
binutils-arm-none-eabi
gcc-arm-none-eabi
gdb-arm-none-eabi
stlink
The STM
firmware bundle
for the F4 Discovery. The one I have is called
stsw-stm32068.zip
. There's a newer firmware bundle available, but I haven't yet tried it.
The minicom
terminal program, installable via apt-get
.
Getting Ready To Go
Start by powering up the Discovery using the mini-USB
cable. You should get lots of pretty colored lights.
- If the Discovery has been messed with previously, the
default demo firmware may have been overwritten. See
"Recovering the Demo Firmware" below for how to get the
default demo firmware load back onto the board.
Tap the blue button and the lights will disappear. Tilt or move
the board to see the lights light up in the direction the
onboard Inertial Measurement Unit (IMU) thinks the board is going
right now.
Have big fun with connecting the micro-USB port and
noticing that the board IMU now acts like a (terrible)
mouse.
Discovery Board Architecture
This is probably a good point to explain a little bit about
the Discovery board architecture. The board consists of two
loosely-coupled sections.
One section of the Discovery board has the STM32F407VG
microcontroller, the audio subsystem, the buttons, and the
micro-USB OTG port. (USB "On-The-Go" is a standard by which
a USB port can serve as either a gadget port or a host port,
and can auto-negotiate endpoints when plugged into another
OTG port.) There is a JTAG-ish port here, labeled SWD (for
"Single-Wire Debug").
The other Discovery board section has the mini-USB gadget
port, which provides power to the board and also serves as a
connection to the ST-Link processor on the board. ST-Link is
an ST semi-proprietary protocol by which a USB host can
manipulate the operation of the STM32 microcontroller. As
near as I can work out, ST-Link works by forcing a bootstrap
program into RAM and then executing that program. Thus,
ST-Link will only work when the STM32 is in an awake state
and capable of being programmed.
ST-Link
The software we will use to talk to the ST-Link on the
Discovery board is
texane stlink
. texane
stlink
is an open source Linux version of ST's proprietary
ST-Link software for Windows.
From the point of view of a host talking to the Discovery
board via ST-Link, the 1MB of flash memory lives at
addresses 0-0x100000 if you want to read it, and
0x8000000-0x8100000 if you want to write it. The distinction
is important: trying to write to the lower address range
will silently fail.
Install texane stlink
with apt-get -t unstable install
stlink
and then try
sudo udevadm control --reload-rules
just to make sure that the device will be recognized. If the
mini-USB port is plugged in, unplug and replug it.
Backing Up the Firmware
While it is true that the ZIP from ST contains the demo
firmware, I'm never comfortable with that; who knows whether
it will be OK? To back up the firmware sitting on your
Discovery board, you can follow the steps below. Of course,
if you have no idea what firmware is on your Discovery
board, there's little point in this exercise.
If you haven't already, install the stlink
package as
described above.
Plug the mini-USB port in. The board should power up and
start its little demo dance. You will likely not unplug
the mini-USB for the rest of this HOWTO.
Say
st-flash read /tmp/stm32f4discovery-demo.bin 0x100000
Obviously, you can use whatever path and filename you
want. Put the resulting file somewhere safe, in case you
want to revert your board to how it was when you got it.
Configuring NuttX
If you haven't yet, now is a good time to grab NuttX
tarballs (or from the repo, I guess—haven't yet
tried). There are two tarballs you need, a nuttx
tarball
and an apps
tarball with the same version number. They
must be unpacked into the same parent directory, as the
former refers to the latter. Make a symlink from the versioned apps directory to just apps
.
Next, you need to make sure the gcc-arm-none-eabi
and
binutils-arm-none-eabi
cross-packages are installed as described above. The
configuration process wants to know that they are there.
Now you are going to configure NuttX for the platform. Most
of the work has already been done for us. Go into the
nuttx
directory, then one level down into tools
. Say
sh ./configure.sh stm32f4discovery/usbnsh
and then go back up a level.
Custom NuttX configuration is intended to be done using the
kconfig-frontend
tools as liberated from the Linux
kernel. Go download the latest
kconfig-frontend
tarball,
unpack it, and build and install it using the usual methods. Make sure that you have libncurses5-dev
installed before you try to configure kconfig-frontend
or it will fail to build the kconfig-mconf
you will need.
Now, type make menuconfig
at the nuttx
root and you
should be presented with a fairly familiar-looking
configurator.
You have several choices at this point.
You could carefully
read all the configuration documentation, and meditate over
what you might turn on to get desired functionality.
You could read the README files in the various
config/stm32f4discovery
directories, which describe a
lot of what to do.
You could move aside the .config
file that is sitting
at the top of the nuttx
tree and instead use
mine. Note
that this will only work for NuttX 7.8, but it is
probably the quickest route. You can run make oldconfig
to bring
this file up to date for your newer NuttX version.
Having done all this, you should be ready to go.
Building and Installing NuttX
Building NuttX is easy. Just say make
and wait. NuttX
builds quite quickly.
When the build is complete, you should have files named
nuttx
and nuttx.bin
sitting in the root directory. You
now have two choices. You can install directly using
st-flash
or by using gdb
as a loader. The gdb
method
is slightly less error-prone, but the st-flash
method is
easier if you're careful.
To install using st-flash
... If you haven't already,
install texane stlink
as described above. Then
st-flash write nuttx.bin 0x8000000
You should see a long sequence of interactions, after
which all the lights on the board should be red. This
probably means that you have successfully installed
NuttX.
To install using gdb
... If you haven't already, apt-get
-t unstable install gdb-arm-none-eabi
and also install
texane stlink
as described above.
Next, open a new terminal on your Linux box and run
st-util -v
. You should see a set of reports that ends
with "Listening at *:4242". This last is an indication of
how you can connect with gdb.
Finally, in a separate terminal from st-util
, run
arm-none-eabi-gdb nuttx
(note the weird flip from the package
name) and at the gdb
prompt say:
target extended-remote :4242
monitor halt
monitor reset
load
You should see a long sequence of interactions after the
load
, culminating in "Jolly good!" Now exit gdb
, which
should cause st-util
to die.
Now unplug the mini-USB, plug a cable from the host to the
micro-USB if you haven't already, and then plug the mini-USB
back in.
If all is well, you should see /dev/ttyACM0
on your host,
and some dmesg -T
output that indicates that this USB is
OK.
Talking To NSH
The NuttShell NSH is a simplistic application designed
mainly for light debugging and to show what the OS can do.
At this point, you should be ready to talk to NSH.
If you have not already, apt-get install minicom
. Once
it is up, you should be able to use minicom -s
as root.
Edit the "Serial port setup" to point minicom
at
/dev/ttyACM0
. No other changes should be needed. Then
"Save setup as dfl" and "Exit".
Now hit return three times. You should see the NSH prompt.
Play around with NSH; when you are done, you can use '^AQ'
to quit minicom. Always say "OK" to "Leave without reset?"
Congratulations on installing NuttX!
Recovering The Demo Firmware
At some point it may seem that the Discovery board is
"bricked" because the texane stlink
tools can no longer
talk to it. Unless you have managed to damage the hardware
physically by shorting things or something, you are almost
certainly still OK. Here's how to get back to where we
started:
If you have a file stm32f4discovery-demo.bin
containing a backup of the firmware as described earlier:
Go to the directory where that file is. Now flash
the firmware file with:
st-flash write stm32f4discovery-firmware.bin 0x8000000
If you do not have a backup: unpack
stsw-stm32068.zip
. Change to
the directory
STM32F4-Discovery_FW_V1.1.0/Project/FW_upgrade/Binary/
.
Now flash the firmware file with:
st-flash write STM32F4-Discovery_Demo_0x08008000.bin 0x08008000
If either of the above steps fails, the probable cause is
that the STM32F4 side of the Discovery board is in a state
that makes it unable to accept the boot program from the
ST-Link side of the board. To fix this, you can put the
Discovery board in Direct Firmware Upload (DFU) mode.
Power down the Discovery board by unplugging the mini-USB.
Get one of the little jumper "feet" off the bottom of the
Discovery board.
Use this jumper to connect the BOOT0
and VDD
pins in
the double row of pins on the right side of the board when
the lettering on the board is upside-up. Be careful to
connect exactly these two pins, or you could damage the
Discovery board on powerup.
Plug the mini-USB back in to power the Discovery board.
Push the black RESET
button on the board.
You should now be in a state where texane stlink
can talk
to the Discovery board without problem. Proceed with
uploading firmware as above.
Conclusions
The STM32F4 Discovery board is an incredible value at
$15. NuttX seems to be a fairly nice BSD-licensed RTOS with
great support for this board. Getting this all running is a
great preliminary to the software stage of Summer Hardware
Project, about which more soon. 