Improve this doc

I2C and Other Interfaces

Raspberry Pi Family

Many sensors and peripherals use either the I²C (Inter-Integrated Circuit) or the SPI (Serial Peripheral Interface) to communicate with the CPU. In most linux environments, using this kind of low level communication requires enabling a kernel module. In balena containers this can be done in a similar way because the containers are run in --privileged mode.


To enable I2C communication in your projects you will need to add the command modprobe i2c-dev to your package.json or Dockerfile.

The easiest way to add it to the package.json is to add it to the "start" key. As shown here.

 "scripts": {
    "preinstall": "bash",
    "start": "modprobe i2c-dev && node app.js"

To add it to your Dockerfile, just add it before your entry script in the CMD command like so:

CMD modprobe i2c-dev && python /app/

After your first push, the code will most likely throw an error caused by the modules not being loaded. If this is the case, simply reboot the pi and the modules should be loaded.

Note: A few places will talk about adding the modules to the /etc/modules file so that they are there on boot. This will not work on the balena system because that file is not mapped to the host OS.

To get you started, here is an example that uses i2c to communicate with the ADS1115 analog-to-digital converter to allow the Raspberry Pi to read analog signals, which is useful for a bunch of sensor types.


SPI is enabled by default on balenaOS via the dtparam=spi=on device tree parameter. This default behavior can be modified by editing the device configuration variables.

For Node.js applications it should work out of the box with the spi node module. For an example of this, check out this project: digitiser.


Serial is disabled by default on the Raspberry Pi 3. To enable it you will need to do the following:

  • Edit the config.txt in balena-boot partition of the SD card and append the following lines.

1-wire and Digital Temperature sensors

In order to work work with 1-wire and digital temperature sensors you will need to do the following:

  • Edit the config.txt in balena-boot partition of the SD card and append the following lines.
  • Add modprobe w1-gpio && modprobe w1-therm before your start scripts in either your package.json start command or Dockerfile CMD command.

An example of this is shown in our Firebase Temperature Logger project.

Using UART or Serial on Raspberry Pi 3

To enable UART on GPIO14 / UART0 TX and GPIO15 / UART0 RX , you will need to apply the pi3-miniuart-bt device tree overlay. This can be done in two ways:

  1. Add the following Device (or Fleet) Configuration variable to your device (or Fleet).

    BALENA_HOST_CONFIG_dtoverlay = pi3-miniuart-bt
  2. The second, more manual way to enable this configuration is to mount the SD card on your development machine. Find the resin-boot partition and in there you should see the Raspberry Pi's boot files, one of which is called config.txt. Open this file up and add the following line to the end of the file:


Now eject the SD card and pop it back into the RPI3, and you can boot the device up again.

To demonstrate this functionality, you can push this project ( to your RPI3. You will also need to add a small jumper wire between GPIO14 / UART0 TX and GPIO15 / UART0 RX, so that the data sent out of the UART is read back in and displayed in the logs.

Raspberry Pi camera module

Depending on the version of your balenaOS, the system contains different version of the Raspberry Pi firmware, and you need to apply slightly different settings. In both cases you can either modify config.txt on the resin-boot partition of your SD card, or add the settings remotely by using BALENA_HOST_CONFIG_variablename settings in your fleet or device configuration.

BalenaOS 1.16.0 and newer

Set the following values in config.txt:


or for remote update

  • BALENA_HOST_CONFIG_gpu_mem to 128
  • BALENA_HOST_CONFIG_start_x to 1 in the fleet or device configuration.

BalenaOS 1.8.0 and earlier

Set the following values in config.txt:


or for remote update

  • BALENA_HOST_CONFIG_gpu_mem to 128
  • BALENA_HOST_CONFIG_start_file to start_x.elf
  • BALENA_HOST_CONFIG_fixup_file to fixup_x.dat in the fleet or device configuration.

You will also need to add modprobe bcm2835-v4l2 before your start scripts in either your package.json start command or Dockerfile CMD command.

An example of this is shown in our Raspberry Pi python picamera project.

Raspberry Pi 7” Touchscreen Display

In order to work with the Raspberry Pi display you will need to do the following:

  • Edit the config.txt in resin-boot partition of the SD card and append the following line.

If you want a quick example project to get you started with you new screen, you might want to checkout our Raspberry Pi Electron starter App.

If you find that you need to change the orientation of you LCD screen, you can easily achieve this by adding the following key/value to your /boot/config.txt on your SD card:

lcd_rotate = 0

And set the value to either 0, 90, 180 or 270, depending on your desired orientation.

Note: The 90 and 270 degrees rotation options require additional memory on GPU, so won't work with the 16M GPU split.

Customizing config.txt

These are some tips and tricks for customizing your raspberry pi. Most of them require changing settings in the config.txt file on the SD cards boot partition. See here for more details.

You can also set all of these variables remotely in the Device Configuration (for a single device) or Fleet Configuration (for all devices within a fleet) menu. If the setting in config.txt is variable=value, you can achieve the same settings by adding a configuration variable with BALENA_HOST_CONFIG_variable set to the value value. For example:

Setting the device configuration for Raspberry Pi config.txt variables

For simplicity, below all examples are using the config.txt formatting, but all of them are available to set remotely as outlined above.

For further details and explanation regarding the settings below you may check the official config.txt documentation.

Binary Blobs for GPU/vcore

This is necessary for any graphics acceleration or if you want to use the official raspberry pi camera module

Increase USB current throughput:

This can be useful if you are running a power hungry USB peripheral like a 3G dongle.

overclock RPI2:
temp_limit=80 #Will throttle to default clock speed if hit.
Fill the screen to the edges


Currently the Beaglebone devices are running a very new 4.1 kernel (which is obviously awesome), unfortunately many of the userspace libraries haven't caught up yet so they only work with the older 3.8 kernel. Luckily ruth0000 was kind enough to patch the Octalbonescript JS library and made a lovely node.js module over here: .

With this module you should be able to basic GPIO and analog-to-digital conversion stuff. To get you started we have a simple example using this module here.

Note: The ADC voltage is only rated to 1.8V, if you apply more you risk frying the pin.

Capemgr support

Warning: Capemgr is only supported in balena BBB devices with a 4.1 linux kernel. This kernel was only enabled in production on 25-09-2015. If you don't know which kernel you are running, open a web terminal to your BBB and run uname -a.

Loading a Cape
echo cape-universaln > /sys/devices/platform/bone_capemgr/slots
Checking which Capes are loaded.
cat /sys/devices/platform/bone_capemgr/slots
cat /sys/devices/platform/ocp/ocp:cape-universal/status


Disable HDMI

Before provisioning, mount the .img, in the flash-boot partition you should see a file named uEnv.txt_internal open that up with your favorite text editor and add the following line to the bottom of the file:


You should now be able to use any of the pins that used to be occupied by the HDMI. To test this you can run the following from your web terminal:

echo 74 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio74/direction
echo 1 > /sys/class/gpio/gpio74/value

Pin 41 of Header P8 should go high.

Intel Edison

MRAA for GPIO and hardware access

The best and easiest way to interface with GPIO, I2C, SPI or UART on the Intel Edison is to use the MRAA library, this library gives you a simple way to write C, python or Node.js applications that interact directly with the Edison hardware.

If you use our balenalib/edison-node or balenalib/edison-python base images in your applications, you will automatically have the mraa setup correctly for node.js or python respectively.

Have a look at this python example or this node.js example to get started.

UPM for high level sensor and actuator libraries

Intel provides the UPM library which contains software drivers for a wide variety of commonly used sensors and actuators. These software drivers interact with the underlying hardware platform (or microcontroller), as well as with the attached sensors, through calls to MRAA APIs.

Edison in USB Host mode

The Edison needs a kernel module to be loaded to trigger the UBS HOST mode. This can be done in the following way.

Hardware Pre-requisites:

Your Edison will need to be powered externally for the USB host mode to be active - Either through the DC jack on the Arduino board or through the battery connector on the smaller Intel carrier board.

Software Pre-requisites:

The following code needs to be placed at the start before any device operations run in the container.


mount -t devtmpfs none /dev
udevd --daemon

# g_multi needs a file to be passed which shows up as USB storage if Edison is in device mode.
# We are creating a blank file here.
dd if=/dev/zero of=/data/blank.img bs=10M count=1

# The following is needed to get the Edison to switch to host mode - If the power connections aren't made for the HOST mode this exposes the file above as USB storage, emulates a USB network card and USB serial connected to the Edison.
sync && modprobe g_multi file=/data/blank.img stall=0 idVendor=0x8087 idProduct=0x0A9E iProduct=Edison iManufacturer=Intel

udevadm trigger
udevadm settle

# Shutdown the unnecessary usb0 spawned by g_mutli
sleep 5s && ifconfig usb0 down

After this you should be able to easily use your Intel Edison in USB host mode.