README.md

   1 # Cerebrum
   2
   3 Cerebrum is a RPC-like protocol for calling C functions on AVRs from a host
   4 application connected via serial port. Currently, the only viable host ist a
   5 still incomplete python library. The line protocol is very simple. A short
   6 description is in ```PROTOCOL```.  When a new device is connected, the host
   7 pulls the device's exported functions and parameters via a standardized, special
   8 function at address 0x0000.
   9
  10 ## Build process
  11
  12 The device-side code is generated by a python script (```generate.py```) living
  13 in the device directory according to a json configuration file passed to the
  14 top-level build script (```generatefw.py```).
  15
  16 When the device firmware is built, a build config file containing information on
  17 the actual ids of the callbacks and so on is generated. One copy is put in the
  18 ```builds/``` folder, another is lzma-compressed and hardcoded into the firmware
  19 to be used by host libraries for device discovery.
  20
  21 ## Adding Modules
  22
  23 More modules can be added in form of "module-name.c.tp" files in the respective
  24 device directories (currently implemented are avr and msp430 versions). If
  25 possible, when adding a new module generate.py should not be touched. These .tp
  26 files are mako templates which will be included once for each time the module
  27 is included in the device configuration ```.json```.
  28
  29 ### Parameters
  30
  31 A parameter is defined with a format and a function id. The parameter has two
  32 functions: a "getter" and a "setter" function. The getter can be found at the
  33 function id in the parameter spec, to address the setter the id must be
  34 incremented by 1. The getter takes no arguments and returns the current value of
  35 the parameter. The setter takes the new value of the parameter as an argument.
  36
  37 ### Format strings
  38
  39 The format strings are as used in the python ```struct``` module. Between host
  40 and device, values are exchanged in binary form as marshaled by the
  41 beforementioned python ```struct``` module according to the format strings given
  42 for function parameters or return values. On the device side, the marshaling and
  43 unmarshaling of the module names still is done by hand, the automation of that
  44 is on the to-do list.
  45
  46 ### Module support functions
  47
  48 There are a few python functions which can be used from module templates.
  49
  50  * ```init_function()``` will be replaced by the unique name of an init function
  51    for this module instance that is automagically called on startup.
  52  * ```loop_function()``` will be replaced by the unique name of a loop funtion
  53    for this moduel that is called regularly (as often as the system finds time
  54    for it, at most each 100µs).
  55  * ```modulevar(name, ctype, fmt, array)``` handles the definition and usage of
  56    module parameters. When called with ```name``` alone set it will return the
  57    an name for the named module parameter that is unique down to a module
  58    instance level. If ```ctype``` and ```fmt``` are also set, the parameter is
  59    automatically registered as such and getter and setter methods are generated.
  60     * ```ctype``` is the name of the c type used for this module parameter.
  61     * ```fmt``` is a string containing the python struct format specification
  62       string corresponding to the c type used for this module instance
  63       parameter.
  64     * ```array``` is an optional parameter which may be set to an integer to
  65       tell the code generator that this parameter is an array of size
  66       ```array```.
  67  * ```module_callback(name, argformat, retformat)``` registers a new module
  68    callback. This callback will appear in this module instance's ```functions```
  69    section in the build config. ```argformat``` and ```retformat``` are the
  70    python struct format strings for the callback's arguments and return value,
  71    respectively. They can be omitted. The callback is passed three arguments:
  72     * an uint16_t containing the offset of the current block of data
  73     * an uint16_t containing the size of the current block of data
  74     * an uint8_t* pointing to the next block of data
  75    If more data is sent to the function than ```ARGBUF_SIZE``` bytes (default:
  76    32), the callback is called repeatedly with increasing ```payload_offset```.
  77
  78 On top of that the templates can access pretty much all of python thanks to
  79 mako.
  80
  81 For more details on the invocation of these helper functions please have a look
  82 at the existing templates as well as the python code.