English
资源说明：RPC framework for interaction with c firmware from python host applications
# 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](http://www.fourwalledcubicle.com/LUFA.php)
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.
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
