Adding custom device to openBalena instance

I have ported a custom device to work w/BalenaOS and am now trying to get this device connected to an openBalena server (running locally). The device shows up when running balena scan and is on the same network as the openBalena server.

When running balena devices supported -v the expected list of supported devices comes up. I was wondering how (if it is possible) the custom device could be added to that list so that it could be interfaced with via the balena-cli and managed with openBalena.

As I understand it, openBalena needs to have the device be supported with an official version of balenaOS to connect the board. Is it possible to configure openBalena/balena-cli to use the custom image built for the device?


unfortunately at this time, custom devices support in openBalena is still on the roadmap: (and don’t have any timeline for them unfortunately)

What board is this? One thing you could do it is to contribute it to the platform. One such example is which is a user contributed board. But that may not be suited if the board is a really custom one, not available for other users to purchase.
Another approach would be to pick a board with the same architecture as your custom board and masquerade your board as that other board with the same arch. You would use against your device’s image to configure it to the app device you want to masquerade it as.

1 Like

Just coming back to let you know this feature is currently being worked on as I was told by colleagues involved in that area. So I created for you to monitor progress on this

Hi floion,

I appreciate the advice and suggested workaround, I have been working on configuring the device image as though it were another device with the same architecture, and it’ll be a suitable workaround for now. I’ll keep an eye on the github issue for when the feature is integrated in the api.

Fortunately that workaround itself seems to be functional, however I am having issues with using the balena join command. The error I get is “Failed to determine OS version ID” from balena-cli, which appears to look for the /etc/os-release file on the device for a version ID (code should be this line: There is no such line in the os-release file for the custom image. Would this be an issue with the balena-cli version or a mistake in how I have done OS configuration? Aside from this the workaround has solved the other issues I had.

Thanks for all the help

Hi there,

Could you clarify a) what version of the CLI you are running and b) what standard device type you are masquerading as? That line you pointed out actually comes from the host OS, so that’ll need to be in line with a meta-balena version in order to work properly. If you are building a custom OS, that field is of course necessary (again given this is not yet fully supported, there may be other sharp edges in deploying your custom device).

I think my colleague was suggesting to use a standard balenaOS release, but use os configure to set a custom slug or other metadata.

Currently the CLI version that I’m running is 12.2.0 due to this issue which seems to be compatible with the self-hosted openbalena instance (which is version 2.0.3).

The standard device type I’ve used is the imx8m-var-dart as it is the closest to the custom board, with meta-balena version 2.54.2. I’ll make sure to include the version file, however there is no other version-related line I saw missing with the custom build as compared to examples such as balena-beaglebone or balena-intel.


I have managed to get the device version working correctly now - my mistake for missing the version file in the root directory of the build, I had thought it was autogenerated and unnecessary. Now that portion of the interaction works.

Now I’m working to get meta-balena rolled back to 2.49.0 for compatibility and properly mount /dev/disk/by-state symlinks again as that seems to be a recurring issue (worked on 2.54.2, will have to backport to 2.49.0)

For posterity the (tentative) solution that I’ve found w/this thread’s suggestions is to use the generic-aarch64 device type in the balena os configure command to create the application on openBalena and configure the custom image. Using this the device is able to be interfaced with using balena-cli v12.2.0. I’ll update again once I’ve been successful but this approach works as desired so far

Hey there glad that you are making progress and really grateful you can share the findings so the community can benefit from it.

Cheers and keep us posted :slight_smile:

The issue I ended up running in to was with mounting /dev/disk/by-state (again), fix is simple enough. Backporting the balenaOS changes to the initrdscripts files (found here) as well as the os-helpers (found here) was what did it for me. It seems these fix the boot process when partition uuid is not used in booting the kernel (I pass the label as boot param)

openBalena works fine once I have the device working on balenaOS v2.49 and configured correctly. I configured it as a generic-aarch64 device-type and had it join an app configured w/that type, and it seems to work as expected. The /etc/hosts/ file had to be configured to add the local openBalena instance, and once that was done the device could be added to an openBalena app using balena join.

Found that production images are not working as expected, it is possible to ssh in to development images using instructions from this thread, but I have not had any luck with production versions. balena scan was the way I found the device UUID previously, and now even with configuring the OS w/the test application I have the device “running” it is not functioning as the development version does.

It might be to do with configuration of the IP addresses for the openBalena server, since that’s local (a 192.168.x.x address). Is this a normal issue?

edit: Have tried configuration with a UUID supplied as well though the method shown in the masterclass here, still no luck getting a production version to show up in openBalena. Perhaps I am missing something in the config generation? Command I am running:
balena config generate --app test --version v2.49.0 --device (UUID from openssl rand call) --network ethernet --appUpdatePollInterval 10 --output config.json
Using this config.json in the os configure call has not successfully had the device show up under the test application when running balena devices --app test

Hi there, if you are looking to SSH into the production image, you would need to add the SSH public keys to config.json on the boot partition. If the correct keys are there, a systemd service will add them to the authorized_keys file on the machine and start SSHd.