What is BittyBuzz?

BittyBuzz is an implementation of the Buzz programming language for microcrontrollers. BittyBuzz is designed to fit a 32k flash memory and work with as little as 2k of RAM.

While the BittyBuzz VM has a number of limitations with respect to the original Buzz VM, BittyBuzz supports 100% of the Buzz bytecode.

Compiling BittyBuzz

For your PC

Type these commands:

$ cd bittybuzz
$ mkdir build
$ cd build
$ cmake ../src/
$ make

For the Kilobot

To compile BittyBuzz to an .hex file that can be used with the Kilobot, you need avr-gcc and related tools. avr-gcc is expected to be installed under /usr/lib/avr/ so that CMake may find its header files.

Type these commands:

$ cd bittybuzz
$ mkdir build_kilobot
$ cd build_kilobot
$ cmake -DCMAKE_TOOLCHAIN_FILE=../src/cmake/Kilobot.cmake ../src/
$ make

Generating documentation

A good place to get started with BittyBuzz is the source code documentation. One may optionaly create such Doxygen-generated documentation of BittyBuzz. This requires Doxygen and can be done via:

$ make doc

The documentation will be subsequently available in HTML and LaTeX formats under <build_dir>/doc, for example, build/doc.

Writing your own behaviors

For kilobots

Currently, BittyBuzz does not support global installation. Behaviors must thus be implemented under src/kilobot/behaviors directly.

The C source file should be placed inside src/<robot_name>/behaviors, whereas the Buzz script is expected to have the same name and be placed under src/<robot_name>/behaviors/buzz_scripts. You should also place a Buzz String Table (.bst) file (which allows BittyBuzz to generate a string ID corresponding to each string) next to your Buzz script, which should contain any string used within the C code and that does not appear in the Buzz script. Look at existing files if you are unsure.

EDIT: It is no longer required to put any thing in the .bst file. However, the file itself is still required to be there. It will eventualy become optional.

At this point, you may run make inside your kilobot build directory to generate a HEX file that can be sent to the kilobots. You will find it under <build_dir>/kilobot/behaviors/<buzz_script_name>/<buzz_script_name>.hex. This file can be sent to the kilobots using the KiloGUI.

Important: After adding new files, be sure to run cmake ../src inside your kilobot build directory for CMake to take them into account.

For Zooids

See src/zooids/README.md

For Crazyflie

See src/crazyflie/README.md

Options

It is possible to specify a custom value for a range of configuration values. Behaviors on low-resource robots often require parameter-tweaking. However, we recommend against changing these values unless it is necessary.

The table below describes all configurable values and classifies each one by the likelihood that one will require changing it.

Option	Description	Adjustment likelihood	PC	Kilobot
`BBZHEAP_SIZE`	Size of the heap (B)	High	3264	1088
`BBZHEAP_ELEMS_PER_TSEG`	Num. entries per table segment	Moderate	5	5
`BBZSTACK_SIZE`	Size of the stack (num. objects)	High	96	96
`BBZVSTIG_CAP`	Capacity of the `stigmergy` structure (num. entries)	High	3	3
`BBZNEIGHBORS_CAP`	Capacity of the `neighbors` structure (num. neighbors)	Low	15	15
`BBZINMSG_QUEUE_CAP`	Capacity of the incoming message queue (num. msgs)	Low	10	10
`BBZOUTMSG_QUEUE_CAP`	Capacity of the outgoing message queue (num. msgs)	Low	10	10
`BBZHEAP_RSV_ACTREC_MAX`	Num. objects on the heap reserved for activation records	Moderate	28	28
`BBZLAMPORT_THRESHOLD`	Length of Lamport clocks' accepting zone	Low	50	50
`BBZHEAP_GCMARK_DEPTH`	Garbage collector max recursion depth	Low	8	8
`BBZMSG_IN_PROC_MAX`	Max. num. of incoming messages processed per timestep	Moderate	10	10
`BBZNEIGHBORS_CLR_PERIOD`	Num. timesteps between neighbor clears	Low	10	10
`BBZNEIGHBORS_MARK_TIME`	Num. timesteps before clear we spend marking neighbors	Low	4	4
`BBZ_XTREME_MEMORY`	Whether to reduce RAM at the cost of Flash	Moderate	OFF	ON
`BBZ_USE_PRIORITY_SORT`	Whether to use priority sort on outgoing message queue	Low	OFF	OFF
`BBZ_USE_FLOAT`	Whether to use float type	Low	OFF	OFF
`BBZ_DISABLE_NEIGHBORS`	Whether to disable the `neighbors` structure	High	OFF	OFF
`BBZ_DISABLE_VSTIGS`	Whether to disable the `stigmergy` structure	High	OFF	OFF
`BBZ_DISABLE_SWARMS`	Whether to disable the `swarms` structure	High	OFF	OFF
`BBZ_DISABLE_MESSAGES`	Whether to disable Buzz messages	Moderate	OFF	OFF
`BBZ_DISABLE_PY_BEHAV`	Whether to disable Python behaviors of closures	Low	OFF	OFF
`BBZ_NEIGHBORS_USE_FLOATS`	Whether to use floats for the neighbor's range and bearing	Moderate	ON	OFF
`BBZ_ENABLE_FLOAT_OPERATIONS`	Whether to enable floats operations	<span style="color:#880>	ON	OFF

For example, for a Buzz program requiring larger stack sizes but less heap allocations, you may run cmake as:

$ cmake -DBBZHEAP_SIZE=750 -DBBZSTACK_SIZE=200 ../src

buzz-lang / BittyBuzz

readme