diff --git a/source/_integrations/upb.markdown b/source/_integrations/upb.markdown index df4410671fe..ff879f52549 100644 --- a/source/_integrations/upb.markdown +++ b/source/_integrations/upb.markdown @@ -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.