ModbusAttr

ModbusAttr
Zweck / Funktion
Extract information from devices with a Modbus interface or send information to such devices
Allgemein
Typ	Gerätemodul
Details
Dokumentation	EN / DE Thema
Support (Forum)	Sonstiges
Modulname	98_ModbusAttr.pm
Ersteller	StefanStrobel (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

ModbusAttr provides a generic way to retrieve data objects from devices with a modbus Interface and store these objects in Readings, or modify such objects by sending write commands to such devices. The devices can be connected via RS232, RS485, or IP network, and the supported protocols are Modbus RTU or Modbus TCP.

The data objects to be used and the correspondig readings are defined by attributes in a way similar to HTTPMOD. They are continuously updated in the interval specified with the define command. This behavior can be modified with attribues to have some data objects updated at a lower frequency or only once and after each change.

There are several attributes that modify the way data objects are converted before they are stored in readings. They can be modified by a perl expression defined in an atribute, formatted with a format string defined in another attribute or mapped to a table defined in an attribute.

Readings can directly correspond to one data object or they can span several objects. A float value for example might be stored in two input or holding registers in the modbus device. By specifying attributes that define the length of a reading in objects or by specifying the unpack code to get from a raw string to perl variables, all these cases can be described by attributes and no perl coding is necessary.

Availability

The module has been checked in.

Prerequisites

This module uses the Modbus base module 98_Modbus.pm which uses the DevIO module

Define for Modbus RTU over serial lines / RS485 bus

define <iodevice> Modbus /dev/device@baudrate
define <name> ModbusAttr <Id> <Interval> </code>

In this case, a physical serial interface device is defined first using the Modbus module. Then a ModbusAttr device is defined for each modbus device connected to the serial line. For a RS485 bus, several modbus devices with different Ids can be connected to the same bus.

Example:

define ModbusRS485 Modbus /dev/rs485@9600
define PWP ModbusAttr 5 60

attr PWP obj-h256-reading Temp_Wasser_Ein
attr PWP obj-h256-expr $val/10

attr PWP obj-h258-reading Temp_Wasser_Aus
attr PWP obj-h258-expr $val/10

attr PWP obj-h262-reading Temp_Luft
attr PWP obj-h262-expr $val / 10

this defines the device with three readings (Temp_Wasser_Ein, Temp_Wasser_Aus and Temp_Luft) that are stored in holding registers with the decimal addresses 256, 258 and 262 as the temperatures multiplied by 10.

Define for Modbus TCP or Modbus RTU over TCP

define <name> ModbusAttr <Id> <Interval> <Address:Port> <RTU|TCP>

In this case no serial interface device is necessary and ModbusAttr connects to the modbus device directly via TCP using either Modbus TCP or Modbus RTU over TCP.

Example:

define PWP ModbusAttr 1 30 192.168.1.115:502 TCP

attr PWP obj-h256-reading Temp_Wasser_ein
attr PWP obj-h256-expr $val/10

Set-Commands

can be defined for holding registers and coils by using attributes, Every object for which an attribute like obj-xy-set is set to 1 will create a valid set option.

Get-Commands

Every reading can be manually requested by a Get. Internally a Get command triggers the corresponding request to the device and then interprets the data and returns the right field value. To avoid huge option lists in FHEMWEB, the objects visible as Get in FHEMWEB can be defined by setting an attribute obj-xy-showget to 1.

Simple Attributes

Attributes to define data objects start with obj- followed by a code that identifies the type and address of the data object. Modbus devices offer the following types of data objects: holding registers (16 bit objects that can be read and written), input registers (16 bit objects that can only be read), coils (single bit objects that can be read and written) or discrete inputs (single bit objects that can only be read).

Bigger Example:

define PWP ModbusAttr 1 30 192.168.1.115:502 TCP

attr PWP obj-h256-reading Temp_Wasser_Ein
attr PWP obj-h256-expr $val/10

attr PWP obj-h258-reading Temp_Wasser_Aus
attr PWP obj-h258-expr $val/10

attr PWP obj-h262-reading Temp_Luft
attr PWP obj-h262-expr $val / 10

attr PWP obj-h770-reading Temp_Soll
attr PWP obj-h770-expr $val / 10
attr PWP obj-h770-set 1
attr PWP obj-h770-setexpr $val * 10
attr PWP obj-h770-max 32
attr PWP obj-h770-min 10
attr PWP obj-h770-hint 8,10,20,25,28,29,30,30.5,31,31.5,32

attr PWP dev-h-combine 5
attr PWP dev-h-defPoll 1

The module uses the first character of modbus data object types to define attributes. Thus h770 refers to a holding register with the decimal address 770 and c120 refers to a coil with address 120. The address has to be specified as pure decimal number without any leading zeros or spaces.

attr PWP obj-h258-reading Temp_Wasser_Aus defines a reading with the name Temp_Wasser_Aus that is read from the Modbus holding register at address 258. With the attribute ending on -expr you can define a perl expression to do some conversion or calculation on the raw value read from the device. In the above example the raw value has to be devided by 10 to get the real temperature value.

An object attribute ending on -set creates a fhem set option. In the above example the reading Temp_Soll can be changed to 12 degrees by the user with the fhem command set PWP Temp_Soll 12 The object attributes ending on -min and -max define min and max values for input validation and the attribute ending on -hint will tell fhem to create a selection list so the user can graphically select the defined values.

To define general properties of the device you can specify attributes starting with dev-. E.g. with dev-timing-timeout you can specify the timeout when waiting for a response from the device. With dev-h- you can specify several default values or general settings for all holding registers like the function code to be used when reading or writing holding registers. These attributes are optional and the module will use defaults that work in most cases. dev-h-combine 5 for example allows the module to combine read requests to objects having an address that differs 5 or less into one read request. Without setting this attribute the module will start individual read requests for each object. Typically the documentation for the modbus interface of a given device states the maximum number of objects that can be read in one function code 3 request.

More complex example

define MD ModbusAttr 1 30 192.168.1.115:502 TCP

attr MD dev-i-combine 10     # combine read for up to 10 adjacent input registers
attr MD dev-i-read 4         # use function code 4 to read input registers (this would be the default anyway)
attr MD dev-i-defLen 2       # input registers define objects that span 2 registers by default
attr MD dev-i-defUnpack f>   # default unpack code for all objects that don't specify anything else will be f> (big endian 32 bit float, see perldoc pack)
attr MD dev-i-defFormat %.1f # format values with one digit after the comma by default if nothing else is specified for individual readings

attr MD dev-h-read 3         # this can be omitted since 3 is the default anyways
attr MD dev-h-write 16       # use function code 16 instead of 6 to write holding registers
attr MD dev-h-defPoll 1      # include all readings for holding registers in the update unless overwritten per object
attr MD dev-h-defShowGet 1   # show a get option in fhemweb for all readings based on holding registers

attr MD obj-i1010-reading Temp_Wasser_Ein                   # given the above defaults, this will be 
                                                            # a float unpacked with f> that spans 2 input registers
attr MD obj-i1020-reading HystMode 
attr MD obj-i1020-len 1                                     # this overrides the default specified with dev-i-defLen above
attr MD obj-i1020-format %s                                 # override default set above
attr MD obj-i1020-map 0:mittig, 1:oberhalb, 2:unterhalb     # convert the raw value 0 to "mittig", the value 1 to "oberhalb" and "2" to "unterhalb"
attr MD obj-i1020-pollDelay x10                             # only update this reading every 10th iteration

All Attributes

the following list of attributes can be applied to any data object by specifying the objects type and address in the variable part. For many attributes you can also specify default values per object type (see dev- attributes later) or you can specify an object attribute without type and address (e.g. obj-len) which then applies as default for all objects:

obj-[cdih][1-9][0-9]*-reading

define the name of a reading that corresponds to the modbus data object of type c,d,i or h and a decimal address (e.g. obj-h225-reading).

obj-[cdih][1-9][0-9]*-name

defines an optional internal name of this data object (this has no meaning for fhem and serves mainly documentation purposes.

obj-[cdih][1-9][0-9]*-set

if set to 1 then this data object can be changed (works only for holding registers and coils since discrete inputs and input registers can not be modified by definition.

obj-[cdih][1-9][0-9]*-min

defines a lower limit to the value that can be written to this data object. This ist just used for input validation.

obj-[cdih][1-9][0-9]*-max

defines an upper limit to the value that can be written to this data object. This ist just used for input validation.

obj-[cdih][1-9][0-9]*-hint

this is used for set options and tells fhemweb what selection to display for the set option (list or slider etc.)

obj-[cdih][1-9][0-9]*-expr

defines a perl expression that converts the raw value read from the device.

obj-[cdih][1-9][0-9]*-map

defines a map to convert values read from the device to more convenient values when the raw value is read from the device or back when the value to write has to be converted from the user value to a raw value that can be written. Example: 0:mittig, 1:oberhalb, 2:unterhalb

obj-[cdih][1-9][0-9]*-setexpr

defines a perl expression that converts the user specified value in a set to a raw value that can be sent to the device. This is typically the inversion of -expr above.

obj-[cdih][1-9][0-9]*-format

defines a format string to format the value read e.g. %.1f

obj-[cdih][1-9][0-9]*-len

defines the length of the data object in registers. It defaults to 1. Some devices store 32 bit floating point values in two registers. In this case you can set this attribute to two.

obj-[cdih][1-9][0-9]*-unpack

defines the unpack code to convert the raw data string read from the device to a reading. For an unsigned integer in big endian format this would be "n", for a signed 16 bit integer in big endian format this would be "s>" and for a 32 bit big endian float value this would be "f>". (see the perl documentation of the pack function).

obj-[cdih][1-9][0-9]*-showget

every reading can also be requested by a get command. However these get commands are not automatically offered in fhemweb. By specifying this attribute, the get will be visible in fhemweb.

obj-[cdih][1-9][0-9]*-poll

if set to 1 then this obeject is included in the cyclic update request as specified in the define command. If not set, then the object can manually be requested with a get command, but it is not automatically updated each interval. Note that this setting can also be specified as default for all objects with the dev- atributes described later.

obj-[cdih][1-9][0-9]*-polldelay

this attribute allows to poll objects at a lower rate than the interval specified in the define command. you can either specify a time in seconds or number prefixed by "x" which means a multiple of the interval of the define command. if you specify a normal numer then it is interpreted as minimal time between the last read and another automatic read. Please note that this does not create an individual interval timer. Instead the normal interval timer defined by the interval of the define command will check if this reading is due or not yet. So the effective interval will always be a multiple of the interval of the define.

dev-([cdih]-)*read

specifies the function code to use for reading this type of object. The default is 3 for holding registers, 1 for coils, 2 for discrete inputs and 4 for input registers.

dev-([cdih]-)*write

specifies the function code to use for writing this type of object. The default is 6 for holding registers and 5 for coils. Discrete inputs and input registers can not be written by definition.

dev-([cdih]-)*combine

defines how many adjacent objects can be read in one request. If not specified, the default is 1

dev-([cdih]-)*defLen

defines the default length for this object type. If not specified, the default is 1

dev-([cdih]-)*defFormat

defines a default format string to use for this object type in a sprintf function on the values read from the device.

dev-([cdih]-)*defUnpack

defines the default unpack code for this object type.

dev-([cdih]-)*defPoll

if set to 1 then all objects of this type will be included in the cyclic update by default.

dev-([cdih]-)*defShowGet

if set to 1 then all objects of this type will have a visible get by default.

dev-timing-timeout

timeout for the device (defaults to 2 seconds)

dev-timing-sendDelay

delay to enforce between sending two requests to the device. Default ist 0.1 seconds.

dev-timing-commDelay

delay between the last read and a next request. Default ist 0.1 seconds.

Links

• [www.modbus.org]
• About Modbus (English / German)