rasperrypi-home/hassio-plejd
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #203 from icanos/release/v0.8.0-beta

Browse source 
Merge Release/v0.8.0 beta to develop
This commit is contained in:
Victor 2021-06-14 10:23:36 +02:00 • committed by GitHub
commit 2b0c6cbb53
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 156 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

28
Details.md
View file

@ -1,28 +0,0 @@
# Details for Home Assistant beginners
If you can reach your Home Assistant at [http://homeassistant.local:8123](http://homeassistant.local:8123) the links below should work.
## Mosquitto
Head over to Supervisor -> Add-on Store and search for `mosquitto broker`.
Install it and then start [mosquito addon link](http://homeassistant.local:8123/hassio/addon/core_mosquitto/info)
## Add api user for Mosquito
Add a Home Assistant user for the Plejd addon to be able to connect to Mosquito [Configuration -> Users](http://homeassistant.local:8123/config/users)
Call the user e.g. `mqtt-api-user`, set a password and save
## Plejd
Follow the `Easy Installation` in [README.MD](plejd/README.md)
And `Configuration Parameters` on the same page.
The only parameters needing a value are
* site
* username
* password
* mqttUsername e.g. `mqtt-api-user`
* mqttPassword
Now you can start the Plejd add-on
## Where are the lights?
Head over to [Configuration -> Integrations](http://homeassistant.local:8123/config/integrations) and click Configure on MQTT
After this step a new `Mosquito broker` should appear on the same page. If everything was setup correctly. It will list your lights under
`1 entity`/`n entities`

33
plejd/CHANGELOG.md
View file

@ -1,10 +1,12 @@
# Changelog hassio-plejd Home Assistant Plejd addon # Changelog hassio-plejd Home Assistant Plejd addon
## 0.8.0-dev ## [0.8.0-beta](https://github.com/icanos/hassio-plejd/tree/0.8.0-beta) (2021-06-14)
[Full Changelog](https://github.com/icanos/hassio-plejd/compare/0.7.1...0.8.0-beta)
**BREAKING - READ BELOW FIRST** **BREAKING - READ BELOW FIRST**
Release 0.8 will break ALL EXISTING DEVICES. Unique mqtt id:s will change, meaning HA will create new devices. Scenes will be added as scenes not as switches. Devices will be installed to Areas named by the rooms defined in the Plejd app (can be changed) Release 0.8 and later will break ALL EXISTING DEVICES from earlier versions. Unique mqtt id:s will change, meaning HA will create new devices. Scenes will be added as scenes not as switches. Devices will be installed to Areas named by the rooms defined in the Plejd app (can be changed)
Recommendations to minimize impact Recommendations to minimize impact
@ -14,6 +16,30 @@ Recommendations to minimize impact
- Go to Configuration => Integration => MQTT. Go to entities and after that devices and remove all Plejd devices (should be listed as unavailable) - Go to Configuration => Integration => MQTT. Go to entities and after that devices and remove all Plejd devices (should be listed as unavailable)
- Upgrade addon to latest version and start - Upgrade addon to latest version and start
- All devices should now be back. With luck they will have the same HA id:s as before so most things should work. Room assignments, icons, automations, scenes, etc will have to be gone though. - All devices should now be back. With luck they will have the same HA id:s as before so most things should work. Room assignments, icons, automations, scenes, etc will have to be gone though.
- If all else fails you can uninstall the Plejd addon and the Mqtt addon (which should remove all Mqtt devices after restart), re-install and get back the same device id:s as you had before.
**Closed issues:**
- Configuration instruction outdated [\#189](https://github.com/icanos/hassio-plejd/issues/189)
- Cant turn on lights after update [\#183](https://github.com/icanos/hassio-plejd/issues/183)
- Discovery finds lights but claims not to [\#182](https://github.com/icanos/hassio-plejd/issues/182)
- MQTTS connection problems with mqtt@~3.0.0 [\#181](https://github.com/icanos/hassio-plejd/issues/181)
- Adding repository to HACS [\#180](https://github.com/icanos/hassio-plejd/issues/180)
- WPH-01 buttons to trigger generic automations in HA [\#172](https://github.com/icanos/hassio-plejd/issues/172)
- Scene id and device id can overlap meaning mqtt commands overlap [\#161](https://github.com/icanos/hassio-plejd/issues/161)
- Add to "Tested on" section [\#122](https://github.com/icanos/hassio-plejd/issues/122)
- USB Bluetooth adapter [\#101](https://github.com/icanos/hassio-plejd/issues/101)
- Ignores devices if they have same name [\#91](https://github.com/icanos/hassio-plejd/issues/91)
- Scene does not change state [\#85](https://github.com/icanos/hassio-plejd/issues/85)
**Merged pull requests:**
- Added more documentation to install steps [\#201](https://github.com/icanos/hassio-plejd/pull/201) ([polyzois](https://github.com/polyzois))
- Fix for issue discussed in \#198. [\#199](https://github.com/icanos/hassio-plejd/pull/199) ([faanskit](https://github.com/faanskit))
- Suggested Area and fix for \#189 [\#192](https://github.com/icanos/hassio-plejd/pull/192) ([faanskit](https://github.com/faanskit))
- Support for WPH-01 and WRT-01 added. [\#188](https://github.com/icanos/hassio-plejd/pull/188) ([faanskit](https://github.com/faanskit))
- Refactor unique id handling throughout the addon [\#179](https://github.com/icanos/hassio-plejd/pull/179) ([SweVictor](https://github.com/SweVictor))
- Update README.md [\#178](https://github.com/icanos/hassio-plejd/pull/178) ([zissou1](https://github.com/zissou1))
## [0.7.1](https://github.com/icanos/hassio-plejd/tree/0.7.1) (2021-03-25) ## [0.7.1](https://github.com/icanos/hassio-plejd/tree/0.7.1) (2021-03-25)
@ -23,6 +49,9 @@ Recommendations to minimize impact
- Can't connect to device: TypeError: Cannot read property 'dimmable' [\#175](https://github.com/icanos/hassio-plejd/issues/175) - Can't connect to device: TypeError: Cannot read property 'dimmable' [\#175](https://github.com/icanos/hassio-plejd/issues/175)
**Merged pull requests:**
- Release 0.7.1 [\#177](https://github.com/icanos/hassio-plejd/pull/177) ([SweVictor](https://github.com/SweVictor))
## [0.7.0](https://github.com/icanos/hassio-plejd/tree/0.7.0) (2021-03-23) ## [0.7.0](https://github.com/icanos/hassio-plejd/tree/0.7.0) (2021-03-23)
[Full Changelog](https://github.com/icanos/hassio-plejd/compare/0.6.2...0.7.0) [Full Changelog](https://github.com/icanos/hassio-plejd/compare/0.6.2...0.7.0)

55
plejd/Details.md Normal file
View file

@ -0,0 +1,55 @@
# Details regarding installation
If you can reach your Home Assistant at [http://homeassistant.local:8123](http://homeassistant.local:8123) the links below should work.
## Mosquitto
Head over to Supervisor -> Add-on Store and search for `mosquitto broker`.
Install it and then start [mosquito addon link](http://homeassistant.local:8123/hassio/addon/core_mosquitto/info)
## Add api user for Mosquito
Add a Home Assistant user for the Plejd addon to be able to connect to Mosquito [Configuration -> Users](http://homeassistant.local:8123/config/users)
Call the user e.g. `mqtt-api-user`, set a password and save
## Plejd
Follow the `Easy Installation` in [README.MD](plejd/README.md)
And `Configuration Parameters` on the same page.
The only parameters needing a value are
- site
- username
- password
- mqttUsername e.g. `mqtt-api-user`
- mqttPassword
Now you can start the Plejd add-on
## Where are the lights?
Head over to [Configuration -> Integrations](http://homeassistant.local:8123/config/integrations) and click Configure on MQTT
After this step a new `Mosquito broker` should appear on the same page. If everything was setup correctly. It will list your lights under
`1 entity`/`n entities`
## Running the Plejd add-on in VirtualBox on Windows
If on Windows + VirtualBox or similar setup
- Install VirtualBox extensions to get USB 2/3
- Redirect correct USB device
- Potentially try to replace BT drivers with WinUSB using Zadig
- (Re)start VirtualBox HA machine
## Running the Plejd add-on outside of Home Assistant Operating System ("HassOS")
If you're planning on running this add-on outside of HassOS, you might need to turn off AppArmor in the `config.json` file. This is due to missing AppArmor configuration that is performed in HassOS (if you've manually done it, ignore this).
Open the `config.json` file and locate `host_dbus`, after that line, insert: `"apparmor": "no",` and then restart the add-on.
More information about available parameters can be found here:
https://developers.home-assistant.io/docs/en/hassio_addon_config.html
## Migration from 32bit to 64 bit
If you restore a backup from a 32bit system to a new 64bit system, use the Rebuild option in the Add-on

163
plejd/README.md
View file

@ -3,31 +3,6 @@
Hass.io add-on for Plejd home automation devices. Gives you the ability to control the Plejd home automation devices through Home Assistant. Hass.io add-on for Plejd home automation devices. Gives you the ability to control the Plejd home automation devices through Home Assistant.
It uses MQTT to communicate with Home Assistant and supports auto discovery of the devices in range. Changed made in the Plejd app are propagated to Home Assistant. It uses MQTT to communicate with Home Assistant and supports auto discovery of the devices in range. Changed made in the Plejd app are propagated to Home Assistant.
Plejd output devices typically appears as either lights or switches in Home Assistant depending on how they are configured.
| Device | Plejd Configuration | Home Assistant Role | Comment |
| ------ | ------------------- | ------------------- | --------------------------------------------------------------------- |
| CTR-01 | Relay, Light | Light | |
| CTR-01 | Relay, Other | Switch | |
| REL-01 | Relay, Light | Light | |
| REL-01 | Relay, Other | Switch | |
| REL-02 | Relay, Light | Light | |
| REL-02 | Relay, Other | Switch | |
| SPR-01 | Relay, Light | Light | Not tested, not supported |
| SPR-01 | Relay, Other | Switch | Not tested, not supported |
| DIM-01 | - | Light | |
| DIM-02 | - | Light | |
| LED-10 | - | Light | |
| DAL-01 | - | - | Not supported, not released by Plejd |
| WPH-01 | - | Device Automation | type:button_short_press, subtype:button_1, button_2,button_3,button_4 |
| WRT-01 | - | Device Automation | type:button_short_press, subtype:button_1 |
| GWY-01 | - | - | |
| RTR-01 | - | - | |
| Scene | - | Scene | |
| Scene | - | Device Automation | type:scene, subtype:trigger |
| Room | - | Area | Can be changed by Home Assistant |
| Room | - | Light | If includeRoomsAsLights is set to true |
Thanks to [ha-plejd](https://github.com/klali/ha-plejd) for inspiration. Thanks to [ha-plejd](https://github.com/klali/ha-plejd) for inspiration.
Disclaimer: Disclaimer:
@ -44,28 +19,23 @@ To get started, make sure that the following requirements are met:
### Requirements ### Requirements
- A Bluetooth device (BLE), for eg. the built-in device in Raspberry Pi 4. - A Bluetooth device (BLE), se "Tested on" section below.
- An MQTT broker (the Mosquitto Hass.io add-on works perfectly well). - An MQTT broker (the [Mosquitto broker Home Assistant add-on](https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md) works perfectly well).
### Tested on ### Tested on
The add-on has been tested on the following platforms: The add-on has been tested on the following platforms:
- Odroid-n2+ / Home Assistant Blue / Home Assistant Operating System ("HassOS") / BT ASUS USB-BT400 - Chipset: Broadcom BCM20702A1-0b05-17cb
- Raspberry Pi 4 with Home Assistant ("Hass.io") / Built-in BT
- Raspberry Pi 4 with Home Assistant ("Hass.io"/aarch64) / Built-in BT
- Raspberry Pi 3+ with Home Assistant ("Hass.io") / Built-in BT
- Intel NUC7i5BNH with Home Assistant Operating System ("HassOS") intel NUC image / Built-in BT
- Windows 10 Pro host / Oracle VirtualBox 6.1 / Home Assistant VBox image / Deltaco BT-118 with Cambridge Silicon Radio chipset / Windows + Zadig to change driver to WinUSB
- Windows 10 host / Oracle Virtualbox 6.1 / Home Assistant VBox image / ASUS BT400
- Mac OS Catalina 10.15.1 with Node v. 13.2.0 - Mac OS Catalina 10.15.1 with Node v. 13.2.0
- Raspberry Pi 4 with Hass.io
- Raspberry Pi 4 with Hass.io/aarch64
- Intel NUC7i5BNH with HassOS intel NUC image (built-in BT)
#### Tested Plejd devices Supported Plejd devices are detailed in a specific "Plejd devices" section below.
- DIM-01
- DIM-02
- LED-10
- CTR-01
- REL-01
- REL-02
- WPH-01
- WRT-01
### Easy Installation ### Easy Installation
@ -81,7 +51,7 @@ Browse to your Home Assistant installation in a web browser and click on `Superv
### Manual Installation ### Manual Installation
Browse your Hass.io installation using a tool that allows you to manage files, for eg. SMB or an SFTP client etc. Browse your Home Assistant installation using a tool that allows you to manage files, for eg. SCP, SMB, SFTP client, etc.
- Open the `/addon` directory - Open the `/addon` directory
- Create a new folder named `hassio-plejd` - Create a new folder named `hassio-plejd`
@ -92,16 +62,15 @@ Browse your Hass.io installation using a tool that allows you to manage files, f
- A new Local Add-on should appear named Plejd. Open that and install. - A new Local Add-on should appear named Plejd. Open that and install.
- Enjoy! - Enjoy!
### Detailed Home Assistant instructions ### Install older versions or development version
[The details](../Details.md)
### Install older versions or developemnt version
To install older versions, follow the "Manual Installation" instructions above, but copy the code from [one of the releases](https://github.com/icanos/hassio-plejd/releases). To test new functionality you can download the development version, available in the [develop branch](https://github.com/icanos/hassio-plejd/tree/develop). To install older versions, follow the "Manual Installation" instructions above, but copy the code from [one of the releases](https://github.com/icanos/hassio-plejd/releases). To test new functionality you can download the development version, available in the [develop branch](https://github.com/icanos/hassio-plejd/tree/develop).
### IMPORTANT INFORMATION ### More details regarding installation
#### Startup error message Please look at [The details](./Details.md) separate document for more detailed instructions regarding Home Asssistant, Mosquitto, etc.
### Startup error message
When starting the add-on, the log displays this message: When starting the add-on, the log displays this message:
@ -112,42 +81,20 @@ parse error: Expected string key before ':' at line 1, column 4
However, the add-on still works as expected and this is something I'm looking into, but not with that much effort yet though. However, the add-on still works as expected and this is something I'm looking into, but not with that much effort yet though.
#### Running the Plejd add-on in VirtualBox on Windows ## Configuration
If on Windows + VirtualBox or similar setup ### Simple MQTT Configurations
- Install VirtualBox extensions to get USB 2/3
- Redirect correct USB device
- Potentially try to replace BT drivers with WinUSB using Zadig
- (Re)start VirtualBox HA machine
#### Running the Plejd add-on outside of HassOS
If you're planning on running this add-on outside of HassOS, you might need to turn off AppArmor in the `config.json` file. This is due to missing AppArmor configuration that is performed in HassOS (if you've manually done it, ignore this).
Open the `config.json` file and locate `host_dbus`, after that line, insert: `"apparmor": "no",` and then restart the add-on.
More information about available parameters can be found here:
https://developers.home-assistant.io/docs/en/hassio_addon_config.html
#### Migration from 32bit to 64 bit
If you restore a backup from a 32bit system to a new 64bit system, use the Rebuild option in the Add-on
### Configuration
#### Simple MQTT Configurations
When you are using the official Mosquitto Broker from Home Assistant Add-on store, minimal configuration is required. When you are using the official Mosquitto Broker from Home Assistant Add-on store, minimal configuration is required.
Create a user in [Configuration -> Users](http://homeassistant.local:8123/config/users) named e.g. mqtt-api-user Create a user in [Configuration -> Users](http://homeassistant.local:8123/config/users) named e.g. mqtt-api-user
| Parameter | Value | | Parameter | Value |
| ------------ | ---------------------------------------------------------------------------------------------------------------- | | ------------ | ------------------------------------------------ |
| mqttBroker | mqtt:// | | mqttBroker | mqtt:// |
| mqttUsername | Arbitrary Home Assistant User e.g. mqtt-api-user | | mqttUsername | Arbitrary Home Assistant User e.g. mqtt-api-user |
| mqttPassword | Users password | | mqttPassword | Users password |
#### Advanced MQTT Configurations ### Advanced MQTT Configurations
For more advanced instllations, you need to add the MQTT integration to Home Assistant either by going to Configuration -> Integrations and clicking the Add Integration button, or by adding the following to your `configuration.yaml` file: For more advanced instllations, you need to add the MQTT integration to Home Assistant either by going to Configuration -> Integrations and clicking the Add Integration button, or by adding the following to your `configuration.yaml` file:
@ -162,7 +109,7 @@ mqtt:
The above is used to notify the add-on when Home Assistant has started successfully and let the add-on send the discovery response (containing information about all Plejd devices found). The above is used to notify the add-on when Home Assistant has started successfully and let the add-on send the discovery response (containing information about all Plejd devices found).
#### Configuration Parameters ### Configuration Parameters
The plugin needs you to configure some settings before working. You find these on the Add-on page after you've installed it. The plugin needs you to configure some settings before working. You find these on the Add-on page after you've installed it.
@ -171,7 +118,7 @@ The plugin needs you to configure some settings before working. You find these o
| site | Name of your Plejd site, the name is displayed in the Plejd app (top bar). | | site | Name of your Plejd site, the name is displayed in the Plejd app (top bar). |
| username | Username of your Plejd account, this is used to fetch the crypto key and devices from the Plejd API. | | username | Username of your Plejd account, this is used to fetch the crypto key and devices from the Plejd API. |
| password | Password of your Plejd account, this is used to fetch the crypto key and devices from the Plejd API. | | password | Password of your Plejd account, this is used to fetch the crypto key and devices from the Plejd API. |
| mqttBroker | URL of the MQTT Broker, eg. mqtt:// | | mqttBroker | URL of the MQTT Broker, eg. mqtt:// |
| mqttUsername | Username of the MQTT broker | | mqttUsername | Username of the MQTT broker |
| mqttPassword | Password of the MQTT broker | | mqttPassword | Password of the MQTT broker |
| includeRoomsAsLights | Adds all rooms as lights, making it possible to turn on/off lights by room instead. Setting this to false will ignore all rooms. | | includeRoomsAsLights | Adds all rooms as lights, making it possible to turn on/off lights by room instead. Setting this to false will ignore all rooms. |
@ -180,6 +127,49 @@ The plugin needs you to configure some settings before working. You find these o
| connectionTimeout | Number of seconds to wait when scanning and connecting. Might need to be tweaked on platforms other than RPi 4. Defaults to: 2 seconds. | | connectionTimeout | Number of seconds to wait when scanning and connecting. Might need to be tweaked on platforms other than RPi 4. Defaults to: 2 seconds. |
| writeQueueWaitTime | Wait time between message sent to Plejd over BLE, defaults to 400. If that doesn't work, try changing the value higher in steps of 50. | | writeQueueWaitTime | Wait time between message sent to Plejd over BLE, defaults to 400. If that doesn't work, try changing the value higher in steps of 50. |
## Plejd devices and corresponding Home Assistant devices
Plejd output devices typically appears as either lights or switches in Home Assistant depending on how they are configured.
| Device | Plejd Configuration | Home Assistant Role | Comment |
| ------ | ------------------- | ------------------- | --------------------------------------------------------------------- |
| CTR-01 | Relay, Light | Light | |
| CTR-01 | Relay, Other | Switch | |
| REL-01 | Relay, Light | Light | |
| REL-01 | Relay, Other | Switch | |
| REL-02 | Relay, Light | Light | |
| REL-02 | Relay, Other | Switch | |
| SPR-01 | Relay, Light | Light | Not tested, not supported |
| SPR-01 | Relay, Other | Switch | Not tested, not supported |
| DIM-01 | - | Light | |
| DIM-02 | - | Light | |
| LED-10 | - | Light | |
| DAL-01 | - | - | Not tested, not supported |
| WPH-01 | - | Device Automation | type:button_short_press, subtype:button_1, button_2,button_3,button_4 |
| WRT-01 | - | Device Automation | type:button_short_press, subtype:button_1 |
| GWY-01 | - | - | |
| RTR-01 | - | - | |
| Scene | - | Scene | |
| Scene | - | Device Automation | type:scene, subtype:trigger |
| Room | - | Area | Can be changed by Home Assistant |
| Room | - | Light | If includeRoomsAsLights is set to true |
## Transitions
Transitions from Home Assistant are supported (for dimmable devices) when transition is longer than 1 second. Plejd will do a bit of internal transitioning (default soft start is 0.1 seconds).
This implementation will transition each device independently, meaning that brightness change might be choppy if transitioning many devices at once or a changing brightness a lot in a limited time. Hassio-plejd's communication channel seems to handle a few updates per second, this is the combined value for all devices.
Transition points will be skipped if the queue of messages to be sent is over a certain threshold, by default equal to the number of devices in the system. Total transition time is prioritized rather than smoothness.
Recommendations
- Only transition a few devices at a time when possible
- Entire rooms can be transitioned efficiently after settin gincludeRoomsAsLights to true
- Expect 5-10 brightness changes per second, meaning 5 devices => 1-2 updates per device per second
- ... meaning that SLOW transitions will work well (wake-up light, gradually fade over a minute, ...), but quick ones will only work well for few devices or small relative changes in brightness
- When experiencing choppy quick transitions, turn transitioning off and let the Plejd hardware do the work instead
## Troubleshooting ## Troubleshooting
If you're having issues to get the addon working, there are a few things you can look into: If you're having issues to get the addon working, there are a few things you can look into:
@ -202,21 +192,6 @@ If you're having issues to get the addon working, there are a few things you can
- One Plejd device means max one BLE connection, meaning using the Plejd app over BT will disconnect the addon BLE connection - One Plejd device means max one BLE connection, meaning using the Plejd app over BT will disconnect the addon BLE connection
- It seems you can kick yourself out (by connecting using the app) even when you have multiple devices if the app happens to connect to the same device as the addon is using - It seems you can kick yourself out (by connecting using the app) even when you have multiple devices if the app happens to connect to the same device as the addon is using
## Transitions
Transitions from Home Assistant are supported (for dimmable devices) when transition is longer than 1 second. Plejd will do a bit of internal transitioning (default soft start is 0.1 seconds).
This implementation will transition each device independently, meaning that brightness change might be choppy if transitioning many devices at once or a changing brightness a lot in a limited time. Hassio-plejd's communication channel seems to handle a few updates per second, this is the combined value for all devices.
Transition points will be skipped if the queue of messages to be sent is over a certain threshold, by default equal to the number of devices in the system. Total transition time is prioritized rather than smoothness.
Recommendations
- Only transition a few devices at a time when possible
- Expect 5-10 brightness changes per second, meaning 5 devices => 1-2 updates per device per second
- ... meaning that SLOW transitions will work well (wake-up light, gradually fade over a minute, ...), but quick ones will only work well for few devices or small relative changes in brightness
- When experiencing choppy quick transitions, turn transitioning off and let the Plejd hardware do the work instead
## I want voice control! ## I want voice control!
With the Google Home integration in Home Assistant, you can get voice control for your Plejd lights right away, check this out for more information: With the Google Home integration in Home Assistant, you can get voice control for your Plejd lights right away, check this out for more information: