mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-19 15:26:59 +00:00
Add events and device triggers to LCN (#20080)
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
Andre Lengwenus
GitHub
parent
8f705e4d13
commit
d21e38e185
@ -42,8 +42,8 @@ There is currently support for the following device types within Home Assistant:
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Please note: Besides the implemented platforms, the `lcn` integration offers a variety of [service calls](#services).
|
||||
These service calls cover functionalities of the LCN system, which cannot be represented by the platform implementations.
|
||||
The implemented platforms do not cover the whole functionality of the LCN system.
|
||||
Therefore the `lcn` integration offers a variety of [events](#events), [device triggers](#device-triggers) and [service calls](#services).
|
||||
They are ideal to be used in automation scripts or for the `template` platforms.
|
||||
|
||||
</div>
|
||||
@ -483,8 +483,10 @@ The `lcn` sensor platform allows the monitoring of the following [LCN](https://w
|
||||
The sensor can be used in automation scripts or in conjunction with `template` platforms.
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Ensure that the LCN module is configured properly to provide the requested value.
|
||||
Otherwise, the module might show unexpected behavior or return error messages.
|
||||
|
||||
</div>
|
||||
|
||||
### Switch
|
||||
@ -494,12 +496,207 @@ The `lcn` switch platform allows the control of the following [LCN](https://www.
|
||||
- Output ports
|
||||
- Relays
|
||||
|
||||
## Additional Features
|
||||
|
||||
### Transponder and fingerprint sensor
|
||||
|
||||
To use LCN transponders or fingerprint sensors ensure that the corresponding module's I-port property
|
||||
is enabled in the LCN-PRO software and properly configured.
|
||||
LCN transponders and fingerprints are identified by a six value hexadecimal code (e.g. *123abc*).
|
||||
If a code is received a corresponding event ([transponder event](#event-lcn_transponder), [fingerprint event](#event-lcn_fingerprint))
|
||||
is fired and can be used to trigger an automation.
|
||||
Alternatively, you can use the corresponding [device triggers](#device-triggers).
|
||||
|
||||
Example:
|
||||
|
||||
This example shows how the `event_data` can be extracted and used in a condition using Home Assistant's templating engine.
|
||||
Trigger on a transponder event and ensure that the received code is in the given list:
|
||||
|
||||
{% raw %}
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: lcn_transponder
|
||||
condition: "{{ trigger.event.data.code in ['aabbcc', 'ddeeff', '112233'] }}"
|
||||
action:
|
||||
...
|
||||
```
|
||||
|
||||
{% endraw %}
|
||||
|
||||
Further examples can be found in the [event section](#events).
|
||||
|
||||
### Remote control
|
||||
|
||||
To use LCN remote controls (e.g., LCN-RT or LCN-RT16) ensure that the corresponding module's I-port property
|
||||
is enabled in the LCN-PRO software and its behavior is properly configured as "IR access control".
|
||||
With this configuration each remote control is identified by a six value hexadecimal code (e.g. *123abc*).
|
||||
If a command from a remote control is received a corresponding event ([transponder event](#event-lcn_transponder))
|
||||
is fired and can be used to trigger an automation. Along with the transmitted code, the pressed key and the key action
|
||||
are transmitted.
|
||||
Alternatively, you can use the corresponding [device triggers](#device-triggers).
|
||||
|
||||
Examples can be found in the [event section](#events).
|
||||
|
||||
### LCN commands addressed to PCHK host (Home Assistant)
|
||||
|
||||
A LCN module can not only be programmed to send commands to other modules/groups but also to the PCHK host configured
|
||||
in the LCN integration. These commands are directly passed to Home Assistant and can be evaluated. Only the *send keys*
|
||||
(former) command is supported.
|
||||
|
||||
Within LCN-PRO program the *send keys* command (only "A-C former command" is supported) to a key. For the target address
|
||||
manually enter the PCHK host id (default: 4). Select the keys and key actions as desired.
|
||||
|
||||
When a *send keys* command is received, the LCN integration will fire a [send keys event](#event-lcn_send_keys) for each
|
||||
key configured. These events can be used to trigger an automation.
|
||||
Alternatively, you can use the corresponding [device triggers](#device-triggers).
|
||||
|
||||
Examples can be found in the [event section](#events).
|
||||
|
||||
<div class='note'>
|
||||
|
||||
Only commands sent from physical buttons of a module are evaluated. The "Test command" button in the LCN-PRO software
|
||||
is not evaluated and therefore cannot be used for testing purposes.
|
||||
|
||||
</div>
|
||||
|
||||
## Events
|
||||
|
||||
There are several functionalities of the LCN system which are not exposed as regular entities by the integration, but as events.
|
||||
Examples are button presses from remote controls (transmitters), transponder findings, fingerprint sensors and so called *send keys* events.
|
||||
|
||||
<div class='note'>
|
||||
|
||||
If you find it difficult to deal with events in scripted automations, you can also use [device triggers](#device-triggers)
|
||||
which offer automation design via the UI.
|
||||
|
||||
</div>
|
||||
|
||||
All events have some common attributes in their `event_data` which identify the sending LCN hardware module (e.g., the module the transponder is connected to):
|
||||
|
||||
| Event payload | Description | Values |
|
||||
| ------------- | ----------- | ------ |
|
||||
| `device_id` | Internal device id of LCN module | string |
|
||||
| `segment_id` | Module's segment id | 5..128 |
|
||||
| `module_id` | Module id | 5..254 |
|
||||
|
||||
In addition, every event has its own special attributes which are described below.
|
||||
All special attributes are optional and can be used as supplementary filters.
|
||||
|
||||
### Event: `lcn_transmitter`
|
||||
|
||||
The `lcn_transmitter` event is fired if a LCN remote control command is received.
|
||||
|
||||
| Special payload | Description | Values |
|
||||
| --------------- | ----------- | ------ |
|
||||
| `code` | Transmitter code | string (6 hex values) |
|
||||
| `level` | Key level | 0..4 |
|
||||
| `key` | Key | 0..4 |
|
||||
| `action` | Key action | `hit`, `make`, `break` |
|
||||
|
||||
Example:
|
||||
|
||||
The trigger will fire if any key on the remote control with code *123abc* is `hit` as long as the
|
||||
receiver hardware is connected to module 7 in segment 0.
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: lcn_transmitter
|
||||
event_data:
|
||||
segment_id: 0
|
||||
module_id: 7
|
||||
code: 123abc
|
||||
action: hit
|
||||
```
|
||||
|
||||
### Event: `lcn_transponder`
|
||||
|
||||
The `lcn_transponder` event is fired if a LCN transponder command is received.
|
||||
|
||||
| Special payload | Description | Values |
|
||||
| --------------- | ----------- | ------ |
|
||||
| `code` | Transponder code | string (6 hex values) |
|
||||
|
||||
Example:
|
||||
|
||||
The trigger will fire if the transponder with code *123abc* was detected at
|
||||
any hardware module.
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: lcn_transponder
|
||||
event_data:
|
||||
code: 123abc
|
||||
```
|
||||
|
||||
### Event: `lcn_fingerprint`
|
||||
|
||||
The `lcn_fingerprint` event is fired if a LCN fingerprint command is received.
|
||||
|
||||
| Special payload | Description | Values |
|
||||
| --------------- | ----------- | ------ |
|
||||
| `code` | Fingerprint code | string (6 hex values) |
|
||||
|
||||
Example:
|
||||
|
||||
The trigger will fire if the fingerprint with code *123abc* was detected at
|
||||
any hardware module.
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: lcn_fingerprint
|
||||
event_data:
|
||||
code: 123abc
|
||||
```
|
||||
|
||||
### Event: `lcn_send_keys`
|
||||
|
||||
The `lcn_send_keys` event is fired if the PCHK host receives a *send keys* command.
|
||||
|
||||
| Special payload | Description | Values |
|
||||
| --------------- | ----------- | ------ |
|
||||
| `key` | LCN Key | a1..c8 |
|
||||
| `action` | Key action | `hit`, `make`, `break` |
|
||||
|
||||
Example:
|
||||
|
||||
The trigger will fire if the PCHK host receives a command that issues a `hit` of
|
||||
key `a1`.
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: lcn_send_keys
|
||||
event_data:
|
||||
key: a1
|
||||
action: hit
|
||||
```
|
||||
|
||||
## Device triggers
|
||||
|
||||
To simplify using events in automations the LCN integration exposes them as device triggers.
|
||||
Those device triggers can be selected from the automation editor within Home Assistant.
|
||||
|
||||
After creating a new automation select *Device* as trigger type and search for the module which is
|
||||
supposed to cause the event in the device list. You may select the trigger type and configure its
|
||||
attributes. If an attribute is optional it is considered as a supplementary filter for the trigger.
|
||||
For an explanation of the attributes refer to the corresponding [events](#events).
|
||||
|
||||
## Services
|
||||
|
||||
In order to directly interact with the LCN system, and invoke commands which are not covered by the implemented platforms, the following service calls can be used.
|
||||
Refer to the [Services Calls](/docs/scripts/service-calls) page for examples on how to use them.
|
||||
|
||||
### Service `output_abs`
|
||||
### Service: `output_abs`
|
||||
|
||||
Set absolute brightness of output port in percent.
|
||||
|
||||
@ -521,7 +718,7 @@ data:
|
||||
transition: 0
|
||||
```
|
||||
|
||||
### Service `output_rel`
|
||||
### Service: `output_rel`
|
||||
|
||||
Set relative brightness of output port in percent.
|
||||
|
||||
@ -542,7 +739,7 @@ data:
|
||||
brightness: 30
|
||||
```
|
||||
|
||||
### Service `output_toggle`
|
||||
### Service: `output_toggle`
|
||||
|
||||
Toggle output port.
|
||||
|
||||
@ -562,7 +759,7 @@ data:
|
||||
transition: 0
|
||||
```
|
||||
|
||||
### Service `relays`
|
||||
### Service: `relays`
|
||||
|
||||
Set the relays status. The relays states are defined as a string with eight characters.
|
||||
Each character represents the state change of a relay (1=on, 0=off, t=toggle, -=nochange).
|
||||
@ -583,7 +780,7 @@ data:
|
||||
state: t---001-
|
||||
```
|
||||
|
||||
### Service `led`
|
||||
### Service: `led`
|
||||
|
||||
Set the LED status.
|
||||
|
||||
@ -602,7 +799,7 @@ data:
|
||||
state: blink
|
||||
```
|
||||
|
||||
### Service `var_abs`
|
||||
### Service: `var_abs`
|
||||
|
||||
Set the absolute value of a variable or setpoint.
|
||||
If `value` is not defined, it is assumed to be 0.
|
||||
@ -631,7 +828,7 @@ data:
|
||||
Otherwise the module might show unexpected behaviors or return error messages.
|
||||
</div>
|
||||
|
||||
### Service `var_rel`
|
||||
### Service: `var_rel`
|
||||
|
||||
Set the relative value of a variable or setpoint.
|
||||
If `value` is not defined, it is assumed to be 0.
|
||||
@ -660,7 +857,7 @@ data:
|
||||
Otherwise the module might show unexpected behavior or return error messages.
|
||||
</div>
|
||||
|
||||
### Service `var_reset`
|
||||
### Service: `var_reset`
|
||||
|
||||
Reset value of variable or setpoint.
|
||||
|
||||
@ -683,7 +880,7 @@ data:
|
||||
Otherwise the module might show unexpected behavior or return error messages.
|
||||
</div>
|
||||
|
||||
### Service `lock_regulator`
|
||||
### Service: `lock_regulator`
|
||||
|
||||
Locks a regulator setpoint.
|
||||
If `state` is not defined, it is assumed to be `False`.
|
||||
@ -704,7 +901,7 @@ data:
|
||||
state: true
|
||||
```
|
||||
|
||||
### Service `send_keys`
|
||||
### Service: `send_keys`
|
||||
|
||||
Send keys (which executes bound commands).
|
||||
The keys attribute is a string with one or more key identifiers. Example: `a1a5d8`
|
||||
@ -741,7 +938,7 @@ data:
|
||||
time_unit: s
|
||||
```
|
||||
|
||||
### Service `lock_keys`
|
||||
### Service: `lock_keys`
|
||||
|
||||
Locks keys.
|
||||
If the table is not defined, it is assumed to be table `a`.
|
||||
@ -778,7 +975,7 @@ data:
|
||||
time_unit: s
|
||||
```
|
||||
|
||||
### Service `dyn_text`
|
||||
### Service: `dyn_text`
|
||||
|
||||
Send dynamic text to LCN-GTxD displays.
|
||||
The displays support four rows for text messages.
|
||||
@ -801,7 +998,7 @@ data:
|
||||
text: "text in row 1"
|
||||
```
|
||||
|
||||
### Service `pck`
|
||||
### Service: `pck`
|
||||
|
||||
Send arbitrary PCK command. Only the command part of the PCK command has to be specified in the `pck` string.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user