Cerebrum is a system building modular firmware images for embedded
microcontrollers that can be controlled from a host application connected via
an RPC-like protocol on any serial bus. Currently, there is a python module
implementing such a host. It is simple enough to be easily ported to other
languages. A C library is planned. The serial protocol is very simple. A short
description is in
PROTOCOL. The host automatically discovers new devices
connected to the bus, assigns them short bus-addresses and pulls the device's
exported functions and parameters.
The device-side code is generated by
When the device firmware is built, a build config file containing information
on the actual ids of the callbacks, the random device MAC address etc. is
generated. One copy is put in the
builds/ folder, another is
lzma-compressed and hardcoded into the firmware to be used by host libraries
for device discovery.
To use the integrated USB controller of some AVRs with the avrusb target place a
copy of the LUFA not-so-lightweight AVR usb stack
More modules can be added in form of "module-name.c.tp" files in the respective
device directories (currently implemented are avr and msp430 targets, the AVR
target is available in a version using the default UART and a version using the
integrated USB controller of certain AVRs). These .tp files are mako templates
which will be included once for each time the module is included in the device
.json, so it is best to avoid global variables or functions
(except in some special cases).
A parameter is defined with a format and a function id. The parameter has two functions: a "getter" and a "setter" function. The getter can be found at the function id in the parameter spec, to address the setter the id must be incremented by 1. The getter normally takes no arguments and returns the current value of the parameter. The setter takes the new value of the parameter as an argument. It may be possibe to use the getter to write a variable and read back the new value in one pass.
The format strings are as used in the python
struct module. Between host
and device, values are exchanged in binary form as marshaled by the
struct module according to the format strings given
for function parameters or return values. On the device side, the marshaling and
unmarshaling of the module names is done by hand e.g. using structs (which is
not too bad considering the simple data format).
Module support functions
There are a few python functions which can be used from module templates.
init_function()returns the unique name of an init function for this module instance that is automagically called on startup.
loop_function()returns the unique name of a loop funtion for this module that is called regularly (as often as the system finds time for it, hopefully at most each few hundred microseconds or something).
modulevar(name, ctype, fmt, array, callbacks)handles the definition and usage of module parameters. When called with
namealone it will return the an module instance-level unique name for the module parameter. If
fmtare given, the parameter is registered as such in the device config and getter and setter methods are generated. For more advanced options, see the doc in
ctypeis the name of the c type used for this module parameter (e.g.
fmtis a string containing the python struct format specification string corresponding to the c type used for this module instance parameter. *
arrayis an optional parameter which may be set to True or an integer to tell the code generator that this parameter is an array.
module_callback(name, argformat, retformat)registers a new module callback. This callback will appear in this module instance's
functionssection in the build config.
retformatare the python struct format strings for the callback's arguments and return value, respectively. They can be omitted. The callback is passed two arguments:
- The current callback descriptor containing the address of the argument buffer
- A pointer to the byte after the last byte of the argument buffer written to
On top of that the templates can access pretty much all of python thanks to mako. For more details on the invocation of these helper functions please have a look at the existing templates as well as the python code.