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```) on its standard input. This
  15 configuration file may contain a number of device configurations for devices
  16 connected to the computer as well as a mapping of logical names to the
  17 peripherals connected to these devices. Somehow this smells like
  18 over-engineering to me, if you don't like it, please tell me. I invented this
  19 layer of indirection because it is not very likely that the logical grouping of
  20 peripherals connected to a computer corresponds to the interfaces (arduinos
  21 etc.) by which the peripherals are connected to the computer.
  22
  23 When the device firmware is built, a build config file containing information on
  24 the actual ids of the callbacks and so on is generated. One copy is put in the
  25 ```builds/``` folder, another is lzma-compressed and hardcoded into the firmware
  26 to be used by host libraries for device discovery.
  27
  28 ## Adding Modules
  29
  30 More modules can be added in form of "module-name.c.tp" files in the respective
  31 device directories (currently implemented are avr and msp430 versions). If
  32 possible, when adding a new module generate.py should not be touched. These .tp
  33 files are mako templates which will be included once for each time the module
  34 is included in the device configuration ```.json```.
  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 takes no arguments and returns the current value of
  42 the parameter. The setter takes the new value of the parameter as an argument.
  43
  44 ### Format strings
  45
  46 The format strings are as used in the python ```struct``` module. Between host
  47 and device, values are exchanged in binary form as marshaled by the
  48 beforementioned python ```struct``` module according to the format strings given
  49 for function parameters or return values.
  50
  51 ### Module support functions
  52
  53 There are a few python functions which can be used from module templates.
  54
  55  * ```init_function()``` will be replaced by the unique name of an init function
  56    for this module instance that is automagically called on startup.
  57  * ```loop_function()``` will be replaced by the unique name of a loop funtion
  58    for this moduel that is called regularly (as often as the system finds time
  59    for it, at most each 100µs).
  60  * ```modulevar(name, ctype, fmt, array)``` handles the definition and usage of
  61    module parameters. When called with ```name``` alone set it will return the
  62    an name for the named module parameter that is unique down to a module
  63    instance level. If ```ctype``` and ```fmt``` are also set, the parameter is
  64    automatically registered as such and getter and setter methods are generated.
  65     * ```ctype``` is the name of the c type used for this module parameter.
  66     * ```fmt``` is a string containing the python struct format specification
  67       string corresponding to the c type used for this module instance
  68       parameter.
  69     * ```array``` is an optional parameter which may be set to an integer to
  70       tell the code generator that this parameter is an array of size
  71       ```array```.
  72  * ```module_callback(name, argformat, retformat)``` registers a new module
  73    callback. This callback will appear in this module instance's ```functions```
  74    section in the build config. ```argformat``` and ```retformat``` are the
  75    python struct format strings for the callback's arguments and return value,
  76    respectively. They can be omitted.
  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.