From 620d7091c8a63ff552891585474cfec7aba82ca2 Mon Sep 17 00:00:00 2001 From: wjtje <33957974+wjtje@users.noreply.github.com> Date: Sun, 19 Jan 2025 11:23:46 +0000 Subject: [PATCH 1/5] Added documentation about the shell.script_event --- source/_integrations/shelly.markdown | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index 6ada2d20a971..b9aa91902083 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -158,6 +158,8 @@ If the **BUTTON TYPE** of the switch connected to the device is set to `momentar Also, some devices do not add an entity for the button/switch. For example, the Shelly Button1 has only one entity for the battery level. It does not have an entity for the button itself. To trigger automations based on button presses, use the `shelly.click` event. +At last it's possible to send events from scripts using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function, these events will show up under the type `shelly.script_event`. + ### Listening for events You can subscribe to the `shelly.click` event type in [Developer Tools/Events](/docs/tools/dev-tools/) in order to examine the event data JSON for the correct parameters to use in your automations. For example, `shelly.click` returns event data JSON similar to the following when you press the Shelly Button1. @@ -185,6 +187,32 @@ Event 0 fired 9:53 AM: The `generation` value indicates the generation of the device that is the source of the event. +The `shelly.script_event` returns event data JSON similar to the following when using the example code for [Shell.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent). + +```json +Event 1 fired 9:50 AM: +{ + "event_type": "shelly.script_event", + "data": { + "device_id": "e58a73d99f7c0d789d80e60ac20d0e01", + "device": "shellyplus2pm-d0ef76c7242c", + "component": "script:1", + "event": "this_happened", + "data": { + "why": 42, + "what": "when" + } + }, + "origin": "LOCAL", + "time_fired": "2025-01-19T08:50:52.214180+00:00", + "context": { + "id": "01JHYW3YNPBHP6C5Z8BJDTPHDN", + "parent_id": null, + "user_id": null + } +} +``` + ### Automations The simplest way to create automations is to use the Home Assistant automation editor. For example, to set an automation triggered by a double press of a particular Shelly Button1: From 4a5b63b657169e3a805bc4f9231e2e7ad741b3d7 Mon Sep 17 00:00:00 2001 From: wjtje <33957974+wjtje@users.noreply.github.com> Date: Sun, 19 Jan 2025 19:55:43 +0000 Subject: [PATCH 2/5] Added missing comma to improve the flow of the text --- source/_integrations/shelly.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index b9aa91902083..e0590f5119b4 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -158,7 +158,7 @@ If the **BUTTON TYPE** of the switch connected to the device is set to `momentar Also, some devices do not add an entity for the button/switch. For example, the Shelly Button1 has only one entity for the battery level. It does not have an entity for the button itself. To trigger automations based on button presses, use the `shelly.click` event. -At last it's possible to send events from scripts using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function, these events will show up under the type `shelly.script_event`. +At last, it's possible to send events from scripts using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function, these events will show up under the type `shelly.script_event`. ### Listening for events From 63f9be7c0cd2076c6b13109bf361a98f9401d512 Mon Sep 17 00:00:00 2001 From: wjtje <33957974+wjtje@users.noreply.github.com> Date: Wed, 22 Jan 2025 18:01:05 +0100 Subject: [PATCH 3/5] Updated documentation about the new script event entity --- source/_integrations/shelly.markdown | 32 +++------------------------- 1 file changed, 3 insertions(+), 29 deletions(-) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index e0590f5119b4..e55026595fc8 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -158,8 +158,6 @@ If the **BUTTON TYPE** of the switch connected to the device is set to `momentar Also, some devices do not add an entity for the button/switch. For example, the Shelly Button1 has only one entity for the battery level. It does not have an entity for the button itself. To trigger automations based on button presses, use the `shelly.click` event. -At last, it's possible to send events from scripts using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function, these events will show up under the type `shelly.script_event`. - ### Listening for events You can subscribe to the `shelly.click` event type in [Developer Tools/Events](/docs/tools/dev-tools/) in order to examine the event data JSON for the correct parameters to use in your automations. For example, `shelly.click` returns event data JSON similar to the following when you press the Shelly Button1. @@ -187,32 +185,6 @@ Event 0 fired 9:53 AM: The `generation` value indicates the generation of the device that is the source of the event. -The `shelly.script_event` returns event data JSON similar to the following when using the example code for [Shell.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent). - -```json -Event 1 fired 9:50 AM: -{ - "event_type": "shelly.script_event", - "data": { - "device_id": "e58a73d99f7c0d789d80e60ac20d0e01", - "device": "shellyplus2pm-d0ef76c7242c", - "component": "script:1", - "event": "this_happened", - "data": { - "why": 42, - "what": "when" - } - }, - "origin": "LOCAL", - "time_fired": "2025-01-19T08:50:52.214180+00:00", - "context": { - "id": "01JHYW3YNPBHP6C5Z8BJDTPHDN", - "parent_id": null, - "user_id": null - } -} -``` - ### Automations The simplest way to create automations is to use the Home Assistant automation editor. For example, to set an automation triggered by a double press of a particular Shelly Button1: @@ -359,7 +331,9 @@ The integration supports the following virtual components: ## Scripts (generation 2 and 3) -For each device script, the integration creates a `switch` entity that allows you to control the script. These entities are disabled by default. +For each device script, the integration creates a `switch` entity that allows you to control the script and an `event` entity. These entities are disabled by default. + +The `event` entity shows event that are emitted by the script using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent). After changing a script, it's required to manually reload the device before new event types show up. ## Additional info From 30b1050f08e6b4af4def90ddea169341a1f0af2e Mon Sep 17 00:00:00 2001 From: Wouter van der Wal <33957974+wjtje@users.noreply.github.com> Date: Sun, 2 Feb 2025 15:08:02 +0100 Subject: [PATCH 4/5] Added an example script which uses events --- source/_integrations/shelly.markdown | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index e55026595fc8..90fbea0edd19 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -335,6 +335,22 @@ For each device script, the integration creates a `switch` entity that allows yo The `event` entity shows event that are emitted by the script using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent). After changing a script, it's required to manually reload the device before new event types show up. +For example, the following script will emit an event every time an input (button or switch) on the device is changed. + +```javascript +// Example shelly script +function eventHandler(event, userdata) { + if ( + typeof event.component === "string" && + event.component.substring(0, 5) === "input" + ) { + let id = Number(event.component.substring(6)); + Shelly.emitEvent("input_event", { id: id }); + } +} +Shelly.addEventHandler(eventHandler); +``` + ## Additional info Shelly devices rely on [SNTP](https://en.wikipedia.org/wiki/Network_Time_Protocol#SNTP) for features like power measurement. From beca9632baa7aa65e620dc422940e734c5163e4a Mon Sep 17 00:00:00 2001 From: wjtje <33957974+wjtje@users.noreply.github.com> Date: Sun, 2 Feb 2025 17:42:12 +0100 Subject: [PATCH 5/5] Moved the script entity to the correct location in the shelly documentation Signed-off-by: wjtje <33957974+wjtje@users.noreply.github.com> --- source/_integrations/shelly.markdown | 38 ++++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/source/_integrations/shelly.markdown b/source/_integrations/shelly.markdown index 90fbea0edd19..57ae80756c1e 100644 --- a/source/_integrations/shelly.markdown +++ b/source/_integrations/shelly.markdown @@ -152,6 +152,24 @@ If the **BUTTON TYPE** of the switch connected to the device is set to `momentar If the **Input Mode** of the switch connected to the device is set to `Button`, the integration creates an event entity for this switch. You can use this entity in your automations. +Each script which generates events using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) also gets an corresponding event entity. This entity is disabled by default. After changing a script, it's required to manually reload the device before new event types show up. + +For example, the following script will emit an event every time an input (button or switch) on the device is changed. + +```javascript +// Example shelly script +function eventHandler(event, userdata) { + if ( + typeof event.component === "string" && + event.component.substring(0, 5) === "input" + ) { + let id = Number(event.component.substring(6)); + Shelly.emitEvent("input_event", { id: id }); + } +} +Shelly.addEventHandler(eventHandler); +``` + ## Events If the **BUTTON TYPE** of the switch connected to the device is set to `momentary` or `detached switch`, integration fires events under the type `shelly.click` when the switch is used. You can use these events in your automations. @@ -331,25 +349,7 @@ The integration supports the following virtual components: ## Scripts (generation 2 and 3) -For each device script, the integration creates a `switch` entity that allows you to control the script and an `event` entity. These entities are disabled by default. - -The `event` entity shows event that are emitted by the script using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent). After changing a script, it's required to manually reload the device before new event types show up. - -For example, the following script will emit an event every time an input (button or switch) on the device is changed. - -```javascript -// Example shelly script -function eventHandler(event, userdata) { - if ( - typeof event.component === "string" && - event.component.substring(0, 5) === "input" - ) { - let id = Number(event.component.substring(6)); - Shelly.emitEvent("input_event", { id: id }); - } -} -Shelly.addEventHandler(eventHandler); -``` +For each device script, the integration creates a `switch` entity that allows you to control the script. These entities are disabled by default. ## Additional info