Switch branches/tags
1.X-supervisor-7.1.22 1.X-supervisor-v6.2.1 1.X-supervisor-v6.2.3 1.X 1.1.0-hotfix 1.1.1-hotfix 1.1.4-hotfix 1.1.4-ts-hotfix 1.1.4-ts 1.6-hotfix 2.4.X 2.15.x 2.23.x 1164-no_proxy-file-is-newline-sensitive RES-1002-add-ptest-support-with-basic-ho RES-1540-u-boot RES-1569-persistent-systemd-journal ag_balena_rename1 ag_dropbear_security-build-11a97fc76ce4515f4b7d685adb0b75a014a8b105 ag_dropbear_security-build-492e266707214c0bc052992a864b8b3c639369ed ag_dropbear_security-build-824d45b2c1de86d8991d99a030f8badbeb4b7ee3 ag_dropbear_security-build-836dc076189cb7b63192b15c7f8944a0d9eef027 ag_dropbear_security-build-a53bcb52ca66c667abaad668a909977970479126 ag_fix-build-df2782d ag_flasher_fixes-build-5a85a14 ag_flasher_fixes-build-40db1c2 ag_flasher_fixes-build-4381e4a ag_flasher_fixes-build-a56bdcf ag_flasher_fixes-build-bcd08fd ag_flasher_fixes ag_license ag/mm-fix-udevrules-build-609c83301f951d20a8c5863eb649ebf3701a532a ag/mm-up-build-9724fad538360cd2291889608dfab1c8c42939c6 ag/mm-up ag/nm-custom-config-build-3ce3360c58071c8cb1f3780b80d158056d4770ec ag/pretty-configjson-build-6c5eeadf215f2743684e470ff163046a110e38e3 ag/public_ssh_keys-build-3b58c24f75318d0284c03b5be67ca0a687690d9d ag_release ag/superup-build-4df59542ffbbf71359d19412ed4cf9fd5f28a81f ag/supervisor-update-build-e5a882a75ca49828cabcba227c4972d9e4d753d9 ag_tini ag_typo ag/upx_127-build-69bc7e1c6c8382d69b57b662518909c4f7824644 append_required_kernel_configs_for_mbim_and_qmi development-build-9ce47c9c07b55dc78e565cac5e0653ae5309f18f development dhcp_fix-build-600d8d1f6be72b4a623d730234dfa85877893ae3 dhcp_fix ebpf-build-c5aa298bd03bc7731aa05f9929071550751b5190 ebpf fix_extraneous_space-build-cefe95861eaed14c00eae07f1e2b314464c20ec6 fix_host_docker_path fix_pinning fix_sumo-mobynit_static_PIE healthcheck-timeout-build-8eb9b7bbd6fd84c5cc852d8c5e040bd4f0ba2367 ignore-node-files-build-becc602a39ec9c788e4f1765ec696f2f71ceb321 issue_190 issue_204 issue_323 kernel-modules-headers master nested-changelog netdata_prelim-build-403535ef49e025c6e674cf7668fba3304b61af9b netdata_prelim nm-update noudev openvpn resinos-ubi super-7.25.4-build-a8880257d8098b6f592a491e253829f849d4ab5e super-7.25.4 superisor-7.19.7-build-2e55e7850c611df86cf5f05d1e9f27b1b063f6f8 supervisor-7.19.4-build-c6a686ab63f150fe1e8fe86ee5172fd97a2fc92c supervisor-7.21.3 supervisor-7.25.13-build-7114ec652971ab035e65a408ec6515fa90d02973 supervisor-7.25.13 supervisor-8.0.0 supervisor-8.7.0 supervisor-os-migration-backup supervisor-release-update support_non_efi syslog_ids-build-b54143eed928e4786990865c7b2af7a46935ecdc syslog_ids update-balena update_aufs_4.14.56+-build-830ad433c3d8bbd8d4ac04e3aebad6dc8ffee7f5 update_libqmi_and_libmbim-build-19bb5410ac28a89db7193490001ea358bbb37912 update_supported_modems_list-build-9c3f6b8ccfa0df2a4b37e682c356c43c090b6703 upgrade-dnsmasq v2.0.6-maintenance wpa-supplicant-krack xt-log-build-12043aab75e830c9c0228945ea95ea2b1483fc14 zlk_balenapie-build-60f4dd3f37887600890d3d922dc9e808b0ee5599 zlk/bump_sup-build-a9cf9b06e9775612f2397c7abaca507428558722 zlk_bumpbalena-build-2138758 zlk_dhcp_ntp zlk/fix_huawei_udev_rule_path zlk/fix_kernel zlk/fix_rollbacks zlk_fs_holes zlk_movekernelmeta-build-2ab0b41 zlk_movekernelmeta-build-3f02d62 zlk_movekernelmeta-build-896a09b331f4139174d280b34ce4761fa1277803 zlk_movekernelmeta-build-c61da03734bb2a5800bdc427f8896849eb5d5936 zlk_movekernelmeta-build-d67c271 zlk_movekernelmeta zlk/nmconf zlk_plymouth_rework zlk_rollbacks_hotfix1 zlk_rollbacks_hotfix2 zlk_rollbacks
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (151 sloc) 9.56 KB layers for Yocto


This repository enables building for various devices.

Layers Structure

  • meta-resin-common : layer which contains common recipes for all our supported platforms.
  • meta-resin-* : layers which contain recipes specific to yocto versions.
  • other files : README, COPYING, etc.



meta-resin version is kept in DISTRO_VERSION variable. resin-<board> version is kept in the file called VERSION located in the root of the resin-<board> repository and read in the build as variable HOSTOS_VERSION.

  • The version of meta-resin is in the format is 3 numbers separated by a dot. The patch number can have a beta label. e.g. 1.2.3, 1.2.3-beta1, 2.0.0-beta1.
  • The version of resin-<board> is constructed by appending to the meta-resin version a rev label. This will have the semantics of a board revision which adapts a specific meta-resin version for a targeted board. For example a meta-resin 1.2.3 can go through 3 board revisions at the end of which the final version will be 1.2.3+rev3 .
  • The first resin-board release based on a specific meta-resin release X.Y.Z, will be X.Y.Z+rev1 . Example: the first resin-board version based on meta-resin 1.2.3 will be 1.2.3+rev1 .
  • When updating meta-resin version in resin-board, the revision will reset to 1. Ex: 1.2.3+rev4 will be updated to 1.2.4+rev1 .
  • Note that the final OS version is NOT based on semver specification so parsing of such a version needs to be handled in a custom way.
  • e.g. For meta-resin release 1.2.3 there can be resin-<board> releases 1.2.3+revX.
  • e.g. For meta-resin release 2.0.0-beta0 there can be resin-<board> releases 2.0.0-beta0+revX.

We define host OS version as the resin-<board> version and we use this version as HOSTOS_VERSION.

Build flags

Before bitbake-ing with meta-resin support, a few flags can be changed in the conf/local.conf from the build directory. Editing of local.conf is to be done after source-ing. See below for explanation on such build flags.

Development Images

The DEVELOPMENT_IMAGE variable gets injected into DISTRO_FEATURES. If DEVELOPMENT_IMAGE = "1" then 'development-image' distro feature is added. Based on this, recipes can decide what development specific changes are needed. By default DEVELOPMENT_IMAGE = "0" which corresponds to a normal (non-development) build (development-image won't be appended to DISTRO_FEATURE). If user wants a build which creates development images (to use the serial console for example), DEVELOPMENT_IMAGE = "1" needs to be added to local.conf.

To make it short:

  • If DEVELOPMENT_IMAGE is not present in your local.conf or it is not "1" : Non-development images will be generated (default behavior)
  • If DEVELOPMENT_IMAGE is defined local.conf and its value is "1" : Development images will be generated

Generation of host OS update bundles

In order to generate update resin host OS bundles, edit the build's local.conf adding:

RESINHUP = "yes"

Configure custom network manager

By default resin uses NetworkManager on host OS to provide connectivity. If you want to change and use other providers, list your packages using NETWORK_MANAGER_PACKAGES. You can add this variable to local.conf. Here is an example:

NETWORK_MANAGER_PACKAGES = "mynetworkmanager mynetworkmanager-client"

Customizing splash

We configure all of our initial images to produce a resin logo at boot, shutdown or reboot. But we encourage any user to go and replace that logo with their own. All you have to do is replace the splash/resin-logo.png file that you will find in the first partition of our images (boot partition) with your own image. NOTE: As it currently stands plymouth expects the image to be named resin-logo.png.

Docker storage driver

By the default the build system will set all the bits needed for the docker to be able to use the aufs storage driver. This can be changed by defining BALENA_STORAGE in your local.conf. It supports aufs and overlay2.

The OS

SSH and Avahi services

The OS runs SSH (dropbear) on port 22222. Running this service takes advantage of the socket activation systemd feature so dropbear will only run when there is a SSH connection to the device saving idle resources in this way. In order to connect to a device, one can use it's IP when known or resolve the hostname over mDNS as its hostname is advertised over network using an avahi service. When the latter is used, configuration of the client is needed (see for example

Time in the OS

We currently have three time sources:

  • build time - stored in /etc/timestamp and generated by the build system when the image is generated
  • network time - managed by chronyd
  • RTC time when available

Early in the boot process, the OS will start three services associated with the sources listed above, which manage the system clock.

The first one is timeinit-rtc. This service, when a RTC is available (/etc/rtc) will update the system clock using the value read from the RTC. If there is no RTC available, the service will not do anything. The second service is timeinit-timestamp which reads the build timestamp and updates the system clock if the timestamp is after the current system clock. The third service is chronyd.service which is responsible of managing the time afterwards over NTP.

The order of the services is as stated above and provides a robust time initialization at boot in both cases where RTC is or not available.

Devices support

WiFi Adapters

We currently tested and provide explicit support for the following WiFi adapters:

  • bcm43143 based adapters
    • Example: Official RPI WiFi adapter link


We currently test as part of our release process and provide explicit support for the following modems:

  • USB modems (tested on Raspberry Pi 3, Balena Fin, Intel NUC and Nvidia TX2)
    • Huawei MS2131i-8
    • Huawei MS2372
  • mPCI modems (tested on Balena Fin and Nvidia TX2 Spacely carrier)
    • Huawei ME909s-120
    • Quectel EC20
    • SIM7600E

How to fix various build errors

  • Supervisor fails with a log similar to:
Step 3 : RUN chmod 700 /
---> Running in 445fe69866f9
operation not supported

This is probably because of a docker bug where, if you update kernel and don't reboot, docker gets confused. The fix is to reboot your system. More info:


The behaviour of resinOS can be configured by setting the following keys in the config.json file in the boot partition. This configuration file is also used by the supervisor.


String. The configured hostname of this device, otherwise the UUID is used.


Boolean. Enable or disable persistent logging on this device.


String. The country in which the device is operating. This is used for setting with WiFi regulatory domain.


String. A space-separated list of NTP servers to use for time synchronization. Defaults to servers.


String. A space-separated list of preferred DNS servers to use for name resolution. Falls back to DHCP provided servers and Google DNS.


Multiple settings that customize the OS at runtime are nested under here.



This object defines configuration related to Wi-Fi as it follows:

  • "randomMacAddressScan" string key where the value is a boolean
    • Configures MAC address randomization of a Wi-Fi device during scanning.

See below an example of a config.json snippet which disables MAC address randomization of Wi-Fi device during scanning:

"os": {
  "network" : {
    "wifi": {
      "randomMacAddressScan": false


String. Custom udev rules can be passed via config.json.

To turn a rule into the format that can be easily added to config.json, use

cat rulefilename | jq -sR . e.g.

root@resin:/etc/udev/rules.d# cat 64.rules | jq -sR .
"ACTION!=\"add|change\", GOTO=\"modeswitch_rules_end\"\nKERNEL==\"ttyACM*\", ATTRS{idVendor}==\"1546\", ATTRS{idProduct}==\"1146\", TAG+=\"systemd\", ENV{SYSTEMD_WANTS}=\"u-blox-switch@'%E{DEVNAME}'.service\"\nLBEL=\"modeswitch_rules_end\"\n"

An example config.json snippet with 2 rules:

  "os": {
    "udevRules": {
      "56": "ENV{ID_FS_LABEL_ENC}==\"resin-root*\", IMPORT{program}=\"resin_update_state_probe $devnode\", SYMLINK+=\"disk/by-state/$env{RESIN_UPDATE_STATE}\"",
      "64" : "ACTION!=\"add|change\", GOTO=\"modeswitch_rules_end\"\nKERNEL==\"ttyACM*\", ATTRS{idVendor}==\"1546\", ATTRS{idProduct}==\"1146\", TAG+=\"systemd\", ENV{SYSTEMD_WANTS}=\"u-blox-switch@'%E{DEVNAME}'.service\"\nLBEL=\"modeswitch_rules_end\"\n"

This will create /etc/udev/rules.d/56.rules and /etc/udev/rules.d/64.rules The first time rules are added/modified, these rules will be added and udevd will be asked to reload rules and re-trigger.


Array of strings. Holds a list of public SSH keys that will be used by the SSH server for authentication.


  "os": {
    "sshKeys": [

Yocto version support

The following Yocto versions are supported:

  • Sumo (2.5)
  • Rocko (2.4)
  • Pyro (2.3)
  • Morty (2.2)
  • Krogoth (2.1)