Advanced boot settings
Warning: This page contains details of the more involved configuration options that expose more functionality but potentially enable you to break things should you configure them incorrectly - tread carefully!
The Raspberry Pi exposes device configuration options via a text file on the
config.txt - you change boot options simply by editing this file.
config.txt locally before the first boot
config.txt is located in the root of the
balena-boot partition, and you can modify it by mounting the SD card on a computer. This will only work if you edit the SD card before the device's first boot.
If your device has a supervisor version above 1.0.0, it has support for modifying the values in
config.txt remotely using configuration variables. These can be set as fleet-wide values (for all devices in an application) or device-specific ones.
The variables that start with the
RESIN_HOST_CONFIG_ prefix will be added to the
config.txt file, also replacing the preexisting values of such variables in the file.
For example, setting the value of
RESIN_HOST_CONFIG_gpu_mem to 16 will produce the following entry in
These variables can be set using the API or any of its clients, including the SDK, the CLI, and the dashboard. To configure via the dashboard, add variables to the Fleet Configuration page for fleet-wide config variables and to Device Configuration for device specific variables. The device-specific variables, if defined, will override the fleet-wide variables of the same name.
After modifying a config.txt variable, the device supervisor will apply the changes and reboot the device.
Note: Configuration variables defined through the API will not apply to devices in local mode.
You can configure the amount of memory shared with the GPU by adding entries to
config.txt as follows:
gpu_mem=16 gpu_mem_256=64 gpu_mem_512=128
Each of these values is specified in megabytes.
gpu_mem_256 is used by the 256MB Raspberry Pi (Model A - you
probably don't have one of these), and
gpu_mem_512 is used by the 512MB
Raspberry Pi (Model B/B+ - this is probably what you have.)
The Model A Raspberry Pi ignores the 512MB setting altogether while the model B
and B+ ignore the 256MB setting. Both
By default we assign 16MB of memory to the GPU (specified by
may well be less than you require depending on your application (particularly
applications which make heavy use of the Pi's graphics card.)
Enable serial interface
The BCM2837 on the Raspberry Pi3 has 2 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 miniUART is now available on /dev/ttyS0, disabled by default.
- 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.
To enable the miniUART an entry should be added to
config.txt as follows:
Setting device tree overlays (
dtoverlay) and parameters (
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 and above (supervisor 7.0.0 and above), will parse the values of
RESIN_HOST_CONFIG_dtparam in a special way: 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 will be split into several lines.
For example, the default value of
RESIN_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
Another example would be setting several overlays with their own parameters, e.g.
RESIN_HOST_CONFIG_dtoverlay = "i2c-rtc,ds1307","lirc-rpi" will translate to:
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
RESIN_HOST_CONFIG_dtoverlay = i2c-rtc,ds1307 will translate to:
There are more details on the options available in
config.txt over at
elinux's RPi Config page.