Skip to content

Commit 5b5d2e5

Browse files
MartinHjelmareMartinHjelmare
authored
Add mysensors MQTT client gateway docs (home-assistant#841)
* Add mysensors MQTT client gateway docs * Add note about not all 2.0 feautures are supported
1 parent 2eb5b35 commit 5b5d2e5

File tree

1 file changed

+114
-13
lines changed

1 file changed

+114
-13
lines changed

‎source/_components/mysensors.markdown

Lines changed: 114 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
layout: page
33
title: "MySensors"
44
description: "Instructions how to integrate MySensors sensors into Home Assistant."
5-
date: 2016-04-21 13:30 +0100
5+
date: 2016-08-26 23:00 +0200
66
sidebar: true
77
comments: false
88
sharing: true
@@ -16,7 +16,7 @@ The [MySensors](https://www.mysensors.org) project combines Arduino boards with
1616

1717
### {% linkable_title Configuration %}
1818

19-
Integrate your Serial or Ethernet MySensors Gateway by adding the following to your `configuration.yaml` file:
19+
Integrate your Serial, Ethernet or MQTT Client MySensors Gateway by adding the following to your `configuration.yaml` file:
2020

2121
```yaml
2222
# Example configuration.yaml entry
@@ -31,43 +31,144 @@ mysensors:
3131
- device: '192.168.1.18'
3232
persistence_file: 'path/mysensors3.json'
3333
tcp_port: 5003
34+
- device: mqtt
35+
persistence_file: 'path/mysensors4.json'
36+
topic_in_prefix: 'mygateway1-out'
37+
topic_out_prefix: 'mygateway1-in'
3438
debug: true
35-
persistence: true
36-
version: '1.5'
3739
optimistic: false
40+
persistence: true
41+
retain: true
42+
version: 2.0
3843
```
3944
4045
Configuration variables:
4146
42-
- **device** (*Required*): The path to the serial gateway where it is connected to your Home Assistant host, or the address of the tcp ethernet gateway. Resolving DNS addresses is theoretically supported but not tested.
47+
- **device** (*Required*): The path to the serial gateway where it is connected to your Home Assistant host, or the address of the tcp ethernet gateway, or `mqtt` to setup the MQTT gateway. Resolving DNS addresses is theoretically supported but not tested.
4348
- **baud_rate** (*Optional*): Specifies the baud rate of the connected serial gateway. Default is 115200.
4449
- **tcp_port** (*Optional*): Specifies the port of the connected tcp ethernet gateway. Default is 5003.
50+
- **topic_in_prefix** (*Optional*): Set the prefix of the MQTT topic for messages coming from the MySensors gateway in to Home Assistant. Default is an empty string.
51+
- **topic_out_prefix** (*Optional*): Set the prefix of the MQTT topic for messages going from Home Assistant out to the MySensors gateway. Default is an empty string.
4552
- **debug** (*Optional*): Enable or disable verbose debug logging. Default is false.
4653
- **persistence** (*Optional*): Enable or disable local persistence of sensor information. If this is disabled, then each sensor will need to send presentation messages after Home Assistant starts. Default is true.
4754
- **persistence_file** (*Optional*): The path to a file to save sensor information. The file extension determines the file type. Currently supported file types are 'pickle' and 'json'.
48-
- **version** (*Optional*): Specifies the MySensors protocol version to use. Supports 1.4 and 1.5. Default is 1.4.
55+
- **version** (*Optional*): Specifies the MySensors protocol version to use. Supports 1.4, 1.5 and 2.0. Default is 1.4.
4956
- **optimistic** (*Optional*): Enable or disable optimistic mode for actuators (switch/light). Default is false. Set this to true if no state feedback from actuators is possible. Home Assistant will assume that the command succeeded and change state.
57+
- **retain** (*Optional*): Enable or disable retain flag for published messages from Home Assistant when using the MQTT gateway. Default is true.
58+
59+
<p class='note'>
60+
Not all features of MySensors 2.0 are yet supported by Home Assistant. As more features are added, they will be described here in the documentation. Go to the MySensors platform pages under "related components" to see what message types are currently supported.
61+
</p>
5062

5163
If you are using an original Arduino as a serial gateway, the port will be named `ttyACM*`. The exact number can be determined with the command shown below.
5264

5365
```bash
5466
$ ls /dev/ttyACM*
5567
```
5668

69+
If using the MQTT gateway, you also need to have the [MQTT component](/components/mqtt/) configured in Home Assistant. See below for a minimum MQTT configuration:
70+
71+
```yaml
72+
mqtt:
73+
client_id: home-assistant-1
74+
```
75+
76+
<p class='note'>
77+
The MQTT gateway requires MySensors version 2.0 and only the MQTT client gateway is supported.
78+
</p>
79+
5780
### {% linkable_title Presentation %}
5881

5982
Present a MySensors sensor or actuator, by following these steps:
6083

61-
1. Connect the serial gateway to your computer or the ethernet gateway to your network.
62-
2. Configure the MySensors component in configuration.yaml.
84+
1. Connect the serial gateway to your computer or the ethernet or MQTT gateway to your network.
85+
2. Configure the MySensors component in `configuration.yaml`.
6386
3. Start hass.
64-
4. Wait for "Connected to [device]" in the log output.
65-
5. Write and upload your MySensors sketch to the sensor. Make sure you:
66-
- Either use a manual node id, or AUTO for requesting a node id from the controller, in the begin method for initialization of the MySensors library.
87+
4. Write and upload your MySensors sketch to the sensor. Make sure you:
6788
- Send sketch name.
6889
- Present the sensor's S_TYPE.
69-
- Send at least one initial value per V_TYPE.
70-
6. Start the sensor.
90+
- Send at least one initial value per V_TYPE. In version 2.0 of MySensors this has to be done in the loop function. See below for an example in 2.0 of how to make sure the initial value has been received by the controller.
91+
5. Start the sensor.
92+
93+
```cpp
94+
/*
95+
* Documentation: http://www.mysensors.org
96+
* Support Forum: http://forum.mysensors.org
97+
*
98+
* http://www.mysensors.org/build/relay
99+
*/
100+
101+
#define MY_DEBUG
102+
#define MY_RADIO_NRF24
103+
#define MY_REPEATER_FEATURE
104+
#define MY_NODE_ID 1
105+
#include <SPI.h>
106+
#include <MySensors.h>
107+
#include <Bounce2.h>
108+
109+
#define RELAY_PIN 5
110+
#define BUTTON_PIN 3
111+
#define CHILD_ID 1
112+
#define RELAY_ON 1
113+
#define RELAY_OFF 0
114+
115+
Bounce debouncer = Bounce();
116+
bool state = false;
117+
bool initialValueSent = false;
118+
119+
MyMessage msg(CHILD_ID, V_STATUS);
120+
121+
void setup()
122+
{
123+
pinMode(BUTTON_PIN, INPUT_PULLUP);
124+
debouncer.attach(BUTTON_PIN);
125+
debouncer.interval(10);
126+
127+
// Make sure relays are off when starting up
128+
digitalWrite(RELAY_PIN, RELAY_OFF);
129+
pinMode(RELAY_PIN, OUTPUT);
130+
}
131+
132+
void presentation() {
133+
sendSketchInfo("Relay+button", "1.0");
134+
present(CHILD_ID, S_BINARY);
135+
}
136+
137+
void loop()
138+
{
139+
if (!initialValueSent) {
140+
Serial.println("Sending initial value");
141+
send(msg.set(state?RELAY_ON:RELAY_OFF));
142+
Serial.println("Requesting initial value from controller");
143+
request(CHILD_ID, V_STATUS);
144+
wait(2000, C_SET, V_STATUS);
145+
}
146+
if (debouncer.update()) {
147+
if (debouncer.read()==LOW) {
148+
state = !state;
149+
// Send new state and request ack back
150+
send(msg.set(state?RELAY_ON:RELAY_OFF), true);
151+
}
152+
}
153+
}
154+
155+
void receive(const MyMessage &message) {
156+
if (message.isAck()) {
157+
Serial.println("This is an ack from gateway");
158+
}
159+
160+
if (message.type == V_STATUS) {
161+
if (!initialValueSent) {
162+
Serial.println("Receiving initial value from controller");
163+
initialValueSent = true;
164+
}
165+
// Change relay state
166+
state = (bool)message.getInt();
167+
digitalWrite(RELAY_PIN, state?RELAY_ON:RELAY_OFF);
168+
send(msg.set(state?RELAY_ON:RELAY_OFF));
169+
}
170+
}
171+
```
71172

72173
Visit the [library api] of MySensors for more information.
73174

0 commit comments

Comments
 (0)