ArturandGitHub
8296ca0f7e
* feat(hassio): Implemented the Home Assistant plugin for Noctalia v5. * Update plugin.toml * Update plugin.toml * fix(*): Changed curl HTTP calls to native noctalia HTTP calls. * fix(*): Fixed headers on HTTP requests. * fix(service_sse): Fixed HA tokens visible on argv during streams. * fix(service_sse): Added an explicit exit signal for the stream and refresh/reload_entities no longer force `sseActive = false`. * fix(*): Fixed xdg-open missing from README.md and plugin.toml * refact(widget): Changed runInTerminal to runAsync on xdg-open calls to prevent the termial from popping up. * fix(*): Changed plugin data location to be stored where pluginDataDir() points. * fix(README): Added all IPC calls to README. * Updated README to reflect recent changes. * refact(*): Removed some dead code. * fix(*): Changed toggle timeout logic to use real time, fixing toggles being stuck in a loding animation. * refact(*): Added a token cleaner function. * refact(service_sse): Changed curl stream calls for the new native HTTP streaming API. * feat(*): Fixed some translations.
78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
# Home Assistant
|
||
|
||
Monitor and control your Home Assistant entities from the Noctalia bar and control center. Useful for quickly toggling lights, checking sensor states, and opening a full entity manager panel for richer controls.
|
||
|
||
## Plugin
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| ID | `pozzoo/hassio` |
|
||
| Entries | Widget: `status`; Service: `connection`; Shortcuts: `ha_toggle_1`, `ha_toggle_2`, `ha_toggle_3`, `ha_toggle_4`, `ha_panel`; Panel: `entity_manager` |
|
||
| Launcher Prefix | — |
|
||
|
||
## Requirements
|
||
|
||
- A running Home Assistant instance with API access enabled
|
||
- A Long-lived Access Token (Profile → Security → Long-lived access tokens)
|
||
- `xdg-open` available on `PATH` (used to open the Home Assistant URL in your browser)
|
||
|
||
## Usage
|
||
|
||
1. Configure the plugin: open **Settings → Plugins → Home Assistant** and set:
|
||
|
||
| Setting | Description |
|
||
| --- | --- |
|
||
| Home Assistant URL | The URL to your HA instance, for example `http://homeassistant.local:8123` |
|
||
| Long-Lived Access Token | Token created in HA under Profile → Security |
|
||
| Quick Toggle 1–4 — Entity ID | (Optional) Entity IDs to assign to each quick-toggle tile (e.g. `light.living_room`) |
|
||
|
||
2. Add the bar widget: add the **status** widget from the widget picker to show connection state and (optionally) the number of monitored entities. Right-click the widget to open your Home Assistant URL in the default browser.
|
||
|
||
3. Add control-center tiles: go to **Settings → Control Center** and add any combination of:
|
||
- **Home Assistant** (×4) — Quick-toggle tiles. Each corresponds to one of the four entity slots configured in plugin settings.
|
||
- **Home Assistant** (panel opener) — Opens the entity manager panel.
|
||
|
||
4. Open the entity manager panel: use the panel opener tile or the panel IPC command to open the full browser and pin entities for monitoring.
|
||
|
||
```sh
|
||
noctalia msg panel-toggle pozzoo/hassio:entity_manager
|
||
```
|
||
|
||
## Settings
|
||
|
||
| Setting | Type | Default | Description |
|
||
| --- | --- | --- | --- |
|
||
| `ha_url` | `string` | `""` | Home Assistant base URL used for API requests (include protocol and port if needed). |
|
||
| `ha_token` | `string` | `""` | Long-lived access token for Home Assistant. Keep this secret. |
|
||
| `shortcut_entity_1` | `string` | `""` | Entity ID used by Quick Toggle 1 (e.g. `light.kitchen`). |
|
||
| `shortcut_entity_2` | `string` | `""` | Entity ID used by Quick Toggle 2. |
|
||
| `shortcut_entity_3` | `string` | `""` | Entity ID used by Quick Toggle 3. |
|
||
| `shortcut_entity_4` | `string` | `""` | Entity ID used by Quick Toggle 4. |
|
||
| `show_entity_count` | `bool` | `false` | Show the number of monitored entities next to the connection status in the `status` bar widget. |
|
||
|
||
## IPC
|
||
|
||
- Open the panel:
|
||
|
||
```sh
|
||
noctalia msg panel-toggle pozzoo/hassio:entity_manager
|
||
```
|
||
|
||
- Force a refresh of the connection and entity states:
|
||
|
||
```sh
|
||
noctalia msg plugin pozzoo/hassio:status focused refresh
|
||
```
|
||
|
||
Use `all` in place of `focused` to target every bar instance. This triggers the same refresh as sending the `refresh` command internally, and shows a notification when it starts.
|
||
|
||
Notes: the plugin forwards Home Assistant state updates internally and uses Noctalia's state routing to update widgets and shortcuts.
|
||
|
||
## Notes
|
||
|
||
- The plugin maintains a live SSE connection to Home Assistant to receive real-time state changes. Noctalia's native HTTP streaming API is used for this connection; all other requests (fetching states, toggling entities, browsing) go through Noctalia's native HTTP API.
|
||
- The pinned entity list is saved to `managed_entities.json` in the plugin's persistent data directory (`noctalia.pluginDataDir()`), so it survives plugin updates.
|
||
- To authenticate the SSE connection without exposing the access token on the command line, the plugin uses Noctalia's native streaming request headers.
|
||
- The plugin issues HTTP requests to your HA instance; do not install untrusted plugins if you do not want them to access your network or tokens.
|
||
- If authentication fails, generate a new long-lived access token in Home Assistant and paste it into plugin settings.
|