Ed3Design Victron Cerbo GX — Onboarding a new Modbus-TCP device
Pattern verified against a real Cerbo GX with a JK-BMS that remained invisible at the Modbus layer despite correct VLAN routing. The non-obvious cause is the per-port
Enabled=0factory-default. The 5-step sequence +dbus-sendfix is the deterministic onboarding workflow; the fallback branch coversEnabled=1cases where the device is still invisible.
The non-obvious problem
dbus-modbus-client discovers new Modbus devices via TCP subnet scan (port 502, every 25 s) — creates settings in localsettings and sets Enabled = 0 as the default. The device is registered but invisible. No hint in the log, no error in the UI.
Applies to all Victron Modbus-TCP devices: EV Charging Station, Carlo Gavazzi meters, SolarEdge, external inverters.
Diagnostic sequence (5 steps)
SSH access pattern (replace placeholders with your own credentials and hosts):
ssh -J <your-jumphost-user>@<your-jumphost-ip> root@<cerbo-ip>
Note: the Cerbo's root SSH access is enabled via the Cerbo UI under Settings → General → Access Level → Superuser. Use ssh-copy-id to set up key-auth and avoid password prompts. Do NOT hardcode passwords into shell scripts or skill bodies.
1 — Network check
ping -c 2 <device-ip>
No response → LAN/VLAN problem, check DHCP. Response → continue.
2 — D-Bus check
dbus -y | grep -i "evcharger\|evc_\|<device-type>"
Empty → settings problem (Enabled=0 candidate). Service visible → check UI refresh / VRM cache.
3 — Read the modbus-client log
cat /var/log/dbus-modbus-client/current | tr -d "\000" | grep -v "^$" | tail -30
Watch for these patterns:
Found EV charger: Victron Energy AC22NS→ device detected ✓Setting /Settings/Devices/<id>/Enabled does not exist yet→ default-Enabled problem
4 — Check the Enabled value
dbus -y com.victronenergy.settings /Settings/Devices/<device-id>/Enabled GetValue
Returns 0 → that's the bug. Device-ID from log (format: evc_<Serial>).
5 — Fix: set Enabled to 1
dbus-send --system --print-reply \
--dest=com.victronenergy.settings \
/Settings/Devices/<device-id>/Enabled \
com.victronenergy.BusItem.SetValue \
variant:int32:1
Return int32 0 = success. Device appears in D-Bus and the Cerbo UI within a few seconds.
Fallback: Enabled=1 set but device still not visible
# Restart the service (re-reads settings)
killall dbus-modbus-client
# Cerbo waits ~25s for dbus-modbus-client to rescan — then check again:
dbus -y | grep -i evc_
Alternative path (without SSH)
Cerbo Remote Console (web UI on port 80 or via VRM) → Settings → Device List → find device → toggle Enable.
BusyBox compatibility on Venus OS
Standard GNU flags do not work on the Cerbo — use BusyBox variants:
| What you want | GNU (does not work) | BusyBox (works) |
|---|---|---|
| Limit bytes | cat file | head -c 2000 |
cat file (truncate if needed) |
| Processes | ps aux |
ps (no flag) |
| Read file with NUL bytes | cat file |
cat file | tr -d "\000" |
Example setup (anonymized reference)
| Device | IP (example) | Serial (example) | D-Bus path |
|---|---|---|---|
| Victron EVCS NS | <charger-ip> |
<charger-serial> |
com.victronenergy.evcharger.evc_<charger-serial> |
| Cerbo GX | <cerbo-ip> |
<cerbo-serial> |
— |
| SSH Jump-Host (optional) | <user>@<jumphost-ip> |
— | e.g. Tailscale, WireGuard |
SSH pattern (use key-auth, never hardcoded passwords):
ssh -J <user>@<jumphost-ip> root@<cerbo-ip>
Background: TDD log (Bulletproofing-Log)
Cycle 1 — 2026-05-27 (PASS)
RED sub-agent (without skill): Suggested generic steps — check Modbus TCP settings, power-cycle, VLAN, firmware compatibility. Explicitly admitted "I don't know the concrete onboarding protocol for this device class". No knowledge of the
Enabled=0default — would lead to long false-trail diagnostics.GREEN sub-agent (with skill): Directly applied the 5-step sequence,
dbus -y→dbus-sendfix within seconds. Self-reflection: missing fallback branch whenEnabled=1but still no device → polish item integrated directly (killall dbus-modbus-client).Refactor: Fallback section added after step 5. Do-NOT-load clause added. No R1-R3 needed.
Cycle-2 backlog (polish, non-blocking)
- Multi-device onboarding: when 2+ Modbus devices appear on the LAN simultaneously — identify device IDs in the log when multiple
Foundlines appear - VRM remote activation: when SSH access is not possible (e.g. Cerbo behind NAT without VPN) — document the VRM Console path in more detail
- Automatic Enable on first discovery: long-term a Cerbo update might change the default → check whether Venus OS 3.4+ handles this differently