File Format: User Defined MODBUS Devices

History

When Eco Warrior Classic was first launched each type of device it was required to communicate with needed programming from scratch, which was a time consuming process. With Eco Warrior Pro the procedure of adding new devices was simplified by creating a set of building blocks (objects) which could be extended to work with new devices. For example there is a basic Modbus object which can be extended to support both RS485 and IP addressable modbus devices. The reduced the time and effort needed to support new types of device but still meant that some programming and a new version of Eco Warrior Pro was required each time a new logger or meter was added to the list of supported devices.

As Modbus has (so far at least) been the most popular protocol for the devices we have been asked to support it was decided to create a custom”, or “user defined” device which could be programmed from a simple (well, reasonably simple!) text file. The result is described below.

Definition

These files are based on INI files. Whenever Eco Warrior Pro is run it scans the config folder (..EW32Config) for files ending with “.modbus” and attempts to load the definition, which it then adds to the list of possible devices. This means that once you have added a “custom” device using one of these files you MUST leave the .modbus file in the config folder or an error will occur when EWPro attempts to initialise the device.

For example, the file which defines an Autometer IC970 looks like this :-

[Device]
Name=Autometer IC970
CircuitCount=9
EnergyType=etElectric
Comms=RS485
[Group Start Registers]
Group1=352
Group2=80
Group3=88
Group4=16
Group5=78
[Item 1]
Count=1
Group=1
Command=4
LogMethod=Incremental
EnergyUnit=eukW
Caption=Active Energy Sum
RegisterFormat=F32
[Item 2]
Count=3
Group=2
Command=4
LogMethod=Variable(avg)
EnergyUnit=euAmps
Caption=Current Phase
RegisterFormat=F32
[Item 3]
Count=1
Group=3
Command=4
LogMethod=Variable(avg)
EnergyUnit=euAmps
Caption=Current Sum
RegisterFormat=F32
[Item 4]
Count=3
Group=4
Command=4
LogMethod=Variable(avg)
EnergyUnit=euVolts
Caption=Phase-Neutral Voltage Phase
RegisterFormat=F32
[Item 5]
Count=1
Group=5
Command=4
LogMethod=Variable(avg)
EnergyUnit=euFrequency
Caption=Frequency
RegisterFormat=F32

The definition is split into sections. Each section begins with the name of the section in square brackets (eg “[Device]”). The section ends when a new section begins or when the end of the file is reached.

The minimum number of sections is three, as there must be a “Device” section followed by a “Group Start Registers” section and at least one “Item” section.

Section: Device

These settings apply to the whole device and, in cases such as “EnergyType”, they apply to all circuits.

Name	Required	This is the device type as seen in EWPro
CircuitCount	Required	MUST be equal to the number of circuits defined by all the “groups” in total (used as a cross-check)
EnergyType	Required	The default energy type measured by this device as found in the Measurand File (“Internal Name”). The energy type can also be overridden for each item if required.
Comms	Required	Defines the communications methods supported by the device. Options are “RS485” and “Network”. eg: “Comms=RS485,Network” OR “Comms=RS485” OR “Comms=Network”
WordByteOrder	Optional	Defines the order of the Words within a Double-Word and the order of Bytes within each Word. Used when sending/receiving packets of data to/from the device. Options are :- “HH” – High byte first, High word first (the default if no order is specified) “HL” – High byte first, Low word first “LH” – Low byte first, High word first “LL” – Low byte first , Low word first eg: “WordByteOrder=HL” (as used by EM21 meter)

Section: Group Start Registers

Circuits can be clumped together in groups, to simplify and speed up communication. The fewer the number of groups that need to be read from a device, the fewer the number of packets of data which need requesting/receiving and hence the sooner the communications process can be completed and we can move on to the next device. Each group of data starts at a given memory address within the device and continues sequentially for the remainder of the group. If a jump forwards or backwards in memory is needed then another group is required.

Group1	Required	Specifies the starting address of the first register to read for the first “Group”
Group2	Optional	Starting address for second group
Group….	Optional	… and so on. There is no enforced limit to the number of groups.

Section: Item

A group is comprised of one or more “Items”. Each item comprises one or more registers, which must be situated sequentially in the memory of the device. You need to specify how many registers need reading, what size and type each register is, how they should be interpreted, which energy unit they are and to which group they belong. Each register in this “Item” must have the same settings.

Count	Required	Number of sequential registers to read
Group	Required	Which group this item belongs to
LogMethod	Required	Options are :- “Incremental”,”Variable(min)”,”Variable(avg)”,”Variable(max)”,”Variable(ovr)”, “Variable(min/max)”,”Variable(min/avg/max)”, etc, etc … for Minimum, Average, Maximum, Overwrite (always equal to last value) A circuit will be created for each variable type included.
EnergyType	Optional	The energy type measured by this item, if different from the default value (see Device section). Valid values are found in the Measurand File (“Internal Name”).
EnergyUnit	Required	The energy unit measured by each register as found in the Measurand File (see unit “Internal Name”)
Caption	Required	This will be used as the basis for the circuit names. For example, if the caption is “Pulse”, the count is “2” and the LogMethod is “Incremental” then the circuit names will be “Pulse 1” and “Pulse 2”.
RegisterFormat	Required	Options are :- “U16” – Unsigned Word “S16” – Signed 16-bit Integer “U32” – Unsigned Double-Word “S32” – Signed 32-bit Integer “U64” – Unsigned Quadword “S64” – Signed 64-bit Integer “F32” – 32-bit single-precision floating point (not an official mobus type but sometimes used)
Command	Optional	The modbus command used to read the register(s). Default value is “3” if not specified. Some registers require command 4 – eg “Command=4”.
ScalingFactor	Optional	Scaling to be applied to register value in order to convert to given unit type. Default is 1.0 if not specified. This is separate to the scaling factor which can be applied to each circuit in the Eco Warrior Pro configuration section.