Orchard Firmware Developer's Guide

Setting up your Environment

For the sake of convenience, Orchard firmware development, including compilation, flashing, and manufacturing provisioning is all done with a single tool: A Raspberry Pi.

Recommended tools:

• Raspberry Pi 2 Model B with 8 GB microSD card
• Firmware image: Raspberry pi Orchard development SD disk image
• A Linux machine to write the initial firmware image out
• Jumper cables, 5-wire (for SWD) and 2-wire (for UART), going between male 0.1" headers.

Hardware Setup

1. Download the RPi firmware image (~2GiB).

2. Image the downloaded firmware onto an SD card using the following Linux command: (This may take about 10 minutes)

zcat orchard-pi-dev.img.gz | sudo dd of=/dev/sdX bs=1M   # for SD cards mounted via USB adapters

or

zcat orchard-pi-dev.img.gz | sudo dd of=/dev/mmcblkX bs=1M  # for machines with directly accessible SD cards

Note that /dev/sdX is the device node of the SD card as mounted on your Linux system. If you don't know what we're talking about, be careful, because if you pick the wrong /dev/sdX node you'll end up destroying your local system boot disk.

3. Insert card into RPi and boot.

4. Figure out the IP address of the RPi and ssh into it. This is probably the hardest step.

• Here's a guide to figuring out your IP address
• One method is to access the local router configuration page and query the DHCP client list and look for the rasperrypi client. This works if you're in a home environment where you have access to the local DHCP server
• If you don't have access to that, you can plug in an HDMI monitor and keyboard and find the IP address using ifconfig
• A final method is to use nmap to scan for the IP address
• Another solution is to use zeroconf. The image provided runs zeroconf and if your local system supports that. Linux users should install avahi-dnsconfd. Windows users will need to install bonjour printing services. If you have zeroconf, you should be able to run

ssh pi@raspberrypi.local 

And the system will automatically find it (assuming it's the only Pi on the network, additional Pi's get a hyphenated numeral after the raspberrypi name)

Either way, the credentials are "pi" and "raspberry" for the username and password.

5. Wire up your raspberry pi to the orchard dev board.

Be careful to not use the two pins closest to the outside corner of the board. They have 5V on them and will damage orchard if you wire it up to its signal pins.

If you're unsure, here's some photos of the orchard-raspberry pi connection.

6. Plug power into the orchard dev board via the microUSB cable.

Firmware Development

Build your firmware image

1. Update your source code

cd orchard-src
git pull

2. Build an image

cd ~/orchard-src/orchard
make -j4

Note: If you're using an alternate keyboard or board version from the default Makefile (currently BC1/EVT1B), specify the version as follows in the environment variable:

make -j4 KEY_LAYOUT=BM BOARD_REV=EVT1

Connect OpenOCD

Start openocd, the connection between the Rpi host and the Orchard target CPU:

sudo openocd -f sysfsgpio-rpi.cfg &

If you've wired up the boards correctly, you should see this somewhere in the log:

Info : SWD IDCODE 0x0bc11477

The correct IDCODE means we can see the CPU over the SWD debug port.

First-time Provisioning

On a blank device (factory new or mass-erased), you will need to provision an initial firmware image.

The Kinetis W repeatedly stabs itself in the eye when the Flash is empty, and will not work with GDB until it has something valid to run. The current procedure involves using a telnet protocol to run openOCD commands directly to provision an initial image:

telnet localhost 4444

Once in the telnet session, use these commands:

reset halt
program build/orchard.elf
reset

GDB Debugging

Once the initial image is provisioned, you can connect via gdb.

gdb build/orchard.elf
target remote localhost:3333

From this point, you can use all your usual gdb commands: breakpoints, running, source code listing, disassembly, variable inspection, single-stepping, etc. etc. For a list of common gdb commands, see Orchard gdb cheatsheet

If when you try to connect via GDB, you see this message:

(gdb) target remote localhost:3333
Remote debugging using localhost:3333
Info : accepting 'gdb' connection on tcp/3333
Warn : Cannot communicate... target not halted.
Error: auto_probe failed

You need to halt the CPU manually. You can do this by doing

telnet localhost 4444
reset halt
exit

And then running the gdb command again.

Serial Console

To talk to the serial console, open another window (perhaps via a second ssh session) and type this command:

screen /dev/ttyAMA0 115200

You should see a "ch>" prompt if you hit enter.

To exit the screen session, type cntrl-A \ y

Code Documentation

Overview

Orchard runs ChibiOS 3, a lightweight multi-threaded RTOS.

For those who have not done multi-threaded programming, the key thing to pay attention to are the locks on resources, to prevent contention that can lead to hardware lock-ups and hanging. As you write code, think to yourself, "if someone else interrupted me in the middle of this, would that be bad?" If the answer is yes, you should consider using a lock on a resource.

The base firmware as of June 2015 runs the following threads:

• main
• idle
• charger watchdog
• LED effects
• shell
• orchard app

3792 bytes of heap are free, out of 16k total RAM, and 80k of ROM is used (this includes -f debug-all-the-things).

Threads

The main thread is the first thread run by chibiOS. Eventually, this thread is responsible for managing and launching the apps. It has a 768 byte stack area.

The charger watchdog is responsible for pinging the BQ24260 charger when in boost or charger mode. The charger will turn off charging or boosting if it thinks the MCU has crashed, as a matter of safety. The thread is always running, and the behavior to ping the the charger is configured via a static variable called the "chargerIntent". The idea being that another thread will communicate the intent of the system to the thread, and the next time it's scheduled to run the charger thread will actually implement that intent. This thread has a 192 byte stack area.

The LED effects thread is responsible for rendering the WS2812B frame buffer (16 pixels total on the burning man edition), compositing with the UI cues, and running the bit-bang protocol to send data to the LEDs. The bit-bang protocol is a hand-coded assembly routine (see ws281b_ll.s), tuned via clock counting to create the correct waveforms. Since it's timing sensitive, the actual LED update locks the entire system for the duration of the update. The LED thread also has a one-way mode to turn off the LEDs for system shutdown (if you don't render all off-state to the LEDs, they'll stay on). This thread has a 256 byte stack area.

The shell thread launches shell commands. These are commands entered via the serial debug port. Shell commands are typically used for debugging and configuration. More on this later. The shell thread has a 768 byte stack.

The orchard app thread launches UI apps. These are applets that use the OLED and typically respond to touch surface events for interaction. Apps are the actual user-visible front ends to orchard functionality. The app thread has a 2048 byte stack.

The idle thread runs when nothing else is scheduled to be run. See chibiOS thread documentation.

Conventions

• Functions that are globally visible have names in camelCase.
• Functions that are static to a file use_underscores_between_words.
• All low level drivers have a Start and Stop function (e.g., accelStart(), accelStop()). Calling Stop puts it into a low-power state, calling Start brings it back to life.
• Some drivers also have an Init call, that should get called exactly once.
• Use two spaces for indentation. No tabs.
• Use /* and */ for comments.

Gotchas

Be aware when you're executing in an interrupt context. Typically callbacks and handlers run in an interrupt context. This includes:

• Timer callbacks
• interrupt handlers
• ADC callbacks

When you're in an interrupt context, you can't run operations that can potentially cause another interrupt to happen, which turns out to be most interesting things. You can only run system functions that have an I or S in their name (e.g. chEvtBroadcastI() or chVTSetI()).

Typically to get around this, handlers issue events which are queued into a thread, and handled in a normal, interruptable context.

Eventing system example

One fun feature of ChibiOS is a many-to-many event system. Events are represented by an object of type event_source_t. Objects must be initialized once using chEvtObjectInit().

Events can then be hooked and unhooked using the call evtTableHook() and evtTableUnhook(). You can assign multiple hooks to a single event, thus allowing one event to drive behaviors in multiple threads.

An event is broadcast to the system using chEvtBroadCast(), or alternatively, chEvtBroadCastI() when you're running in an interrupt context. chEvtBroadCastI must be flanked by chSysLockFromISR() and chSysUnlockFromISR() on either side.

An example of a fairly complex event system is the USB charge detection loop. The purpose of this loop is to periodically measure the D+/D- pins on the USB interface to see if we've been plugged into a charger.

Most of the code is in orchard-app.c. It starts with a timer, chargecheck_timer, that runs a callback run_chargecheck:

chVTReset(&chargecheck_timer);
chVTSet(&chargecheck_timer, MS2ST(CHARGECHECK_INTERVAL), run_chargecheck, NULL); 

run_chargecheck itself is in an interrupt context, so it can't directly query the ADC -- the ADC is interrupt-driven. So all it can do is issue an event, and then reschedule itself to run again:

static void run_chargecheck(void *arg) {
  (void)arg;

  chSysLockFromISR();
  chEvtBroadcastI(&chargecheck_timeout);
  chVTSetI(&chargecheck_timer, MS2ST(CHARGECHECK_INTERVAL), run_chargecheck, NULL);
  chSysUnlockFromISR();
}

chargechcek_timeout is an event that's setup as follows:

 chEvtObjectInit(&chargecheck_timeout);
 evtTableHook(orchard_events, chargecheck_timeout, handle_chargecheck_timeout);

The code for the event handler is simple, it just kicks off a call to update the USB status:

static void handle_chargecheck_timeout(eventid_t id) {
  (void)id;

  // this kicks off an asynchronous ADC request that results in a usbdet_rdy event 
  analogUpdateUsbStatus();
}

Inside analog.c, we see how an ADC call is made:

void analogUpdateUsbStatus(void) {
  adcAcquireBus(&ADCD1);
  adcConvert(&ADCD1, &adcgrpusb, usb_samples, ADC_GRPUSB_BUF_DEPTH);
  adcReleaseBus(&ADCD1);
}

Note how adcConvert is flanked by an Acquire/Release motif. Most shared hardware resources, such as SPI and I2C, will require you to lock a mutex, so that multiple threads don't bash each other during a hardware operation. Failing to acquire/release mutexes like this is one of the most common causes of unreliability in chibiOS -- so do it!

adcConvert in this case has a callback of adc_usb_end_cb given to it, which was plugged into the correct spot in the ADCConverionGroup structure (adcgrpusb).

adc_usb_end_cb is handed a sample buffer and it computes the USB status and stores it in a static variable for another thread to later retrieve, and then issues a usbdet_rdy event. Again, this routine has to be minimal because it's running in an interrupt context and we use the event system to signal to a regular thread that it should read the usb_status variable:

static void adc_usb_end_cb(ADCDriver *adcp, adcsample_t *buffer, size_t n) {
 (void)adcp;
 (void)n;

 usbn = (uint16_t) buffer[0];
 usbp = (uint16_t) buffer[1];

 // plugged into "live" USB port: USBN > 0xE000 && < 0xF800, USBP < 0x200 
 // not connected: UNBN > 0xFF00, USBP > 0x200 (primarily USBN is the determining factor)
 // plugged into "CDP" port: USBN ~ USBP ~ FD00
                     
 usb_status = usbStatNC;
 if( (usbn > 0xE000) && (usbn < 0xF800) && (usbp < 0x400) ) {
   usb_status = usbStat500;
 } else if( (usbn > 0xF000) && (usbp > 0xF000) ) {
   usb_status = usbStat1500;
 } else if( (usbn > 0xFE80) ) {
   usb_status = usbStatNC;
 }

 chSysLockFromISR();
 chEvtBroadcastI(&usbdet_rdy);
 chSysUnlockFromISR();
}

Back in orchard-app.c, we look and see what's going on with the usbdet_rdy event system:

 chEvtObjectInit(&usbdet_rdy); // this line is actually in orchard-events.c

 evtTableHook(orchard_events, usbdet_rdy, handle_charge_state);
 evtTableHook(orchard_app_events, usbdet_rdy, adc_usb_event);

Here, we see that the usbdet_rdy event actually broadcasts to two handlers: handle_charge_state, and adc_usb_event. handle_charge_state is part of the orchard_events group, and is routed to the main thread. adc_usb_event is routed to the application-specific event handler, giving applications an opportunity to react to the charge state (this is necessary for the charger status app, for example).

handle_charge_state reads the cached USB status (previously computed in an interrupt context) using an API call, and then dispatches to the correct intent behavior that's eventually swept up by the charger thread that manages the charging watchdog. The code is too big to include here but you can find it in orchard-app.c.

adc_usb_event is pretty compact. It just issues an event into the running instance app informing it of the updated USB detection code:

static void adc_usb_event(eventid_t id) {
 (void) id;
 OrchardAppEvent evt;

 evt.type = adcEvent;
 evt.adc.code = adcCodeUsbdet;
 instance.app->event(instance.context, &evt);
}

The app itself would then have a main event loop that would check to see the type of event it received and update the UI accordingly. An example of this is in app-charging.c, inside charging_event().

Command line programs

A serial protocol-driven command line is provided in Orchard. A simple example of a command line program is cmd-mem.c. The entire program can be shown here:

void cmd_mem(BaseSequentialStream *chp, int argc, char *argv[])
{
 size_t n, size;

 (void)argv;
 if (argc > 0) {
   chprintf(chp, "Usage: mem\r\n");
   return;
 }
 n = chHeapStatus(NULL, &size);
 chprintf(chp, "core free memory : %u bytes\r\n", chCoreGetStatusX());
 chprintf(chp, "heap fragments   : %u\r\n", n);
 chprintf(chp, "heap free total  : %u bytes\r\n", size);
}

orchard_command("mem", cmd_mem);

A command is passed a stream (for printf IO -- you can print to any of multiple serial ports, so a stream is passed similar to fprintf()), and an argc/argv pair. Unlike C argc/argv, the command itself isn't passed as one of the pairs, so the 0-index is the first argument, not the name of the command.

Adding a new command is easy. The build system is filename-driven, so:

• Create a file called cmd-yourcommand.c. The cmd-* prefix is a wildcard that informs the Makefile to automatically include this source file in the build.
• Inside the file, include the macro orchard_command("command_name", command_callback).
  • A single file can have multiple orchard_command() macros, and it will create commands for each of them. So you don't need one file per command, it's one file per command subsystem.
  • cmd-touch.c is an example of multiple command callbacks in a single file.

Applications

Applications are user-facing programs that run in their own thread. They will typically draw to the screen and respond to events generated from low level drivers.

You can only have one application running at a time, and they run in a single thread. ChibiOS threads are cooperative: you can't kill a thread. You can only request its termination. Therefore, apps are wrapped in code that does the following:

• Hooks events into an event handler that ultimately drives app behavior
• Cleans up any UI primitives left dangling by the app
• Listens for the thread termination request and sets up the next app to run upon termination

You don't see any of this code; an app simply implements a unique set of _init, _start, _event, and _exit routines.

Adding an app is similar to creating a new command. The build system is filename-driven, so:

• Create a flie called app-yourapp.c. The app-* prefix tips off the Makefile to include your app for building.
• Include the macro orchard_app("name", app_init, app_start, app_event, app_exit);
  • The name is the display name of the app, used by the app launcher
  • The app launcher is itself an app, with the exception that its position on the app-list is hard coded as the first app (it doesn't use the orchard_app() macro)
  • _init is used to determine how much privileged memory an app needs prior to calling _start. In most cases, it can be left NULL or a dummy.
  • _start initializes the app and sets up the UI
  • _event handles events and drives the UI in response to events
  • _exit cleans up the app
• While you can have multiple apps in a single file, apps are heavyweight enough it's discouraged.
• By convention, a function called redraw_ui() is used to update the graphical UI.

Graphics and UI Primitives

Graphics

Any app is free to grab the frame buffer and just start drawing into it. Because multiple threads can contend for UI resources, any UI operation must be flanked by mutex operations orchardGfxStart() and orchardGfxEnd().

Graphics calls are from the gdisp set of calls in the uGfx library. A subset of the available functions are provided, to keep the memory footprint small. In particular, we have most of the gdisp series of functions, but we don't use their windowing system or eventing system.

Generally, a UI redraw should first blank the screen, and then draw its primitives. Primitives are not flushed to the display until gdispFlush() is called. In other words, you can do all the drawing you want and nothing will appear on the screen until gdispFlush() happens.

Drawing itself is a fairly inexpensive operation, the gdispFlush() call tends to be the most expensive bit, so first complete all your UI drawing before calling the flush.

Remember, you're trying to do UI in just a couple thousand bytes of RAM and a few hundred bytes of code, so when making your wireframes and workflow, keep the resource restrictions in mind. You are not coding for an Android or iOS device!

In theory, it's possible to display bitmaps on Orchard, but it's unclear if there's enough RAM to run the decoder.

UI primitives

Because Orchard is very lightweight and runs on a very small stack, we can't afford to have a windowing system. In order to re-use UI between apps, UI primitives are patched in over an app's event system when they are needed.

Generally, the UI primitives envisioned to be used on Orchard are simple: text entry, selection lists, check boxes, radio boxes, and dialog boxes.

UI state is kept in a UiContext, which has an item list, a linked list of items to render on a UI. It's important that a UI implementation de-allocates any heap structures it creates while running. A single 32-bit value is provided as the ui_result, and the meaning of this value is dependent upon the UI primitive implementation.

When a UI primitive is created, it's hooked into the orchard_app_instance context. Once the pointers no the OrchardUi are non-null, the app event system will redirect all events to the UI, allowing it to draw items on the screen and capture user input. Upon exit, the ui_result is returned, memory is de-allocated, and the UI unlinks itself from the orchard_app_instance state.

An example of how to use a UI primitive is found in app-name.c