mirror of
https://github.com/XiaoMi/ha_xiaomi_home.git
synced 2025-12-16 18:32:17 +08:00
Created Event parameters (markdown)
Li Shuzhen
122
Event-parameters.md
Normal file
122
Event-parameters.md
Normal file
@@ -0,0 +1,122 @@
|
||||
To explain what the MIoT-Spec-V2 event parameter is, we take examples of some typical devices that have event instances with event parameters.
|
||||
|
||||
## Lock
|
||||
|
||||
For example, [xiaomi.lock.s2](https://miot-spec.org/miot-spec-v2/instance?type=urn:miot-spec-v2:device:lock:0000A038:xiaomi-s2:1) siid=2 eiid=1020 is an event instance named "Lock Event". Its "arguments" field is [1,2,3,4,5,6], meaning that piid=1 "Operation Position" property, piid=2 "Operation Method" property, piid=3 "Lock Action" property, piid=4 "Abnormal Condition", piid=5 "Operation ID" property and piid=6 "Current Time" in siid=2 service is the event parameters of this event. Each parameter follows the format, unit, value-range or value-list restrictions defined in the corresponding property instance.
|
||||
|
||||
When the device triggers this event, it will report an `event_occured` message like this:
|
||||
```json
|
||||
{"id":123,"method":"event_occured","params":{"did":"2834","siid":2,"eiid":1020,"arguments":[{"piid":1,"value":1},{"piid":2,"value":14},{"piid":3,"value":2},{"piid":4,"value":11},{"piid":5,"value":0},{"piid":6,"value":1764110215}]}}
|
||||
```
|
||||
|
||||
If xiaomi_home log level is set to debug level in Home Assistant, the following log will be printed:
|
||||
```
|
||||
Lock Event, attributes: {'Operation Position': 1, 'Operation Method': 14, 'Lock Action': 2, 'Abnormal Condition': 11, 'Operation ID': 0, 'Current Time': 1764110215}
|
||||
```
|
||||
|
||||
Meanwhile in xiaomi_home, the Event entity "Lock Lock Event" whose entity_id is `event.xiaomi_cn_2834_s2_lock_event_e_2_1020` is triggered and the Logbook records the time when this event occurred.
|
||||
|
||||
|
||||
<div align="center">
|
||||
<img src="https://github.com/user-attachments/assets/a1cf1d4d-d323-4b6e-8814-1b10e4e93425" width="60%" alt="Lock event">
|
||||
<br>
|
||||
<em>Figure 1: Lock event</em>
|
||||
</div>
|
||||
|
||||
## Wireless Switch Sensor
|
||||
|
||||
For example, [xiaomi.remote.mcn002](http://poc.miot-spec.srv/miot-spec-v2/instance?type=urn:miot-spec-v2:device:remote-control:0000A021:xiaomi-mcn002:1:0000D057) siid=2 eiid=1013 is an event instance named "Double Click". Its "arguments" field is [2], meaning that piid=2 "Button Type" property in siid=2 service is the only one parameter of this event. This parameter's value should be 0, 1 or 2, for the corresponding property has a value-list to indicate the button type that is "Left Button", "Right Button" or "Left and Right Button".
|
||||
|
||||
When the device's left button is double clicked triggering an event, it will report an `event_occured` message like this:
|
||||
```json
|
||||
{"id":456,"method":"event_occured","params":{"did":"blt.3.p0c1","siid":2,"eiid":1013,"arguments":[{"piid":2,"value":1}]}}
|
||||
```
|
||||
|
||||
If xiaomi_home log level is set to debug level in Home Assistant, the following log will be printed:
|
||||
```
|
||||
Double Press, attributes: {'Button Type': 1}
|
||||
```
|
||||
|
||||
Meanwhile in xiaomi_home, the Event entity "switch-sensor-for-ble Double press" whose entity_id is `event.xiaomi_cn_blt_3_p0c1_mcn002_double_click_e_2_1013` is triggered and the Logbook records the time when this event occurred.
|
||||
|
||||
<div align="center">
|
||||
<img src="https://github.com/user-attachments/assets/5b0d2490-d9f1-45b4-b0c9-b842fad7b20a" width="60%" alt="click event">
|
||||
<br>
|
||||
<em>Figure 2: Switch click event</em>
|
||||
</div>
|
||||
|
||||
## Use event parameters as conditions in automation
|
||||
|
||||
For example, we want to trigger an automation when the lock [xiaomi.lock.s2](https://miot-spec.org/miot-spec-v2/instance?type=urn:miot-spec-v2:device:lock:0000A038:xiaomi-s2:1) is unlocked indoor, we can set the automation trigger and condition in YAML like this:
|
||||
|
||||
```yaml
|
||||
alias: lock_event
|
||||
description: "unlock indoor"
|
||||
triggers:
|
||||
- trigger: event
|
||||
event_type: state_changed
|
||||
event_data:
|
||||
entity_id: event.xiaomi_cn_2834_s2_lock_event_e_2_1020
|
||||
conditions:
|
||||
- condition: template
|
||||
value_template: |
|
||||
{{
|
||||
trigger.event.data.new_state is not none and
|
||||
trigger.event.data.new_state.attributes.get('Operation Position') == 1 and
|
||||
trigger.event.data.new_state.attributes.get('Lock Action') == 2
|
||||
}}
|
||||
```
|
||||
|
||||
<div align="center">
|
||||
<img src="https://github.com/user-attachments/assets/bbd3006a-a6a7-4e3d-9ce2-6539eaa390bf" alt="condition parameter">
|
||||
<br>
|
||||
<em>Figure 3: Set automation condition with event parameters</em>
|
||||
</div>
|
||||
|
||||
|
||||
## Display the event parameter in the Sensor entity
|
||||
|
||||
For example, [xiaomi.waterpuri.s1200g](http://poc.miot-spec.srv/miot-spec-v2/instance?type=urn:miot-spec-v2:device:water-purifier:0000A013:xiaomi-s1200g:1:0000D05A) reports siid=8 eiid=1 "Water Production Completed" event when the water production is completed. This event contains piid=2 "Pure Water Output" property as the event parameter. The Event entity does not display the parameters in the entity history. Here is the method to extract the event parameter and display it in a Sensor entity.
|
||||
|
||||
1. Add the following code in configuration.yaml. input_text is used to store the event parameter which is displayed in template sensor.
|
||||
|
||||
```yaml
|
||||
input_text:
|
||||
last_event_data:
|
||||
name: "Last Event Data"
|
||||
initial: "No event yet"
|
||||
|
||||
template:
|
||||
- sensor:
|
||||
- name: "Last Pure Water Output"
|
||||
state: "{{ states('input_text.last_event_data') }}"
|
||||
device_class: volume
|
||||
unit_of_measurement: "mL"
|
||||
state_class: total_increasing
|
||||
```
|
||||
|
||||
2. Create an automation of which the automation action will set the event parameter as the value of input_text when the event is triggered.
|
||||
|
||||
```yaml
|
||||
alias: event_attribute_to_input_text
|
||||
description: "Set event data as input text"
|
||||
triggers:
|
||||
- trigger: state
|
||||
entity_id:
|
||||
- event.xiaomi_cn_4047_s1200g_water_production_completed_e_8_1
|
||||
conditions: []
|
||||
actions:
|
||||
- action: input_text.set_value
|
||||
metadata: {}
|
||||
data:
|
||||
value: "{{ trigger.to_state.attributes['Pure Water Output'] }}"
|
||||
target:
|
||||
entity_id: input_text.last_event_data
|
||||
mode: single
|
||||
```
|
||||
|
||||
<div align="center">
|
||||
<img src="https://github.com/user-attachments/assets/78d8ea29-cb6e-441b-9069-d86949533bfe" alt="display sensor">
|
||||
<br>
|
||||
<em>Figure 4: Display the event parameter in the Sensor entity</em>
|
||||
</div>
|
||||
Reference in New Issue
Block a user