From cc404acb2007d9c86f7df834a8ea510aa2f73fd2 Mon Sep 17 00:00:00 2001 From: mueslo Date: Fri, 9 Mar 2018 12:15:10 +0100 Subject: [PATCH 1/6] Add device_tracker.openwrt --- .../device_tracker.openwrt.markdown | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 source/_components/device_tracker.openwrt.markdown diff --git a/source/_components/device_tracker.openwrt.markdown b/source/_components/device_tracker.openwrt.markdown new file mode 100644 index 00000000000..4c319341590 --- /dev/null +++ b/source/_components/device_tracker.openwrt.markdown @@ -0,0 +1,48 @@ +--- +layout: page +title: "OpenWRT" +description: "Instructions how to integrate OpenWRT routers into Home Assistant." +date: 2018-03-09 12:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: openwrt.png +ha_category: Presence Detection +ha_release: pre 0.7 +--- + +There are _multiple_ ways of integrating an OpenWRT router for presence detction. A broad distinction can be made between presence detection methods which actively scan for devices (by default every 12 seconds) and those that are notified by some external service on changes. It is essentially a problem of synchronizing states between two remote machines. + +* __active scanning__ + Scan for devices regularly. + * Advantages: + * robust on an unreliable set-up where the the router may not be reachable occasionally + * Disadvantages: + * average six-second delay between connecting and being registered as `home` + * lots of unnecessary network requests + * Examples: + * [ubus](/components/device_tracker.ubus/) + * [luci](/components/device_tracker.luci/) +* __passive/event-based__ + External services which notify Home Assistant of devices vie the [REST API endpoint](/developers/rest_api.markdown). + * Advantages: + * devices typically registered in under one second when they connect + * very few network requests + * Disadvantages: + * prone to missed events when connectivity between Home Assistant and the router is not guaranteed + * Examples: + * [openwrt_hass_devicetracker](https://github.com/mueslo/openwrt_hass_devicetracker) + * your own custom script + +### Event-based device tracker + +This can be achieved by running a simple shell script on the OpenWRT router which calls the appropriate Home Assistant service. An OpenWRT package which does this is listed above. As this method directly calls the [service API](/developers/rest_api.markdown#post-apiservicesltdomainltservice), no special configuration is necessary on the Home Assistant side, except for ensuring the device_tracker API is running, which is achieved by adding the following to your `configuration.yaml` file: + +```yaml +device_tracker: +``` + +To get the best of both worlds, you can combine the two approaches, running both a periodic device scanner and an event-based device tracker. + +See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. From 4070d0a009e5c9f38f6dfa5fcf65b6f1875b37e2 Mon Sep 17 00:00:00 2001 From: mueslo Date: Fri, 9 Mar 2018 12:19:26 +0100 Subject: [PATCH 2/6] Update device_tracker.luci.markdown --- source/_components/device_tracker.luci.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_components/device_tracker.luci.markdown b/source/_components/device_tracker.luci.markdown index 621f70a9054..16f8b5d7431 100644 --- a/source/_components/device_tracker.luci.markdown +++ b/source/_components/device_tracker.luci.markdown @@ -12,7 +12,7 @@ ha_category: Presence Detection ha_release: pre 0.7 --- -_This is one of the two ways we support OpenWRT. If you encounter problems, try [ubus](/components/device_tracker.ubus/)._ +_This is one of multiple ways we support OpenWRT. For an overview, see [openwrt](/components/device_tracker.openwrt/)._ This is a presence detection scanner for OpenWRT using [luci](http://wiki.openwrt.org/doc/techref/luci). From 933c3b3cd2e7d9535bec1618f1ec84052ada93d4 Mon Sep 17 00:00:00 2001 From: mueslo Date: Fri, 9 Mar 2018 12:20:03 +0100 Subject: [PATCH 3/6] Update device_tracker.ubus.markdown --- .../_components/device_tracker.ubus.markdown | 53 ++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/source/_components/device_tracker.ubus.markdown b/source/_components/device_tracker.ubus.markdown index 3df045db24b..54e25ebd9b1 100644 --- a/source/_components/device_tracker.ubus.markdown +++ b/source/_components/device_tracker.ubus.markdown @@ -12,7 +12,58 @@ ha_category: Presence Detection ha_release: 0.7.6 --- -_This is one of the two ways we support OpenWRT. If you encounter problems, try [luci](/components/device_tracker.luci/)._ +_This is one of the multiple ways we support OpenWRT. If you encounter problems, see [openwrt](--- +layout: page +title: "OpenWRT (luci)" +description: "Instructions how to integrate OpenWRT routers into Home Assistant." +date: 2015-03-23 19:59 +sidebar: true +comments: false +sharing: true +footer: true +logo: openwrt.png +ha_category: Presence Detection +ha_release: pre 0.7 +--- + +_This is one of multiple ways we support OpenWRT. For an overview, see [openwrt](/components/device_tracker.openwrt/)._ + +This is a presence detection scanner for OpenWRT using [luci](http://wiki.openwrt.org/doc/techref/luci). + +

+This component requires a [workaround](https://github.com/home-assistant/home-assistant/issues/1258#issuecomment-252469880) when using luci with HTTPS and a self-signed certificate. +

+ +Before this scanner can be used you have to install the luci RPC package on OpenWRT: + +```bash +# opkg install luci-mod-rpc +``` + +To use this device tracker in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +device_tracker: + - platform: luci + host: ROUTER_IP_ADDRESS + username: YOUR_ADMIN_USERNAME + password: YOUR_ADMIN_PASSWORD +``` + +Configuration variables: + +- **host** (*Required*): The IP address of your router, e.g. `192.168.1.1`. +- **username** (*Required*): The username of an user with administrative privileges, usually `admin`. +- **password** (*Required*): The password for your given admin account. + +See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. + +

+Some installations have [a small bug](https://github.com/openwrt/luci/issues/576). The timeout for luci RPC calls is not set and this makes the call fail. +

+ +)._ This is a presence detection scanner for [OpenWRT](https://openwrt.org/) using [ubus](http://wiki.openwrt.org/doc/techref/ubus). It scans for changes in `hostapd.*`, which will detect and report changes in devices connected to the access point on the router. From 7ba9794a09eb5da22e51cdca904c2b6fd180c996 Mon Sep 17 00:00:00 2001 From: mueslo Date: Fri, 9 Mar 2018 12:21:49 +0100 Subject: [PATCH 4/6] Update device_tracker.ubus.markdown --- source/_components/device_tracker.ubus.markdown | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/source/_components/device_tracker.ubus.markdown b/source/_components/device_tracker.ubus.markdown index 54e25ebd9b1..5f9cb6206ba 100644 --- a/source/_components/device_tracker.ubus.markdown +++ b/source/_components/device_tracker.ubus.markdown @@ -12,20 +12,6 @@ ha_category: Presence Detection ha_release: 0.7.6 --- -_This is one of the multiple ways we support OpenWRT. If you encounter problems, see [openwrt](--- -layout: page -title: "OpenWRT (luci)" -description: "Instructions how to integrate OpenWRT routers into Home Assistant." -date: 2015-03-23 19:59 -sidebar: true -comments: false -sharing: true -footer: true -logo: openwrt.png -ha_category: Presence Detection -ha_release: pre 0.7 ---- - _This is one of multiple ways we support OpenWRT. For an overview, see [openwrt](/components/device_tracker.openwrt/)._ This is a presence detection scanner for OpenWRT using [luci](http://wiki.openwrt.org/doc/techref/luci). From c8343de48ed17c8c805819e48f6004fdb3c3b017 Mon Sep 17 00:00:00 2001 From: mueslo Date: Fri, 9 Mar 2018 12:51:12 +0100 Subject: [PATCH 5/6] Add linkable heading --- source/_components/device_tracker.openwrt.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_components/device_tracker.openwrt.markdown b/source/_components/device_tracker.openwrt.markdown index 4c319341590..a5e0f0c349a 100644 --- a/source/_components/device_tracker.openwrt.markdown +++ b/source/_components/device_tracker.openwrt.markdown @@ -35,7 +35,7 @@ There are _multiple_ ways of integrating an OpenWRT router for presence detction * [openwrt_hass_devicetracker](https://github.com/mueslo/openwrt_hass_devicetracker) * your own custom script -### Event-based device tracker +### {% linkable_title Event-based device tracker %} This can be achieved by running a simple shell script on the OpenWRT router which calls the appropriate Home Assistant service. An OpenWRT package which does this is listed above. As this method directly calls the [service API](/developers/rest_api.markdown#post-apiservicesltdomainltservice), no special configuration is necessary on the Home Assistant side, except for ensuring the device_tracker API is running, which is achieved by adding the following to your `configuration.yaml` file: From 3ca4b48dca858298661f1ebf8b7b6b4f729ea392 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Fri, 23 Mar 2018 21:11:53 +0100 Subject: [PATCH 6/6] :pencil2: Tweak --- source/_components/device_tracker.openwrt.markdown | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/_components/device_tracker.openwrt.markdown b/source/_components/device_tracker.openwrt.markdown index a5e0f0c349a..2f4b0f5a18e 100644 --- a/source/_components/device_tracker.openwrt.markdown +++ b/source/_components/device_tracker.openwrt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenWRT" -description: "Instructions how to integrate OpenWRT routers into Home Assistant." +description: "Instructions on how to integrate OpenWRT routers into Home Assistant." date: 2018-03-09 12:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Presence Detection ha_release: pre 0.7 --- -There are _multiple_ ways of integrating an OpenWRT router for presence detction. A broad distinction can be made between presence detection methods which actively scan for devices (by default every 12 seconds) and those that are notified by some external service on changes. It is essentially a problem of synchronizing states between two remote machines. +There are _multiple_ ways of integrating an OpenWRT router for presence detection. A broad distinction can be made between presence detection methods which actively scan for devices (by default every 12 seconds) and those that are notified by some external service on changes. It is essentially a problem of synchronizing states between two remote machines. * __active scanning__ Scan for devices regularly. @@ -25,7 +25,7 @@ There are _multiple_ ways of integrating an OpenWRT router for presence detction * [ubus](/components/device_tracker.ubus/) * [luci](/components/device_tracker.luci/) * __passive/event-based__ - External services which notify Home Assistant of devices vie the [REST API endpoint](/developers/rest_api.markdown). + External services which notify Home Assistant of devices via the [REST API endpoint](/developers/rest_api.markdown). * Advantages: * devices typically registered in under one second when they connect * very few network requests