← Panoramica | Indice | Avanti: Compilazione →

1. Hardware Wiring Guide

ACRouter v2.0. Sensing and dimming moved to smart I2C modules. The on-chip ADC voltage/current measurement and direct GPIO/TRIAC dimming of v1.x have been removed. A v2.0 build is an ESP32-family host plus one or more rbAmp (measurement) and DimmerLink (dimmer) modules sharing a single I2C bus. If you are migrating from a v1.x ADC build, see §1.8 Migrating from v1.x.

---

⚠️ DANGER — Mains Voltage

AC mains (110 V / 230 V) can cause serious injury or death. ACRouter modules sit on the mains side. De-energize the circuit before wiring, keep the low-voltage I2C wiring (SDA/SCL/3V3/GND) physically isolated from the mains section, and have mains work done by qualified personnel. Full safety requirements: §1.7 Safety — read it before you build.

1.1 Architecture at a Glance

A functional v2.0 Solar Router consists of:

• All modules share one I2C bus (bus0). Each module has its own I2C address.
• Minimum viable build: one ESP32-family host + one rbAmp (with a grid channel) + one DimmerLink. Grid measurement is mandatory — see §1.4.
• Firmware auto-discovers modules by an I2C scan and identifies each family from a device registry; you then assign sensing roles and reboot once (see the Commissioning guide).

1.2 The I2C Bus

All ACRouter modules communicate over a single I2C bus running at 100 kHz (Standard Mode). Because the bus carries every module, correct pins, pull-ups, and power are the foundation of a working build.

1.2.1 Bus Pins by Target

The default SDA/SCL pins depend on which chip you flash. Both are firmware defaults from the Hardware Config Manager and can be reconfigured (see §1.6).

1.2.2 Pull-Up Resistors — Required

⚠️ External pull-up resistors on SDA and SCL are mandatory.

• Use 4.7 kΩ pull-ups from each of SDA and SCL to 3V3 (one pair per bus, not per module).
• The ESP32's weak internal pull-ups are not sufficient for I2C modules on a mains-side bench — always fit external resistors.

1.2.3 Power

• Power the rbAmp and DimmerLink modules from 3V3.
• Share a common ground between the host and all modules.

1.2.4 Bus Topology

3V3
                      │
                 4.7k ┴ 4.7k        (one pull-up pair for the whole bus)
                   │      │
  ESP32 / C2 ──────┼──────┼──────────────┬───────────────┐
   host       SDA  │  SCL │              │               │
                   │      │           ┌──┴───┐        ┌───┴────┐
                   └──────┴───────────┤ rbAmp├────────┤DimmerLink│
                                      │ 0x51 │        │  0x50   │
                                      └──┬───┘        └───┬────┘
                                    CT clamps         phase-cut
                                  (grid/solar/load)   output → load

(Addresses shown are the reference-bench values; see §1.4 / §1.5 for how they are assigned.)

1.3 Modules on the Bus

Two module families are recognised by the firmware device registry:

The addresses above are example / reference values used on the validation bench — not guaranteed factory defaults (each module's shipping address is set by the module vendor). Every module is re-addressable, so if two modules of the same family share the bus you assign each a unique address (see the re-addressing commands in §1.4 / §1.5). Run i2c-scan to see what is actually present on your bus.

1.4 rbAmp (Measurement Module)

The rbAmp module measures AC current with clamp-on current transformers (CTs) — the CT clips around a conductor, it is not wired in-line — plus line voltage, and reports over I2C. Clip the grid CT around the mains-supply conductor, the solar CT around the solar/inverter line, and a load CT around the diverted-load line as needed.

• I2C address: 0x51 on the reference bench (example, re-addressable — not a guaranteed factory default). Re-address with the rbamp-address serial command or POST /api/rbamp/modules/address (verify-then-set; the new address applies after a module reset).
• Per-channel roles: each rbAmp channel is assigned one of grid, solar, load, or voltage.
• 🔴 A grid channel is mandatory. Real-time power sign (import vs. export) is derived only from the grid measurement — without it the router cannot decide when to divert.
• Assign roles with dev-role <addr> <ch> <role> (serial) or via /api/modules roles.

1.4.1 CT Model

The current-transformer model must match your physical CT so the firmware scales readings correctly. The catalog is the firmware source of truth — fetch it with GET /api/rbamp/ct-models.

Set the model with POST /api/rbamp/modules/ct-model {addr, ct_model:"sct013-010"} or the serial command rbamp-ct-model.

⚠️ The selector key is the id (e.g. sct013-010), not the display name.

1.4.2 Advanced (optional)

Not needed for a standard single-bus build:

• DRDY (data-ready) signal. The rbAmp exposes an optional DRDY line for interrupt-driven reads; bind it to a GPIO with hw-rbamp-drdy. By default the firmware polls without DRDY (the bench ran with DRDY disabled), so you can leave it unconnected.
• Bus selection. hw-rbamp-bus chooses which I2C bus (bus0 / bus1) an rbAmp lives on. With a single shared bus you never need it; when several rbAmp modules of the same family are present, give each a unique address (see §1.3).

1.5 DimmerLink (Dimmer Module)

The DimmerLink module performs phase-cut dimming on its own PY32 controller and takes commands over I2C.

• I2C address: 0x50 on the reference bench (example, re-addressable — not a guaranteed factory default). Re-address with the dl-address serial command.
• Role: always dimmer — implied by the family, so you do not assign it manually.

1.5.1 How a DimmerLink becomes a dimmer output (recommended path)

The normal, user-facing flow: assign the module the dimmer role, and the firmware auto-binds it to a dimmer output.

1. Discover the module (i2c-scan / rescan) — the device registry identifies it as DimmerLink.
2. Set its role to dimmer via POST /api/modules/role or the web app's Dimmers page.
3. The firmware auto-binds it to the first free I2C dimmer output — dimmer id 4 (bridge_role → dimmer_bind_i2c).
4. Drive that output with dimmer <id> <0-100> (e.g. dimmer 4 60).

Why id 4? Dimmer output ids 0–3 are reserved empty — they were the legacy on-chip GPIO dimmer channels, removed in v2.0. I2C dimmer outputs therefore start at id 4 (DIMMER_I2C_START = 4).

1.5.2 Advanced: dl-config and slots

dl-config <slot> <addr> <role> is a low-level developer command that registers a DimmerLink in the DL-manager by slot (0–7, DL_MAX_DEVICES = 8). Most users never need it — use the role assignment above instead.

🔴 Slot ≠ dimmer id. The slot is the module's registration index inside the DL-manager; the dimmer id (e.g. id 4) is the actuation index inside the dimmer manager. They are two separate numbering schemes — don't conflate them.

1.6 Configuring the Bus Pins

If your wiring differs from the target default (§1.2.1), reconfigure the bus.

Persistent (survives reboot):

POST /api/hardware/config
{"i2c":{"bus0":{"sda":25,"scl":26,"enabled":true}}}

The configuration is stored in NVS. A reboot is required — bus pins are read from the hardware config only during boot-time initialization.

Runtime (not persisted):

i2c-reinit <bus> <sda> <scl> <freq>

Re-initializes the bus immediately for testing, but the change is lost on reboot.

🔁 Order of operations: wire the modules → set bus pins (if non-default) → reboot → discover & assign roles → reboot once more (DimmerLink polling only starts at boot when at least one dimmer is enabled). The full first-time flow is covered in the Commissioning guide.

1.7 Safety

⚠️ PERICOLO: Tensione di rete

La tensione di rete AC (110 V/230 V) può causare gravi lesioni o morte.

The rbAmp and DimmerLink modules operate on the mains side of your installation. Treat the whole build as a live-mains project.

Prima di lavorare con questo progetto:

1. Qualifiche: i lavori elettrici devono essere eseguiti da personale qualificato
2. De-energize first — always disconnect power before making or changing connections.
3. Verify — confirm the circuit is dead with a multimeter before touching conductors.
4. Insulation — use properly rated wire, connectors, and CT clamps.
5. Protection — install appropriate fusing plus RCD/GFCI protection for your loads.
6. Enclosure — house all mains connections in a suitable enclosure.

Isolate low-voltage from mains. Keep the I2C wiring (SDA / SCL / 3V3 / GND between the host and the modules) physically separated from the mains-carrying section. Do not run signal wiring loose alongside live conductors.

Grounding. Ensure proper protective-earth grounding of enclosures and metal frames — it is essential for safety, independent of the shared signal ground the I2C bus needs (§1.2.3).

A more detailed electrical-safety reference may be published as a separate page; this callout is the minimum you must observe when wiring an ACRouter.

1.8 Migrating from v1.x

If you built a v1.x ACRouter, the following on-board hardware is no longer used and its firmware support has been removed:

A v2.0 build reuses your ESP32 host and mains wiring, but the sensing and dimming front-ends are now the external rbAmp and DimmerLink modules on the I2C bus.

← Panoramica | Indice | Avanti: Compilazione →