Skip to content

Modbus

This page documents the Modbus register interface exposed by Savee. For configuration instructions, see Settings → Modbus.

Register Allocation

Savee exposes Modbus holding registers in two groups: general registers that exist once per system, and group registers that are repeated for each Modbus-enabled control group.

General Registers

The general registers are defined once, at whatever indexes are configured in the application settings.

HEARTBEAT

Toggles between 1 and 0 on every refresh interval. Used to verify that the Modbus connection is alive. The refresh interval is configured in Settings.

UPTIME

A 32-bit value spread across two consecutive registers, returning the Savee application's uptime in seconds. The register order (Big Endian or Little Endian) is set in Settings.

Warning

Because UPTIME occupies two registers, leave the address immediately following the configured UPTIME index empty.

Group Registers

Each Modbus-enabled group occupies 16 consecutive holding registers, starting at the address configured for that group. Addresses must therefore be spaced at least 16 apart between groups.

Offset Register Direction
0 MODE R/W
1 REGULATION_VALUE R/W
2 AUTOMATION_MIN R/W
3 AUTOMATION_MAX R/W
4 TRANSITION_FROM R/W
5 TRANSITION_TO R/W
6 REQUESTED_VALUE R/W
7–10 RESERVE —
11 POWER_LOW R
12 POWER_HIGH R
13 VALUE R
14 MEASURED_LUX R
15 ERROR R

Register Reference

MODE

Controls the operational state of the group.

Value Meaning
0 Off
1 On
2 Automation — Regulation (lux target)
3 Automation — Transition (lux curve)

Note

  • When MODE = 1, the group can also be turned off by setting REQUESTED_VALUE to 0 without changing MODE.
  • When MODE = 2 or 3, a Modbus-controlled automation is active for the group. It is visible in the group overview but does not appear on the Automations page.

REGULATION_VALUE

Sets the target illumination level in lux for lux-regulated groups.

Active only when MODE = 2.

AUTOMATION_MIN

Sets the minimum lighting intensity (%) that the automation may apply. Valid values: 0, 10, 20, … 100.

Active when MODE = 2 or 3.

AUTOMATION_MAX

Sets the maximum lighting intensity (%) that the automation may apply. Valid values: 0, 10, 20, … 100.

Active when MODE = 2 or 3.

TRANSITION_FROM

Sets the lux level at which the group is set to its minimum intensity (AUTOMATION_MIN).

Active only when MODE = 3.

TRANSITION_TO

Sets the lux level at which the group is set to its maximum intensity (AUTOMATION_MAX).

Active only when MODE = 3.

REQUESTED_VALUE

Sets the group's lighting intensity in percent. Valid values: 0, 10, 20, … 100.

Active only when MODE = 1.

Warning

Only increments of 10 are valid. Any other value (e.g. 12) will trigger an INPUT_OUT_OF_RANGE error.

How REQUESTED_VALUE differs from the value shown in the Savee app

Setting REQUESTED_VALUE to 0 turns the group off, but Savee internally retains the last non-zero value. The app will continue to display the retained value (e.g. 30 %) while the group is off. The VALUE register reflects the same behaviour.

POWER_LOW and POWER_HIGH

Together these two registers form a 32-bit value representing the group's computed total power draw. The register order is set by the Register Order setting (Big Endian or Little Endian).

VALUE

Returns the group's current lighting intensity in percent (0–100). Read-only.

See the note under REQUESTED_VALUE for details on how this value behaves when the group is turned off via REQUESTED_VALUE = 0.

MEASURED_LUX

Returns the average lux reading from all sensors paired to the group. Returns -1 if no sensors are paired or none are reachable.

ERROR

A bitmask of active error codes. The register value is the sum of all active error bits.

Bit Error Code Description
0 NO_API_RESPONSE Modbus received no response from the Savee API.
1 AUTOMATION_ACTIVATION_FAILED Automation could not be activated (e.g. due to a conflict).
2 HAS_DESYNCHRONIZED_CONTROL Group elements are out of sync due to interference.
3 HAS_UNRESPONSIVE_CONTROL One or more elements in the group are offline.
4 HAS_CONTROL_IN_SERVICE_MODE The group contains elements whose gateway is in service mode.
5 INPUT_OUT_OF_RANGE A writable register contains an invalid value (e.g. REQUESTED_VALUE = 12).
6 INVALID_OPERATION_REQUEST Raised when REQUESTED_VALUE is written while an automation is active. Clears after the next HEARTBEAT cycle.
7 VALUE_DESYNCHRONIZED REQUESTED_VALUE and VALUE differ while MODE is not set to an automation mode.

Example

  • ERROR = 32 → binary 0b00100000 → bit 5 set → INPUT_OUT_OF_RANGE
  • ERROR = 40 → binary 0b00101000 → bits 3 and 5 set → HAS_UNRESPONSIVE_CONTROL + INPUT_OUT_OF_RANGE