logto send data to the cloud, or a
discoverto only display information. There must be a config file when running
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
discoverfirst, before committing the plugin to collect data.
_cmdis the commands to run. Only
mbpollgithub command OR the
Modbus Ruby CLI(see the readme file) to read and write to modbus registers.
mbpollis preferred. The registers being collected MUST MATCH the registers listed in the configuration items. If not, you will have empty fields when running a
discover. If the registers in
_cmdcommands overlap, then there could be unexpected errors. Make sure each output of the
_cmdcommands do not overlap. The phrase
--translatecan 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.
Scalewill only be used for
integertypes. 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 as
0.75-9, where the
-9is 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 a
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 the
RO/RW/INVcolumn 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 on
decvalues. This invalidation feature is intended for those machines that have poor quality control, and sometimes transmit wildly wrong values.
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 the
modpollto handle this translation.
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.
Typeare as follows:
dec... Converts the modbus register to a decimal. Can be scaled (including division).
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 a
scalevalue that is not a whole number will be rejected. See also the explanation for
scaleabove, since it can include a bias and scale factor.
bit... Used with a lookup table (in the
Lookup Tablecolumn) to define a bit being turned or off. See example contents of file below. Bits start at "1" (not "0"), and are defined in the
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 field
str_rep... Same as
str, but it will clear
\0values in the resultant string.
bool... Modbus register is converted to an INT. This value is then check as follows: Anything other than
0will output a
True. Else, output will be
int_bool... Modbus register is converted to an INT. This value is then check as follows: Anything other than
0will output a
1. Else, output will be
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 file
hi8... Mask out the first (low) 8 bits of an Modbus integer
lo8... Mask out the last (high) 8 bits of an Modbus integer
sum... This is to sum the values of specific registers. In this case the
Registerfield MUST be set to
0and the registers to sum is a list in Summation Registers separated by spaces only
after... This is the same as
sum, but each register is added AFTER the scale and bias line. You MUST have the
0This means 2 things: a. The register to be added must exist as a separate line, and b. The
afterline must appear AFTER ALL the registers to be added.
cond_bit... This type will use the CONTENTS of the register listed in the
Sum/Conditional Registersand whether the bit detailed in the
Conditional Bitcolumn 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 keyword
log_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/9in 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" (
110in 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" (
111in 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.
RO/RWcolumn) are required.
endpoint. This is either a serial device like
/dev/ttyS0or an IP or DNS like
bus_addresses. A Modbus address in the range 2-255. This can be a hyphenated list like
3-10or a list like
--port. This is an optional parameter used in an Ethernet gateway, and is the TCP port used for the gateway. Default is
--attempts. This is an optional parameter, and determines how many times to times to attempt to read an inverter value. Default is
--delay. This is the delay in seconds between inverter send and receive commands, AND if
attempts> 1. Fractions like
0.3can be used. Default is
--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 all
SWAP16values will be collected as an average. In other words; it will take a sample at the nominated frequency. After X samples defined by
sampling_rate, a record will be written and sent to the cloud.
1. Include a
0value to display something (or blank) if no bits are turned on
cond_bittype. It operates by using the CONTENTS of the register listed in the
Sum/Conditional Registers, and whether the bit detailed in the
Conditional Bitcolumn 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 the
Sum/Conditional Registers, and the second key is the bit detailed in the
Conditional Bitcolumn. If this bit is true, then the third item is displayed.