DOCSEARCHbyAlgolia
Submit Docs

Venus OS Documentation

repository·master·Indexed 20 days ago

https://github.com/victronenergy/venus

A Victron Energy Unix-like distribution based on the Linux kernel. This repository provides the wrapper functions and orchestration using Bitbake and Git to compile the full Venus OS image and its associated SDK via the OpenEmbedded build system.

Tokens
1.5K
Snippets
4
Records
5
Agent score
23%

What's inside Venus OS

  1. Create a new maintenance branch

    master

    Maintenance branches are used to support older versions. These branches should be prefixed with b (e.g., b2.20).

    Workflow for creating a maintenance branch

    1. Create a new branch in the venus repository prefixed with b (e.g., git checkout -b b2.20).
    2. Fetch all meta repositories using make fetch-all.
    3. Use ./repos to checkout the target version, create a new branch in the sub-repos, and push them with the new upstream.
    4. Update the Venus configuration using make update-repos.conf to pin branches to the new maintenance version.
    5. Manually update relevant configuration files (like raspbian configs) and .gitlab-ci.yml to ensure the build environment is correctly pinned.
    6. Push the new branch to the remote.
    # Example: Creating maintenance branch b2.20
git clone git@github.com:victronenergy/venus.git venus-b2.20
cd venus-b2.20
git checkout v2.20
git checkout -b b2.20

make fetch-all

./repos checkout v2.20
./repos checkout -b b2.20
./repos push --set-upstream origin b2.20

make update-repos.conf
git commit -a -m "pin dunfell branches to b2.20"

# (Manual steps for raspbian config and .gitlab-ci.yml follow)

git push --set-upstream origin b2.20

  2. Setup and build Venus OS from source

    master

    Venus OS is built using the OpenEmbedded build system. To build from source, you need a Linux environment (Ubuntu is recommended). Note that a full build can take several hours and requires significant disk space. If you only need binaries, you can download them directly from the Victron Energy update feeds.

    Prerequisites

    1. Clone the repository.
    2. Install host dependencies using make prereq.
    3. Fetch the required subtrees (repositories) using make fetch. If you have access to private Victron Energy repositories, use make fetch-all to ensure a complete build environment.

    Building

    You can build for all machines defined in conf/machines, build for a specific machine, or build only the .swu update file.

    # Clone and enter the repository
git clone https://github.com/victronenergy/venus.git
cd venus

# Install host packages (Debian based)
sudo make prereq

# Fetch needed subtrees
make fetch

# Build all machines
make venus-images

# Build for a specific machine
make ccgx-venus-image

# Build the swu file only
make ccgx-swu

  3. Configure build settings and machines

    master

    The build configuration is managed via the ./conf symlink, which points to a specific directory in ./configs.

    Using different configurations

    You can specify a configuration during the fetch process using the CONFIG variable: make CONFIG=rocko fetch-all

    Configuration files

    Each configuration directory contains:

    • repos.conf: Defines the repositories to be checked out. Rebuild this with make update-repos.conf.
    • metas.whitelist: A list of meta directories to be added to bblayers.conf (only if they exist).
    • machines: A list of target machines supported by this configuration.

    Adding new repositories

    1. Place the repository in the sources directory.
    2. Checkout the desired branch and set an upstream branch.
    3. Make the change permanent by running make repos.conf.
    4. Add the relevant directories from the new repository to metas.whitelist.

  4. Troubleshoot Linux update and Rust crate errors

    master

    If you encounter specific build errors during the OpenEmbedded/Bitbake process, try the following fixes:

    Kernel image provider errors

    If you see errors stating that a package (e.g., packagegroup-machine-base) cannot find a provider for kernel-image-X.X.X:

    1. Run make einstein-bb (or the relevant machine command).
    2. Clean the problematic package: bitbake -c cleanall packagegroup-machine-base.
    3. Retry the build.

    Missing Rust crates

    If the build fails due to missing Rust crates, clean the specific Python recipes that depend on them: bitbake -c cleanall python3-cryptography python3-orjson python3-bcrypt

    # Fix kernel provider issues
make einstein-bb
bitbake -c cleanall packagegroup-machine-base

# Fix missing Rust crates
bitbake -c cleanall python3-cryptography python3-orjson python3-bcrypt

  5. Use the `repos` command for multi-repo management

    master

    The ./repos script is a wrapper for managing multiple git repositories within the Venus build environment, similar to git submodule foreach but optimized for this workflow. It allows you to perform git operations across all sub-repositories simultaneously.

    # Push all repositories
./repos push origin

# Tag all repositories
./repos tag xyz

# Revert all repositories to a specific revision
./repos checkout tagname

# Check for patches not yet in upstream
./repos cherry -v

# Rebase local checkout branches on upstream master
./repos fetch origin
./repos rebase 'origin/$checkout_branch'