Modbus Python Plugin
Purpose
Purpose of this plugin is to read from Modbus Servers via Python.
Usage
You run a log
to send data to the cloud, or a discover
to only display information. There must be a config file when running log
or a discover
. The config file defines which variables need to be collected, what names they appear on the the Ardexa cloud, units and scaling, what table(s) they variables will be sent to, and the source name(s). Example config file as follows. Always verify data accuracy by running a discover
first, before committing the plugin to collect data.
Notes:
_cmd
is the commands to run. Onlymodpoll
or thembpoll
github command OR theModbus Ruby CLI
(see the readme file) to read and write to modbus registers.mbpoll
is preferred. The registers being collected MUST MATCH the registers listed in the configuration items. If not, you will have empty fields when running adiscover
. If the registers in_cmd
commands overlap, then there could be unexpected errors. Make sure each output of the_cmd
commands do not overlap. The phrase--translate
can be included in a modbus command. It MUST appear in lower case and at the end of the command. If used, it will scale (by adding), all the register values. It will hence have the effect of translating them to another set of registers, so as they do not "collide" with the registers from another command.Scale
will only be used fordecimal
andinteger
types. An error will be reported if you try and divide an integer, or multiply by anything other than a whole number. The scale can also be a value such as0.75-9
, where the-9
is a BIAS value (addition or subtraction). In which case it will FIRST subtract the 9, THEN multiply by 0.75. If using a bias value, then it can ONLY be used with adecimal
type.RO/RW/INV
. This column will only do the following task": If an entry starts with>
, it will invalidate ALL entries in a configuration file, if the absolute value (+ or -) for this entry is greater than the specified amount. For example; if theRO/RW/INV
column entry is>10000
, then a value of 12,000 will ensure ALL readings in the configuration file are invalidated. Use this item with caution. Also, it will ONLY work ondec
values. This invalidation feature is intended for those machines that have poor quality control, and sometimes transmit wildly wrong values.In
Num of Regs
; Sometimes you may need to read 2 consecutive registers, to form a floating point (32 bit) number, rather than a single register (16 bit). Rarely, we may want to read a number of (perhaps) non-consecutive registers to form a string. Usually, it is best for thembpoll
ormodpoll
to handle this translation. Note that if you use a number value of2e
, it will reverse the endianess, fordec
andint
values.In
Lookup Table
; Sometimes you want to convert an INT to a keyword, through a lookup table. Or you may want to get a register bit and convert it to a keyword.Allowable
Type
are as follows:
dec
... Converts the modbus register to a decimal. Can be scaled (including division).udec
... This will convert the register to unsigned first, then convert the modbus register to a decimal. Can be scaled (including division). Only works on 16 bit registers.swap16
... Swaps the modbus register and converts it to a decimal. Can be scaled (including division).int
... Converts the modbus register to an integer. Can only be scaled upwards (not divided). So ascale
value that is not a whole number will be rejected. See also the explanation forscale
above, since it can include a bias and scale factor.bit
... Used with a lookup table (in theLookup Table
column) to define a bit being turned or off. See example contents of file below. Bits start at "1" (not "0"), and are defined in theLookup Table
column.bitb
... If a bit in the modbus register is turned on/off, it will reflect a boolean ("True"/"False") output.bitb_int
... If a bit in the modbus register is turned on/off, it will reflect a boolean ("1"/"0") output.str
... Treated as an ASCII character. If it can't be converted, it will output an empty fieldstr_rep
... Same asstr
, but it will clear\0
values in the resultant string.bool
... Modbus register is converted to an INT. This value is then check as follows: Anything other than0
will output aTrue
. Else, output will beFalse
.int_bool
... Modbus register is converted to an INT. This value is then check as follows: Anything other than0
will output a1
. Else, output will be0
.bin
... Converts the modbus register to an integer, then to a binary reprentation.int8
... Mask out the first 8 bits of an Modbus integer, then use a lookup filehi8
... Mask out the first (low) 8 bits of an Modbus integerlo8
... Mask out the last (high) 8 bits of an Modbus integersum
... This is to sum the values of specific registers. In this case theRegister
field MUST be set to0
and the registers to sum is a list in Summation Registers separated by spaces onlyafter
... This is the same assum
, but each register is added AFTER the scale and bias line. You MUST have theregister
set to0
This means 2 things: a. The register to be added must exist as a separate line, and b. Theafter
line must appear AFTER ALL the registers to be added.cond_bit
... This type will use the CONTENTS of the register listed in theSum/Conditional Registers
and whether the bit detailed in theRegister
andConditional Bit
column are 1 to then display the result of the lookup table. See the entry below on how this feature works.mask
... Mask out the Modbus integer based on the bits listed in the last 2 entries (bits 2 to 4 in the example - Bits start at "1" (not "0")) And use the resultant integer to lookup up and keywordlog_scale
... This will log scale the register, based on the contents of another register. In the example above, the final result will be:result = scale * (contents_of_register(365) * 10 ** (contents_of_register(569)-3)))
depend
... This will read the contents of the Lookup Table, the "depend register" (2456/7/8/9
in the above example). If the depend number, which is the next column in the config file, exceeds the value of the contents of the "depend register", then the particular line will be ignored. Otherwise it will collect the data and treat it as a DECIMAL value.master
... This will read the contents of the Lookup Table, the "master register" (110
in the above example). If the master register content is 1, it will collect the data and treat it as a DECIMAL value. If it is 0, then the particular line will be ignored.slave
... This will read the contents of the Lookup Table, the "master register" (111
in the above example). If the master register content is 0, it will collect the data and treat it as a DECIMAL value. If it is 1, then the particular line will be ignored.ge_fix
... This is used to convert a modbus integer to a signed integer using the "Signed Magnitude Method" discussed in: https://www.geeksforgeeks.org/representation-of-negative-binary-numbers/ The conversion will be handled during the early parts of processing, and then the value will be converted to DECIMAL
There are up to 11 columns. Only the first 8 (up to and including the
RO/RW
column) are required.A lookup file must be defined for the type
bit
andcond_bit
Arguments
Arguments are as follows:
endpoint
. This is either a serial device like/dev/ttyS0
or an IP or DNS like192.168.1.15
bus_addresses
. A Modbus address in the range 2-255. This can be a hyphenated list like3-10
or a list like2,5,7,9
--port
. This is an optional parameter used in an Ethernet gateway, and is the TCP port used for the gateway. Default is502
--attempts
. This is an optional parameter, and determines how many times to times to attempt to read an inverter value. Default is1
--delay
. This is the delay in seconds between inverter send and receive commands, AND ifattempts
> 1. Fractions like0.3
can be used. Default is0.05
--stop_on_any_command_fail
. If this is specified, then any Modbus commands that fail will stop all further queries for all bus addresses and attempts.--serial_lock
. If this is set, the program can only be run one at a time (so as not to overload a Modbus device). If the device being queried is a serial device, this will automatically be set to "on". For IP addresses it is optional.--sampling_rate
. If this is defined, and the sampling rate is greater than 1, then allDECIMAL
andSWAP16
values will be collected as an average. In other words; it will take a sample at the nominated frequency. After X samples defined bysampling_rate
, a record will be written and sent to the cloud.
Example of "bit" lookup
File would be something like:
/home/ardexa/ess_modbus/dict/container_alarm0.dict
Bit starts at
1
. Include a0
value to display something (or blank) if no bits are turned on
Example of "str" lookup file
File would be something like:
/home/ardexa/dict/mode.dict
Numbers can be anything, since they are read from a single modbus (16 bit) register
Example of a "conditional lookup" file
This is a lookup file used by the
cond_bit
type. It operates by using the CONTENTS of the register listed in theSum/Conditional Registers
, and whether the bit detailed in theRegister
andConditional Bit
column are 1/true, to then display the result of the lookup table. The file contents example is as below. There are 2 keys separated by a colon ":". The first item is the contents of theSum/Conditional Registers
, and the second key is the bit detailed in theRegister
andConditional Bit
column. If this bit is true, then the third item is displayed.