With the Update from openHAB 2.3 (or earlier) to openHAB 2.4 a new, oh2-compliant version of the modbus binding is introduced. The new version is not backward compatible, so the old modbus config will not work. I describe here how I created the new config based on my old config.
My old modbus configuration defined 4 slaves:
poll=500
tcp.slave1.connection=192.168.2.9:502
tcp.slave1.type=coil
tcp.slave1.id=1
tcp.slave1.start=12288
tcp.slave1.length=128
tcp.slave1.updateunchangeditems=false
tcp.slave2.connection=192.168.2.9:502
tcp.slave2.type=holding
tcp.slave2.id=2
tcp.slave2.start=12338
tcp.slave2.length=100
tcp.slave2.updateunchangeditems=false
tcp.slave3.connection=192.168.2.9:502
tcp.slave3.type=holding
tcp.slave3.id=3
tcp.slave3.start=12438
tcp.slave3.length=100
tcp.slave3.updateunchangeditems=false
tcp.slave4.connection=192.168.2.9:502
tcp.slave4.type=holding
tcp.slave4.id=4
tcp.slave4.start=12538
tcp.slave4.length=100
tcp.slave4.updateunchangeditems=false
As you can see, all the slaves poll the same modbus device, in my case a Wago 750-841 controller. Now, how to create a thing file for this pollers.
The new modbus binding uses a three-level definition.
Level one defines a Bridgefor every modbus slave. As I only have one, my new config will only contain one top-level bridge:
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
}
Host and Port are from my old modbus config.
Within the top level Bridge there are one or more second level bridges that replace the former slave configurations. The poll frequency can now be set per slave, so you may want to define different poll cycles up to your needs. The slave Bridge configs go inside the top level config. For me it now looks like this:
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
Bridge poller wago_slave1 [ start=12288, length=128, refresh=500, type="coil" ] {
}
Bridge poller wago_slave2 [ start=12338, length=100, refresh=4000, type="holding" ] {
}
Bridge poller wago_slave3 [ start=12438, length=100, refresh=5000, type="holding" ] {
}
Bridge poller wago_slave4 [ start=12538, length=100, refresh=10000, type="holding" ] {
}
}
The third (and most complex) part is now the definition of Thing objects for every Item bound to modbus. This definitions go into the corresponding 2nd level Bridge definitions. Here it is especially important that the modbus binding now uses absolute addresses all over the place, while the addresses in the item definition were relative to the start address of the slave definition before.
One example:
My old Item definition contained a line like this:
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
I now have to define a Thing that can later be bound to that Item.
My slave1 poller used 12288 as start address. So I define a data Thing within my poller wago_slave2 with this address:
Thing data wago_s1_000 [ readStart="12288", readValueType="bit", writeStart="12288", writeValueType="bit", writeType="coil" ]
The Item
Switch BarSwitch "Bar Switch" {modbus="slave1:1"}
with relative address 1 leads to the thing definition
Thing data wago_s1_001 [ readStart="12289", readValueType="bit", writeStart="12289", writeValueType="bit", writeType="coil" ]
Note the absolute address used here.
The Thing file now looks like this:
Bridge modbus:tcp:wago [ host="192.168.2.9", port=502, id=1 ] {
Bridge poller wago_slave1 [ start=12288, length=128, refresh=500, type="coil" ] {
Thing data wago_s1_000 [ readStart="12288", readValueType="bit", writeStart="12288", writeValueType="bit", writeType="coil" ]
Thing data wago_s1_001 [ readStart="12289", readValueType="bit", writeStart="12289", writeValueType="bit", writeType="coil" ]
}
Bridge poller wago_slave2 [ start=12338, length=100, refresh=4000, type="holding" ] {
}
Bridge poller wago_slave3 [ start=12438, length=100, refresh=5000, type="holding" ] {
}
Bridge poller wago_slave4 [ start=12538, length=100, refresh=10000, type="holding" ] {
}
}
Save this in the āthingsā subdirectory of your openHAB 2 config. Watch the file events.log as it lists your new added data Things. Given that there are no config errors, they quickly change from INITIALIZING to ONLINE.
Finally the Item definition has to be changed to refer to the new created data Thing. you can copy the names you need for this directly from the events.log file:
Switch FooSwitch "Foo Switch" {modbus="slave1:0"}
Switch BarSwitch "Bar Switch" {modbus="slave1:1"}
turn into
Switch FooSwitch "Foo Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_000:switch", autopudate="false"}
Switch BarSwitch "Bar Switch" {channel="modbus:data:wago:wago_slave1:wago_s1_001:switch", autoupdate="false"}
Notice that the names I have chosen for my data Things end with the numbers of the relative addresses in the former item definition. That made it possible to change my Item file with only a few āsearch and replaceā commands.
The definition of autoupdate is optional; please refer to the modbus binding documentation to check whether you need it or not.
Continue to add data Things for all your other Items the same way and link them to your Items.
Save your updated item file and check whether updates come in as expected.
If you have many modbus items (>50) and made use of the updateunchangeditems feature of the old modbus binding, be sure to read this discussion and use the snapshot version of the modbus binding linked there. Otherwise you might see high CPU load due to the way the new binding works.
If you make use of other features of the old modbus binding this article doesnāt cover feel free to describe how to update them in a comment.
@ssalonen: If you think this article is helpful, maybe you might refer to it from your binding documentation.
Yours
Wolfgang
