Minimal stripped-down firmware for the Warp family of hardware platforms

This is the firmware for the Warp hardware and its publicly available and unpublished derivatives. This firmware also runs on the Freescale/NXP FRDM KL03 evaluation board which we use for teaching at the University of Cambridge. When running on platforms other than Warp, only the sensors available in the corresponding hardware platform are accessible.

Prerequisites: You need an arm cross-compiler such as arm-none-eabi-gcc installed as well as a working cmake (installed, e.g., via apt-get on Linux or via MacPorts on macOS). You will also need an installed copy of the SEGGER JLink commander, JlinkExe, which is available for Linux, macOS, and Windows (here are direct links for downloading it for macOS, and Linux tgz 64-bit).

1. Compiling the Warp firmware

First, make sure the environment variable ARMGCC_DIR is set correctly (you can check whether this is set correctly, e.g., via echo $ARMGCC_DIR; if this is unfamiliar, see here or here). If your arm-none-eabi-gcc is in /usr/local/bin/arm-none-eabi-gcc, then you want to set ARMGCC_DIR to /usr/local. If your shell is tcsh:

  setenv ARMGCC_DIR <full path to the directory containing bin/arm-none-eabi-gcc>

Alternatively, if your shell is bash

  export ARMGCC_DIR=<full path to the directory containing bin/arm-none-eabi-gcc>

(You can check what your shell is, e.g., via echo $SHELL.) Second, edit the jlink command file, tools/scripts/jlink.commands to include the correct path.

Third, you should be able to build the Warp firmware by

cd build/ksdk1.1/
./build.sh

This copies the files from Warp/src/boot/ksdk1.1.0/ into the KSDK tree, builds, and converts the binary to SREC. See Warp/src/boot/ksdk1.1.0/README.md for more. When editing source, edit the files in Warp/src/boot/ksdk1.1.0/, not the files in the build location, since the latter are overwritten during each build.

NOTE: If you run into a compile error such as /usr/lib/gcc/arm-none-eabi/6.3.1/../../../arm-none-eabi/bin/ld: region m_data overflowed by 112 bytes, the error is that the firmware image size exceeded the KL03 memory size. Some arm-gcc cross compilers, particularly on Linux, generate firmware images that are quite large. Easiest fixes are either:

Comment out some of the driver includes in the list between lines 64 and 71 (these trigger the instantiation of various driver data structures which take up memory)

or

Modify src/boot/ksdk1.1.0/CMakeLists.txt and reduce the default stack size, e.g., by changing all occurrences of "stack_size=0x300” to, e.g., "stack_size=0x100"

Fourth, you will need two terminal windows. In one shell window, run the firmware downloader:

  JLinkExe -device MKL03Z32XXX4 -if SWD -speed 100000 -CommanderScript ../../tools/scripts/jlink.commands

In the other shell window, launch the JLink RTT client^{See note 1 below}:

JLinkRTTClient

2. Using the Warp firmware on the Freescale FRDMKL03 Board

The SEGGER firmware allows you to use SEGGER’s JLink software to load your own firmware to the board, even without using their specialized JLink programming cables. You can find the SEGGER firmware at the SEGGER Page for OpenSDA firmware.

To build the Warp firmware for the FRDM KL03, you will need to uncomment the #define WARP_FRDMKL03 define in src/boot/ksdk1.1.0/warp-kl03-ksdk1.1-boot.c.

3. Editing the firmware

The firmware is currently all in src/boot/ksdk1.1.0/, in particular, see src/boot/ksdk1.1.0/warp-kl03-ksdk1.1-boot.c and the per-sensor drivers in src/boot/ksdk1.1.0/dev*.[c,h].

The firmware builds on the Kinetis SDK. You can find more documentation on the Kinetis SDK in the document doc/Kinetis SDK v.1.1 API Reference Manual.pdf.

The firmware is designed for the Warp hardware platform, but will also run on the Freeacale FRDM KL03 development board. In that case, the only driver which is relevant is the one for the MMA8451Q. For more details about the structure of the firmware, see src/boot/ksdk1.1.0/README.md.

4. To update your fork

From your local clone:

git remote add upstream https://github.com/physical-computation/Warp-firmware.git
git fetch upstream
git pull upstream master

If you use Warp in your research, please cite it as:

Phillip Stanley-Marbell and Martin Rinard. “A Hardware Platform for Efficient Multi-Modal Sensing with Adaptive Approximation”. ArXiv e-prints (2018). arXiv:1804.09241.

BibTeX:

@ARTICLE{1804.09241,
	author = {Stanley-Marbell, Phillip and Rinard, Martin},
	title = {A Hardware Platform for Efficient Multi-Modal 
	Sensing with Adaptive Approximation},
	journal = {ArXiv e-prints},
	archivePrefix = {arXiv},
	eprint = {1804.09241},
	year = 2018,
}

Phillip Stanley-Marbell and Martin Rinard. “Warp: A Hardware Platform for Efficient Multi-Modal Sensing with Adaptive Approximation”. IEEE Micro, Volume 40 , Issue 1 , Jan.-Feb. 2020.

BibTeX:

@ARTICLE{8959350,
	author = {P. {Stanley-Marbell} and M. {Rinard}},
	title = {Warp: A Hardware Platform for Efficient Multi-Modal
	Sensing with Adaptive Approximation},
	journal = {IEEE Micro},
	year = {2020},
	volume = {40},
	number = {1},
	pages = {57-66},
	ISSN = {1937-4143},
	month = {Jan},
}

Acknowledgements

This research is supported by an Alan Turing Institute award TU/B/000096 under EPSRC grant EP/N510129/1, by Royal Society grant RG170136, and by EPSRC grants EP/P001246/1 and EP/R022534/1.

Notes

¹ On some Unix platforms, the JLinkRTTClient has a double echo of characters you type in. You can prevent this by configuring your terminal program to not echo the characters you type. To achieve this on bash, use stty -echo from the terminal. Alternatively, rather than using the JLinkRTTClient, you can use a telnet program: telnet localhost 19021. This avoids the JLink RTT Client's "double echo" behavior but you will then need a carriage return (↵) for your input to be sent to the board. Also see Python SEGGER RTT library from Square, Inc. (thanks to Thomas Garry for the pointer).

JamesTimothyMeech/Warp-firmware-minimal