README.md

   1 # Cerebrum
   2
   3 Cerebrum is a system building modular firmware images for embedded
   4 microcontrollers that can be controlled from a host application connected via
   5 an RPC-like protocol on any serial bus. Currently, there is a python module
   6 implementing such a host. It is simple enough to be easily ported to other
   7 languages. A C library is planned.  The serial protocol is very simple. A short
   8 description is in ```PROTOCOL```.  The host automatically discovers new devices
   9 connected to the bus, assigns them short bus-addresses and pulls the device's
  10 exported functions and parameters.
  11
  12 ## Build process
  13
  14 The device-side code is generated by ```build.py```.
  15
  16 When the device firmware is built, a build config file containing information
  17 on the actual ids of the callbacks, the random device MAC address etc. is
  18 generated. One copy is put in the ```builds/``` folder, another is
  19 lzma-compressed and hardcoded into the firmware to be used by host libraries
  20 for device discovery.
  21
  22 To use the integrated USB controller of some AVRs with the avrusb target place a
  23 copy of the [LUFA not-so-lightweight AVR usb stack](http://www.fourwalledcubicle.com/LUFA.php)
  24 in ```avrusb/lufa```.
  25
  26 ## Adding Modules
  27
  28 More modules can be added in form of "module-name.c.tp" files in the respective
  29 device directories (currently implemented are avr and msp430 targets, the AVR
  30 target is available in a version using the default UART and a version using the
  31 integrated USB controller of certain AVRs). These .tp files are mako templates
  32 which will be included once for each time the module is included in the device
  33 configuration ```.json```, so it is best to avoid global variables or functions
  34 (except in some special cases).
  35
  36 ### Parameters
  37
  38 A parameter is defined with a format and a function id. The parameter has two
  39 functions: a "getter" and a "setter" function. The getter can be found at the
  40 function id in the parameter spec, to address the setter the id must be
  41 incremented by 1. The getter normally takes no arguments and returns the
  42 current value of the parameter. The setter takes the new value of the parameter
  43 as an argument. It may be possibe to use the getter to write a variable and
  44 read back the new value in one pass.
  45
  46 ### Format strings
  47
  48 The format strings are as used in the python ```struct``` module. Between host
  49 and device, values are exchanged in binary form as marshaled by the
  50 beforementioned python ```struct``` module according to the format strings given
  51 for function parameters or return values. On the device side, the marshaling and
  52 unmarshaling of the module names is done by hand e.g. using structs (which is
  53 not too bad considering the simple data format).
  54
  55 ### Module support functions
  56
  57 There are a few python functions which can be used from module templates.
  58
  59  * ```init_function()``` returns the unique name of an init function for this
  60    module instance that is automagically called on startup.
  61  * ```loop_function()``` returns the unique name of a loop funtion for this
  62    module that is called regularly (as often as the system finds time for it,
  63    hopefully at most each few hundred microseconds or something).
  64  * ```modulevar(name, ctype, fmt, array, callbacks)``` handles the definition
  65    and usage of module parameters. When called with ```name``` alone it will
  66    return the an module instance-level unique name for the module parameter.  If
  67    ```ctype``` and ```fmt``` are given, the parameter is registered as such in
  68    the device config and getter and setter methods are generated. For more
  69    advanced options, see the doc in ```generator.py```.
  70     * ```ctype``` is the name of the c type used for this module parameter (e.g.
  71       ```int```).
  72     * ```fmt``` is a string containing the python struct format specification
  73       string corresponding to the c type used for this module instance
  74       parameter.
  75     * ```array``` is an optional parameter which may be set to True or an
  76           integer to tell the code generator that this parameter is an array.
  77       ```array```.
  78  * ```module_callback(name, argformat, retformat)``` registers a new module
  79    callback. This callback will appear in this module instance's ```functions```
  80    section in the build config. ```argformat``` and ```retformat``` are the
  81    python struct format strings for the callback's arguments and return value,
  82    respectively. They can be omitted. The callback is passed two arguments:
  83     * The current callback descriptor containing the address of the argument
  84       buffer
  85     * A pointer to the byte after the last byte of the argument buffer written
  86       to
  87
  88 On top of that the templates can access pretty much all of python thanks to
  89 mako. For more details on the invocation of these helper functions please have
  90 a look at the existing templates as well as the python code.