@enyo-energy/sunspec-sdk 0.0.38 → 0.0.40

package/README.md

@@ -1 +1,626 @@
-# enyo Sunspec SDK
+# enyo SunSpec SDK
+
+SunSpec Modbus client for reading data from solar inverters, batteries, meters, and other energy devices over Modbus TCP/RTU.
+
+## Table of Contents
+
+- [How Addressing Works](#how-addressing-works)
+- [Bulk Register Reading](#bulk-register-reading)
+- [Data Types](#data-types)
+- [Scale Factors](#scale-factors)
+- [Model 1 — Common Block](#model-1--common-block)
+- [Model 101 — Single-Phase Inverter](#model-101--single-phase-inverter)
+- [Model 103 — Three-Phase Inverter](#model-103--three-phase-inverter)
+- [Model 121 — Inverter Settings](#model-121--inverter-settings)
+- [Model 123 — Inverter Controls](#model-123--inverter-controls)
+- [Model 124 — Battery Basic Storage Controls](#model-124--battery-basic-storage-controls)
+- [Model 160 — MPPT](#model-160--mppt-multiple-maximum-power-point-tracker)
+- [Models 201/203/204 — Meters](#models-201203204--meters)
+- [Model 802 — Battery Base](#model-802--battery-base)
+- [Writable Registers](#writable-registers)
+- [Enum Reference](#enum-reference)
+
+---
+
+## How Addressing Works
+
+### Base Address Detection
+
+SunSpec devices expose a `"SunS"` identifier at a known base address. The SDK auto-detects:
+
+| Mode | Base Address | `"SunS"` Location | First Model Address |
+|------|-------------|-------------------|---------------------|
+| 1-based (most common) | 40001 | 40001–40002 | 40003 |
+| 0-based | 40000 | 40000–40001 | 40002 |
+| Custom | user-provided | user-provided | base + 2 |
+
+### Model Discovery
+
+Starting from the first model address, the SDK scans through contiguous model blocks:
+
+```
+┌──────────────┬──────────────┬─────────────────────────┐
+│ Model ID     │ Model Length │ Model Data Registers    │
+│ (1 register) │ (1 register) │ (Length registers)      │
+├──────────────┼──────────────┼─────────────────────────┤
+│ offset 0     │ offset 1     │ offset 2 ... Length+1   │
+└──────────────┴──────────────┴─────────────────────────┘
+         ▲                              ▲
+    model.address               model.address + 2
+```
+
+- **`model.address`** — Modbus address of the model ID register (start of the 2-register header)
+- **`model.length`** — Number of data registers (does NOT include the 2-register header)
+- **Next model** — Located at `model.address + 2 + model.length`
+- **End marker** — Model ID `0xFFFF` (65535) signals end of model chain
+
+### Register Offsets
+
+All register offsets in this document are relative to `model.address`:
+
+- **Offset 0** = Model ID register
+- **Offset 1** = Model Length register
+- **Offset 2** = First data register (for most models)
+
+---
+
+## Bulk Register Reading
+
+Each model is read in a **single Modbus call** via `readModelBlock()`, which reads `model.length + 2` contiguous registers starting at `model.address`. Individual fields are then extracted from the resulting buffer — no additional network round trips.
+
+---
+
+## Data Types
+
+| Type | Registers | Bytes | Description |
+|------|-----------|-------|-------------|
+| `uint16` | 1 | 2 | Unsigned 16-bit integer |
+| `int16` | 1 | 2 | Signed 16-bit integer (two's complement) |
+| `uint32` | 2 | 4 | Unsigned 32-bit integer (big-endian) |
+| `acc32` | 2 | 4 | 32-bit accumulator (unsigned, monotonically increasing) |
+| `string` | N | 2N | UTF-8 string, null-padded |
+| `enum16` | 1 | 2 | Enumerated value (uint16) |
+| `enum32` | 2 | 4 | Enumerated value (uint32) |
+| `bitfield16` | 1 | 2 | Bit flags (uint16) |
+| `bitfield32` | 2 | 4 | Bit flags (uint32) |
+
+### NOT_IMPLEMENTED Sentinel Values
+
+Registers may return sentinel values indicating the field is not implemented:
+
+| Type | Sentinel Value | Hex |
+|------|---------------|-----|
+| int16 | -32768 | `0x8000` |
+| uint16 | 65535 | `0xFFFF` |
+| int32 | -2147483648 | `0x80000000` |
+| uint32 | 4294967295 | `0xFFFFFFFF` |
+| enum16 / bitfield16 | 65535 | `0xFFFF` |
+| enum32 / bitfield32 | 4294967295 | `0xFFFFFFFF` |
+| acc16 | 0 | `0x0000` (NOT_ACCUMULATED) |
+| acc32 | 0 | `0x00000000` (NOT_ACCUMULATED) |
+| string | all NULLs | `0x0000` per register |
+
+---
+
+## Scale Factors
+
+Many numeric fields have an associated **scale factor** (SF) register. The final value is:
+
+```
+scaled_value = raw_value × 10^SF
+```
+
+Scale factor registers are `int16` and typically contain values like `-2`, `-1`, `0`, `1`, `2`.
+
+For example: raw value `2345` with SF `-1` → `2345 × 10⁻¹` = `234.5`
+
+---
+
+## Model 1 — Common Block
+
+**Method:** `readCommonBlock()`
+
+| Offset | Field | Type | Qty | Description |
+|--------|-------|------|-----|-------------|
+| 0 | ID | uint16 | 1 | Model ID (= 1) |
+| 1 | L | uint16 | 1 | Model length (typically 65–66) |
+| 2–17 | Mn | string | 16 | Manufacturer name |
+| 18–33 | Md | string | 16 | Model name |
+| 34–41 | Opt | string | 8 | Options |
+| 42–49 | Vr | string | 8 | Firmware version |
+| 50–65 | SN | string | 16 | Serial number |
+| 66 | DA | uint16 | 1 | Modbus device address |
+
+---
+
+## Model 101 — Single-Phase Inverter
+
+**Method:** `readSinglePhaseInverterData()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 6 | A_SF | int16 | Current SF |
+| 10 | W_SF | int16 | Power SF |
+| 12 | Hz_SF | int16 | Frequency SF |
+| 13 | V_SF | int16 | Voltage SF |
+| 18 | DCA_SF | int16 | DC current SF |
+| 19 | DCV_SF | int16 | DC voltage SF |
+| 21 | DCW_SF | int16 | DC power SF |
+
+### Data Registers
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 2 | A | uint16 | A_SF | AC current (A) |
+| 7 | PhVphA | uint16 | V_SF | Phase voltage AN (V) |
+| 9 | W | int16 | W_SF | AC power (W) |
+| 11 | Hz | uint16 | Hz_SF | Frequency (Hz) |
+| 14 | DCA | uint16 | DCA_SF | DC current (A) |
+| 15 | DCV | uint16 | DCV_SF | DC voltage (V) |
+| 20 | DCW | int16 | DCW_SF | DC power (W) |
+| 24 | St | uint16 | — | Operating state (enum) |
+
+---
+
+## Model 103 — Three-Phase Inverter
+
+**Method:** `readInverterData()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 6 | A_SF | int16 | Current SF |
+| 13 | V_SF | int16 | Voltage SF |
+| 15 | W_SF | int16 | Power SF |
+| 17 | Hz_SF | int16 | Frequency SF |
+| 19 | VA_SF | int16 | Apparent power SF |
+| 21 | VAr_SF | int16 | Reactive power SF |
+| 23 | PF_SF | int16 | Power factor SF |
+| 26 | WH_SF | int16 | Energy SF |
+| 28 | DCA_SF | int16 | DC current SF |
+| 29 | DCV_SF | int16 | DC voltage SF |
+| 31 | DCW_SF | int16 | DC power SF |
+| 36 | Tmp_SF | int16 | Temperature SF |
+
+### Data Registers
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 2 | A | uint16 | A_SF | Total AC current (A) |
+| 3 | AphA | uint16 | A_SF | Phase A current (A) |
+| 4 | AphB | uint16 | A_SF | Phase B current (A) |
+| 5 | AphC | uint16 | A_SF | Phase C current (A) |
+| 7 | PPVphAB | uint16 | V_SF | Line voltage AB (V) |
+| 8 | PPVphBC | uint16 | V_SF | Line voltage BC (V) |
+| 9 | PPVphCA | uint16 | V_SF | Line voltage CA (V) |
+| 10 | PhVphA | uint16 | V_SF | Phase voltage AN (V) |
+| 11 | PhVphB | uint16 | V_SF | Phase voltage BN (V) |
+| 12 | PhVphC | uint16 | V_SF | Phase voltage CN (V) |
+| 14 | W | int16 | W_SF | AC power (W) |
+| 16 | Hz | uint16 | Hz_SF | Frequency (Hz) |
+| 18 | VA | uint16 | VA_SF | Apparent power (VA) |
+| 20 | VAr | int16 | VAr_SF | Reactive power (VAr) |
+| 22 | PF | int16 | PF_SF | Power factor |
+| 24–25 | WH | acc32 | WH_SF | Cumulative energy (Wh) |
+| 27 | DCA | uint16 | DCA_SF | DC current (A) |
+| 28 | DCV | uint16 | DCV_SF | DC voltage (V) |
+| 30 | DCW | int16 | DCW_SF | DC power (W) |
+| 32 | TmpCab | int16 | Tmp_SF | Cabinet temperature (°C) |
+| 34 | TmpSnk | int16 | Tmp_SF | Heat sink temperature (°C) |
+| 35 | TmpTrns | int16 | Tmp_SF | Transformer temperature (°C) |
+| 36 | TmpOt | int16 | Tmp_SF | Other temperature (°C) |
+| 38 | St | uint16 | — | Operating state (enum) |
+| 39 | StVnd | uint16 | — | Vendor-specific state |
+| 40–41 | Evt1 | bitfield32 | — | Event flags 1 |
+| 42–43 | Evt2 | bitfield32 | — | Event flags 2 |
+| 44–45 | EvtVnd1 | bitfield32 | — | Vendor events 1 |
+| 46–47 | EvtVnd2 | bitfield32 | — | Vendor events 2 |
+| 48–49 | EvtVnd3 | bitfield32 | — | Vendor events 3 |
+| 50–51 | EvtVnd4 | bitfield32 | — | Vendor events 4 |
+
+---
+
+## Model 121 — Inverter Settings
+
+**Method:** `readInverterSettings()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 22 | WMax_SF | int16 | Power SF |
+| 23 | VRef_SF | int16 | Voltage reference SF |
+| 24 | VRefOfs_SF | int16 | Voltage offset SF |
+| 25 | VMinMax_SF | int16 | Min/max voltage SF |
+| 26 | VAMax_SF | int16 | Apparent power SF |
+| 27 | VArMax_SF | int16 | Reactive power SF |
+| 28 | WGra_SF | int16 | Ramp rate SF |
+| 29 | PFMin_SF | int16 | Power factor SF |
+| 30 | MaxRmpRte_SF | int16 | Max ramp rate SF |
+| 31 | ECPNomHz_SF | int16 | Frequency SF |
+
+### Data Registers
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 2 | WMax | uint16 | WMax_SF | Maximum power output (W) |
+| 3 | VRef | uint16 | VRef_SF | Voltage at PCC (V) |
+| 4 | VRefOfs | int16 | VRefOfs_SF | Voltage offset from PCC (V) |
+| 5 | VMax | uint16 | VMinMax_SF | Maximum voltage (V) |
+| 6 | VMin | uint16 | VMinMax_SF | Minimum voltage (V) |
+| 7 | VAMax | uint16 | VAMax_SF | Maximum apparent power (VA) |
+| 8 | VArMaxQ1 | int16 | VArMax_SF | Max reactive power Q1 (VAr) |
+| 9 | VArMaxQ2 | int16 | VArMax_SF | Max reactive power Q2 (VAr) |
+| 10 | VArMaxQ3 | int16 | VArMax_SF | Max reactive power Q3 (VAr) |
+| 11 | VArMaxQ4 | int16 | VArMax_SF | Max reactive power Q4 (VAr) |
+| 12 | WGra | uint16 | WGra_SF | Default ramp rate (%WMax/sec) |
+| 13 | PFMinQ1 | int16 | PFMin_SF | Min power factor Q1 |
+| 14 | PFMinQ2 | int16 | PFMin_SF | Min power factor Q2 |
+| 15 | PFMinQ3 | int16 | PFMin_SF | Min power factor Q3 |
+| 16 | PFMinQ4 | int16 | PFMin_SF | Min power factor Q4 |
+| 17 | VArAct | enum16 | — | VAR action on mode change |
+| 18 | ClcTotVA | enum16 | — | Total VA calculation method |
+| 19 | MaxRmpRte | uint16 | MaxRmpRte_SF | Maximum ramp rate (%WGra) |
+| 20 | ECPNomHz | uint16 | ECPNomHz_SF | Nominal frequency (Hz) |
+| 21 | ConnPh | enum16 | — | Connected phase (single phase) |
+
+---
+
+## Model 123 — Inverter Controls
+
+**Method:** `readInverterControls()` / `writeInverterControls()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 21 | WMaxLimPct_SF | int16 | Power limit SF |
+| 22 | OutPFSet_SF | int16 | Power factor SF |
+| 23 | VArPct_SF | int16 | VAR percentage SF |
+
+### Connection Control
+
+| Offset | Field | Type | R/W | Description |
+|--------|-------|------|-----|-------------|
+| 0 | Conn_WinTms | uint16 | R | Time window for connect/disconnect (sec) |
+| 1 | Conn_RvrtTms | uint16 | R | Timeout for connect/disconnect (sec) |
+| 2 | Conn | enum16 | **W** | Connect/disconnect (0=DISCONNECT, 1=CONNECT) |
+
+### Power Limit Control
+
+| Offset | Field | Type | R/W | SF | Description |
+|--------|-------|------|-----|----|-------------|
+| 3 | WMaxLimPct | uint16 | **W** | WMaxLimPct_SF | Power limit (%WMax) |
+| 4 | WMaxLimPct_WinTms | uint16 | R | — | Time window (sec) |
+| 5 | WMaxLimPct_RvrtTms | uint16 | R | — | Timeout (sec) |
+| 6 | WMaxLimPct_RmpTms | uint16 | R | — | Ramp time (sec) |
+| 7 | WMaxLim_Ena | enum16 | **W** | — | Enable (0=DISABLED, 1=ENABLED) |
+
+### Power Factor Control
+
+| Offset | Field | Type | R/W | SF | Description |
+|--------|-------|------|-----|----|-------------|
+| 8 | OutPFSet | int16 | **W** | OutPFSet_SF | Power factor setpoint |
+| 9 | OutPFSet_WinTms | uint16 | R | — | Time window (sec) |
+| 10 | OutPFSet_RvrtTms | uint16 | R | — | Timeout (sec) |
+| 11 | OutPFSet_RmpTms | uint16 | R | — | Ramp time (sec) |
+| 12 | OutPFSet_Ena | enum16 | **W** | — | Enable (0=DISABLED, 1=ENABLED) |
+
+### Reactive Power Control
+
+| Offset | Field | Type | R/W | SF | Description |
+|--------|-------|------|-----|----|-------------|
+| 13 | VArWMaxPct | int16 | R | VArPct_SF | Reactive power at max W (%) |
+| 14 | VArMaxPct | int16 | R | VArPct_SF | Max reactive power (%) |
+| 15 | VArAvalPct | int16 | R | VArPct_SF | Available reactive power (%) |
+| 16 | VArPct_WinTms | uint16 | R | — | Time window (sec) |
+| 17 | VArPct_RvrtTms | uint16 | R | — | Timeout (sec) |
+| 18 | VArPct_RmpTms | uint16 | R | — | Ramp time (sec) |
+| 19 | VArPct_Mod | enum16 | R | — | Mode (0=NONE, 1=WMAX, 2=VARMAX) |
+| 20 | VArPct_Ena | enum16 | R | — | Enable (0=DISABLED, 1=ENABLED) |
+
+---
+
+## Model 124 — Battery Basic Storage Controls
+
+**Method:** `readBatteryData()` / `writeBatteryControls()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 18 | WChaMax_SF | int16 | Max charge power SF |
+| 19 | WChaDisChaGra_SF | int16 | Charge/discharge gradient SF |
+| 20 | VAChaMax_SF | int16 | Max charging VA SF |
+| 21 | MinRsvPct_SF | int16 | Min reserve percentage SF |
+| 22 | ChaState_SF | int16 | Charge state SF |
+| 23 | StorAval_SF | int16 | Available storage SF |
+| 24 | InBatV_SF | int16 | Battery voltage SF |
+| 25 | InOutWRte_SF | int16 | Charge/discharge rate SF |
+
+### Data Registers
+
+| Offset | Field | Type | R/W | SF | Description |
+|--------|-------|------|-----|----|-------------|
+| 2 | WChaMax | uint16 | **W** | WChaMax_SF | Max charge power (W) |
+| 3 | WChaGra | uint16 | R | WChaDisChaGra_SF | Charge rate gradient (%/sec) |
+| 4 | WDisChaGra | uint16 | R | WChaDisChaGra_SF | Discharge rate gradient (%/sec) |
+| 5 | StorCtlMod | bitfield16 | **W** | — | Storage control mode (see enum) |
+| 6 | VAChaMax | uint16 | R | VAChaMax_SF | Max charging VA |
+| 7 | MinRsvPct | uint16 | **W** | MinRsvPct_SF | Min reserve (%) |
+| 8 | ChaState | uint16 | R | ChaState_SF | State of charge (%AhrRtg) |
+| 9 | StorAval | uint16 | R | StorAval_SF | Available storage (AH) |
+| 10 | InBatV | uint16 | R | InBatV_SF | Battery voltage (V) |
+| 11 | ChaSt | enum16 | R | — | Charge status (see enum) |
+| 12 | OutWRte | int16 | **W** | InOutWRte_SF | Discharge rate (%WDisChaMax) |
+| 13 | InWRte | int16 | **W** | InOutWRte_SF | Charge rate (%WChaMax) |
+| 14 | InOutWRteWinTms | uint16 | R | — | Rate change time window (sec) |
+| 15 | InOutWRteRvrtTms | uint16 | R | — | Rate change timeout (sec) |
+| 16 | InOutWRteRmpTms | uint16 | R | — | Rate change ramp time (sec) |
+| 17 | ChaGriSet | enum16 | **W** | — | Charge source (0=PV, 1=GRID) |
+
+---
+
+## Model 160 — MPPT (Multiple Maximum Power Point Tracker)
+
+**Method:** `readAllMPPTData()` / `readMPPTData(moduleId)`
+
+### Fixed Block (Scale Factors)
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 2 | DCA_SF | int16 | DC current SF |
+| 3 | DCV_SF | int16 | DC voltage SF |
+| 4 | DCW_SF | int16 | DC power SF |
+| 5 | DCWH_SF | int16 | DC energy SF |
+| 8 | N | uint16 | Number of MPPT modules |
+
+### Repeating Module Block (20 registers each)
+
+Module 1 starts at offset **10**, Module 2 at offset **30**, Module N at offset `10 + (N-1) × 20`.
+
+| Relative Offset | Field | Type | SF | Description |
+|-----------------|-------|------|----|-------------|
+| 0 | ID | uint16 | — | Module ID |
+| 1–8 | IDStr | string (8 regs) | — | Module string identifier |
+| 9 | DCA | uint16 | DCA_SF | DC current (A) |
+| 10 | DCV | uint16 | DCV_SF | DC voltage (V) |
+| 11 | DCW | uint16 | DCW_SF | DC power (W) |
+| 12–13 | DCWH | acc32 | DCWH_SF | Cumulative DC energy (Wh) |
+| 14–15 | Tms | uint32 | — | Timestamp (seconds since epoch) |
+| 16 | Tmp | int16 | fixed (−1) | Module temperature (°C) |
+| 17 | DCSt | enum16 | — | Operating state |
+
+---
+
+## Models 201/203/204 — Meters
+
+**Method:** `readMeterData()`
+
+The SDK reads Model 203 (3-Phase Delta), 204 (3-Phase Wye), or 201 (Single-Phase) — trying in that order. All three share the same register offsets for the fields we read:
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 17 | Hz_SF | int16 | Frequency SF |
+| 22 | W_SF | int16 | Power SF |
+| 54 | TotWh_SF | int16 | Energy SF |
+
+### Data Registers
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 16 | Hz | uint16 | Hz_SF | Frequency (Hz) |
+| 18 | W | int16 | W_SF | Total real power (W) |
+| 38–39 | TotWhExp | acc32 | TotWh_SF | Total exported energy (Wh) |
+| 46–47 | TotWhImp | acc32 | TotWh_SF | Total imported energy (Wh) |
+
+---
+
+## Model 802 — Battery Base
+
+**Method:** `readBatteryBaseData()`
+
+### Scale Factors
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 52 | AHRtg_SF | int16 | Amp-hour rating SF |
+| 53 | WHRtg_SF | int16 | Watt-hour rating SF |
+| 54 | WChaDisChaMax_SF | int16 | Charge/discharge max rate SF |
+| 55 | DisChaRte_SF | int16 | Self-discharge rate SF |
+| 56 | SoC_SF | int16 | State of charge SF |
+| 57 | DoD_SF | int16 | Depth of discharge SF |
+| 58 | SoH_SF | int16 | State of health SF |
+| 59 | V_SF | int16 | Voltage SF |
+| 60 | CellV_SF | int16 | Cell voltage SF |
+| 61 | A_SF | int16 | Current SF |
+| 62 | AMax_SF | int16 | Max current SF |
+| 63 | W_SF | int16 | Power SF |
+
+### Nameplate (Offsets 2–5)
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 2 | AHRtg | uint16 | AHRtg_SF | Nameplate charge capacity (AH) |
+| 3 | WHRtg | uint16 | WHRtg_SF | Nameplate energy capacity (WH) |
+| 4 | WChaRteMax | uint16 | WChaDisChaMax_SF | Max charge rate (W) |
+| 5 | WDisChaRteMax | uint16 | WChaDisChaMax_SF | Max discharge rate (W) |
+
+### State of Charge / Health (Offsets 6–13)
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 6 | DisChaRte | uint16 | DisChaRte_SF | Self-discharge rate (%) |
+| 7 | SoCMax | uint16 | SoC_SF | Max state of charge (%) |
+| 8 | SoCMin | uint16 | SoC_SF | Min state of charge (%) |
+| 9 | SoCRsvMax | uint16 | SoC_SF | Max reserve SOC (%) |
+| 10 | SoCRsvMin | uint16 | SoC_SF | Min reserve SOC (%) |
+| 11 | SoC | uint16 | SoC_SF | Current state of charge (%) |
+| 12 | DoD | uint16 | DoD_SF | Depth of discharge (%) |
+| 13 | SoH | uint16 | SoH_SF | State of health (%) |
+
+### Status (Offsets 14–22)
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 14–15 | NCyc | uint32 | Cycle count |
+| 16 | ChaSt | enum16 | Charge status (see enum) |
+| 17 | LocRemCtl | enum16 | Local/remote control mode |
+| 21 | Typ | enum16 | Battery type (see enum) |
+| 22 | State | enum16 | Battery bank state (see enum) |
+
+### Events (Offsets 26–33)
+
+| Offset | Field | Type | Description |
+|--------|-------|------|-------------|
+| 26–27 | Evt1 | bitfield32 | Event bitfield 1 |
+| 28–29 | Evt2 | bitfield32 | Event bitfield 2 |
+| 30–31 | EvtVnd1 | bitfield32 | Vendor event bitfield 1 |
+| 32–33 | EvtVnd2 | bitfield32 | Vendor event bitfield 2 |
+
+### Voltage (Offsets 34–43)
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 34 | V | uint16 | V_SF | Battery voltage (V) |
+| 35 | VMax | uint16 | V_SF | Max battery voltage (V) |
+| 36 | VMin | uint16 | V_SF | Min battery voltage (V) |
+| 37 | CellVMax | uint16 | CellV_SF | Max cell voltage (V) |
+| 38 | CellVMaxStr | uint16 | — | String containing max cell |
+| 39 | CellVMaxMod | uint16 | — | Module containing max cell |
+| 40 | CellVMin | uint16 | CellV_SF | Min cell voltage (V) |
+| 41 | CellVMinStr | uint16 | — | String containing min cell |
+| 42 | CellVMinMod | uint16 | — | Module containing min cell |
+| 43 | CellVAvg | uint16 | CellV_SF | Average cell voltage (V) |
+
+### Current (Offsets 44–46)
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 44 | A | int16 | A_SF | Battery current (A) |
+| 45 | AChaMax | uint16 | AMax_SF | Max charge current (A) |
+| 46 | ADisChaMax | uint16 | AMax_SF | Max discharge current (A) |
+
+### Power / Control (Offsets 47–51)
+
+| Offset | Field | Type | SF | Description |
+|--------|-------|------|----|-------------|
+| 47 | W | int16 | W_SF | Battery power (W, +charge/−discharge) |
+| 48 | ReqInvState | enum16 | — | Requested inverter state |
+| 49 | ReqW | int16 | W_SF | Requested power (W) |
+| 50 | SetOp | enum16 | — | Set operation |
+| 51 | SetInvState | enum16 | — | Set inverter state |
+
+---
+
+## Writable Registers
+
+### Model 123 — Inverter Controls (`writeInverterControls`)
+
+| Register Offset | Field | Scale Factor Offset | Description |
+|----------------|-------|---------------------|-------------|
+| 2 | Conn | — | Connect/disconnect |
+| 3 | WMaxLimPct | 21 (WMaxLimPct_SF) | Power limit percentage |
+| 7 | WMaxLim_Ena | — | Throttle enable/disable |
+| 8 | OutPFSet | 22 (OutPFSet_SF) | Power factor setpoint |
+| 12 | OutPFSet_Ena | — | PF control enable/disable |
+
+### Model 124 — Battery Controls (`writeBatteryControls`)
+
+| Register Offset | Field | Scale Factor Offset | Description |
+|----------------|-------|---------------------|-------------|
+| 2 | WChaMax | 18 (WChaMax_SF) | Max charge power (W) |
+| 5 | StorCtlMod | — | Storage control mode bits |
+| 7 | MinRsvPct | 21 (MinRsvPct_SF) | Min reserve percentage |
+| 12 | OutWRte | 25 (InOutWRte_SF) | Discharge rate (%) |
+| 13 | InWRte | 25 (InOutWRte_SF) | Charge rate (%) |
+| 17 | ChaGriSet | — | Charge source (PV/Grid) |
+
+### Helper: `setFeedInLimit(limitW)`
+
+Reads `WMax` from Model 121, computes `(limitW / WMax) × 100`, then writes `WMaxLimPct` + enables `WMaxLim_Ena` via Model 123. Pass `null` to disable the limit.
+
+### Helper: `setStorageMode(mode)` / `enableGridCharging(enable)`
+
+Convenience wrappers around `writeBatteryControls()` for common battery operations.
+
+---
+
+## Enum Reference
+
+### SunspecBatteryChargeState (Model 124 offset 11 / Model 802 offset 16)
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 1 | OFF | Battery off |
+| 2 | EMPTY | Battery empty |
+| 3 | DISCHARGING | Discharging |
+| 4 | CHARGING | Charging |
+| 5 | FULL | Fully charged |
+| 6 | HOLDING | Holding charge |
+| 7 | TESTING | Under test |
+
+### SunspecStorageControlMode (Model 124 offset 5 — bitfield)
+
+| Bit | Value | Name | Description |
+|-----|-------|------|-------------|
+| 0 | 0x0001 | CHARGE | Enable charging |
+| 1 | 0x0002 | DISCHARGE | Enable discharging |
+
+**Derived modes via `setStorageMode()`:**
+
+| Mode | Bits | Description |
+|------|------|-------------|
+| CHARGE | 0x01 | Charge only |
+| DISCHARGE | 0x02 | Discharge only |
+| HOLDING | 0x00 | Neither charge nor discharge |
+| AUTO | 0x03 | Both charge and discharge |
+
+### SunspecChargeSource (Model 124 offset 17)
+
+| Value | Name | Description |
+|-------|------|-------------|
+| 0 | PV | Charge from PV only |
+| 1 | GRID | Charge from grid |
+
+### SunspecEnableControl (Model 123 — various enable fields)
+
+| Value | Name |
+|-------|------|
+| 0 | DISABLED |
+| 1 | ENABLED |
+
+### SunspecBatteryType (Model 802 offset 21)
+
+| Value | Name |
+|-------|------|
+| 0 | NOT_APPLICABLE_UNKNOWN |
+| 1 | LEAD_ACID |
+| 2 | NICKEL_METAL_HYDRIDE |
+| 3 | NICKEL_CADMIUM |
+| 4 | LITHIUM_ION |
+| 5 | CARBON_ZINC |
+| 6 | ZINC_CHLORIDE |
+| 7 | ALKALINE |
+| 8 | RECHARGEABLE_ALKALINE |
+| 9 | SODIUM_SULFUR |
+| 10 | FLOW |
+| 11 | SUPER_CAPACITOR |
+| 99 | OTHER |
+
+### SunspecBatteryBankState (Model 802 offset 22)
+
+| Value | Name |
+|-------|------|
+| 1 | DISCONNECTED |
+| 2 | INITIALIZING |
+| 3 | CONNECTED |
+| 4 | STANDBY |
+| 5 | SOC_PROTECTION |
+| 6 | SUSPENDING |
+| 99 | FAULT |