Modbus TCP

This guide explains how to connect Modbus TCP devices to Aqara Studio.

Prerequisites

Before you begin, please make sure:

• Your Modbus TCP device, Aqara Gateway, and your computer are all on the same local network.
• Your Modbus TCP device is properly configured for Modbus TCP communication. Please refer to your product manual or contact your device manufacturer for support if needed.

Add a Modbus TCP Device

1. Click the Devices page in the left sidebar.
2. In the device tree on the left, click the “+” button, select Modbus TCP in the popup.
3. Click Modbus TCP, switch to Add Device page, fill in and save the following parameters:

• Device Configuration:

  Parameter Name	Required	Description
  Device Name	✔	The name you define for this device.
  Device Address	✘	The slave device address (unit identifier), range 0~255.
  IP Address	✔	The IP address of this device.
  Port	✔	The Modbus TCP communication port, default is 502.

• Advanced Configuration:

  Parameter		Description
  Ping Address	Address Format	The holding register address used to check if this Modbus device works properly. Supported formats are: Hexadecimal Decimal Standard Modbus Address
  	Address	The actual holding register address.
  Rx Process Mode		Choose how received data is processed: Byte: Byte stream mode. Packet: Packet mode.
  Use Force MultIPle Coil		Whether to use the "Force Multiple Coils" command to write multiple coils (Modbus function code 15).
  Use Preset Multiple Register		Whether to use the "Preset Multiple Registers" command to write multiple holding registers (Modbus function code 16).
  Float Byte Order		The byte order used for 32-bit float values. Only Order1032 and Order3210 are supported.
  Long Byte Order		The byte order for 64-bit long integer values. Only Order1032 and Order3210 are supported.
  Input Register Base Address	Address Format	The format of input register (Modbus function code 04: Read Input Registers) offset address. Supported options: Hexadecimal Decimal Standard Modbus Address If you are not sure what an offset address is, please see What is an Offset Address? below.
  	Address	The offset address.
  Holding Register Base Address	Address Format	The format of holding register (Modbus function code 03: Read Holding Registers) offset address. The supported formats are the same as those for Input Register Offset Address.
  	Address	The offset address.
  Coil Status Base Address	Address Format	The format of coil status (Modbus function code 01: Read Coils) offset address. Supported formats are the same as Input Register Offset Address.
  	Address	The offset address.
  Input Status Base Address	Address Format	The format of discrete input (Modbus function code 02: Discrete Inputs) offset address. Supported formats are the same as Input Register Offset Address.
  	Address	The offset address.
  Enable/Disable Device		Note: If disabled, this device will not be available.

4. In the "Add Point" page, click the + button in the “Type selection” area to add a point.

5. Click the new point to set its type and configure it. When finished, click Complete adding.

   Parameter Name	Required	Description	Example
   Point Name	Yes	Your custom name for the point.	-
   Object Type	No	No need to modify; use the default value.
   Status Type	Required for Boolean Point	Choose when the point is Boolean. Supported options: Coil Input	Coil
   Reg Type	Required for Numeric Point	Supported options: Holding Input	Holding
   Data Type	Required for Numeric Point	Supported options: Integer Type Long Integer Type Float Type Signed Integer Unsigned Long	Integer Type
   Poll Frequency	No	Supported options: Fast: High frequency polling (for key control) Normal: Standard frequency Slow: Low frequency polling (for non-real-time status)	Normal
   Address Format	Yes	Type of address format. Supported options: Hex: Hexadecimal, e.g., 0x0013. Decimal: e.g., 19. Modbus: Standard modbus address, e.g., 00001, 10001.	Decimal
   Address	Yes	Input value = Actual address – The offset address you set above	0
   Device Type	Yes	It is used to link this point to the corresponding trait in the Aqara Spec protocol for standardized control and management.	-

What is an Offset Address?

In the Modbus protocol, each data item in the device (such as registers or coils) has a numbered address used for reading or writing.

However, the addresses used in Modbus messages start from 0 internally, while users often see addresses starting from 1, 30001, 40001, and so on. Therefore, Aqara Studio asks for an “offset address” to help automatically convert these values.

For example, imagine a point with a real address of 40001 (holding register). If you set the “Holding Register Offset Address” to 40000, then when you add this point, you only need to input a data address of 1. Aqara Studio will automatically add the offset and calculate:

Final read address = Offset address + Data address = 40000 + 1 = 40001

This helps you configure many points easily. Just use the relative address (like 1, 2, 3) instead of the full Modbus address each time. This is both simple and consistent.

Next Steps

Now, you can view details and control the device, or use the device in automation.