Need help understanding the items file

Setup, Configuration and Use Beginners
,
1

About 2 years ago, I got an EzRain insteon sprinkler controller. I briefly tried to get it to work from openHAB but gave up but with Bernd Pfrommer’s help I wrote an extension to InsteonTerminal, got it to work and I’ve been using that ever since. This Christmas I got an Amazon Echo and thought it would be cool to be able to voice control the sprinklers. The Echo has an openHAB skill so its time to revisit.

From what I’ve read, there is still no insteon binding compatible with openHAB2 and people are using the version 1 binding. I’ve set up the insteonplm.cfg file and I can see in the logs that it has been loaded OK. It reports that there are 2 items in the modem database but that nothing is configured.

OK, so I need an items file. Do I need one for the PLM and one for the EzRain or just one for the EzRain? I’m not clear on what an item is. Is a device or a capability of a device? For example, the EzRain controls 8 zones and each zone has a valve that can be on or off. Does that mean I need 8 items in my item file or just one for the device with a parameter to specify the zone? Also, there is no itemType for a valve. Can I use the switch type or will I need to create a new itemType?
I’m thinking my item file would look something like this:

Valve SprinklerControl “Front yard On [%d]” { insteonplm=“05.93.D6:F0.00.00”#ValveOn"}
Valve SprinklerControl “Front yard Off [%d]” { insteonplm=“05.93.D6:F00.00.00”#ValveOff"}
Valve SprinklerControl “Back yard On [%d]” { insteonplm=“05.93.D6:F00.00.00”#ValveOn"}
Valve SprinklerControl “Back yard Off [%d]” { insteonplm=“05.93.D6:F00.00”#ValveOff"}

where ValveOn/ValveOff is the command.

Thanks,
Steve

2

There is no such item type as Valve, but you can use Switch (as a valve is kind of water switch, this should be ok). openHAB has no icons for valves nor sprinklers, so you either have to draw one by yourself or search the internet for an appropriate one. You can place the file(s) at /conf/icons/classic/. file format is png and/or svg. The name scheme is iconname-state.png or iconname-state.svg. You can use this icons through the items file by using

Switch MyValve1 "Valve No. 1 is [%s]" <valve> {...}

the icon would be named

valve-on.svg 
valve-off.svg 
valve.svg 
valve-on.png 
valve-off.png 
valve.png
3

Hi Udo,

OK I’ll try a Switch type. I originally thought that this would not work because the underlying insteon command to control a valve is different to that which controls a switch but if the item type is independent of the control mechanism, ie insteon, I guess that it should not matter.

Now I’m understanding the documentation a little better, I see that I need to add my own additional device file and corresponding feature file. It also looks like I might have to mod the java code similar to what I did with the python code for the insteon terminal.

Thanks,
Steve

4

Steve,

Yes, there are only a few controls in openHAB that control virtually every
kind of item that you bind to them. Since you valve is on/off a switch is
perfect to command a 1(on) or 0(off) to this valve. If you have
intermediate states, like a variable valve, you would use “slider” which
commands a percentage of 0-100%

so - moding your item line would look like this

switch SprinklerControl “Front yard On [%d]” {
insteonplm=“05.93.D6:F0.00.00”#ValveOn"}

Now the other part I’m concerned with is the “F0.00.00”#ValveOn” part.

There is no device defined in the insteonPLM openHAB binding “F0.00.00”.
Actually that isn’t even enough numbers to match the pattern. The first
item is “F00.00.01”. These numbers are called "product keys ". Then the
binding receives a command from the switch, it uses the product key to
determine what to send to the device. If you look at the below link,
you’ll see all of the product keys that will work with the insteonPLM
openHAB binding.

Now - as you said - your EZRain sprinkler controller is not listed here.
Unfortunately don’t know anything about your device, but since you worked
with Bernd to get it functioning under Insteon-Terminal, it sounds like you
do. You might want to play around with existing product keys to see if any
of they will work to trigger your device. Adding new functionality in the
additional device/features file isn’t trivial. Actually moding the binding
is even another level beyond that.

Tom

5

Hi Tom,

I was just guessing with the device type. I found a reference to EzRain in the very old (2008) list of devices here (http://cache.insteon.com/pdf/INSTEON_DevCats_and_Product_Keys_20081008.pdf) although the number 0x000001 seems unlikely. So I just called tech support at SmartenIt who seems to own this product now. They asked me to e-mail them my question so we’ll see if I get an answer.

So now my items file (/etc/openhab2/items/ezrain.items) looks like this:
Switch FrontYardOn “Front yard [%d]” { insteonplm=“05.93.D6:0x000001#ValveOn”}
Switch FrontYardOff “Front yard [%d]” { insteonplm=“05.93.D6:0x000001#ValveOff”}
Switch BackYardOn “Back yard [%d]” { insteonplm=“05.93.D6:0x000001#ValveOn”}
Switch BackYardOff “Back yard [%d]” { insteonplm=“05.93.D6:0x000001#ValveOff”}

I’m still not sure how to specify which valve to control. Do I need to to create a Valve1On, Valve2On etc?

I modified my config file (etc/openhab2/services/insteonplm.cfg) and added these 2 lines:
more_devices=/usr/local/openhab/rt/extra_devices.xml
more_features=/usr/local/openhab/rt/ezrain_features.xml

The extra_devices file looks like this:

<xml>

    <device productKey="0x000001">

        <model>5010A</model>

        <feature name="ValveOn">ValveOn</feature>

        <feature name="ValveOff">ValveOff</feature>

    </device>

</xml>

When I restart openHAB I get this:
2017-12-29 16:35:13.946 [INFO ] [er.internal.HomeBuilderDashboardTile] - Started Home Builder at /homebuilder
2017-12-29 16:35:14.758 [INFO ] [.dashboard.internal.DashboardService] - Started dashboard at http://192.168.2.19:8080
2017-12-29 16:35:14.760 [INFO ] [.dashboard.internal.DashboardService] - Started dashboard at https://192.168.2.19:8443
2017-12-29 16:35:16.379 [ERROR] [io.openhabcloud.internal.CloudClient] - Socket.IO error: not authorized
2017-12-29 16:35:17.846 [INFO ] [el.core.internal.ModelRepositoryImpl] - Loading model 'ezrain.items’
2017-12-29 16:35:18.971 [INFO ] [thome.model.lsp.internal.ModelServer] - Started Language Server Protocol (LSP) service on port 5007
2017-12-29 16:35:19.742 [INFO ] [basic.internal.servlet.WebAppServlet] - Started Basic UI at /basicui/app
2017-12-29 16:35:19.775 [INFO ] [arthome.ui.paper.internal.PaperUIApp] - Started Paper UI at /paperui
2017-12-29 16:35:19.823 [INFO ] [panel.internal.HABPanelDashboardTile] - Started HABPanel at /habpanel
2017-12-29 16:35:19.862 [INFO ] [nding.insteonplm.InsteonPLMActivator] - Insteon PLM binding has been started.
2017-12-29 16:35:19.941 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - read additional device definitions from /usr/local/openhab/rt/extra_devices.xml
2017-12-29 16:35:19.941 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - reading additional feature templates from /usr/local/openhab/rt/ezrain_features.xml
2017-12-29 16:35:19.996 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - dead device timeout set to 3000s
2017-12-29 16:35:20.001 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - config: port_0 -> /hub2/Elizabet:Hllze9WB@192.168.2.27:25105,poll_time=1000
2017-12-29 16:35:20.001 [INFO ] [b.core.service.AbstractActiveService] - InsteonPLM has been started
2017-12-29 16:35:20.003 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - devices: 0 configured, 0 polling, msgs received: 0
2017-12-29 16:35:20.018 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - config: more_features -> /usr/local/openhab/rt/ezrain_features.xml
2017-12-29 16:35:20.018 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - config: more_devices -> /usr/local/openhab/rt/extra_devices.xml
2017-12-29 16:35:20.019 [INFO ] [g.insteonplm.InsteonPLMActiveBinding] - config: service.pid -> org.openhab.insteonplm
2017-12-29 16:35:20.106 [ERROR] [steonplm.internal.device.PollHandler] - error trying to create message handler: DefaultPollHandler
java.lang.ClassNotFoundException: org.openhab.binding.insteonplm.internal.device.PollHandler$DefaultPollHandler cannot be found by org.openhab.binding.insteonplm_1.11.0

and then similar stuff for the unknown comands ValveOnCommandHandler and ValveOffCommandHandler.

So now I think I have to write those commands so openHAB can send the 0x40 and 0x41 commands to the device.

Steve

and the ezrain_features files like this:

<xml>

    <feature name="ValveOn">

        <message-dispatcher>DefaultDispatcher</message-dispatcher>

        <command-handler command="OnOffType">ValveOnCommandHandler</command-handler>

        <poll-handler>DefaultPollHandler</poll-handler>

    </feature>

    <feature name="ValveOff">

        <message-dispatcher>DefaultDispatcher</message-dispatcher>

        <command-handler command="OnOffType">ValveOffCommandHandler</command-handler>

        <poll-handler>DefaultPollHandler</poll-handler>

    </feature>

</xml>
6

A percentage value would be represented by a Dimmer Item. The Slider is a widget, this is only used in sitemap definition!

7

@tommycw10 you might find these links helpful:

Items:

http://docs.openhab.org/concepts/items.html
http://docs.openhab.org/configuration/items.html

Sitemaps:

http://docs.openhab.org/configuration/sitemaps.html

Cheers

8

Oh right. My mistake.

9

So I got an answer from SmartenIt. They said they were going to look into why the ProductId was not being sent but they said they generally use the IdRequest command to get back the Device Category, Sub-category and firmware version. The insteon documentation says that the response to IdRequest is that the device first returns an ACK message then it sends a SET Button Pressed Broadcast message but it does not enter linking mode.
They sent me this output:

15:44:58.804 [TX] - 02 62 3D D1 1B 0F 10 00
15:44:58.813 [RX] - 02 62 3D D1 1B 0F 10 00 06 Send Raw INSTEON
15:44:59.053 [RX] - 02 50 3D D1 1B 30 00 05 2F 10 00 INSTEON Received
15:44:59.388 [RX] - 02 50 3D D1 1B 04 00 03 8F 02 FF INSTEON Received

The “04 00 03” is the last line being the 3 items mentioned above. The '*'s are their highlighting.

So I modified my insteon terminal code to send an idRequest command but I only get back the ack:
Insteon Terminal
Connecting
Connected
Terminal ready!
>>> ezrain.idRequest()
sent msg: OUT:Cmd:0x62|toAddress:05.93.D6|messageFlags:0x0F=DIRECT:3:3|command1:0x10|command2:0x00|
12:22:26: idRequest got msg: IN:Cmd:0x50|fromAddress:05.93.D6|toAddress:34.27.59|messageFlags:0x2F=ACK_OF_DIRECT:3:3|command1:0x10|command2:0x00|

Perhaps my python code is not correct?
Here is what I have:

    def idRequest(self):

        """idRequest()

        gets device category, sub-category and firmware version"""

        self.querier.setMsgHandler(DefaultMsgHandler("idRequest"))

        self.querier.querysd(ID_REQUEST, 0x00)

Do I need to add something more to receive the messages after the ACK?
Also I think there is a way to have insteon terminal print all raw data received in hex But I don’t remember how.

Thanks,
Steve

10

Steve,

I’m not sure I’d spend the time looking for the real device ID. Frankly it
doesn’t matter to the binding at all. If you notice nearly all of the
devices listed on the insteonPLM wiki page are product keys that start with
"F". If you read the wiki page, you’ll see that the F stands for “fake”.
These are all devices that either there was never a product key defined by
Smarthome or no one knows what it is.

The product key is only used in the Insteon PLM binding to tell it what to
do with a device, however telling it the actual product key vs. a made up
fake key doesn’t matter. Either way, you are going to have to add
functionality to the binding (either through the more features/more devices
files or through adding code to the binding itself - not sure which yet) to
get it to do something then the real or fake product key is used. The
functionality currently doesn’t exist.

A comment on your earlier post on the items file you wrote:

Switch FrontYardOn “Front yard [%d]” { insteonplm=“05.93.D6:0x000001#
ValveOn”}
Switch FrontYardOff “Front yard [%d]” { insteonplm=“05.93.D6:0x000001#
ValveOff”}
Switch BackYardOn “Back yard [%d]” { insteonplm=“05.93.D6:0x000001#ValveOn”}
Switch BackYardOff “Back yard [%d]” { insteonplm=“05.93.D6:0x000001#
ValveOff”}

Note: a single switch has both on and off functionality, so you’ll only
need one line per item. Also with the single device having multiple (8?)
zone valve controls, the stuff after the “#” would probably best be used to
tell the device with of these valves you are controlling. So I’m thinking
maybe something more like this (remember when you add the functionality to
the binding, you will define the exact nomenclature to use after the #)

Switch FrontYard “Front yard” { insteonplm=“05.93.D6:0x000001#Valve1”}
Switch BackYard “Back yard” { insteonplm=“05.93.D6:0x000001#Valve2”}

11

Hi Tom,

It’s the engineer in me that says if something is supposed to work and it doesn’t I have to find out why and fix it.

As for my items file, if I make it as you suggested, the how do I specify if I want to turn it on or off? Valves are not quite like switches. When they are turned on they only stay on for a certain amount of time and then they turn themselves off but they can also be commanded off before that time. Do the items only relay status and commands come from somewhere else? This gets back to my original topic of understanding the use of the items file.

Thanks,
Steve

12

Hi Steve,

Understood. I’m an engineer as well!

I think what you really need is a spec sheet for this device. If you look at the wiki page, look at the device list near the top. I added links to all of the device names where I could find a spec sheet. Without one of these or a good amount of time to do some reverse engineering, you’re guessing about how the device operates. This will solve both questions you have.

For the ID, some devices respond to an ID request with a standard message and others need an expended message. A spec sheet would tell you how to do this.

For the switch: most devices will send out a power line/Rf message if the turn themselves on/off. If you link the device to your PLM as both a responder and a controller, the binding would see this and update the switch to off. Again a spec sheet or time spent reverse engineering would give the answer. An example is a simple switch, linked correctly, when I operate it manually, I can watch openHAB update the virtual state to match the physical state.