Configuration

Modbus Configure File

In order to communicate with modbus devices, a proper modbus configure file is required. It is mainly to describe the device address and register mappings.

Here is the basic structure of modbus configure file.

# Modbus Configuration File
# --------------------------
# This configuration file is to describe the Modbus registers of target device(s) and defines poller(s) to help polling data.
# The file format uses "csv" instead of json or yaml because many vendor's modbus registers are described in a table so it is easier to edit the information in excel and export to csv format.
#
# Configuration Types
# --------------------------
# device,<device_name>,<device_id>
# poll,<object_type>,<start_address>,<size>,<endian>
# ref,<ref_name>,<address>,<dtype>,<rw>,<unit>,<scale>
#
# Configuration Objects
# --------------------------
# <device_name>: any string without spaces to describe the device (must be unique in the file)
# <device_id>: integer 1 to 254; Modbus slave address used on the bus
# Multiple device rows may share the same <device_id> when they are logical views of one
# physical slave (distinct MQTT topics via {{device_name}}); poll ranges must not overlap
# <object_type>: coil/discrete_input/holding_register/input_register
# <start_address>: integer 0 to 65535 (The start address of Modbus registers to poll)
# <size>: integer 0 to 65535 (No. of registers to poll and value must not exceed the limits of Modbus)
# <endian>: byte_order and word_order e.g. BE_BE/BE_LE/LE_LE/LE_BE
# <ref_name>: any string without spaces to describe the reference
# <address>: integer 0 to 65535 (the modbus address and should match the poller range)
# <dtype>: uint16/int16/uint32/int32/float16/float32/bool/bool8/bool16/stringXXX (defaults to uint16)
# <rw>: read/write setting e.g. r/w/rw
# <unit> (optional): the measurement unit of reference
# <scale> (Optional): a float value to be multiplied with actual register reading; leave empty to disable scaling (0 is not supported as a multiplier)
# <endian> must be one of BE_BE, LE_BE, LE_LE, BE_LE (typos give unpredictable results)
# bool on coil/discrete_input: absolute Modbus coil address, publishes one boolean
# bool8/bool16 on coil/discrete_input: legacy grouped reads; address is group index (0=coils 0-7, 1=coils 8-15 / "09-16" in tables)
# if the poll ends mid-group, missing bits are padded with false (bool8 and bool16)
# bool with address:bit (0-15): use on holding_register or input_register pollers only (not coils)
#
# Typical Structure
# -----------------------------
# device,dev001,1   <- the first device (dev001)
# poll,...          <- the first poller of dev001
# ref,...           <- the references in poller
# ref,...
# poll,...          <- the second poller of dev001
# ref,...
# ref,...
# device,dev002,2   <- a second physical slave (dev002)
# poll,...          <- the first poller of dev002
# ref,...
# device,dev001b,1  <- optional: another logical device on slave 1 (unique name, non-overlapping polls)
# poll,...
# ref,...
#
# Configuration Example
# !!! Please remove all comments for your config file !!!
# -----------------------------
device,modsim01,1,,
poll,coil,0,12,BE_BE
ref,coil01,0,bool,rw
ref,coil02,1,bool,rw
ref,coil09-12,1,bool8,rw
poll,holding_register,40000,20,BE_BE
ref,holding_reg01,40000,uint16,rw
ref,holding_reg02,40001,uint16,rw
ref,holding_reg03,40002,uint16,rw
ref,holding_reg04,40003,uint16,rw
ref,holding_reg05,40004,int16,rw
ref,holding_reg06,40005,int16,rw
ref,holding_reg07,40006,int16,rw
ref,holding_reg08,40007,int16,rw
ref,holding_reg09,40008,uint32,rw
ref,holding_reg10,40010,uint32,rw
ref,holding_reg11,40012,int32,rw
ref,holding_reg12,40014,int32,rw
ref,holding_reg13,40016,float32,rw
ref,holding_reg14,40018,float32,rw
# Example of reading a single bit from a register
# The format is address:bit (0-15), and is only for dtype=bool on registers.
ref,alarm_bit_15,40019:15,bool,r,

Example 1: Modsim device (Modbus TCP device)

This example configuration is included for local testing with a Modbus TCP simulator or device.

Here is an example of modbus configure file for reading modsim device.

device,modsim01,1,,
poll,coil,0,16,BE_BE
ref,coil01-08,0,bool8,rw
ref,coil09-16,1,bool8,rw
poll,discrete_input,10000,16,BE_BE
ref,di01-08,10000,bool8,rw
ref,di09-16,10001,bool8,rw
poll,input_register,30000,20,BE_BE
ref,input_reg01,30000,uint16,rw
ref,input_reg02,30001,uint16,rw
ref,input_reg03,30002,uint16,rw
ref,input_reg04,30003,uint16,rw
ref,input_reg05,30004,int16,rw
ref,input_reg06,30005,int16,rw
ref,input_reg07,30006,int16,rw
ref,input_reg08,30007,int16,rw
ref,input_reg09,30008,uint32,rw
ref,input_reg10,30010,uint32,rw,,0.001
ref,input_reg11,30012,int32,rw
ref,input_reg12,30014,int32,rw,,1000
ref,input_reg13,30016,float32,rw
ref,input_reg14,30018,float32,rw
poll,holding_register,40000,44,BE_BE
ref,holding_reg01,40000,uint16,rw
ref,holding_reg02,40001,uint16,rw
ref,holding_reg03,40002,uint16,rw
ref,holding_reg04,40003,uint16,rw
ref,holding_reg05,40004,int16,rw
ref,holding_reg06,40005,int16,rw
ref,holding_reg07,40006,int16,rw
ref,holding_reg08,40007,int16,rw
ref,holding_reg09,40008,uint32,rw
ref,holding_reg10,40010,uint32,rw,,0.001
ref,holding_reg11,40012,int32,rw
ref,holding_reg12,40014,int32,rw,,1000
ref,holding_reg13,40016,float32,rw
ref,holding_reg14,40018,float32,rw
ref,holding_reg15,40020,uint64,rw
ref,holding_reg16,40024,int64,rw
ref,holding_reg17,40028,float64,rw
ref,holding_reg18,40032,float64,rw
ref,holding_reg19,40036,string16,rw

Example 2: SCPM-S6 Power Meter (Modbus RTU device)

SCPM-S6 is designed as a sub-circuit power meter to monitor multiple electrical circuit power consumptions.

Here is an example of modbus configure file for SCPM-S6.

device,scpm001,1,,,
poll,holding_register,46001,6,BE_BE,
ref,CT_TYPE,46001,uint16,rw,
ref,CT_RATING,46002,uint16,rw,
ref,DATA_SCALAR,46003,uint16,rw,
ref,ReservedA,46004,uint16,rw,
ref,ReservedB,46005,uint16,rw,
ref,SIGNED_MODE,46006,uint16,rw,
poll,holding_register,46011,92,BE_BE,
ref,Hz,46011,int16,r,Hz,1
ref,V,46012,int16,r,V,1
ref,CH1_A,46013,int16,r,A,1
ref,CH2_A,46014,int16,r,A,1
ref,CH3_A,46015,int16,r,A,1
ref,CH4_A,46016,int16,r,A,1
ref,CH5_A,46017,int16,r,A,1
ref,CH6_A,46018,int16,r,A,1
ref,CH1_kWh,46019,uint32,r,kWh,1
ref,CH2_kWh,46021,uint32,r,kWh,1
ref,CH3_kWh,46023,uint32,r,kWh,1
ref,CH4_kWh,46025,uint32,r,kWh,1
ref,CH5_kWh,46027,uint32,r,kWh,1
ref,CH6_kWh,46029,uint32,r,kWh,1
ref,CH1_kWh_P,46031,uint32,r,kWh,1
ref,CH2_kWh_P,46033,uint32,r,kWh,1
ref,CH3_kWh_P,46035,uint32,r,kWh,1
ref,CH4_kWh_P,46037,uint32,r,kWh,1
ref,CH5_kWh_P,46039,uint32,r,kWh,1
ref,CH6_kWh_P,46041,uint32,r,kWh,1
ref,CH1_kWh_N,46043,uint32,r,kWh,1
ref,CH2_kWh_N,46045,uint32,r,kWh,1
ref,CH3_kWh_N,46047,uint32,r,kWh,1
ref,CH4_kWh_N,46049,uint32,r,kWh,1
ref,CH5_kWh_N,46051,uint32,r,kWh,1
ref,CH6_kWh_N,46053,uint32,r,kWh,1
ref,CH1_kVARh,46055,uint32,r,kVARh,1
ref,CH2_kVARh,46057,uint32,r,kVARh,1
ref,CH3_kVARh,46059,uint32,r,kVARh,1
ref,CH4_kVARh,46061,uint32,r,kVARh,1
ref,CH5_kVARh,46063,uint32,r,kVARh,1
ref,CH6_kVARh,46065,uint32,r,kVARh,1
ref,CH1_kVARh_P,46067,uint32,r,kVARh,1
ref,CH2_kVARh_P,46069,uint32,r,kVARh,1
ref,CH3_kVARh_P,46071,uint32,r,kVARh,1
ref,CH4_kVARh_P,46073,uint32,r,kVARh,1
ref,CH5_kVARh_P,46075,uint32,r,kVARh,1
ref,CH6_kVARh_P,46077,uint32,r,kVARh,1
ref,CH1_kVARh_N,46079,uint32,r,kVARh,1
ref,CH2_kVARh_N,46081,uint32,r,kVARh,1
ref,CH3_kVARh_N,46083,uint32,r,kVARh,1
ref,CH4_kVARh_N,46085,uint32,r,kVARh,1
ref,CH5_kVARh_N,46087,uint32,r,kVARh,1
ref,CH6_kVARh_N,46089,uint32,r,kVARh,1
ref,CH1_kVA,46091,int16,r,kVA,1
ref,CH2_kVA,46092,int16,r,kVA,1
ref,CH3_kVA,46093,int16,r,kVA,1
ref,CH4_kVA,46094,int16,r,kVA,1
ref,CH5_kVA,46095,int16,r,kVA,1
ref,CH6_kVA,46096,int16,r,kVA,1
ref,CH1_PF,46097,int16,r,,1
ref,CH2_PF,46098,int16,r,,1
ref,CH3_PF,46099,int16,r,,1
ref,Reserved1,46100,int16,r,
ref,Reserved2,46101,int16,r,
ref,Reserved3,46102,int16,r,