jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-18 23:06:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add UPB service descriptions (#13416)

Browse Source
This commit is contained in:
Glenn Waters 2020-05-13 07:14:45 -04:00 committed by GitHub
parent 845bcd2363
commit 4dd0e6cfea
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 115 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
source/_integrations/upb.markdown
View File

@ -15,6 +15,7 @@ ha_domain: upb
The UPB integration allows Home Assistant to connect to a Universal Powerline Bus Powerline Interface Module (UPB PIM) to get status and control UPB devices and UPB links. The UPB PIM may be connected either to a serial port or over TCP. The integration implements the following platforms:
- Light
- Scene
## Configuration
@ -44,7 +45,120 @@ The `event_data` contains the following:
For example for UPB Network number 42 and UPB Link number 24 the
`address` would be 42_24.
- `brightness_pct`: The brightness level as a percentage. `brightness_pct` is
reported as -1 if the brightness is a default level or brightness is not
reported as -1 if the brightness is a default level of brightness is not
applicable to the link change.
- `rate`: The rate for link to transition to the new level. `rate` is
-1 for the default transiton rate.
## Services
Besides the standard services provided by the Home Assistant [Light](/integrations/light/) and [Scene](/integrations/scene) integrations, the following extra services are provided by the UPB integration:
- `upb.light_fade_start`
- `upb.light_fade_stop`
- `upb.light_blink`
- `upb.scene_deactivate`
- `upb.scene_goto`
- `upb.scene_fade_start`
- `upb.scene_fade_stop`
- `upb.scene_blink`
### Rate Transition Time
Both standard and custom services that take a `transition` or a `rate` for changing brightness levels take time in seconds. The UPB
system only offers a discrete set of transition times. As such, the transition time requested is changed to the closest time based on
the table below. Note that this table does not apply to blink rates, only to brightness transition times.
| Request rate >= | Requested rate < | Rate Used |
| --------------- | ---------------- | --------- |
| 0 seconds | 0.4 seconds | 0 seconds
| 0.4 seconds | 1.2 seconds | 0.8 seconds
| 1.2 seconds | 2.45 seconds | 1.6 seconds
| 2.45 seconds | 4.15 seconds | 3.3 seconds
| 4.15 seconds | 5.8 seconds | 5.0 seconds
| 5.8 seconds | 8.3 seconds | 6.6 seconds
| 8.3 seconds | 15 seconds | 10 seconds
| 15 seconds | 25 seconds | 20 seconds
| 25 seconds | 45 seconds | 30 seconds
| 45 seconds | 90 seconds | 60 seconds
| 1.5 minute | 3.5 minutes | 2 minutes
| 3.5 minutes | 7.5 minutes | 5 minutes
| 7.5 minutes | 12.5 minutes | 10 minutes
| 12.5 minutes | 22.5 minutes | 15 minutes
| 22.5 minutes | 45 minutes | 30 minutes
| 45 minutes | ∞ | 1 hour
### Service `upb.light_fade_start`
Starts a transition of a light to the specified level. Lights that are not dimmable ignore the fade start command.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB light which to start fading operation.
| `brightness` | no* | Integer between 0 and 255 for how bright the light should be, where 0 means the light is off, 1 is the minimum brightness and 255 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `brightness_pct`| no* | Number between 0 and 100 in percentage that specifies how bright the light should be, where 0 means the light is off, 1 is the minimum brightness and 100 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `rate` | yes | Number that represents the time (in seconds) the light should take to transition to the new state. See section on "Rate Transition Time" for how this time value is interpreted.
### Service `upb.light_fade_stop`
Stop a light when transitioning from one light level to another. Stops either a fade or a goto (goto occurs when using a `light.turn_on` or `light.turn_off`.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB light which to stop fading operation.
### Service `upb.light_blink`
Start a light blinking.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB light which to blink.
| `rate` | no | Number between 0 and 4.25 that represents the time (in seconds) the rate the light blinks. Note the UPB implementation limits the blink rate to no faster than 1/3 of a second.
### Service `upb.scene_deactivate`
Deactivate a scene. The term “deactivate” is a general UPB term that usually means to turn to the OFF state, but each individual device manufacturer can define it differently for their device.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB scene to deactivate.
### Service `upb.scene_goto`
Starts a transition of a scene to the specified level.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB scene to transition.
| `brightness` | no* | Integer between 0 and 255 for how bright the scene should be, where 0 means the scene is off, 1 is the minimum brightness and 255 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `brightness_pct`| no* | Number between 0 and 100 in percentage that specifies how bright the scene should be, where 0 means the scene is off, 1 is the minimum brightness and 100 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `rate` | yes | Number that represents the time (in seconds) the light should take to transition to the new state. See section on "Rate Transition Time" for how this time value is interpreted.
### Service `upb.scene_fade_start`
Starts a transition of a scene to the specified level. Lights within the scene that are not dimmable ignore the fade start command.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB scene to transition.
| `brightness` | no* | Integer between 0 and 255 for how bright the scene should be, where 0 means the scene is off, 1 is the minimum brightness and 255 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `brightness_pct`| no* | Number between 0 and 100 in percentage that specifies how bright the scene should be, where 0 means the scene is off, 1 is the minimum brightness and 100 is the maximum brightness. *Only one of `brightness` and `brightness_pct` may be used.
| `rate` | yes | Number that represents the time (in seconds) the light should take to transition to the new state. See section on "Rate Transition Time" for how this time value is interpreted.
### Service `upb.scene_fade_stop`
Stop a scene when transitioning from one light level to another. Stops either a fade or a goto.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB scene which to stop fading operation.
### Service `upb.scene_blink`
Start a scene blinking.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | UPB scene which to blink.
| `rate` | no | Number between 0 and 4.25 that represents the time (in seconds) the rate the scene blinks. Note the UPB implementation limits the blink rate to no faster than 1/3 of a second.