File Format: User Defined MODBUS Devices
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.
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.
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.|
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 :-
“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.