The Hail Platform
Hail is an embedded IoT module for running Tock. It is programmable over USB, uses BLE for wireless, includes temperature, humidity, and light sensors, and has an onboard accelerometer. Further, it conforms to the Particle Photon form-factor.
For Hail schematics or other hardware details, visit the Hail repository.
Getting Started with Hail
In addition to the Hail hardware, you will need a Micro USB Cable to power the Hail. Any cable will do (here's what's on my desk).
Hail should come with the Tock kernel and the Hail test app pre-loaded. When you plug in Hail, the blue LED should blink slowly (about once per second). Pressing the User Button—just to the right of the USB plug—should turn on the green LED.
Connecting to Hail
The Hail board should appear as a regular serial device (e.g.
/dev/tty.usbserial-c098e5130006 on my machine). While you can connect with
any standard serial program (set to 115200 baud), Tock ships with the
tockloader utility to make programming and interfacing easier. To
install tockloader, use pip:
(Linux): sudo pip3 install --upgrade (MacOS): pip3 install --upgrade
Tockloader can read attributes from connected serial devices, and will
automatically find your connected Hail. Simply run
$ tockloader listen No device name specified. Using default "tock" Using "/dev/cu.usbserial-c098e5130006 - Hail IoT Module - TockOS" Listening for serial output. [Hail Sensor Reading] Temperature: 2423 1/100 degrees C Humidity: 4090 0.01% Light: 187 Acceleration: 1003 ...
Tockloader has a several other useful features, such as
tockloader list which
collects all of the applications currently installed:
$ tockloader list [App 0] Name: hail Total Size in Flash: 65536 bytes
Check out the tockloader homepage for more information on tockloader.
Running your own applications
First, you will need to get your development environment set up (if you already
rustup and the
arm-none-eabi- toolchain installed, you can skip this
- Follow Tock's Getting Started guide to install Rust and GCC for Arm.
Let's replace the
hail test app with the basic
Start with a clean slate
$ tockloader erase-apps
Use tockloader to load a compiled version of the blink app
$ tockloader install blink
blink app will detect that Hail has three LED channels and rotate through
all eight colors.
The source to blink is in the libtock-c repo.
The stock blink app cycles a little fast for my taste. It also doesn't print
anything about what it's doing. Let's fix that. Open
delay_ms(250)to a larger value, maybe 2000
- Add a
printf("Hello from the Blink app!\n");to the beginning of the program (also
tockloader install --make. This will automatically rebuild
your application and then install it on Hail.
Loading another application
One of the big advantages of Tock over traditional embedded operating systems is
that it can run multiple applications concurrently. Let's head back down into
the examples directory and install (
make && tockloader install) the
application. While we're at it, let's install
Now try running
tockloader listen – three apps running at once, cool!
There are a few more advanced sample applications that are worth checking out:
- accel-leds changes LED color based on the board's orientation
- ble-env-sense shows how to integrate with the onboard Bluetooth to act as an environmental sensor
- find_north acts as a simple compass, turning the LED on when the board is pointed north (the magnetometer tends to get confused in large buildings, best tried outdoors)
Writing a new app
We recommend starting from an existing example app and modifying it. Building Tock applications can be a little complicated, so we recommend using the Tock build system, simply a three-line Makefile in your app:
TOCK_USERLAND_BASE_DIR = ../.. C_SRCS := $(wildcard *.c) include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk
Hacking the Tock Kernel
For information on the Tock kernel itself and where to start editing, head over to the Tock documentation.
Once you've made changes (or if you're simply pulling an updated kernel from
upstream), you can update the kernel via
cd tock/boards/hail make program
Debugging the Kernel
You can use gdb to debug a running kernel. The
jlink/ folder has some scripts
designed to work with the J-Link Debugger.
In one terminal run
jlink_gdbserver.sh, and in another terminal
You may also find the
make lst target helpful. It will generate a listings file
with disassembly of the kernel image at