Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Convert code to full integration with support for input and events from Plejd #54

Open
wants to merge 14 commits into
base: master
Choose a base branch
from
Open

Convert code to full integration with support for input and events from Plejd #54

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
c879f2a
Rewrite code to custom integration, including sensors, switches and s…
bnordli Dec 13, 2021
4d71369
Add SPR-01
bnordli Dec 16, 2021
7ba77a4
Bugfix for dimmable status
bnordli Jan 8, 2022
3c3bd5c
Manually set dimmable status
bnordli Jan 25, 2022
2f648f0
More lenient requirements
bnordli Apr 2, 2022
cd8b6bd
Correct light name
bnordli Jul 15, 2022
df2942c
Update README.md
bnordli Sep 8, 2022
a0e9969
Merge branch 'master' of https://github.com/klali/ha-plejd
bnordli Apr 9, 2023
b4107f3
Move config instructions
bnordli Apr 9, 2023
7c6b226
Correct light name
bnordli Jul 15, 2022
dfc7da4
Implement write_data
bnordli Apr 9, 2023
a394af0
Merge branch 'master' into to-integration
bnordli Apr 9, 2023
ae703d5
Correct function name
bnordli Apr 9, 2023
8f50289
Deprecation notice
bnordli Jan 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 137 additions & 74 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,90 @@
## Deprecation notice

This component has been deprecated in favor of the more user friendly
https://github.com/thomasloven/hass_plejd HACS component.

# Plejd component for Home Assistant

This is a simple Plejd component for Home Assistant, interfacing with the
bluetooth le protocol.
This is a Plejd component for Home Assistant, interfacing with the Bluetooth LE
protocol. All devices are configured locally, without communicating with the
Plejd web API. The crypto key must be extracted from the app image (see below
for instructions).

## Upgrade notes

If you are upgrading from version 1 to version 2 of this component, you should
read the [upgrade notes](upgrade_notes.md).

## Entities

Relay outputs can be configured as either `light`s or `switch`es. Dimmer outputs
should generally be configured as (dimmable) `light`s. They can also be used as
plain `switch`es. Rotary buttons are `sensor`s (measuring percentages) while
push buttons are `binary_sensor`s.

## Events

Plejd buttons send `plejd_button_event`s when pressed and Plejd scenarios and
timers send `plejd_scene_event`s when triggered. These events can be identified
by either by the `plejd_id` field, or the `name` field, if configured.

## Services

Plejd scenarios can be triggered using the `plejd.trigger_scene` service. They
will have to be defined through the Plejd app, though.

## Getting started
## Time

The component will keep the time of the Plejd system up to date.

## Supported Plejd devices

| Name | `light` _or_ `switch` | `binary_sensor` | `sensor` | `plejd_button_event` | Tested? |
| --------- | --------------------- | --------------- | -------- |--------------------- | ------- |
| CTR-01 | 1x (dimmable) | | | | No |
| DIM-01-2P | 1x (dimmable) | | | | |
| DIM-02 | 2x (dimmable) | | | | |
| LED-10 | 1x (dimmable) | | | | No |
| SPR-01 | 1x | | | | |
| REL-01-2P | 1x | | | | No |
| REL-02 | 2x | | | | |
| RTR-01 * | | | 1x* | Yes* | |
| VRI-02 * | 1x (dimmable) | | 1x* | Yes* | |
| WPH-01 | | 2x | | Yes | |
| WRT-01 | | | 1x | Yes | |

Note: For RTR-01 and VRI-02, when the rotary is configured to control an output
on the attached puck, Home Assistant will not receive events from the button
(only the controlled light), so it cannot be a separate `sensor`, and
`plejd_button_event`s will not be triggered.

All lights are by default set to dimmable in Home Assistant. To make a light
non-dimmable, add " (onoff)" or "*" to its name. This suffix will be removed
before added to Home Assistant. (If a light is set to dimmable by error, add a
suffix and then go to Developer Tools for this entity, set `supported_color_modes`
to `- onoff` and remove the `brightness` line, or restart Home Assistant.)

## Tested platforms

This component has been tested on the following platforms:
- Raspberry pi 3b+ running ubuntu (18.04) and home-assistant in venv
- Intel NUC NUC7i7BNH (Bluetooth 4.2 Intel 8265) running ESXi 6.7 and linux guest
* Raspberry Pi 3b+ running ubuntu (18.04) and Home Assistant in venv.
* Raspberry Pi 4b running Pi OS Lite and Home Assistant in docker.
* Intel NUC NUC7i7BNH (Bluetooth 4.2 Intel 8265) running ESXi 6.7 and linux guest.

There's been reports that bluez version 5.37 is problematic while 5.48 works fine.

## Requirements
* A bluetooth adapter that supports Bluetooth Low Energy (BLE)

* A Bluetooth adapter that supports Bluetooth Low Energy (BLE).
* Obtaining the Plejd crypto key and the device ids.

## Gathering crypto and device information

Obtaining the crypto key and the device ids is a crucial step to get this
running, for this it is required to get the .site json file from the plejd app
on android or iOS.
on Android or iOS.

### Steps for android:
### Steps for Android

1. Turn on USB debugging and connect the phone to a computer.
2. Extract a backup from the phone:
Expand All @@ -38,19 +100,19 @@ $ dd if=backup.ab bs=1 skip=24 | zlib-flate -uncompress | tar -xv
$ cp apps/com.plejd.plejdapp/f/*/*.site site.json
```

### Steps for iOS:
### Steps for iOS

1. Open a backup in iBackup viewer.
2. Select raw files, look for AppDomainGroup-group.com.plejd.consumer.light.
3. In AppDomainGroup-group.com.plejd.consumer.light/Documents there should be two folders.
4. The folder that isn't named ".config" contains the .site file.

### Gather cryto key and ids for devices
### Gather crypto key and ids for devices

When the site.json file has been recovered the cryptokey and the output
addresses can be extracted:

1. Extract the cryptoKey:
1. Extract the CryptoKey:
```
$ cat site.json | jq '.PlejdMesh.CryptoKey' | sed 's/-//g'
```
Expand All @@ -60,34 +122,66 @@ $ cat site.json | jq '.PlejdMesh._outputAddresses' | grep -v '\$type' | jq '.[][
```

These steps can obviously be done manually instead of extracting the fields
using jq and shell tricks.

using jq and shell tricks. Device ids can also be found by configuring debug
logging and see when unknown devices appear in the log, while scenario and
timer ids can be found by listening for `plejd_scene_event`s.

## Installing component

### Hassbian:
### Hassbian

Make sure the homeassistant user has permissions to use bluetooth, this might
require putting it in the bluetooth group.
Make sure the Home Assistant user has permissions to use Bluetooth, this might
require putting it in the Bluetooth group.

Run this as a custom component, put the files light.py, manifest.json and
\_\_init\_\_.py in custom\_components/plejd in your configuration.yaml add
something like:
To run this as a custom component, copy all files in `custom_components/plejd`,
to a `custom_components/plejd` folder under your Home Assistant directory.

### Hass.io Docker container

Hass.io default installation script will map `/usr/share/hassio/homeassistant`
to the `/config` directory inside the docker container.
Create a `custom_components` directory if it doesn't exist (it doesn't by default):
```
light:
- platform: plejd
crypto_key: !secret plejd
devices:
11:
name: bedroom
13:
name: kitchen_1
14:
name: kitchen_2
16:
name: bathroom
mkdir -p /usr/share/hassio/homeassistant/custom_components/plejd
```
Checkout the git repo and rename folder
```
cd /usr/share/hassio/homeassistant/custom_components/plejd
git clone https://github.com/klali/ha-plejd.git
mv custom_components/plejd/* .
```

## Configuring component

Put the crypto key in your `secrets.yaml` file:
`plejd_crypto: "********************************"`

And configure the component in your `configuration.yaml`:
```
plejd:
crypto_key: !secret plejd_crypto
lights:
11: bedroom
13: kitchen_1
14: kitchen_2
16: bathroom
switches:
19: heater
binary_sensors:
17: button bedroom left
18: button bedroom right
sensors:
21: bathroom rotary
scenes:
1: morning
2: evening
3: night
```

All dictionary items map from (integral) plejd ids to the name they should
have in Home Assistant.

## Filtering devices

If you know that there are a lot of plejd devices nearby that is not part of your installation you can specify which
plejd ids home assistant is allowed to connect to using `endpoints: ['AAAAAAAAAAAA', 'BBBBBBBBBBBB', ... ]`. You can
Expand All @@ -96,55 +190,23 @@ site.json file under `_outputAddresses`. For example, the following config would
`A1B2C3D4E5F6`.

```
light:
- platform: plejd
crypto_key: !secret plejd
endpoints: ['A1B2C3D4E5F6']
devices:
11:
name: bedroom
13:
name: kitchen_1
14:
name: kitchen_2
16:
name: bathroom
plejd:
crypto_key: !secret plejd_crypto
endpoints: ['A1B2C3D4E5F6']
...
```

### HASS.IO Docker container
## Restarting Home Assistant

Hass.io default installation script will map /usr/share/hassio/homeassistant to the /config directory inside the docker container.
create a custom\_components directory if it doesn't exist (it doesn't by default).
```
mkdir -p /usr/share/hassio/homeassistant/custom_components
```
Checkout the git repo and rename folder
```
cd /usr/share/hassio/homeassistant/custom_components
git clone https://github.com/klali/ha-plejd.git
mv ha-plejd plejd
```
Update your configuration.yaml file
```
light:
- platform: plejd
crypto_key: !secret plejd
devices:
11:
name: bedroom
13:
name: kitchen_1
14:
name: kitchen_2
16:
name: bathroom

```
Last step is to restart homeassistant service, in the homeassistant web ui, go to Configuration -> General -> Server management and hit restart.
The last step is to restart Home Assistant service, in the Home Assistant web
UI, go to Configuration -> General -> Server management and hit restart.

## Troubleshooting

Generally it is helpful to turn on debug logging for the component for any type of troubleshooting, this will show what the component receives and interprets from the plejd network. To do this add something like the following to your configuration:
Generally it is helpful to turn on debug logging for the component for any type
of troubleshooting, this will show what the component receives and interprets
from the plejd network. To do this add something like the following to your
configuration:
```
logger:
logs:
Expand All @@ -156,6 +218,7 @@ logger:

```
Copyright 2019 Klas Lindfors <[email protected]>
Copyright 2021 Børge Nordli <[email protected]>

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
Loading