# Modbus Interface ## Overview This document describes the Modbus TCP/IP interface for controlling the LED strips and SMC buttons of SEHx01/SEH11 devices. The Modbus interface operates in parallel with the existing MQTT control. Both interfaces can be used simultaneously. ## Physical Interface

Parameter	Value
Protocol	Modbus
Interface	TCP/IP
Device ID	1 (configurable)

## Register Overview ### Holding Registers (Function 03/06/16) The controller supports 5 LED strips (LED_STRIP_1 through LED_STRIP_5). Each strip can contain multiple segments. Up to 8 segments per strip are configurable. Each segment supports up to 3 colors. #### Global Registers

Register	Description	Data Type	Range	R/W
0	Modbus Device ID	UINT16	1-247	R/W
2	Apply/Trigger	UINT16	0/1	W
3	Reserved	-	-	-
4	Reserved	-	-	-

**Apply/Trigger (Register 2):** After writing all desired strip/segment registers, register 2 must be set to `1` to apply the changes. The register is automatically reset to `0` after the changes are applied. --- #### Strip Registers Each strip occupies a block of 100 registers. The base address for strip N (N = 1..5) is calculated as: **Base Address = 100 \* N**

Offset	Description	Data Type	Range	R/W
0	Active	UINT16	0/1	R/W
1	Segment Count	UINT16	0-8	R/W
2-9	Reserved	-	-	-

#### Segment Registers Within a strip block, each segment occupies 11 registers. The base address for segment M (M = 0..7) within strip N is: **Segment Base Address = (100 _ N) + 10 + (M _ 11)**

Offset	Description	Data Type	Range	R/W
0	StartLED	UINT16	0-311	R/W
1	StopLED	UINT16	0-311	R/W
2	Effect	UINT16	see Effects	R/W
3	Speed	UINT16	1-246	R/W
4	Color 1 - Red	UINT16	0-255	R/W
5	Color 1 - Green	UINT16	0-255	R/W
6	Color 1 - Blue	UINT16	0-255	R/W
7	Color 2 - Red	UINT16	0-255	R/W
8	Color 2 - Green	UINT16	0-255	R/W
9	Color 2 - Blue	UINT16	0-255	R/W
10	Color 3 - Red	UINT16	0-255	R/W
11	Color 3 - Green	UINT16	0-255	R/W
12	Color 3 - Blue	UINT16	0-255	R/W

--- ### SMC Button Control (Holding Registers) In addition to the LED strips, the connected SMC buttons can also be controlled via Modbus. This corresponds to the existing MQTT control (topic `/Set/Data/Smc`). Both paths internally generate the same SMC command and can be used in parallel. The SMC block occupies a dedicated register range starting at base address **1000** and has its **own Apply trigger**, independent of the LED Apply (register 2).

Register	Description	Data Type	Range	R/W
1000	SMC Address	UINT16	see below	R/W
1001	SMC CommandType	UINT16	0-2 (see below)	R/W
1002	SMC Offset	UINT16	0-5 (see below)	R/W
1003	Button Mode	UINT16	0-2	R/W
1004	Quantity	UINT16	0-65535	R/W
1005	Color	UINT16	0-7	R/W
1006	Ring Effect	UINT16	see Ring Effects	R/W
1007	Text char 0	UINT16	0-255 (ASCII)	R/W
1008	Text char 1	UINT16	0-255 (ASCII)	R/W
1009	Text char 2	UINT16	0-255 (ASCII)	R/W
1010	Text char 3	UINT16	0-255 (ASCII)	R/W
1011	Special Command	UINT16	see Special Commands	R/W
1012	Button Rotation	UINT16	0-1	R/W
1013	Assign Address	UINT16	see below	R/W
1014-1019	Reserved	-	-	-
1020	SMC Apply/Trigger	UINT16	0/1	W
1100-1228	Hub Polling Channels	UINT16	see below	R/W

Following the MQTT protocol, `CommandType` (register 1001) and `Offset` (register 1002) are kept as two separate fields. Together they select which payload registers are evaluated on Apply. The hub polling channels occupy a separate block (registers 1100-1228), described further below. **SMC Address (Register 1000):** Target address of the command.

Value	Meaning
0	HUB (SEH itself)
0xFFFF	ALL_SENSORS (broadcast to all buttons)
other	Specific button address (device address)

**SMC CommandType (Register 1001):** Mirrors the `CommandType` field of the MQTT protocol.

Value	CommandType
0	- (idle, nothing sent)
1	SET_PARAMETER
2	SET_STATUS

_The SMC protocol additionally defines GET_STATUS, SET_UPDATE, GET_INTERNAL_STATUS and SET_INTERNAL_STATUS. These are not yet mapped and can be added later._ **SMC Offset (Register 1002):** Mirrors the `Offset` field of the MQTT protocol.

Value	Offset
0	(none / empty)
1	PRE_BUTTON_MODE
2	POST_BUTTON_MODE
3	BUTTON_ROTATE
4	SPECIAL_COMMANDS
5	ADDRESS_TO_BE_ASSIGNED

**Valid combinations:** On Apply, `CommandType` and `Offset` together determine which payload registers are evaluated.

CommandType	Offset	Address	Payload registers
SET_PARAMETER	PRE_BUTTON_MODE	any	Button Mode, Quantity, Color, Ring Effect, Text (1003-1010)
SET_PARAMETER	POST_BUTTON_MODE	any	Button Mode, Quantity, Color, Ring Effect, Text (1003-1010)
SET_PARAMETER	BUTTON_ROTATE	any	Button Rotation (1012)
SET_PARAMETER	(none)	HUB (0)	Hub Polling Channels (1100-1228)
SET_STATUS	SPECIAL_COMMANDS	any	Special Command (1011)
SET_STATUS	ADDRESS_TO_BE_ASSIGNED	any	Assign Address (1013)

**Button Mode (Register 1003):**

Value	Meaning
0	DISABLED
1	ENABLED
2	LONGPRESS_ENABLED

**Color (Register 1005):**

Value	Meaning	Value	Meaning
0	COLOFF	4	COLYELLOW
1	COLRED	5	COLMAGENTA
2	COLGREEN	6	COLCYAN
3	COLBLUE	7	COLWHITE

**Ring Effect (Register 1006):**

Value	Meaning	Value	Meaning
0	SOLID_RING	94	ANIMATED_ARROW_UP
1	FLASH_RING	95	ANIMATED_ARROW_DOWN
2	CONFIRM	96	ANIMATED_ARROW_LEFT
84	POINT_ANIMATED_CLOCK	97	ANIMATED_ARROW_RIGHT
85	CIRCLE_ANIMATED_CLOCK	102	SOLID_ARROW_UP_LEFT
86	SOLID_ARROW_UP	103	SOLID_ARROW_UP_RIGHT
87	SOLID_ARROW_DOWN	104	SOLID_ARROW_DOWN_LEFT
88	SOLID_ARROW_LEFT	105	SOLID_ARROW_DOWN_RIGHT
89	SOLID_ARROW_RIGHT	106	FLASH_ARROW_UP_LEFT
90	FLASH_ARROW_UP	107	FLASH_ARROW_UP_RIGHT
91	FLASH_ARROW_DOWN	108	FLASH_ARROW_DOWN_LEFT
92	FLASH_ARROW_LEFT	109	FLASH_ARROW_DOWN_RIGHT
93	FLASH_ARROW_RIGHT

**Special Command (Register 1011):** Only effective when CommandType = SET_STATUS and Offset = SPECIAL_COMMANDS.

Value	Meaning
0	PRE_PRESSED_STATE
1	POST_PRESSED_STATE
2	REBOOT
4	SHOW_CURRENT_ADDRESS
5	SELF_TRIGGER
6	LONG_PRESSED_STATE

**Text (Register 1007-1010):** Up to 4 ASCII characters for the button display, one character per register (register 1007 = first character). The character is stored in the low byte; the high byte is ignored. Unused characters (value `0`) are internally padded with `@`. Only relevant for ring effects with text display. **Button Rotation (Register 1012):** Only effective when CommandType = SET_PARAMETER and Offset = BUTTON_ROTATE. Sets the display/button orientation.

Value	Meaning
0	BUTTON_ROTATION_NORMAL
1	BUTTON_ROTATION_UPSIDEDOWN

**Assign Address (Register 1013):** Only effective when CommandType = SET_STATUS and Offset = ADDRESS_TO_BE_ASSIGNED. Assigns a device address to the addressed button(s).

Value	Meaning
0	NEXT (auto-assign next free address)
other	Explicit device address to assign

**Hub Polling Channels (Register 1100-1228):** Only effective when CommandType = SET_PARAMETER, Offset = (none) and Address = HUB (0). Defines which button addresses the HUB (SEH) actively polls. Up to **128** addresses are supported.

Register	Description	Data Type	Range
1100	Polling Channel Count	UINT16	0-128
1101	Polling Channel 0	UINT16	button address
1102	Polling Channel 1	UINT16	button address
...	...	...	...
1228	Polling Channel 127	UINT16	button address

Polling channel K is located at register `1101 + K` (K = 0..127). Register 1100 holds the number of valid channels. As a single Modbus request is limited to ~123 registers, a long channel list must be written in multiple Function-16 requests before setting the Apply trigger (register 1020). The maximum number of polling addresses that can actually be used is product-dependent and may be lower than the 128 registers reserved here. **SMC Apply/Trigger (Register 1020):** After writing the SMC registers, register 1020 must be set to `1` to send the command to the buttons. The register is automatically reset to `0`. The SMC Apply is independent of the LED Apply (register 2). --- ### Input Registers (Function 04) - Status/Read-Only

Register	Description	Data Type	Range
0	Firmware Version Major	UINT16	0-255
1	Firmware Version Minor	UINT16	0-255
2	Firmware Version Patch	UINT16	0-255
3	Number of Configured Strips	UINT16	0-5
4	Strip 1 - Length (LEDs)	UINT16	0-312
5	Strip 2 - Length (LEDs)	UINT16	0-312
6	Strip 3 - Length (LEDs)	UINT16	0-312
7	Strip 4 - Length (LEDs)	UINT16	0-312
8	Strip 5 - Length (LEDs)	UINT16	0-312
9	Power Supply Limit (W×10)	UINT16	0-65535
10	Total Active LEDs	UINT16	0-65535
11	Error Code	UINT16	0-4

**Error Codes:**

Code	Meaning
0	No error
1	No network
2	No MQTT connection
3	No configuration
4	Normal operation

--- ### SMC Button Status (Input Registers) The states of the connected SMC buttons can be read back via input registers. This corresponds to the button feedback published over MQTT on `/Pub/Data/Smc`. The SMC status range starts at input register address **100**. Because Modbus has no server-initiated push, status changes must be detected by polling (see also the Notes section). To avoid reading the full status block cyclically, the **SMC Event Counter** is provided. #### SMC Event Counter

Register	Description	Data Type	Range
100	SMC Event Counter	UINT16	0-65535

The counter is incremented on every SMC button status change and wraps around at 65535. A client can poll this single register cheaply and only re-read the button status blocks when the value has changed. Registers 101-109 are reserved. #### Button Status Registers The number of mapped buttons equals `MAX_SMC_COUNT`. This value depends on the build target (e.g. 5 for standard variants, up to 128 for certain devices). Each button occupies a block of 4 registers. The base address for button K (K = 0 .. MAX_SMC_COUNT-1) is calculated as: **Button Base Address = 110 + (K \* 4)**

Offset	Description	Data Type	Range
0	Button Address	UINT16	0-65535
1	Press Count	UINT16	0-65535
2	Press State	UINT16	see below
3	Reserved	-	-

A Button Address of `0` indicates an unused/empty slot. **Press State (Offset 2):**

Value	Meaning
0	PRE_PRESSED_STATE
1	POST_PRESSED_STATE
3	LONGPRESS_STATE

Button	Address	Press Count	Press State
0	110	111	112
1	114	115	116
2	118	119	120
...	...	...	...
K	110 + K×4	111 + K×4	112 + K×4

--- ## Available LED Effects

Effect ID	Name	Description
1	Static	All LEDs lit at constant color
2	Blink	On/off blinking
3	Flash	Quick bright pulses
4	Leading Lines	Running lines forward
5	Leading Lines Reverse	Running lines backward
6	Multipicker	Cycling through multiple colors
7	Pick	Animation from center outward
8	Place	Animation from outside to center
200	Knight Rider	Bouncing bar animation

## Register Mapping - Example ### Activate Strip 1, Segment 0 (green, static) The following registers must be written (Function 16 - Write Multiple Registers):

Register	Value	Description
100	1	Strip 1 Active = true
101	1	Strip 1 Segment Count = 1
110	0	Segment 0: StartLED = 0
111	20	Segment 0: StopLED = 20
112	1	Segment 0: Effect = Static
113	200	Segment 0: Speed = 200
114	0	Segment 0: Color1 R = 0
115	150	Segment 0: Color1 G = 150
116	0	Segment 0: Color1 B = 0
117	0	Segment 0: Color2 R = 0
118	0	Segment 0: Color2 G = 0
119	0	Segment 0: Color2 B = 0
120	0	Segment 0: Color3 R = 0
121	0	Segment 0: Color3 G = 0
122	0	Segment 0: Color3 B = 0
2	1	Apply/Trigger

This corresponds to the following MQTT message: ```json { "LED_STRIP_1": { "Active": true, "Segments": [ { "StartLED": 0, "StopLED": 20, "Effect": 1, "Speed": 200, "Colors": [{ "R": 0, "G": 150, "B": 0 }] } ] } } ``` ### SMC Button: Set PRE_BUTTON_MODE (all buttons, green, flashing ring) The following registers must be written (Function 16 - Write Multiple Registers):

Register	Value	Description
1000	0xFFFF	Address = ALL_SENSORS (broadcast)
1001	1	CommandType = SET_PARAMETER
1002	1	Offset = PRE_BUTTON_MODE
1003	1	Button Mode = ENABLED
1004	5	Quantity = 5
1005	2	Color = COLGREEN
1006	1	Ring Effect = FLASH_RING
1020	1	SMC Apply/Trigger

This corresponds to the following MQTT message: ```json { "Address": "ALL_SENSORS", "CommandType": "SET_PARAMETER", "Offset": "PRE_BUTTON_MODE", "Payload": "ENABLED/5/COLGREEN/FLASH_RING/@@@@" } ``` ### SMC Button: Trigger Special Command (PRE_PRESSED_STATE, all buttons)

Register	Value	Description
1000	0xFFFF	Address = ALL_SENSORS (broadcast)
1001	2	CommandType = SET_STATUS
1002	4	Offset = SPECIAL_COMMANDS
1011	0	Special Command = PRE_PRESSED_STATE
1020	1	SMC Apply/Trigger

This corresponds to the following MQTT message: ```json { "Address": "ALL_SENSORS", "CommandType": "SET_STATUS", "Offset": "SPECIAL_COMMANDS", "Payload": "PRE_PRESSED_STATE" } ``` ### SMC Button: Set Button Rotation (all buttons, upside down)

Register	Value	Description
1000	0xFFFF	Address = ALL_SENSORS (broadcast)
1001	1	CommandType = SET_PARAMETER
1002	3	Offset = BUTTON_ROTATE
1012	1	Button Rotation = BUTTON_ROTATION_UPSIDEDOWN
1020	1	SMC Apply/Trigger

This corresponds to the following MQTT message: ```json { "Address": "ALL_SENSORS", "CommandType": "SET_PARAMETER", "Offset": "BUTTON_ROTATE", "Payload": "BUTTON_ROTATION_UPSIDEDOWN" } ``` ### SMC Button: Assign Address (all buttons, address 0x1000)

Register	Value	Description
1000	0xFFFF	Address = ALL_SENSORS (broadcast)
1001	2	CommandType = SET_STATUS
1002	5	Offset = ADDRESS_TO_BE_ASSIGNED
1013	0x1000	Assign Address = 0x1000
1020	1	SMC Apply/Trigger

This corresponds to the following MQTT message: ```json { "Address": "ALL_SENSORS", "CommandType": "SET_STATUS", "Offset": "ADDRESS_TO_BE_ASSIGNED", "Payload": "1000" } ``` > Set register 1013 to `0` to assign the next free address automatically (MQTT payload `"NEXT"`). ### SMC HUB: Configure Polling Channels (poll buttons 0x1000-0x1003)

Register	Value	Description
1000	0	Address = HUB
1001	1	CommandType = SET_PARAMETER
1002	0	Offset = (none)
1100	4	Polling Channel Count = 4
1101	0x1000	Polling channel 0
1102	0x1001	Polling channel 1
1103	0x1002	Polling channel 2
1104	0x1003	Polling channel 3
1020	1	SMC Apply/Trigger

This corresponds to the following MQTT message: ```json { "Address": "HUB", "CommandType": "SET_PARAMETER", "Offset": "", "Payload": "1000/1001/1002/1003" } ``` ## Address Calculation - Quick Reference ``` Strip N Base Address: 100 * N (N = 1..5) Strip N Active: 100 * N + 0 Strip N Segment Count: 100 * N + 1 Segment M Base Address: 100 * N + 10 + (M * 11) (M = 0..7) SMC block (holding): selector 1000-1002, payload 1003-1013, Apply = 1020 SMC hub polling (holding): count 1100, channel K = 1101 + K (K = 0..127) SMC event counter (input): 100 SMC status (input): button K base = 110 + (K * 4) (K = 0 .. MAX_SMC_COUNT-1) ```

Strip	Active	Seg Count	Seg 0	Seg 1	Seg 2	Seg 3
1	100	101	110	121	132	143
2	200	201	210	221	232	243
3	300	301	310	321	332	343
4	400	401	410	421	432	443
5	500	501	510	521	532	543

## Notes - **Parallel MQTT/Modbus Operation:** Both interfaces write to the same LED strips. The most recently received command (whether MQTT or Modbus) determines the current state. - **Power Limit:** The power limit applies globally. Segments that would exceed the power limit will not be activated (identical behavior to MQTT). - **StopLED >= StartLED:** If StopLED < StartLED, StopLED is automatically set to StartLED. - **Colors:** The sum of R+G+B per color is limited to a maximum of 180 (per-LED current limiting). - **Unused Colors:** Set unused color registers (Color 2, Color 3) to 0/0/0. - **Apply Register:** Changes to strip/segment registers only take effect when `1` is written to register 2 (Apply). This allows atomic configuration of multiple strips/segments. - **SMC Control:** The SMC block (from register 1000) has its own Apply trigger (register 1020), independent of the LED Apply (register 2). LED and SMC commands can thus be triggered separately. - **SMC Parallel to MQTT:** Modbus and MQTT SMC commands internally generate the same SMC command and are placed into the same send queue. The most recently received command determines the button state. - **SMC Addressing:** `0xFFFF` addresses all buttons (broadcast), `0` the HUB (SEH itself), any other value a specific button. - **SMC Status:** The button status input registers (from address 110) reflect the most recently received button feedback. A Button Address of `0` marks an unused slot. - **Status Change Notification:** Modbus has no server-initiated push; the server only answers requests. Status changes are detected by polling the SMC Event Counter (register 100) and re-reading the button blocks when it changed. For true push notifications use the MQTT channel (`/Pub/Data/Smc`), which runs in parallel.