Sensors & Units

RBgrid measures through two layers:

• Sensors — the physical channels the hub can see. In a v1.1.0 hub these are the channels of the rbAmp I²C modules: a voltage input and one or more current channels per module. There is no built-in ADC; the modules measure and the hub reads them over I²C.
• Units — the measurement points you create by binding a channel. A unit has its own identity, name, role, statistics and history. Moving a unit to another channel keeps its identity and history.

You do not write any code to add a sensor or a unit. Channels appear on their own when a module is connected; you turn a channel into a unit from the web app or the REST API at runtime.

Sensors — the physical channels

Every channel of a connected module is listed, whether or not it is in use. A channel that is not bound to a unit is simply free: it is not read, not summed and raises no alert. A module can be used with any subset of its channels, in any order.

Each channel carries:

• ch_label — the channel as printed on the module housing: I0, I1, … for current channels (numbered from 0), V for the module's voltage input, and L1–L3 on a phase-aware module.
• CT model — for a current channel, the current-transformer model in use (ct_code / readable ct_name, e.g. SCT-013-050, 50 A) and the module's limits for it. On a module that takes a clamp-on CT of your choice, you set the model (see Choosing the CT model below); on a module whose CT is paired with the channel at the factory, the model is fixed.
• Correction status — whether the module has applied its correction for the chosen CT model. If it has not (readings not corrected), the interface shows a warning and the reason (the channel is not calibrated · its gain does not match the CT model · the module does not know this CT model). This status is about whether a correction was applied — it says nothing about the accuracy of the reading.

The modules themselves come from the hub's fleet configuration (Getting Started → Connecting rbAmp modules). The rbAmp module families, their channel make-up and CT lineup are documented with the modules — see the rbAmp module docs.

Units — the measurement points

A unit is created by binding one channel to a point. It carries:

Two units are special supply units — the main supply (the grid connection) and an optional alternative supply (internal generation). Their role is locked and they carry the site's economic tracking; the voltage bus (the module's V input) and the main input cannot be deleted.

Configuring at runtime — web app or REST

Everything is configured on the running hub. Nothing is set in C code.

Web app — Points → bind turns a free channel into a unit; the unit's fields are edited in its settings.

REST — the same operations are available over HTTP:

Write operations take the hub's admin token when one is set — set one with POST /api/system/token and send it on writes; this is recommended. Until you set a token, writes are open on the local network.

Binding a channel, for example:

POST /api/v1/units
{
  "sensor": { "iface": "i2c", "bus": 0, "module": 0, "ch": 1 },
  "name": "Kitchen", "point": "kitchen",
  "role": "ZONE_LOAD", "stat_class": "DAILY", "location": "ground floor"
}

The reply returns the new unit_id. New ids are allocated from 0100 upward. Renaming a point retires the old slug (so an external system does not silently pick up a different point under the same key); deleting a unit frees its channel again.

Parameters such as name, role, phase, rated_power_w, max_current_a and the CT model are changed live with the patch endpoint and are saved across a reboot. The full field reference lives in the units & sensors API.

Choosing the CT model

On a channel whose module takes a clamp-on CT of your choice, set the CT model to the clamp actually fitted (in the point's settings, or ct_code via the patch endpoint). The hub writes the model into the module and keeps it bound to that module's identity, so a different module in the same slot keeps its own stored model. On a factory-paired channel the model is fixed and cannot be changed.

Phase

phase labels which supply line a channel belongs to. On a single-phase supply all channels use the default (1P / L1). Single-phase and three-phase supplies are supported and validated on hardware; split-phase (SPLIT) is not yet validated. The validated set is published by the hub itself — GET /api/v1/schema → enums.grid_system_validated; treat anything absent from that list as an unvalidated code path.

phase is only a label. The hub never multiplies or divides a unit's values by the number of phases: a unit with one current transformer reports what that one conductor carries, whatever its phase says. A unit marked "all three phases" on a three-phase load is the measured energy of one leg — do not divide or multiply it by three.

Statistics

Each unit keeps 3-second and 15-minute data in RAM at all times. Its stat_class sets how deep the flash history goes — 1HOUR, DAILY, WEEKLY, MONTHLY or YEARLY — and so how much memory the unit uses. Deeper classes keep longer history. (A Memory Storage module must be connected to keep statistics across a reboot.)

When a channel is near its limit

A current channel flags its state on the tile and in Needs attention:

• clipping — the current is being clipped; above a CT's rating the reading is under-counted, and the module cannot tell on its own, so this flag is the only warning.
• sensor limit — the current is at or above about 85 % of the sensor's range.
• A reversed CT (sustained negative power on a BASIC channel) is flagged so you can turn the clamp around.

Each episode is also written to the event log and the hour's record. See Hardware & Sensors → Module cards for where these appear.