Skip to content

Configuration

Tim edited this page Jun 7, 2018 · 20 revisions

If you have successfully installed the MySensors binding you're ready to configure your things, items and sitemaps.

Handling of node ids

MySensors uses ids to distinguish between nodes. If you're using sketches from the MySensors page the newly created sensors will ask the controller for an id. This binding hands out random ids that are, according to the binding, not yet occupied. The sensor stores the id that was given by the controller and wont ask again. Another approach is to hardcode an id in the sketch of the sensor.

If you have hardcoded the id in the sketch you just have to assign the id to a thing in OH2. If the id is handed out by the OH2 binding you have to watch the debug output of OH2 to get the id and assign it.

Configuring the gateway

The binding currently supports the MySensors SerialGateway and the EthernetGateway. You are free to choose, which gateway to use. The first step to configure the binding is to activate the gateway/bridge.

You're able to configure the gateway via the PaperUI (Configuration->Things) or with an entry in a things file.

**If OH2 is not running with root privileges for example if you installed via apt please ensure that you are allowed to access the serial port. **

sudo usermod -a -G dialout openhab

Things file under "conf/things/demo.things".

SerialGateway:

Bridge mysensors:bridge-ser:gateway [ serialPort="/dev/pts/2", sendDelay=200 ] {
    /** define things connected to that bridge here */
  }

The serial gateway from MySensors works with a baud rate of 115.200. If you're using a different baud rate you need to add an additional parameter "baudRate":

Bridge mysensors:bridge-ser:gateway [ serialPort="/dev/pts/2", sendDelay=200, baudRate=115200 ] {
    /** define things connected to that bridge here */
  }

EthernetGateway:

Bridge mysensors:bridge-eth:gateway [ ipAddress="127.0.0.1", tcpPort=5003, sendDelay=200 ] {
     /** define things connected to that bridge here */
  }

MQTT Gateway:

The MQTT implementation is based on "org.eclipse.smarthome.mqtt" which will soon replace the current MQTT implementation in OpenHAB.

For OpenHAB 2.2:

The configuration file is: org.eclipse.smarthome.mqtt.cfg. The broker needs to be configured in this file:

mosquitto.url=tcp://192.168.2.3:1883
mosquitto.user=user
mosquitto.pwd=secret
mosquitto.retain=false

For OpenHAB 2.3:

The configuration file is: org.eclipse.smarthome.mqttbroker.cfg. The broker needs to be configured in this file:

name=mosquitto
host=192.168.2.3
port=1883
secure=false
username=user
password=secret
retain=false

Both files: mqtt.cfg AND org.eclipse.smarthome.mqtt.cfg may be used together: mqtt.cfg for the version 1.0 MQTT binding and eventbus and org.eclipse.smarthome.mqtt.cfg for the MySensors binding and future bindings.

Bridge mysensors:bridge-mqtt:gateway [ brokerName="mosquitto", topicPublish="mygateway1-in", topicSubscribe="mygateway1-out", startupCheckEnabled=false ] {
}

Skip startup check

In some cases you need to skip the startup check for I_VERSION. The binding asks the gateway for its version and if no answer is given the connection to the thing will fail.

A reason could be if you see a message like this:

[WARN ] [ome.core.thing.internal.ThingManager] - Initializing handler for thing 'mysensors:bridge-ser:MySGWKeller' takes more than 5000ms.

In this case the hardware OH2 is running on takes a bit too long to startup (due to the lack of CPU power).

To skip the startup check add an option startupCheckEnabled=false to the gateway/thing:

Bridge mysensors:bridge-eth:gateway [ ipAddress="127.0.0.1", tcpPort=5003, sendDelay=200, startupCheckEnabled=false ] {
     /** define things connected to that bridge here */
  }

The default is startupCheckEnabled=true!

Use Imperial instead of Metric

Some sensors, like temperature sensors, ask the controller on startup if values should be reported in metric or imperial. If you would like to receive imperial values you may add the option imperial=true in the corresponding gateway definition:

Bridge mysensors:bridge-eth:gateway [ ipAddress="127.0.0.1", tcpPort=5003, sendDelay=200, imperial=true ] {
     /** define things connected to that bridge here */
  }

Default is imperial=false!

Common parameters for all gateway types

Parameter Value Description
sendDelay Milliseconds The delay between messages send to the gateway
startupCheckEnabled boolean The software version is requested from the gateway at startup to ensure it's up and running
imperial boolean Metric answer with imperial instead of metric
networkSanCheckEnabled boolean Network sanity check periodically ensure that gateway is up and running
networkSanCheckInterval Minutes Network sanity check periodically ensure that gateway is up and running
networkSanCheckConnectionFailAttempts Number Number of retries to establish a connection to the gateway
networkSanCheckSendHeartbeat boolean If network sanity checker is running, send heartbeat to all nodes
networkSanCheckSendHeartbeatFailAttempts Number If nodes do not respond to heartbeat, you could configure how many retries the sanity check will do before disconnecting them

Configuring things

Assuming you have configured a bridge, the next step is to configure things. We use the place holder in the bridge configuration and fill it with content:

conf/things/demo.things:

  Bridge mysensors:bridge-ser:gateway [ serialPort="/dev/pts/2", sendDelay=200 ] {
	humidity 		hum01 	[ nodeId=172, childId=0 ]
	temperature		temp01 	[ nodeId=172, childId=1 ]
        light			light01 [ nodeId=105, childId=0, requestAck=true ]
        light			light02 [ nodeId=105, childId=1, requestAck=true ]
  }

Now, we've added an humidity sensor with a nodeId of 172 and childId of 0 according to your Arduino sketch, and a temperature sensor with (172,1).

Configuring items

Now we need the corresponding items:

conf/items/demo.items:

  Number hum01 	  "Humidity" { channel="mysensors:humidity:gateway:hum01:hum" }
  Number temp01	  "Temperature" { channel="mysensors:temperature:gateway:temp01:temp" }
  Switch light01  "Light01" { channel="mysensors:light:gateway:light01:status" }
  Switch light02  "Light02" { channel="mysensors:light:gateway:light02:status" }
  

In the channel configuration:

  mysensors: name of the binding
  humidity: thing type
  gateway: the bridge
  hum01: thing connected to the bridge
  hum: channel (there is at least one channel per thing)

If you want to know which things are supported and which channels they could listen to, have a look at: https://github.com/tobof/openhab2-addons/blob/MySensors_Binding/addons/binding/org.openhab.binding.mysensors/ESH-INF/thing/channel-types.xml

Configuring a sitemap

Last but not least we create or modify our sitemap:

conf/sitemaps/demo.sitemap:

  sitemap demo label="Main Menu" { 
	Frame { 
		Text item=hum01
		Text item=temp01 
                Switch item=light01
                Switch item=light02
	} 
	
  }

Enable ACK request for things

Only tested with light/status yet!

If you would like to receive an ACK for a command sent to an actuator add the requestAck option:

Bridge mysensors:bridge-ser:gateway [ serialPort="/dev/pts/6", sendDelay=200 ] {
    light           light01     [ nodeId=172, childId=2, requestAck=true ]
  }

If a message is NOT acknowledged by a node the binding retries to send the message five times. If no ACK is received after that the binding will try to revert the item to its old state. This only works, if a state is known (not NULL, for example at startup).

If the binding should not try to revert to the old status if no ACK was received use the option revertState=false.

Enable smart sleep for a node

In the MySensors network smart sleep may be used for nodes that are mostly sleeping. As a controller is not able to send a command to a sleeping node the node may activate smart sleep. If smart sleep is enabled a I_HEARTBEAT_RESPONSE message is send to the controller. The node will wait a short time (default 500 ms) if a message is received from the controller.

If smart sleep is enabled in the binding and a message is send by an item (button activated / light on, text send ...) the message is stored in a separate queue. If a I_HEARTBEAT_RESPONSE message is received from the node the queued message is send immediately.

Configuration in *.things:

light workLight01 [ nodeId=104, childId=2, smartSleep=true ]

The log output should look like:

20:36:41.093 [INFO ] [smarthome.event.ItemCommandEvent    ] - Item 'workLight01' received command OFF
20:36:41.095 [INFO ] [marthome.event.ItemStateChangedEvent] - workLight01 changed from ON to OFF
20:37:15.089 [DEBUG] [rs.internal.protocol.MySensorsReader] - 104;255;3;0;22;1251640
20:37:15.089 [DEBUG] [col.serial.MySensorsSerialConnection] - I_HEARTBEAT_RESPONSE received from 104.
20:37:15.089 [DEBUG] [col.serial.MySensorsSerialConnection] - Message for nodeId: 104 in queue needs to be send immediately!
20:37:15.089 [DEBUG] [rs.internal.protocol.MySensorsWriter] - Sending to MySensors: 104;2;1;0;2;0

Network Sanity Check

The sanity check tries to ensure if the connection to the MySensors bridge is still alive. It sends an I_VERSION message to the gateway and expects an answer. If no answer from the MySensors gateway is received the binding will try to reconnect to the gateway to establish a connection. The default is networkSanCheckEnabled, the sanity check is disabled.

To enable the sanity check insert:

Bridge mysensors:bridge-ser:gateway [ serialPort="/dev/pts/6", sendDelay=200, networkSanCheckEnabled=true ] {
...    
}
You can’t perform that action at this time.