As the ecosystem of third-party drivers (SerialBattery, custom BMS integrations, Aggregators) grows, the generic “Modified” banner on Venus OS is becoming less useful for diagnostics. Currently, it tells us that the system is modified, but not what is running, if that code is up-to-date, or if the user has broken the script logic while trying to change a setting.
I propose a lightweight standard where installers drop a JSON manifest into a specific directory (e.g., /data/etc/venus-mods/). This would allow the system, support staff, or UI to easily list installed extensions without digging through the filesystem.
My Proposal
- Standard Location:
/data/etc/venus-mods/ - Standard File:
unique-package-id.jsoncontaining version, source, and a smart checksum map of the active files.
Benefits
- Granular Visibility: Instead of just “Modified”, we can see “Modified by: Samsung-SDI-Driver v1.1.0”.
- Smart Integrity Check (The “Seal”): The system hashes all executable code (
.py,.sh) but intentionally ignores configuration files (.ini,.conf,.json).- Result: If a user changes config.ini to set their battery capacity, the hash remains valid (Green).
- Result: If a user edits
driver.pyand breaks the logic, the hash mismatches (Red/Tampered).
- Conflict Resolution: Easier to see if two installed mods are trying to control the same hardware.
Reference Implementation (Shell/Python Polyglot)
I have implemented this in my drivers. Since Venus OS ships with Python 3, we can use it to perform robust, recursive hashing without complex shell dependencies.
Here is the register_mod function that any script developer can include in their install.sh:
#!/bin/bash
# Venus OS Mod Registration Standard
# Usage: register_mod <id> <name> <version> <repo_url> <install_directory>
register_mod() {
local MOD_ID=$1
local MOD_NAME=$2
local MOD_VERSION=$3
local MOD_REPO=$4
local MOD_PATH=$5
# Use embedded Python for robust JSON handling and recursive hashing
python3 -c "
import json
import os
import hashlib
import datetime
def get_hash(path):
with open(path, 'rb') as f:
return hashlib.md5(f.read()).hexdigest()
data = {
'id': '$MOD_ID',
'name': '$MOD_NAME',
'version': '$MOD_VERSION',
'repository': '$MOD_REPO',
'installed_at': datetime.datetime.utcnow().isoformat() + 'Z',
'files': {}
}
root = '$MOD_PATH'
# Recursive walk that audits code but ignores config
if os.path.exists(root):
for dirpath, dirnames, files in os.walk(root):
if '__pycache__' in dirnames: dirnames.remove('__pycache__')
for f in files:
if f.startswith('.'): continue
if f.endswith(('.pyc', '.log', '.txt', '.md')): continue
# IGNORE CONFIGS: Allow users to edit settings without breaking integrity check
if f.endswith(('.ini', '.yaml', '.json', '.conf', '.xml')): continue
full_path = os.path.join(dirpath, f)
rel_path = os.path.relpath(full_path, root)
try:
data['files'][rel_path] = get_hash(full_path)
except: pass
manifest_dir = '/data/etc/venus-mods'
if not os.path.exists(manifest_dir):
os.makedirs(manifest_dir)
with open(f'{manifest_dir}/{data['id']}.json', 'w') as f:
json.dump(data, f, indent=2)
"
echo "Module '${MOD_ID}' registered to Venus OS manifest."
}
Example Usage in install.sh
# During installation...
register_mod "samsung-sdi-driver" \
"Samsung SDI Integration" \
"v1.1.0" \
"https://github.com/drurew/samsung-sdi-victron-integration" \
"/data/samsung-sdi"
Resulting Manifest (/data/etc/venus-mods/samsung-sdi-driver.json)
Notice how config.ini is absent, allowing for user customization, while the core logic is fingerprinted.
{
"id": "samsung-sdi-driver",
"name": "Samsung SDI Integration",
"version": "v1.1.0",
"repository": "https://github.com/drurew/samsung-sdi-victron-integration",
"installed_at": "2024-06-15T10:30:00Z",
"files": {
"samsung_sdi_bms_service.py": "5d41402abc4b2a76b9719d911017c592",
"samsung_sdi_can_client.py": "7d793037a0760186574b0282f2f435e7",
"install.sh": "1a79a4d60de6718e8e5b326e338ae533"
}
}
Extension: Request for Flexible “Blind Install” Filenames
In addition to the Manifest system, I would like to propose an enhancement to the Automatic Install (USB/SD Card) mechanism found in /etc/rcS.d/S90setup.
Current Limitation:
The system strictly looks for a file named venus-data.tar.gz. This creates confusion for users and prevents different drivers from sharing a USB stick installer.
Proposed Feature:
Allow the system to scan for *.venus-data.tar.gz.
Example Workflow:
- User places
samsung-sdi.venus-data.tar.gzon USB. - User places
mqtt-driver.venus-data.tar.gzon USB. - Venus OS iterates through all matches → Extracts → Runs setup → Renames to
.done.
Why this is the “Endgame” for Mods
I’ve seen discussion about using opkg or custom repos. While opkg exists, Venus OS wipes the rootfs on every update, making standard package management “volatile”.
The real solution is a First-Party Frontend for modifications. But for Victron to ever build that, they need a standardized way to know what a mod is.
Why the Manifest is the missing piece:
- Metadata Equality: Whether a mod is installed via
opkg, a shell script, or SetupHelper, it writes a.jsonmanifest. This gives the OS a unified way to “audit” the system. - VRM Visibility: If this metadata is standardized, it becomes trivial for the VRM portal to report installed mods remotely.
- Transition to Repos: If we eventually move to a “Custom Repo” model, the transition is easy because we’ve already standardized the metadata schema.
I have updated all my repositories to auto-generate this JSON. Even if Victron doesn’t use it today, having a directory of “Installed Mods” on every system makes it much easier for the community to help troubleshoot.