Added documentation about the shelly.script_event event type #36992
Conversation
wjtje
requested review from
balloob,
bieniu,
thecode,
chemelli74 and
bdraco
as code owners
home-assistant
bot
added
has-parent
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe pull request enhances the Shelly integration documentation by introducing a new Changes
Sequence DiagramsequenceDiagram
participant Script as Shelly Device Script
participant Shelly as Shelly Integration
participant HA as Home Assistant
Script->>Shelly: Shelly.emitEvent()
Shelly-->>HA: Trigger event
HA->>HA: Process event
The sequence diagram illustrates the flow of creating a custom event using Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
source/_integrations/shelly.markdown (2)
161-162: Enhance the introduction of the script event feature.Consider these improvements:
- Add a comma after "At last" for better readability
- Provide example use cases for when developers might want to use this feature
-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`. This feature enables developers to trigger Home Assistant automations from custom Shelly device scripts, useful for scenarios like button press combinations or complex sensor logic.🧰 Tools
🪛 LanguageTool
[uncategorized] ~161-~161: A comma is probably missing here.
Context: ...sses, use theshelly.clickevent. At last it's possible to send events from scrip...(MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
190-214: Update the example timestamp to a more realistic date.The example uses a future date (2025-01-19) which might be confusing for users. Consider using a more recent or current date in the example.
- "time_fired": "2025-01-19T08:50:52.214180+00:00", + "time_fired": "2024-01-19T08:50:52.214180+00:00",
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/shelly.markdown(2 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/shelly.markdown
[uncategorized] ~161-~161: A comma is probably missing here.
Context: ...sses, use the shelly.click event. At last it's possible to send events from scrip...
(MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
source/_integrations/shelly.markdown (2)
161-162: Enhance the introduction of script events.The introduction could be more informative. Consider expanding it to include:
- A brief description of use cases
- The purpose of script events
- The relationship to automation capabilities
-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`. +Scripts running on Shelly devices can emit custom events using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function. These events are received by Home Assistant as `shelly.script_event` events, enabling advanced automation scenarios based on custom device conditions or triggers.
192-214: Update the example timestamp and add practical context.
- The example shows a future date (2025) which might confuse users.
- Consider adding a practical example that demonstrates a real-world use case.
{ "event_type": "shelly.script_event", "data": { "device_id": "e58a73d99f7c0d789d80e60ac20d0e01", "device": "shellyplus2pm-d0ef76c7242c", "component": "script:1", - "event": "this_happened", + "event": "temperature_threshold", "data": { - "why": 42, - "what": "when" + "temperature": 25.5, + "threshold": 25.0, + "status": "exceeded" } }, "origin": "LOCAL", - "time_fired": "2025-01-19T08:50:52.214180+00:00", + "time_fired": "2024-01-19T08:50:52.214180+00:00", "context": { "id": "01JHYW3YNPBHP6C5Z8BJDTPHDN", "parent_id": null, "user_id": null } }Consider adding a practical example of how to use this event in an automation:
# Example automation that reacts to a temperature threshold event trigger: platform: event event_type: shelly.script_event event_data: event: temperature_threshold data: status: exceeded action: - service: notify.mobile_app data: message: "Temperature threshold exceeded: {{ trigger.event.data.data.temperature }}°C"
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
source/_integrations/shelly.markdown (1)
334-335: Add instructions for enabling script entities.The documentation should explain how users can enable these disabled-by-default entities.
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. + +To enable these entities: +1. Go to **Settings** > **Devices & Services** +2. Find your Shelly device and click on it +3. Click on **Enable** next to the script entities you want to use
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/shelly.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/shelly.markdown
[style] ~336-~336: Style-wise, it’s not ideal to insert an adverb (‘manually’) in the middle of an infinitive construction (‘to reload’). Try moving the adverb to avoid split infinitives.
Context: ...itevent). After changing a script, it's required to manually reload the device before new event types show up. ## Add...
(SPLIT_INFINITIVE)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Redirect rules - home-assistant-docs
- GitHub Check: Header rules - home-assistant-docs
- GitHub Check: Pages changed - home-assistant-docs
| 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. |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Improve script events documentation.
The documentation needs enhancement in several areas:
- Fix the split infinitive
- Add event data structure
- Add generation availability information
-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.
+{% note %}
+The script events feature is only available on Shelly Generation 2 and 3 devices.
+{% endnote %}
+
+Scripts running on Shelly devices can emit custom events using the [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent) function. These events are received by Home Assistant as `shelly.script_event` events.
+
+The `shelly.script_event` event contains the following data structure:
+- `device_id`: Unique identifier of the Shelly device
+- `device`: Device name/identifier
+- `component`: The script component that emitted the event
+- `event`: Custom event name specified in the script
+- `data`: Custom data payload from the script
+
+After changing a script, you need to reload the device to see new event types.
+
+Here's an example event data when using [Shelly.emitEvent()](https://shelly-api-docs.shelly.cloud/gen2/Scripts/ShellyScriptLanguageFeatures#shellyemitevent):
+
+```json
+{
+ "device_id": "shellyplus1pm-a8032ab1f840",
+ "device": "Kitchen Light",
+ "component": "script:1",
+ "event": "motion_detected",
+ "data": {
+ "sensor": "pir1",
+ "lux": 50
+ }
+}
+```🧰 Tools
🪛 LanguageTool
[style] ~336-~336: Style-wise, it’s not ideal to insert an adverb (‘manually’) in the middle of an infinitive construction (‘to reload’). Try moving the adverb to avoid split infinitives.
Context: ...itevent). After changing a script, it's required to manually reload the device before new event types show up. ## Add...
(SPLIT_INFINITIVE)
| 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. |
There was a problem hiding this comment.
It would be nice to add a short example script (maybe something similar to what is used as MOCK in the core PR) in addition to the link to Shelly docs.
Proposed change
Added documentation about the new
shell.script_eventtype for Shelly devices. This event type will be used when a script on a Shelly devices usesShell.emitEvent().Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
New Features
Documentation
evententity for device scripts.