Add Integration docs

docs/.vuepress/config.js

@@ -11,14 +11,15 @@ module.exports = {
     sidebar: [
       ['/', 'Overview'],
       'BUILDING',
+      'VS15',
       'CHANGELOG',
       'PRIMER',
       'OPERATION',
       'DATA_FORMAT',
       'HARDWARE',
+      'INTEGRATION',
       'LINKS',
       'TESTS',
-      'VS15'
     ]
   }
 };

docs/INTEGRATION.md

@@ -0,0 +1,129 @@
+# Integration
+
+Integration of rtl_433 output into various home automation gateways.
+
+::: tip
+If you are a user of one these systems, please help to confirm and extend the information here.
+:::
+
+## openHAB
+
+[openHAB](https://www.openhab.org/) - open source automation software for your home
+
+See the wiki page https://github.com/merbanan/rtl_433/wiki/How-to-integrate-rtl_433-sensors-into-openHAB-via-MQTT
+
+Some help comes from https://community.openhab.org/t/rtl-433-to-mqtt/80652/3
+
+Run
+
+    rtl_433 -F "mqtt://192.168.178.42:1883,retain=0,devices=sensors/rtl_433/P[protocol]/C[channel]"
+
+This produces some topics in the broker like this:
+
+    sensors/rtl_433/P25/C1/id 147
+    sensors/rtl_433/P25/C1/temperature_C 33.200001
+    sensors/rtl_433/P25/C1/rain_mm 107.699997
+    sensors/rtl_433/P25/C1/battery_ok 1
+    sensors/rtl_433/P25/C1/mic CRC
+
+You can easily set up some MQTT things then:
+
+    Bridge mqtt:broker:My-MQTT "MQTT Broker" @ "RTL433" [
+      host="192.168.x.x",
+      secure=false,
+      port=1883,
+      qos=0,
+      retain=false,
+      clientid="Oh2Mqtt2Thing",
+      keep_alive_time=30000,
+      reconnect_time=60000
+    ]
+    {
+        Thing topic RTL_433 "433MHz Empfänger" @ "RTL433"  {
+          Channels:
+              Type number : temp "Temperatur" [ stateTopic="sensors/rtl_433/P25/C1/temperature_C" ]
+              Type number : hum  "Luftfeuchtigkeit" [ stateTopic="sensors/rtl_433/P25/C1/humidity" ]
+              Type switch : batt "Battery schwach" [ stateTopic="sensors/rtl_433/P25/C1/battery", transformationPattern="MAP:battery.map"]
+        }
+    }
+
+## Home Assistant
+
+[Home Assistant](https://www.home-assistant.io/) - Open source home automation
+
+Home Assistant has good MQTT support and can read rtl_433 event topics.
+
+::: warning
+Example needed
+:::
+
+See also [rtl_433_mqtt_hass.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_mqtt_hass.py)
+MQTT Home Assistant auto discovery.
+
+## Domoticz
+
+[Domoticz](http://www.domoticz.com/) - Home Automation System
+
+Domoticz has built-in support for reading from rtl_433 using pipes.
+
+There is also a newer plugin using MQTT: [enesbcs/pyrtl433](https://github.com/enesbcs/pyrtl433).
+
+::: warning
+Testing and example needed
+:::
+
+# NodeRED
+
+[NodeRED](https://nodered.org/) - Flow-based programming for the Internet of Things
+
+Node RED has built-in support for reading from MQTT and thus rtl_433 events.
+
+::: warning
+Example needed
+:::
+
+## Databases
+
+You likely need to filter and transform rtl_433's output before sending it to a database.
+It's recommended you read the JSON data and process it to your specific requirements.
+
+Some example pipes/relays for rtl_433 JSON data. Should work with Python 2 and also Python 3.
+
+The `pipe` examples read JSON output from `rtl_433` using a pipe, i.e.
+
+    rtl_433 -F json ... | rtl_433_statsd_pipe.py
+
+The `relay` examples consumes the (UDP) Syslog output from rtl_433 (or a legacy plain JSON datagram).
+Basically run `rtl_433` with `-F syslog:127.0.0.1:1433` and the relay script as an unrelated process, i.e.
+
+    rtl_433_mqtt_relay.py &
+    rtl_433 -F syslog:127.0.0.1:1433
+
+### RRD
+
+See [rtl_433_rrd_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_rrd_relay.py)
+
+### Statsd
+
+See [rtl_433_statsd_pipe.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_statsd_pipe.py)
+See [rtl_433_statsd_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_statsd_relay.py)
+
+### Collectd
+
+See [rtl_433_collectd_pipe.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_collectd_pipe.py)
+
+### Graphite
+
+See [rtl_433_graphite_relay.py](https://github.com/merbanan/rtl_433/tree/master/examples/rtl_433_graphite_relay.py)
+
+### InfluxDB
+
+TBD.
+
+### MySQL
+
+TBD.
+
+### Sqlite
+
+TBD.

docs/OPERATION.md

@@ -439,14 +439,14 @@ Use `-F mqtt` to add an output in MQTT format.
 Specify MQTT server with e.g. `-F mqtt://localhost:1883`.
 
 Add MQTT options with e.g. `-F "mqtt://host:1883,opt=arg"`.
-Supported MQTT options are: `user=foo`, `pass=bar`, `retain[=0|1]`, `<format>[=topic]`.
+Supported MQTT options are: `user=foo`, `pass=bar`, `retain[=0|1]`, `<format>[=<topic>]`.
 
 Supported MQTT formats: (default is all formats)
 - `events`: posts JSON event data
 - `states`: posts JSON state data
 - `devices`: posts device and sensor info in nested topics
 
-The topic string will expand keys like [/model], see below.
+The `<topic>` string will expand keys like `[/model]`, see below.
 E.g. `-F "mqtt://localhost:1883,user=USERNAME,pass=PASSWORD,retain=0,devices=rtl_433[/id]"`
 
 ### MQTT Format Strings
@@ -457,9 +457,10 @@ Use format strings of:
 - `[token:default]` expand to token or default
 - `[/token]` expand to token with leading slash or nothing
 - `[/token:default]` expand to token or default with leading slash
-- the channel-or-id (replaceid) would only be possible with an extra token for that.
 
-Tokens are `type`, `model`, `subtype`, `channel`, `id` for now.
+Tokens are `type`, `model`, `subtype`, `channel`, `id`, and `protocol` for now.
+
+Note that for `protocol` to be available you first need to add it to the meta-data with `-M protocol`.
 
 Examples:
 
@@ -470,9 +471,9 @@ Examples:
 - ...
 
 Defaults are a base topic of `rtl_433/<hostname>/` continued
-- for "devices" with `devices[/type][/model][/subtype][/channel][/id]`
-- for "events" with `events`
-- for "states" with `states`
+- for `devices` with `devices[/type][/model][/subtype][/channel][/id]`
+- for `events` with `events`
+- for `states` with `states`
 
 ### SYSLOG output
 

docs/PRIMER.md

@@ -50,4 +50,8 @@ There are specialized chips like the [EV1527](https://www.sunrom.com/get/206000)
 
 868 is also interesting. Mostly FSK is used, where 433 mostly uses OOK (ASK).
 
+> I would like to send a doorbell button push to MQTT. rtl_433 doesn't decode it, but it's a simple button, so I only need a trigger event. With rtl_433 -a -R 0 I am able to catch the button with {25}... code. What is the correct way to send the raw data to MQTT?
+
+Use `-A` and note the `-X` line. Then use that to write a flex decoder. See e.g. [EV1527-PIR-Sgooway.conf](https://github.com/merbanan/rtl_433/blob/master/conf/EV1527-PIR-Sgooway.conf).
+
 Have fun.

docs/package.json

@@ -7,6 +7,8 @@
     "docs:build": "vuepress build"
   },
   "devDependencies": {
-    "vuepress": "^0.14.11"
+    "vuepress": "^1.0.0",
+    "@vuepress/plugin-back-to-top": "^1.0.0",
+    "@vuepress/plugin-medium-zoom": "^1.0.0"
   }
 }