1. Reference
  2. Host OS
  3. Advanced boot settings
Improve this doc

Advanced boot settings

Warning: This page contains details of advanced configuration options that expose more functionality, but any mistakes may potentially leave a device inaccessible. Be sure to try your changes in a controlled environment before applying them to production devices.

Raspberry Pi

The Raspberry Pi exposes device configuration options via a text file on the boot partition named config.txt. You can change boot options in this file, either by manually editing it before the device's first boot or editing the default configuration values using the device Configuration tab in the balenaCloud dashboard.

The boot partition is mounted on the device at /mnt/boot, so the file is located at /mnt/boot/config.txt on the device. To view the contents of config.txt on a provisioned device, use the following commands:

$ balena ssh <uuid>
$ cat /mnt/boot/config.txt

Modifying config.txt locally before the first boot

Before the device is provisioned, you may edit config.txt by mounting a flashed SD card (with the partition label resin-boot) and editing the file directly. Any values added to config.txt will be added to the balenaCloud API during device provisioning and displayed on the dashboard. This will only work if you edit the file before the device's first boot, as after device provisioning, any changes will be overwritten by the device supervisor with values read from the balenaCloud API.

Modifying config.txt using configuration variables

After the device has been provisioned, you can modify the values in config.txt using the configuration tab on the dashboard. In order to modify a config.txt variable, the device supervisor will apply the changes and reboot the device.

Variables that start with the BALENA_HOST_CONFIG_ or RESIN_HOST_CONFIG_ prefix will be added to the config.txt file, replacing any preexisting values in the file. For example, a variable named BALENA_HOST_CONFIG_start_x with the value of 1 will result in the following entry in config.txt:

start_x=1

To manage the configuration via the dashboard, modify the variables via the Configuration tab on the fleet or device level. The variables with the same named defined at the device level, will override the variables defined fleet wide. See Custom Configuration in order to modify configuration options remotely using the balenaCloud dashboard.

GPU Memory

The amount of memory that is addressable from the GPU may be configured by adding entries to config.txt. You can also set specific values of gpu_mem for Raspberry Pis with 256, 512, or 1024 MB (or greater) of RAM. Values will be ignored for those devices whose memory size does not match. For the Raspberry Pi 4, which has versions with RAM greater than 1GB, the minimum and maximum values are the same as for a 1GB device.

gpu_mem=16
gpu_mem_256=64
gpu_mem_512=128
gpu_mem_1024=256

gpu_mem is the default amount of memory, which, by default, is set to 16MB (specified by gpu_mem=16). This may well be less than you require depending on your application (particularly applications that make heavy use of the Raspberry Pi's graphics capabilities). As per the Raspberry Pi documentation, values of gpu_mem over 512 are not recommended, will provide no performance improvements, and are untested.

Enable serial interface

The BCM2837 on the Raspberry Pi 3 has 2 built-in UARTs (as did its predecessors), however, to support the Bluetooth functionality the fully-featured PL011 UART was moved from the header pins to the Bluetooth chip and the mini UART made available on header pins 8 & 10.

This has a number of consequences for users of the serial interface:

  • The /dev/ttyAMA0 previously used to access the UART now connects to Bluetooth.
  • The mini UART is now available on /dev/ttyS0. This is disabled by default for production images and enabled by default for development images.
  • The mini UART is a secondary low throughput UART intended to be used as a console. it supports the following functionality:
    • 7 or 8 bit operation.
    • 1 start and 1 stop bit.
    • No parities.
    • Break generation.
    • 8 symbols deep FIFOs for receive and transmit.
    • SW controlled RTS, SW readable CTS.
    • Auto flow control with programmable FIFO level.
    • 16550 like registers.
    • Baudrate derived from system clock.

The mini UART is enabled by default for development images. For production images either enable it using the Configuration tab or before device provisioning by adding the following entry to config.txt:

enable_uart=1

Note: For further information on UART device tree overlays, see the Raspberry Pi documentation.

Setting device tree overlays (dtoverlay) and parameters (dtparam)

The Raspberry Pi allows loading custom device tree overlays using the dtoverlay setting in config.txt. It also allows setting parameters for the default overlay with the dtparam setting. For these settings, the syntax is different from other keys because several entries can be added, and the bootloader will use all of them.

To allow setting several values, devices running balenaOS version >= 2.12.0 (supervisor >= 7.0.0), will parse the values of BALENA_HOST_CONFIG_dtoverlay and BALENA_HOST_CONFIG_dtparam in a special way where the value of the configuration variable will be treated as the contents of a JSON array (without the enclosing braces []), so a comma-separated list of quote-enclosed values (straight quotes, not curly) will be split into several lines.

For example, the default value of BALENA_HOST_CONFIG_dtparam = "i2c_arm=on","spi=on","audio=on" will translate into the following entries in config.txt:

dtparam=i2c_arm=on
dtparam=spi=on
dtparam=audio=on

Please note that spi, audio, and all of the i2c params should be specified within their own sets of quotes in order to be written correctly to config.txt.

Another example would be setting several overlays with their own parameters, e.g. BALENA_HOST_CONFIG_dtoverlay = "i2c-rtc,ds1307","lirc-rpi" will translate to:

dtoverlay=i2c-rtc,ds1307
dtoverlay=lirc-rpi

As of Supervisor v16+, the above will translate to:

dtoverlay=i2c-rtc
dtparam=dc1307
dtoverlay=lirc-rpi

This modifies each parameter to be on its own line in order to avoid the 80 character line limit imposed by config.txt. It is the recommended method of setting one or more overlays with their own parameters.

This parsing will only be done if the value is a valid string, so if it doesn't begin with a quote ", the value will be parsed as a single string and not split into several lines. For instance BALENA_HOST_CONFIG_dtoverlay = i2c-rtc,ds1307 will translate to:

dtoverlay=i2c-rtc,ds1307

Disabling the rainbow splash screen

To disable the Raspberry Pi rainbow splash screen, add the disable_splash=1 entry to config.txt.

Note: This setting disables the Raspberry Pi rainbow splash screen but does not disable the balena logo splash screen. If you would like to replace the balena logo with your custom splash logo, replace splash/balena-logo.png located in the boot partition of the image. Note that this file may be called resin-logo.png on older releases.