Cerebrum

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.

Build process

The device-side code is generated by build.py.

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 in avrusb/lufa.

Adding Modules

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 configuration .json, so it is best to avoid global variables or functions (except in some special cases).

Parameters

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.

Format strings

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 beforementioned python 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 name alone it will return the an module instance-level unique name for the module parameter. If ctype and fmt are 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 generator.py.
  • ctype is the name of the c type used for this module parameter (e.g. int).
  • fmt is a string containing the python struct format specification string corresponding to the c type used for this module instance parameter.
  • array is an optional parameter which may be set to True or an integer to tell the code generator that this parameter is an array. array.
• module_callback(name, argformat, retformat) registers a new module callback. This callback will appear in this module instance's functions section in the build config. argformat and retformat are 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.