Modbus Sub-Device

fastbeeAbout 4 min

Modbus Sub-Device

Overview

Modbus sub-device peripherals are used to control external Modbus slave devices via RS485 bus, such as relay modules, PWM controllers, PID controllers, motor drivers, etc. Supports coil write (FC05) and register write (FC06) control protocols.

Supported Peripheral Types

Type	type Value	Description
MODBUS_DEVICE	51	Modbus RS485 sub-device

Communication Method

Physical Layer: RS485 half-duplex
Protocol: Modbus RTU
Control Method: Send commands through the RS485 port configured via UART peripheral

Modbus sub-devices do not occupy GPIO pins (communicate through already configured UART/RS485 ports)

Configuration

Method 1: Web Interface Configuration (Recommended)

Modbus sub-devices also require first confirming Modbus RTU serial parameters, slave address, and baud rate on the communication protocol page.

Area	Field	Example Value / Status
Status Overview	Risk Level	Low
Status Overview	Active Tasks	0
Status Overview	Timeout Rate	0%
Status Overview	Total Polls / Success / Failed / Timeout	0 / 0 / 0 / 0
Basic Config	Enable Modbus RTU	Enabled
Basic Config	Peripheral Config Selection	Select configured RS485/UART peripheral
Basic Config	Transfer Type	Transparent (raw HEX frames)
Basic Config	DE Pin (RS485)	14

Sub-Device Name	Type	Slave Address	Device Info	Enable	Actions
Temp/Humidity	Collection	2	FC04 @0 x2 [2 mappings]	ON	Edit / Map / Delete
PM25-10	Collection	1	FC03 @0 x2 [2 mappings]	ON	Edit / Map / Delete
Weather Louver	Collection	4	FC03 @500 x8 [6 mappings]	ON	Edit / Map / Delete

The peripheral object for Modbus sub-devices only describes "how slave and register mapping works in the system"; the underlying serial port, baud rate, and bus wiring still follow the communication protocol page configuration.

Step 1: Navigate to Peripheral Management Page

Open a browser and navigate to the ESP32 IP address
After logging in, click Peripheral Configuration in the left menu

Step 2: Add Modbus Sub-Device Peripheral

Click the Add Peripheral button

Fill in the configuration:

Field	Value	Description
Peripheral ID	`mb_relay` or `mb_pwm`	Unique identifier
Name	`4-Channel Relay` or `4-Channel PWM Dimming`	Display name
Peripheral Type	Modbus Device (type: 51)	RS485 control
Slave Address	`1` or `2`	Modbus address (1-247)
Channel Count	`4`	Number of relay channels or PWM channels
Control Protocol	Coil(FC05) or Register(FC06)	Based on device type
Device Type	relay or pwm	Relay or PWM

Click Save

Step 3: Verify Configuration

Find the newly added peripheral in the peripheral list
Click the Enable toggle
Use the control panel to test control

⚠️ Important: Modbus devices depend on UART peripherals to provide the RS485 physical channel; UART must be configured first

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

4-Channel Relay Module

{
  "id": "mb_relay",
  "name": "4-Channel Relay",
  "type": 51,
  "enabled": false,
  "pins": [],
  "params": {
    "slaveAddress": 1,
    "channelCount": 4,
    "coilBase": 0,
    "ncMode": false,
    "controlProtocol": 0,
    "deviceType": 0,
    "deviceIndex": 0,
    "batchRegister": 0,
    "pwmRegBase": 0,
    "pwmResolution": 0,
    "motorRegs": [0, 0, 0, 0, 0],
    "motorDecimals": 0,
    "sensorId": ""
  }
}

PWM Dimming Module

{
  "id": "mb_pwm",
  "name": "4-Channel PWM Dimming",
  "type": 51,
  "enabled": false,
  "pins": [],
  "params": {
    "slaveAddress": 2,
    "channelCount": 4,
    "coilBase": 0,
    "ncMode": false,
    "controlProtocol": 1,
    "deviceType": 1,
    "deviceIndex": 1,
    "batchRegister": 0,
    "pwmRegBase": 100,
    "pwmResolution": 10,
    "motorRegs": [0, 0, 0, 0, 0],
    "motorDecimals": 0,
    "sensorId": ""
  }
}

Parameter Description

Parameter	Description
slaveAddress	Modbus slave address (1-247)
channelCount	Number of channels
coilBase	Coil/register base address
ncMode	NC normally-closed mode (true=normally closed, control logic inverted)
controlProtocol	Control protocol: 0=coil(FC05), 1=register(FC06)
deviceType	Device type: 0=relay, 1=pwm, 2=pid, 3=motor
deviceIndex	Index in ModbusHandler config
batchRegister	Bitmap batch register address (0=not used)
pwmRegBase	PWM register base address
pwmResolution	PWM resolution (bits)
motorRegs	Motor register addresses [forward, reverse, stop, speed, pulse count]
motorDecimals	Motor parameter decimal places
motorMinPosition	Motor/slide soft limit minimum position, unit is steps
motorMaxPosition	Motor/slide soft limit maximum position; soft limit enabled when `motorMaxPosition > motorMinPosition`
motorCurrentPosition	Current estimated position; should be updated to corresponding steps after homing or manual calibration
motorMoveStep	`forward`/`reverse` default relative move steps; uses most recent `setPulse` value when not set
motorLastPulse	Most recent pulse count; updated at runtime
sensorId	Sensor identifier (used for data collection reporting)

Modbus Motor Slide Soft Limit

When sub-device deviceType is motor, the following fields can limit slide travel:

{
  "deviceType": "motor",
  "motorRegs": [0, 1, 2, 5, 7],
  "motorMinPosition": 0,
  "motorMaxPosition": 10000,
  "motorCurrentPosition": 0,
  "motorMoveStep": 1600,
  "motorLastPulse": 1600
}

When enabled, forward moves toward motorMaxPosition, reverse moves toward motorMinPosition. If the current move would exceed the boundary, the system first reduces the pulse count to within bounds before sending the direction command; if already at the boundary or lacking available pulses, execution is rejected and MOTOR_SOFT_LIMIT is returned.

Soft limits depend on the current estimated position; after first power-on, manual movement, or homing, motorCurrentPosition must be calibrated to the actual position. For true limit protection, hardware limit switches or emergency stop are still recommended; software limits are for reducing misoperations and rule boundary violations.

Peripheral Execution Integration

Web Interface Configuration Steps

Create Modbus Relay Control Rule

Switch to the Peripheral Execution Management tab
Click the Add Rule button
Configure trigger (e.g., platform trigger, event trigger)
Add Modbus action:
- Action Type: Modbus Coil Write
- Target Peripheral: mb_relay
- Action Value: {"ch":0,"val":1} (channel 0, ON)
Click Save

💡 Tip: Coil write (FC05) is for relays; register write (FC06) is for PWM

JSON Configuration Example

Modbus Coil Write (ACTION_MODBUS_COIL_WRITE = 16)

{
  "targetPeriphId": "mb_relay",
  "actionType": 16,
  "actionValue": "{\"ch\":0,\"val\":1}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Modbus Register Write (ACTION_MODBUS_REG_WRITE = 17)

{
  "targetPeriphId": "mb_pwm",
  "actionType": 17,
  "actionValue": "{\"reg\":100,\"val\":512}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Modbus Poll Collection (ACTION_MODBUS_POLL = 18)

{
  "targetPeriphId": "modbus-task:0",
  "actionType": 18,
  "actionValue": "{\"poll\":[0]}",
  "useReceivedValue": false,
  "syncDelayMs": 0,
  "execMode": 0
}

Notes

UART Prerequisite: Modbus devices depend on UART peripherals to provide the RS485 physical channel; UART must be configured first
Unique Address: Each device address must be unique on the same bus
Communication Interval: Recommend ≥50ms interval between consecutive commands (controlled by pollInterPollDelay parameter)
Timeout Retry: Default response timeout is 1000ms, maximum retry is 2 times
pinCount=0: Modbus devices do not use GPIO pins