From fc20eb5c59dc3b029b648fff340c24dadc9ed1f3 Mon Sep 17 00:00:00 2001 From: jptrsn Date: Wed, 10 Jul 2019 19:51:59 -0400 Subject: [PATCH 1/3] Added more information about generic BLE hardware --- docs/beacons.md | 18 +++++++++++++----- docs/generic_ble.md | 26 ++++++++++++++++++++++++++ docs/home_assistant.md | 4 ++-- docs/index.md | 8 ++++++-- 4 files changed, 47 insertions(+), 9 deletions(-) create mode 100644 docs/generic_ble.md diff --git a/docs/beacons.md b/docs/beacons.md index 9dcd3ed..64eab48 100644 --- a/docs/beacons.md +++ b/docs/beacons.md @@ -6,8 +6,16 @@ Generic beacon hardware should be compatible, provided it meets a beacon standar * [eBay](https://www.ebay.com/sch/i.html?_nkw=nrf51822+ibeacon) * [Ali Express](https://www.aliexpress.com/wholesale?SearchText=nrf51822+ibeacon). -## Non-beacon Hardware -Some other devices that advertise as BLE (such as the Mi Flora plant sensors or the Mi Band fitness tracker) can also be tracked, as long as you can scan the device and see its hardware ID. Here is a list of devices known to be "trackable": -* MiFlora plant sensor -* MiBand 2 Fitness tracker -* [Puck-JS](https://www.espruino.com/Puck.js), if programmed to [broadcast beacon packets](https://gist.github.com/jptrsn/d6cb9b9cdbcd41f3500708f8b694cad2 "An example project to broadcast iBeacon packets") +## configuration.yaml +Here is an example of how an entry into your `configuration.yaml` file should look: +```yaml +sensor: + +# One entry for each beacon you want to track + - platform: mqtt_room + device_id: "fda50693a4e24fb1afcfc6eb07647825-5-0" # Note that major version must match, but any minor version will be ignored + name: 'iBeacon Room Presence' + state_topic: 'room_presence' + timeout: 60 + away_timeout: 120 +``` diff --git a/docs/generic_ble.md b/docs/generic_ble.md new file mode 100644 index 0000000..71509f2 --- /dev/null +++ b/docs/generic_ble.md @@ -0,0 +1,26 @@ +# Generic BLE Hardware +Here is a list of devices known to be "trackable": +* MiFlora plant sensor +* MiBand 2 Fitness tracker +* [Puck-JS](https://www.espruino.com/Puck.js), if programmed to [broadcast beacon packets](https://gist.github.com/jptrsn/d6cb9b9cdbcd41f3500708f8b694cad2 "An example project to broadcast iBeacon packets") + +## Device ID +To track generic BLE advertisements, you will need to know the hardware MAC address of the device. You can use an app on your smart phone to scan for and identify the correct device - I recommend [NRF Connect](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) from [Nordic Semiconductor](https://play.google.com/store/apps/dev?id=7265678888812659353) for Android (and I believe there is an iOS version as well). + +Alternatively, you can subscribe to the `room_presence` topic and view what devices are being reported there. Note that modern smart phones will randomize their hardware MAC address when broadcasting advertisements, so you must use a beacon app to track your phone (see the [section on tracking phones](./android.html) for more information). + +To track the device, specify the `device_id` entry as the hardware MAC address, without the colons. + +## configuration.yaml +Here is an example of how an entry into your `configuration.yaml` file should look: +```yaml +sensor: + +# One entry for each beacon you want to track + - platform: mqtt_room + device_id: C80F104DC7EB # Match the Bluetooth MAC address of the device + name: 'Mi Band' + state_topic: 'room_presence' + timeout: 60 + away_timeout: 120 +``` diff --git a/docs/home_assistant.md b/docs/home_assistant.md index c7d78a8..133ab1f 100644 --- a/docs/home_assistant.md +++ b/docs/home_assistant.md @@ -1,12 +1,12 @@ # Home Assistant Configuration -Once the ESP32 is running, it is important to configure Home Assistant to use the information from the MQTT topic to determine what devices to track. You can read the full documentation [on the Home Assistant website](https://www.home-assistant.io/components/sensor.mqtt_room/). It is critical that you configure your device IDs to include the Major and Minor versions, in the format ``{{beacon uuid}}-{{major}}-{{minor}}`` +Once the ESP32 is running, it is important to configure Home Assistant to use the information from the MQTT topic to determine what devices to track. You can read the full documentation [on the Home Assistant website](https://www.home-assistant.io/components/sensor.mqtt_room/). It is critical that you configure your device IDs to include the Major and Minor versions, in the format `{{beacon uuid}}-{{major}}-{{minor}}` ### configuration.yaml Here is an example of how an entry into your `configuration.yaml` file should look: ```yaml sensor: -# One entry for each BLE beacon you want to track +# One entry for each beacon you want to track - platform: mqtt_room device_id: "fda50693a4e24fb1afcfc6eb07647825-5-0" # Note that major version must match, but any minor version will be ignored name: 'iBeacon Room Presence' diff --git a/docs/index.md b/docs/index.md index b309fce..0e236c1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,8 +30,12 @@ It is possible to update the device using "Over the Air" (OTA) updates from the See the section on [configuring Home Assistant](./home_assistant.html). ## Trackable Devices -### Beacon Hardware -See the section on [tracking beacon hardware](./beacons.html) +### Beacons +See the section on [tracking beacons](./beacons.html) + +### Generic Bluetooth Low-Energy (BLE) Devices +Some other devices that advertise as BLE (such as the Mi Flora plant sensors or the Mi Band fitness tracker) can also be tracked, as long as you can scan the device and see its hardware ID. See the section on [tracking generic BLE devices](./generic_ble.html). + ### Tracking Android Phone [Read more here](./android.html) about getting your Android phone configured and tracked. From c0b9d29ef3f2646c7f2dd3fba05b4b6fd35e4ddc Mon Sep 17 00:00:00 2001 From: Edu_Coder Date: Wed, 10 Jul 2019 20:06:34 -0400 Subject: [PATCH 2/3] Update issue templates --- .github/ISSUE_TEMPLATE/bug_report.md | 36 ++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..c442e4a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,36 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**Configuration** +Please copy and paste your `settings_local.h` (or equivalent) with any sensitive data redacted. It can also help to see the entry for your sensors in your Home Assistant configuration. + +**Logs** +If possible, copy and paste any logs from the serial monitor from the time that you see the bug. + +**Hardware Details** +If the bug is related to tracking a specific piece of hardware (e.g. iBeacon, phone, etc), please enter any relevant details about the hardware (such as firmware version, MAC address, etc). + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Additional context** +Add any other context about the problem here. From abfe2eb844566d4e2b30a3f8c65a191e0b87637e Mon Sep 17 00:00:00 2001 From: Edu_Coder Date: Wed, 10 Jul 2019 20:09:46 -0400 Subject: [PATCH 3/3] Update issue templates --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/ISSUE_TEMPLATE/feature_request.md | 20 ++++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c442e4a..882835e 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -2,7 +2,7 @@ name: Bug report about: Create a report to help us improve title: '' -labels: '' +labels: bug assignees: '' --- diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..11fc491 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: enhancement +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here.