In order to build your very own version of balenaOS for one of our supported boards, you will first need to make sure you have a working Yocto environment setup.
Then pick the device type you want to build, in this example we will use the Raspberry Pi 3. So first we need to grab the
balena-raspberrypi and initialise all its submodules.
git clone https://github.com/balena-os/balena-raspberrypi cd balena-raspberrypi/ git submodule update --init --recursive
We can then use the helpful
BARYS tool to setup up and start our build. To see all the functionality
BARYS provides run
from with in the repo.
Now to actually build a development version of balenaOS for the Raspberry Pi 3, we can run the following:
./balena-yocto-scripts/build/barys -m raspberrypi3
Now sit tight and maybe go and make several cups of tea, this is going to take a little while.
By default, the images are created in the
build/tmp/deploy/<yocto-machine-name> directory with the file extension
.balenaos-img. Rename the file extension to
.img to flash the image to a SD card or USB drive using balenaEtcher.
Pre-requisites: a Yocto Board Support Package (BSP) layer for your particular board. It should be compatible with the Yocto releases balenaOS supports.
The repositories used to build the balenaOS host Operating System (OS) are typically called balena-
<board-family>. For example, consider balena-raspberrypi which is used for building the OS for Raspberryi Pi, or balena-intel repository which can be used to build a balenaOS image for the Intel NUC boards.
Contributing support for a new board is a process that involves the following steps:
The following documentation walks you through creating such a Yocto package. Because of the substantial difference between the hardware of many boards, this document provides general directions, and often it might be helpful to see the examples of already supported boards. The list of the relevant repositories is found at the end of this document.
There is a sample repo which we encourage you use as a starting base for your repository.
<board-family> repositories use git submodules for including required Yocto layers from the relevant sub-projects.
Note: you add submodules by
git submodule add <url> <directory>, see the git documentation for more details. The submodules have to be added using the https protocol.
The root directory structure contains the following directories:
├──.github ├──.versionbot ├── balena-yocto-scripts └── layers
├── .gitignore ├── .gitmodules ├── CHANGELOG.md ├── LICENSE ├── README.md ├── VERSION ├── repo.yml ├── <board-name-1>.coffee ├── <board-name-2>.coffee ... └── <board-name-x>.coffee
One or more files named
<board-name> is the corresponding yocto machine name. Should add one for each of the boards that the repository adds support for (eg. raspberrypi3.coffee or rockpi-4b-rk3399.coffee). This file contains information on the Yocto build for the specific board, in CoffeeScript format.
The typical layout for the
layers directory is:
├── layers │ ├── meta-balena │ ├── meta-balena-<board-family> │ ├── meta-<vendor> │ ├── meta-openembedded │ ├── meta-rust │ └── poky
layers directory contains the git submodules of the yocto layers used in the build process. The BSP git submodule(s) used should be publicly available repositories.
All git submodules need to be cloned using the https protocol. This normally means the following components are present:
In addition to the above git submodules, the
layers directory requires a meta-balena-
<board-family> directory (please note this directory is not a git submodule). This directory contains the required customization for making a board balena.io enabled. For example, the balena-raspberrypi repository contains the directory
layers/meta-balena-raspberrypi to supplement the BSP from
layers/meta-raspberrypi git submodule, with any changes that might be required by balenaOS.
We call this directory the balena integration directory. It is a Yocto layer that includes:
This directory contains optional and mandatory directories:
|Mandatory||Optional (as needed)|
layer.conf, see the layer.conf from
meta-balena-raspberrypifor an example, and see Yocto documentation
samples/bblayers.conf.samplefile in which all the required Yocto layers are listed, see this bblayers.conf.sample, and see the Yocto documentation
samples/local.conf.samplefile which defines part of the build configuration (see the meta-balena README.md for an overview of some of the variables use in the
local.conf.samplefile). You can use as guide an existing sample (e.g. local.conf.sample) but making sure the "Supported machines" area lists the appropriate machines this repository is used for. See also the Yocto documentation.
This directory should contain the changes to the bootloader recipes used by your board. For example, for u-boot based boards, it must define the following, and it must include at least a patch to the u-boot bootcmd that changes the default boot command to include balena required setup. See this example, or if you use a newer u-boot you can simply use config fragments to alter the bootcmd like done here.
This directory contains at least a
balena-image.bbappend file. Depending on the type of board you are adding support for, you should have your device support either just
balena-image or both
balena-image is for boards that run directly from external storage (these boards do not have internal storage to install balenaOS on).
balena-image-flasher is used when the targeted board has internal storage, so this flasher image is burned onto an SD card or USB stick that is used for the initial boot. When booted, this flasher image will automatically install balenaOS on internal storage.
balena-image.bbappend file shall define the following variable(s):
BALENA_BOOT_PARTITION_FILES_<yocto-machine-name>: this allows adding files from the build's deploy directory into the vfat formatted resin-boot partition (can be used to add bootloader config files, first stage bootloader, initramfs or anything else needed for the booting process to take place for your particular board). If the board uses different bootloader configuration files when booting from either external media (USB thumb drive, SD card, etc.) or from internal media (mSATA, eMMC etc.) then you would want to make use of this variable to make sure the different bootloader configuration files get copied over and further manipulated as needed (see
INTERNAL_DEVICE_BOOTLOADER_CONFIG_PATH_<yocto-machine-name>below). Please note that you only reference these files here. It is the responsibility of a
.bbappendto provide and deploy them (for bootloader config files, this is done with an append typically in
recipes-bsp/<your board's bootloader>/<your board's bootloader>.bbappend, see balena-intel grub bbappend for an example).
It is a space separated list of items with the following format: FilenameRelativeToDeployDir:FilenameOnTheTarget. If FilenameOnTheTarget is omitted then the FilenameRelativeToDeployDir will be used.
For example, to have the Intel NUC
bzImage-intel-corei7-64.bin copied from the deploy directory over to the boot partition, renamed to
BALENA_BOOT_PARTITION_FILES_nuc = "bzImage-intel-corei7-64.bin:vmlinuz"
balena-image-flasher.bbappend file shall define the following variable(s):
BALENA_BOOT_PARTITION_FILES_<yocto-machine-name>(see above). For example, if the board uses different bootloader configuration files for booting from SD/USB and internal storage (see below for the use of
INTERNAL_DEVICE_BOOTLOADER_CONFIGvariable), then make sure these files end up in the boot partition (i.e. they should be listed in this
Shall contain a
.bbappend to the kernel recipe used by the respective board. This kernel
.bbappend must "inherit kernel-balena" in order to add the necessary kernel configs for balenaOS
Shall contain a
resin-init-flasher.bbappend file if you intend to install balenaOS to internal storage and hence use the flasher image.
resin-init-flasher.bbappend should define the following variables:
INTERNAL_DEVICE_KERNEL_<yocto-machine-name>: used to identify the internal storage where balenaOS will be written to.
INTERNAL_DEVICE_BOOTLOADER_CONFIG_<yocto-machine-name>: used to specify the filename of the bootloader configuration file used by your board when booting from internal media. Must be the same as the FilenameOnTheTarget parameter of the bootloader internal config file used in the
if required -
INTERNAL_DEVICE_BOOTLOADER_CONFIG_PATH_<yocto-machine-name>: used to specify the relative path, including filename, to the resin-boot partition where
INTERNAL_DEVICE_BOOTLOADER_CONFIG_<yocto-machine-name> will be copied to.
For example, setting.
INTERNAL_DEVICE_BOOTLOADER_CONFIG_intel-corei7-64 = "grub.cfg_internal"
INTERNAL_DEVICE_BOOTLOADER_CONFIG_PATH_intel-corei7-64 = "/EFI/BOOT/grub.cfg"
will result that after flashing the file
grub.cfg_internal is copied with the name
grub.cfg to the /EFI/BOOT/ directory on the resin-boot partition.
BOOTLOADER_FLASH_DEVICE: used to identify the internal storage which the bootloader needs to be flashed to. This is only the case usually when the bootloader needs to be in a SPI flash-like memory where the bootrom code expects it to read it from raw disk instead from a partition. Note that if
BOOTLOADER_FLASH_DEVICEis set, then also
BOOTLOADER_SKIP_OUTPUT_BLOCKSneed to be set.
BOOTLOADER_IMAGE: used to specify the name of the bootloader binary, from the resin-boot partition, that is to be written to
BOOTLOADER_BLOCK_SIZE_OFFSET: used to specify the block size with which
BOOTLOADER_IMAGEis to be written to
BOOTLOADER_SKIP_OUTPUT_BLOCKS: used to specify how many blocks of size
BOOTLOADER_BLOCK_SIZE_OFFSET need to be skipped from
BOOTLOADER_FLASH_DEVICE when writing
BOOTLOADER_IMAGE to it.
Note: Some hardware requires the use of a MLO (a.k.a. SPL - secondary program loader) that is to be copied in static RAM and executed from there (static RAM is small in size), and this first stage bootloader is responsible for initializing the regular RAM and then copying the regular bootloader to this regular RAM and passing execution to it. For this purpose, a second set of variables called BOOTLOADERFLASHDEVICE1, BOOTLOADERIMAGE1, BOOTLOADERBLOCKSIZEOFFSET1, and BOOTLOADERSKIPOUTPUTBLOCKS_1 can be used to accommodate this use case.
For example, setting:
BOOTLOADER_FLASH_DEVICE = "mtdblock0" BOOTLOADER_IMAGE = "u-boot.imx" BOOTLOADER_BLOCK_SIZE_OFFSET = "1024" BOOTLOADER_SKIP_OUTPUT_BLOCKS = "3"
will result that the file
u-boot.imx from the resin-boot partition is written to /dev/mtdblock0 with a block size of 1024 bytes and after the first 3 * 1024 bytes of /dev/mtdblock0.
Shall contain a
hostapp-update-hooks.bbappend with content based on if your board uses u-boot or grub. Then it may also need to include an additional hook for writing the bootloader(s) binary in the right place(s) when doing hostOS updates.
The optional directories in meta-balena-<board-family> are:
balena-supervisor.bbappend that can define the following variable(s):
LED_FILE_<yocto-machine-name>: this variable should point to the Linux sysfs path of an unused LED if available for that particular board. This allows the unused LED to be flashed for quick visual device identification purposes. If no such unused LED exists, this variable shall not be used.
The directory structure then looks similar to this:
├── conf │ ├── layer.conf │ └── samples │ ├── bblayers.conf.sample │ └── local.conf.sample ├── recipes-bsp │ └── <bootloader recipes dir used by your board> ├── recipes-containers │ └── docker-disk │ └── balena-supervisor.bbappend ├── recipes-core │ ├── images │ │ └── balena-image.bbappend ├── recipes-kernel │ └── linux │ ├── linux-<board-family>-<version> │ │ └── <patch files> │ ├── linux-<board-family>_%.bbappend │ └── linux-<board>_<version>.bbappend └── recipes-support └── hostapp-update-hooks ├── files │ └── <bootloader update hook> └── hostapp-update-hooks.bbappend └── resin-init └── resin-init-flasher.bbappend
See the meta-balena Readme on building the new balenaOS image after setting up the new board package as defined above.
When you have completed the development of the yocto board support repository as detailed in the previous step, please get in touch with balena to finish the process of having your board available in the balena dashboard.
This will mean your board repository would need to be hosted in balena-os GitHub organization. Depending on your needs and upon agreeing with balena, it can be hosted either as a public repository for everyone to access or hosted privately with access only to selected users.
Having a board supported by balena also means having a hardware contract describing that device type.
balena allows for public or private device types. Public device types can be used by all users while private device types are only accessible to selected users upon agreeing with balena. Note that public/private device type visibility mentioned here is independent of the GitHub repository visibility (you can choose to have any combination of these two).
For publicly available device types, the hardware contracts are located here and you must send a Pull Request to this public contract repository with the appropriate contract. See this as an example to base on.
For private device types, balena will make the necessary changes when supplied with the hardware contract.
Once the board is supported in balena, it will receive automatic pull requests with updates of meta-balena as new releases of meta-balena get done. These automatic pull requests get merged if the CI builds succeed, so care must be taken from time to time to check that your code is still compatible with the latest meta-balena releases.
Maintaining / pushing updates to the code other than meta-balena updates need to be done through pull requests in the appropriate board repository in the balena-os GitHub org and will be reviewed by balena prior to merging. However, after new code gets merged (either through the automatic meta-balena updates or through contribution pull requests), in order for the new releases to be available in the dashboard, balena needs to be contacted about deploying the new releases.
See the repositories below for specific examples on how board support is provided for existing devices.
The versions before v2.0-beta.3 didn't support kernel sources that were not git repositories. Starting with this version, aufs patches will get applied on kernel recipes that use tar archives, for example as well. For the older version, this is considered a limitation.