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
Support (Forum)	Sonstiges
Modulname	98_ModbusAttr.pm
Ersteller	StefanStrobel (Forum / Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!

This page documents the ModbusAttr module. 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 readings are defined by attributes in a way similar to HTTPMOD.

Availability

The module is currently available through the forum at http://forum.fhem.de/index.php/topic,25315.60.html

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.

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.