This is an implementation of the Firmata protocol for Silicon Labs BGM111. It is compatible with standard Firmata 2.5.8.

The easiest way to install the Firmata application onto your board is to run the balena application provided. This targets the latest verision of the Balena Firmata application. This balena application will run and install OpenOCD on your Fin in order to provision the Coprocessor with both a bootloader and the Firmata application.

We also provide a Dockerfile for you to easily generate an environment for compiling this firmware yourself.

To build the docker image, run:

docker build . --tag firmata 

A container can then be run with:

docker run -it -v ${YOUR-OUTPUT-DIRECTORY}:/out --name firmata-build firmata "make" "all"

🔧 * all can be substituted for balena if you only wish to target to balenaFin or devkit for the Silabs BRD4001A

This will output the build files to a directory specified by YOUR-OUTPUT-DIRECTORY, e.g. ~/Downloads/balena. The output binaries for flashing the coprocessor can be found under ${YOUR-OUTPUT-DIRECTORY}/builds/balena.

If you wish to stop this container:

docker stop firmata-build

And to remove the container:

docker rm firmata-build

It is also possible to build the source and manually flash the Coprocessor however, in order to flash the Coprocessor you will need to either load the compiled firmware onto the Compute Module and flash it using OpenOCD or program the Coprocessor using an external programmer such as a Segger JLink .

Before attempting to build, ensure the following dependencies are installed. We recommend ARM GCC version 9-2019-q4-major, as used in our docker image.

• cmake
• make
• arm-none-eabi-gcc

🔧 Make sure these are all located in your $PATH

With the dependencies installed, build with the following commands:

1. cd src to change directory to the source files
2. make setup to generate the builds directory
3. make balena to execute the build*

🔧 * make devkit can be used to build for the Silabs BRD4001A

As the coprocessor is coupled to the compute module, we recommend that you use our flashing example to automate the flashing process.

If you wish to deploy this coprocessor firmware to a balenaFin running either balenaOS or Raspbian, checkout this example.

An external JLink programmer may be used to flash the coprocessor (for example, if using a Silabs Development Kit)

• JLink tools

To flash, using an external JLink programmer:

1. cd builds/devkit && make flash to flash to a device

Sysex-based sub-commands (0x00 - 0x7F) are used for an extended command set.

I2C Read/Write request and replies are implemented following the official protocol.

Optional Delay is for I2C devices that require a delay between when the register is written to and the data in that register can be read.

Optional I2C Mode allows for changing the I2C interface between the balenaFin's internal pins (SCL 18 & SDA 19) and the external interface (SCL 12 & SDA 10). By default I2C is set to the external interface, upon initialisation under Firmata. Setting the mode to 0 will toggle the internal interface, 1 will set it to the external interface.

0  START_SYSEX (0xF0)
1  I2C_CONFIG (0x78)
2  Delay in microseconds (LSB) [optional]
3  Delay in microseconds (MSB) [optional]
4  I2C Mode (LSB) [optional]
5  I2C Mode (MSB) [optional]
n  END_SYSEX (0xF7)

Balena SYSEX subcommands are structured under the Firmata SYSEX command.

For example, a balena subcommand to report balena firmata firmware would be represented as follows:

[0xF0, 0x0B, 0x00, 0xF7]

Which represents:

[START_SYSEX, BALENA_SUBCOMMAND, BALENA_REPORT_FIRMWARE, END_SYSEX]

While the SYSEX command 0x79 reports the protocol version of firmata, the SYSEX balena subcommand reports the specific version of firmware that the coprocessor is running (generated by the release tag).

This SYSEX command performs a hard power down of the CM3. In order to prevent loss of data or other hard shutdown consequences, users should set an init_delay period and gracefully power down the CM3 from the linux userspace, i.e. with shutdown -h now. After the sleep_period has expired, the coprocessor will resume power to the CM3 allowing it to boot into normal operating mode.

• init_delay is composed of 1 byte, specified in seconds (passing 0 will immediate power down the CM3 and is not recommended!)
• sleep_period is composed of 4 bytes, specified in seconds (max value of (uint32_t / 1000), eqv. of ~4294967 seconds)

The BGM111 has an additional Current Digital to Analogue Converter (IDAC), which can be used as a current source/sink. This is mapped to the balena subcommand 0x02 and can be controlled in a similar way as standard Analogue Write command at this endpoint. The BGM111 only has 1 IDAC peripheral so can only be used on one pin at a time. Changing pin will remove any previous pin configurations.

Each configuration much be selected with 0x0F as the MSB of that option.

⚠️ * Not all pins have access to the IDAC, see table

The IDAC can be set to 4 different ranges as shown in the table below:

For examples, if you wish to select set IDAC mode on pin 6 and subsequently write an output current 8uA, it would look as follows:

[0xF0, 0x0B, 0x02, 0x0, 0x06, 0x02]

[0xF0, 0x0B, 0x02, 0x1, 0x06, 0x0F]

Which represents:

[START_SYSEX, BALENA_SUBCOMMAND, BALENA_IDAC_WRITE, SET_RESOLUTION, PIN, RESOLUTION_MODE, END_SYSEX]

[START_SYSEX, BALENA_SUBCOMMAND, BALENA_IDAC_WRITE, WRITE_STEP, PIN, STEP, END_SYSEX]

The IDAC can be mapped to the same functionality as a standard DAC with additional circuitry.

Alternatively, PWM can be used to generate a psuedo-analogue output voltage.

Resetting the IDAC will disable and clear the configuration on any pin currently using it.

⚠️ Pins are numbered differently in the Firmata software implementation when compared to the balenaFin datasheet. This is due to the Firmata protocol, which maps pins from 0-127.

• SPI Support