From c5ae63d6c1360bb4dcbacea122e60e227485c9d2 Mon Sep 17 00:00:00 2001 From: Koen Vervloesem Date: Fri, 5 Jan 2024 19:08:10 +0100 Subject: [PATCH] [DOC] General documentation fixes, using Vale's Google style guide --- .github/ISSUE_TEMPLATE/feature_request.md | 6 ++++++ .github/pull_request_template.md | 3 +++ .gitignore | 3 +++ .pre-commit-config.yaml | 4 ++++ .vale.ini | 9 ++++++-- CODE_OF_CONDUCT.md | 7 ++---- README.md | 16 +++++++------- docs/README.md | 8 +++---- docs/install/install.md | 6 +++--- docs/participate/adding-decoders.md | 2 +- docs/participate/development.md | 2 +- docs/participate/support.md | 4 ++-- docs/prerequisites/broker.md | 2 +- docs/prerequisites/controller.md | 2 +- docs/use/use.md | 26 +++++++++++------------ 15 files changed, 59 insertions(+), 41 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 066b2d92..18466585 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -4,9 +4,15 @@ about: Suggest an idea for this project --- + + + **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. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 40ab1a0a..675cc385 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,10 @@ ## Description: + ## Checklist: - [ ] The pull request is done against the latest development branch - [ ] Only one feature/fix was added per PR and the code change compiles without warnings - [ ] I accept the [DCO](https://github.com/theengs/gateway/blob/development/docs/participate/development.md#developer-certificate-of-origin). + + diff --git a/.gitignore b/.gitignore index 3b0ed882..3cf6b36d 100644 --- a/.gitignore +++ b/.gitignore @@ -131,3 +131,6 @@ dmypy.json # VuePress node_modules/ + +# Vale styles +vale/styles/Google diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 68d0b392..6eb2f37a 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,6 +4,10 @@ repos: rev: 'v2.30.0' hooks: - id: vale + name: vale-sync + pass_filenames: false + args: [sync] + - id: vale - repo: https://github.com/astral-sh/ruff-pre-commit rev: 'v0.1.9' hooks: diff --git a/.vale.ini b/.vale.ini index e04a2835..61dd701d 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,10 @@ StylesPath = "vale/styles" -MinAlertLevel = error +MinAlertLevel = warning Vocab = Theengs +Packages = Google + [*.md] -BasedOnStyles = Vale +BasedOnStyles = Vale, Google +Google.Headings = NO +Google.WordList = NO +Google.We = NO diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index e65e92ae..bc157623 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -34,13 +34,10 @@ This Code of Conduct applies both within project spaces and in public spaces whe ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at untechnophile@gmail.com. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at untechnophile@gmail.com. The project team reviews and investigates all complaints, and responds in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version] - -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +This Code of Conduct is adapted from the [Contributor Covenant homepage](https://contributor-covenant.org), [version 1.4](https://contributor-covenant.org/version/1/4/). diff --git a/README.md b/README.md index 61fd7d66..1ddba85a 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ -**Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder). -It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html); LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, MiFlora... translates this information into a readable JSON format and pushes those to an MQTT broker. +**Theengs Gateway** is a multi-platform, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder). +It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html), including the LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, and MiFlora, and translates this information into a readable JSON format and pushes those to an MQTT broker. Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/), [ioBroker](https://www.iobroker.net/) or [Domoticz](https://domoticz.com/). -The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging Python and multi platform libraries. +The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop, or server by leveraging Python and multi-platform libraries. ![Gateway](https://github.com/theengs/home/raw/development/docs/img/Theengs-gateway-raspberry-pi.jpg) -**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway. +**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway home automation BLE sensors integration also works with Theengs Gateway. -The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro and many more. +The gateway retrieves data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro and many more. Full documentation for installation and usage can be found [here](https://theengs.github.io/gateway) @@ -34,9 +34,9 @@ python3 -m TheengsGateway -h Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories -> Fill in the URL `https://github.com/mihsu81/addon-theengsgw` -> Add. -2. You should now see "TheengsGateway HA Add-on" at the bottom list. -3. Click on "TheengsGateway", then click "Install". -4. Under the "Configuration" tab, change the settings appropriately (at least MQTT parameters), see [Parameters](#parameters). +2. You should now see **TheengsGateway HA Add-on** at the bottom list. +3. Click on **TheengsGateway**, then click **Install**. +4. Under the **Configuration** tab, change the settings appropriately (at least MQTT parameters), see [Parameters](#parameters). 5. Start the Add-on. ## Install Theengs Gateway as a snap diff --git a/docs/README.md b/docs/README.md index 1e255bef..24ef815a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,14 +4,14 @@ title: Theengs BLE MQTT gateway # Theengs BLE MQTT gateway **Theengs Gateway** is a multi platforms, multi devices BLE to MQTT gateway that leverages the [Theengs Decoder library](https://github.com/theengs/decoder). -It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html); LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, MiFlora... translates this information into a readable JSON format and pushes those to an MQTT broker. +It retrieves data from a wide range of [BLE sensors](https://decoder.theengs.io/devices/devices.html), including the LYWSD03MMC, CGD1, CGP1W, H5072, H5075, H5102, TH1, TH2, BBQ, CGH1, CGDK2, CGPR1, RuuviTag, WS02, WS08, TPMS, MiScale, LYWSD02, LYWSDCGQ, and MiFlora, and translates this information into a readable JSON format and pushes those to an MQTT broker. Enabling integration to IOT platforms or home automation controllers like [NodeRED](https://nodered.org/), [AWS IOT](https://aws.amazon.com/iot/), [Home Assistant](https://www.home-assistant.io/), [OpenHAB](https://www.openhab.org/), [FHEM](https://fhem.de/), [ioBroker](https://www.iobroker.net/) or [Domoticz](https://domoticz.com/). -The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop or server by leveraging Python and multi-platform libraries. +The gateway uses the Bluetooth Low Energy adapter of your Raspberry Pi, Windows, Apple desktop, laptop, or server by leveraging Python and multi-platform libraries. ![Gateway](https://github.com/theengs/home/raw/development/docs/img/Theengs-gateway-raspberry-pi.jpg) -**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway Home Automation BLE sensors integration will work also with Theengs gateway. +**Theengs Gateway** can be used as a standalone solution or as a complementary solution to [OpenMQTTGateway](https://docs.openmqttgateway.com/) as it uses the same MQTT topic structure and the same payload messages. Your OpenMQTTGateway home automation BLE sensors integration also works with Theengs Gateway. -The gateway will retrieve data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more. +The gateway retrieves data from BLE sensors from Govee, Xiaomi, Inkbird, Qingping, ThermoBeacon, Blue Maestro, and many more. diff --git a/docs/install/install.md b/docs/install/install.md index ea167989..81b0b052 100644 --- a/docs/install/install.md +++ b/docs/install/install.md @@ -29,9 +29,9 @@ python3 -m TheengsGateway -h Or by going to Settings -> Add-ons -> Add-on store -> ⁞ (Menu) -> Repositories -> Fill in the URL `https://github.com/mihsu81/addon-theengsgw` -> Add. -2. You should now see "TheengsGateway HA Add-on" at the bottom list. -3. Click on "TheengsGateway", then click "Install". -4. Under the "Configuration" tab, change the settings appropriately (at least MQTT parameters), see [Parameters](https://github.com/mihsu81/addon-theengsgw/blob/main/theengsgateway/DOCS.md#parameters). +2. You should now see **TheengsGateway HA Add-on** at the bottom list. +3. Click on **TheengsGateway**, then click **Install**. +4. Under the **Configuration** tab, change the settings appropriately (at least MQTT parameters), see [Parameters](https://github.com/mihsu81/addon-theengsgw/blob/main/theengsgateway/DOCS.md#parameters). 5. Start the Add-on. ## Install Theengs Gateway as a snap diff --git a/docs/participate/adding-decoders.md b/docs/participate/adding-decoders.md index 64142389..8579843c 100644 --- a/docs/participate/adding-decoders.md +++ b/docs/participate/adding-decoders.md @@ -1,5 +1,5 @@ # Adding decoders -Adding your device protocol to Theengs enable to increase interoperability and to create new use cases with your device. You will find below some guidance to do that. +Adding your device protocol to Theengs enables you to increase interoperability and to create new use cases with your device. Below is some guidance to do that. You can do a pull request directly to the [Decoder Repository](https://github.com/theengs/decoder) by leveraging the Theengs Decoder [example](https://theengs.github.io/decoder/participate/adding-decoders.html). diff --git a/docs/participate/development.md b/docs/participate/development.md index a350a2dd..bd473373 100644 --- a/docs/participate/development.md +++ b/docs/participate/development.md @@ -14,7 +14,7 @@ agree to follow the [code of conduct](https://github.com/theengs/gateway/blob/ma * Request for review. * We may suggest some changes, improvements or alternatives. -Some things that will increase the chance that your pull request is accepted: +Some things that increase the chance that your pull request is accepted: * Comment your code. * Ask eventually for design guidelines. diff --git a/docs/participate/support.md b/docs/participate/support.md index ce4ac7cb..971afeff 100644 --- a/docs/participate/support.md +++ b/docs/participate/support.md @@ -1,8 +1,8 @@ # Supporting the project -If you like the project and/or used it please consider supporting it! It can be done in different ways: +If you like the project and/or use it, please consider supporting us. It can be done in different ways: * Helping others in the [community](https://github.com/theengs/gateway/discussions) * [Contribute](development) to the [code](https://github.com/theengs/gateway) or the documentation, * Buy devices, boards or parts from the [compatible web site](https://compatible.openmqttgateway.com), the devices and parts linked use affiliated links, * Donate or sponsor the project [developers](https://github.com/theengs/gateway/graphs/contributors) -* Make a video or a blog article about what you have done with [TheengsGateway](https://github.com/theengs/gateway) and share it. \ No newline at end of file +* Make a video or a blog article about what you have done with [TheengsGateway](https://github.com/theengs/gateway) and share it. diff --git a/docs/prerequisites/broker.md b/docs/prerequisites/broker.md index 640d773d..9c96ed3d 100644 --- a/docs/prerequisites/broker.md +++ b/docs/prerequisites/broker.md @@ -1,5 +1,5 @@ # Broker -The broker will act as an intermediary between TheengsGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism. +The broker acts as an intermediary between TheengsGateway and your [controller](/prerequisites/controller), it can be seen as a centralized hub at the heart of your automation system. It carry on messages following a publish / subscribe mechanism. All the events or commands could pass by the broker. diff --git a/docs/prerequisites/controller.md b/docs/prerequisites/controller.md index 8ab65b47..2b63ce23 100644 --- a/docs/prerequisites/controller.md +++ b/docs/prerequisites/controller.md @@ -1,5 +1,5 @@ # Controller -MQTT enables you to connect easily a controller so as to monitor, control and automate scenarios. +MQTT enables you to connect easily a controller so as to monitor, control, and automate scenarios. The following controllers (and many other software) are compatible with MQTT: diff --git a/docs/use/use.md b/docs/use/use.md index 36379838..fc8728e0 100644 --- a/docs/use/use.md +++ b/docs/use/use.md @@ -37,7 +37,7 @@ The `mfr` key has the company name of the manufacturer as its value in two cases * The advertisement of the device has been successfully decoded, its manufacturer data have a company ID compliant to the Bluetooth specification, and it's no beacon (iBeacon, Microsoft Advertising Beacon). * The advertisement of the device can't be decoded. -Note that in the latter case, we can't guarantee that the manufacturer name is correct, as many devices are not compliant to the Bluetooth specification and encode their data in the bytes where the manufacturer ID should be. +Note that in the latter case, there's guarantee that the manufacturer name is correct, as many devices are not compliant to the Bluetooth specification and encode their data in the bytes where the manufacturer ID should be. ## Details options ### For a regular installation @@ -150,7 +150,7 @@ docker run --rm \ python -m TheengsGateway -H "192.168.1.17" -u "username" -p "password" -pt "home/TheengsGateway" ``` -## Scan every 55s +## Scan every 55 s ```shell python -m TheengsGateway -H "192.168.1.17" -u "username" -p "password" -pt "home/TheengsGateway" -tb 55 @@ -163,7 +163,7 @@ python -m TheengsGateway ``` ## MQTTtoMQTT decoding -Messages sent to the subscribe topic can be used for decoding BLE data and will be published to the publish topic. This allows for offloading the decode operation from other devices, such as an ESP32, to enhance performance. +Messages with BLE data sent to the subscribe topic are decoded, and the result is published to the publish topic. This allows for offloading the decode operation from other devices, such as an ESP32, to enhance performance. The data sent to the topic is expected to be formatted in JSON and MUST have at least an "id" entry. @@ -177,16 +177,16 @@ Example message: "txpower":12 } ``` -If possible, the data will be decoded and published. +If possible, the data is decoded and published. -[OpenMQTTGateway](https://docs.openmqttgateway.com/), proposes a [web upload](https://docs.openmqttgateway.com/upload/web-install.html) binary `esp32dev-ble-mqtt-undecoded` that will publish directly to 'home//BTtoMQTT` making it directly compatible with Theengs Gateway MQTTtoMQTT decoding feature. +[OpenMQTTGateway](https://docs.openmqttgateway.com/), proposes a [web upload](https://docs.openmqttgateway.com/upload/web-install.html) binary `esp32dev-ble-mqtt-undecoded` that publishes directly to 'home//BTtoMQTT` making it directly compatible with Theengs Gateway MQTTtoMQTT decoding feature. :::tip -By default Theengs Gateway will listen to `home/+/BTtoMQTT/undecoded`, if you have several ESP32 gateways with OpenMQTTGateway sending out MQTT messages with undecoded data, Theengs will pickup all of them and centralize the decoded BT sensor data in one place. +By default Theengs Gateway listens to `home/+/BTtoMQTT/undecoded`, if you have several ESP32 gateways with OpenMQTTGateway sending out MQTT messages with undecoded data, Theengs picks up all of them and centralizes the decoded BLE sensor data in one place. ::: ## Home Assistant auto discovery -If enabled (default), decoded devices will publish their configuration to Home Assistant to be discovered. +If enabled (default), decoded devices publish their configuration to Home Assistant to be discovered. - This can be enabled/disabled with the `-D` or `--discovery` command line argument with a value of 1 (enable) or 0 (disable). - If you want to use Home Assistant discovery with other home automation gateways such as openHAB, set `-Dh` or `--hass_discovery` to 0 (disable). - The discovery topic can be set with the `-Dt` or `--discovery_topic` command line argument. @@ -213,7 +213,7 @@ ExecStart=/usr/lib/bluetooth/bluetoothd --experimental ``` :::tip -On other Linux variants the path might be slightly different. This can usually be seen by the commented out entries of `ExecStart=…` when editing bluetooth.service or with the `which bluetoothd` command. +On other Linux variants the path might be slightly different. This can usually be seen by the commented out entries of `ExecStart=…` when editing `bluetooth.service` or with the `which bluetoothd` command. ::: Save and close the file and then run the following commands: @@ -228,9 +228,9 @@ If you have specified the MAC addresses of [supported Bluetooth clocks](https:// Some Bluetooth clocks let you choose between 12-hour (AM/PM) and 24-hour format to show their time. Use the argument `--time_format 0` (default) for 24-hour format and `--time_format 1` for 12-hour format. -Note that the first time synchronization of each specified clock will happen at a random time in the next day. This way the connections to these devices will be spaced out in time. After this first time synchronization, Theengs Gateway will synchronize its time every 24 hours. +Note that the first time synchronization of each specified clock happens at a random time in the next day. This way the connections to these devices are spaced out in time. After this first time synchronization, Theengs Gateway synchronizes its time every 24 hours. -If a device isn't recognized as a supported clock, Theengs Gateway won't try to synchronize its time ever. But if there are other errors, such as connection errors or write errors (which could be temporary), the device will still be tried every 24 hours. +If a device isn't recognized as a supported clock, Theengs Gateway won't try to synchronize its time ever. But if there are other errors, such as connection errors or write errors (which could be temporary), the device is still tried every 24 hours. If you want to know which of your devices are supported by Theengs Gateway's time synchronization feature, run the following command: @@ -247,7 +247,7 @@ If you want to read encrypted advertisements, you need to add a bindkey for each TheengsGateway --bindkeys 00:11:22:33:44:55:66 0dc540f3025b474b9ef1085e051b1add AA:BB:CC:DD:EE:FF 6385424e1b0341109942ad2a6bb42e58 ``` -Theengs Gateway will then use the bindkey 0dc540f3025b474b9ef1085e051b1add to decrypt all advertisements from device 00:11:22:33:44:55:66 and bindkey 6385424e1b0341109942ad2a6bb42e58 for all advertisements from device AA:BB:CC:DD:EE:FF. +Theengs Gateway then uses the bindkey `0dc540f3025b474b9ef1085e051b1add` to decrypt all advertisements from device `00:11:22:33:44:55:66` and bindkey `6385424e1b0341109942ad2a6bb42e58` for all advertisements from device `AA:BB:CC:DD:EE:FF`. ## Resolving random private addresses If you want to resolve random private addresses into a device's identity address, you need to add an identity resolving key (IRK) for each identity address with the `--identities` argument. For example: @@ -256,7 +256,7 @@ If you want to resolve random private addresses into a device's identity address TheengsGateway --identities 00:11:22:33:44:55:66 0dc540f3025b474b9ef1085e051b1add AA:BB:CC:DD:EE:FF 6385424e1b0341109942ad2a6bb42e58 ``` -Theengs Gateway will then use the identity resolving key 0dc540f3025b474b9ef1085e051b1add to resolve random private addresses from device 00:11:22:33:44:55:66 and identity resolving key 6385424e1b0341109942ad2a6bb42e58 to resolve random private addresses from device AA:BB:CC:DD:EE:FF. +Theengs Gateway then uses the identity resolving key `0dc540f3025b474b9ef1085e051b1add` to resolve random private addresses from device `00:11:22:33:44:55:66` and identity resolving key `6385424e1b0341109942ad2a6bb42e58` to resolve random private addresses from device `AA:BB:CC:DD:EE:FF`. The identity resolving key can also be specified as a Base64 encoded string, such as `"MGRjNTQwZjMwMjViNDc0YjllZjEwODVlMDUxYjFhZGQ="`. @@ -264,7 +264,7 @@ The identity resolving key can also be specified as a Base64 encoded string, suc To get the Bluetooth Identity Address of an Apple device go to ***Settings*** > ***General*** > ***About*** on the device and view the MAC address stated under **Bluetooth**. -On a Mac associated with your devices open the **Keychain Access** application and search the **login** or **iCloud** Keychain - depending on whether you have iCloud *Password and Keychain* syncing activated or not - for either Bluetooth or the identity address you got for your device as described above. +On a Mac associated with your devices open the **Keychain Access** application and search the **login** or **iCloud** Keychain - depending on whether you have iCloud *Password and Keychain* syncing activated or not - for either Bluetooth or the identity address you got for your device as described previously. When you open the Keychain entry, in the Account field it should confirm the identity address as `Public AA:BB:CC:DD:EE:FF`.