Venus OS: the Victron Energy Linux distro built on OpenEmbedded

A build wrapper rather than the operating system

Venus OS is described as the Victron Energy Unix like distro with a Linux kernel, and the naming note in the README explains that the name comes from Roman rather than Greek mythology, with Phoenix already taken by a charger.

What the repository actually contains is the machinery for producing that operating system. The README states it plainly: this repo is the starting point to build Venus, and it contains wrapper functions around bitbake and git to fetch and compile sources. The layers, the recipes and the metadata live elsewhere, in the openembedded-core repository and in various other layers containing the recipes and metadata that define Venus. The Makefile at the root is the public surface, exposing targets such as fetch, fetch-all, venus-image, venus-images and per-machine build targets.

That structure explains a lot about how the project feels to use. There is no single source tree to read, and there is no application code in this repository at all. Instead there are scripts for pushing and tagging many repositories at once, for populating CI artifacts, for rebasing on upstream, and a backport.py helper alongside an update-recipe.py helper.

For an outside developer the practical audience is narrow. It is for Victron staff, for integrators who need a custom image, and for anyone who needs to reproduce the firmware precisely.

The README tells you not to build the whole thing

The first paragraph of the documentation is a warning, and it is worth quoting the substance. Building Venus from source takes several hours, lots of disk space, and results in an image and an SDK which are both already available for download as binaries. The README links the swu image feed and the sdk feed directly.

It goes further. Even when you are developing on one part of Venus OS, for example one of its drivers or the GUI, it says it is still not necessary to build the full operating system from source.

That is a rare README, because it identifies its own main use case as something most readers should avoid. The logic is sound in the OpenEmbedded world: a full build recompiles layers you did not touch, and the parts you changed can be built or packaged on their own.

The other constraint is equally concrete. For a complete build you need access to private repositories of Victron Energy. Building only open source packages is also possible, but the README notes that this is not checked automatically at the moment.

So there are two realistic modes of use here: a partial build using only the public layers, which is possible but not continuously verified, and a complete build with private access, which is what the maintainers themselves do.

OpenEmbedded underneath, with bitbake doing the work

Venus uses OpenEmbedded as its build system. The README explains the pieces after the first fetch: bitbake is a make-like build tool that is part of OpenEmbedded, and alongside it you will find openembedded-core and various other layers containing recipes and other metadata defining Venus.

OpenEmbedded gives the project its recipe model. Each package is described by a recipe, and the layer directories assembled under sources are what tell bitbake what exists. The recipes in this ecosystem are usually Python, and the repository ships update-recipe.py, which is the script you would use when a recipe needs to be refreshed.

The Makefile targets map onto that structure. There is a per-machine target pattern, so make ccgx-venus-image builds for the ccgx machine and make beaglebone-venus-image builds for beaglebone, with the README noting that beaglebone can be substituted by another supported machine. The machine list itself comes from conf/machines, which the Makefile includes directly.

Firmware images are swu files. The Makefile notes that Venus uses swupdate for reliable firmware updates, and the swu targets come in a normal and a large variant, with make swus and make swus-large building for all machines. The repository also carries swu.sh at the top level.

The interesting engineering decision is that the entire build is driven from one wrapper Makefile rather than from raw bitbake invocations. That keeps machine selection and image naming out of the recipes.

Getting started on a Linux host with make prereq and make fetch

Building Venus requires a Linux machine, and the README says Ubuntu is what Victron uses. The setup sequence is three commands. First clone the repository:

git clone https://github.com/victronenergy/venus.git
cd venus

Then install the host packages, which the Makefile describes as the required host packages for Debian based distributions:

sudo make prereq

Then fetch the subtrees you need:

make fetch

The README is explicit about the difference between that last command and make fetch-all. make fetch clones the publicly available repositories, while make fetch-all downloads all repositories and needs Victron git access. The Makefile help text spells out the same split, listing make CONFIG=jethro fetch as the public option and make CONFIG=jethro fetch-all as the one requiring access.

That fetch command clones several things into the ./sources/ directory, which is where bitbake, openembedded-core and the other layers end up. The repository also ships venus-init-build-env, which is presumably what prepares that tree for use.

One caution from the Makefile is worth repeating before you experiment. The help text says switching between configs is deliberately not supported, since it would require resetting git branches forcefully and might throw away pending, unpushed work. If you need to change config, the documented recovery is to remove the sources directory and clean before fetching again.

Configs, the conf symlink and repos.conf pinning

The build targets automatically select the configuration used for Venus OS as distributed. Alternative setups are possible, for example to build against a newer OpenEmbedded version, and the README gives the form:

make CONFIG=rocko fetch-all

The default in the Makefile is CONFIG=scarthgap. To see which configuration your checkout is using, the README says to look at the ./conf symlink, which points at one of the configs in the ./configs directory. That symlink is the single source of truth for what your tree is pinned to, which matters when you are comparing your build against a released firmware.

Each config directory holds a few files. repos.conf contains the repositories that need to be checked out, and it can be rebuilt with make update-repos.conf. metas.whitelist contains the meta directories that will be added to bblayers.conf, but only if they are actually present, which is how a config avoids referring to layers you did not fetch. And machines holds the list of machines that can be built in that configuration.

Adding a repository is a four-step procedure: put it in sources, check out the branch you want, set an upstream branch, and then make the result permanent with make repos.conf. The README also reminds you to add the directories you want to use from the new repository to metas.whitelist, which is the step that is easy to miss and produces a build that silently lacks a layer.

The repos command and multi-repository git work

Because Venus is assembled from many git repositories, the repository ships a helper named repos that operates across all of them at once. The README describes it as just like git submodule foreach -q git, but shorter. The script and a repos_cmd file sit at the repository root.

The operations map onto git verbs. Pushing every repository at once is:

./repos push origin
./repos tag xyz

and reverting all of them to a specific revision is done with ./repos checkout tagname. The README also documents the difference-aware operations for reviewing local work across the whole tree, including ./repos cherry -v to list patches not yet upstream, ./repos diff @{u} for local changes against upstream, and ./repos diff @{push} for git 2.5 and later. Branch-level operations are supported too, with ./repos fetch origin followed by a rebase onto the upstream branch, and ./repos checkout on the branch named by the configuration.

Releasing uses the same idea, with the venus repository tagged first and then all the fetched repositories tagged with the same version:

git tag v2.21
git push origin v2.21

This is the part of the project with the highest learning curve for an outsider. The build is reproducible only if every layer is pinned to the right revision, and the repos tool exists precisely because doing that by hand across dozens of clones is error-prone.

Maintenance branches, the b prefix and backport discipline

The documentation includes a detailed procedure for creating a maintenance branch, which tells you more about how the project is run than any status page would. The base branch for maintenance releases is prefixed with a b.

The worked example is instructive. The context given is that master is already working on v2.30 while the latest official release was v2.20, so a branch named b2.20 is created in which the first release is v2.21, with later maintenance releases pushed on top. The sequence clones the venus repository, checks out v2.20, creates b2.20, runs make fetch-all, then uses the repos tool to check out v2.20, create the matching b2.20 branch across the meta repositories and push it with an upstream. After that the configuration is updated with make update-repos.conf and committed with a message that pins the branches to b2.20, the raspbian config is updated manually in the same way, and .gitlab-ci.yml is modified so that the shared SSTATE cache is not touched and the build comes from b2.20.

The rules that follow are strict. Only take changes from master, by cherry-picking. Do not add changes or new versions that are not in master yet. Use git cherry-pick -x so the commit message records where the change came from. And the inclusion rule is stated as: changes need to be either really small, well tested or very important.

On the choice between approaches, the README distinguishes full cherry-picks from backporting patches, and prefers taking complete commits from the meta repositories where you can, falling back to individual patches only when a repository has accumulated many commits and you need exactly one.

Where building Venus from source is the wrong path

The clearest wrong path is the one the README names first. If you want firmware for a Victron device, the swu images are already published, and the SDK is available as a binary download. Compiling the whole distribution to obtain the same artifact takes hours and a lot of disk space for no functional gain.

The second wrong path is expecting this repository to be a self-contained embedded Linux distribution. It is a wrapper over bitbake and git, and a complete build needs access to private Victron Energy repositories. A public-only build is possible, but the README says it is not checked automatically at the moment, so you would be the first line of verification for anything you produce that way.

The third is treating the maintenance branch workflow as a general branching model. The b prefix, the pinning of every meta repository to a matching branch and the manual edits to the raspbian configuration and to .gitlab-ci.yml all assume the context of a released product with multiple supported machines. Applying that discipline to a side project is a lot of ceremony for a different problem.

If your goal is a general embedded Linux distribution with an OpenEmbedded base, using OpenEmbedded or a Yocto-style distribution directly and adding the drivers you need is the more direct route, since Venus layers its own hardware support and firmware update flow on top of that system.

Editorial conclusion

Use this repository if you are a Victron integrator, need to build a driver or GUI change into Venus OS, or have to reproduce a firmware image for a specific machine such as ccgx or beaglebone. Do not use it as a general embedded Linux distribution to fork, because a complete build depends on private Victron repositories and because the README itself points you to the published swu and sdk binaries. Before you start, confirm you have Linux with the host packages installed by make prereq, decide whether you need make fetch or the private-repository make fetch-all, and pick the configuration deliberately, since the Makefile defaults to CONFIG=scarthgap and the conf symlink records which config your checkout uses.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. victronenergy/venus on GitHub