@camstack/addon-provider-esphome 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +13 -0
- package/README.md +52 -2
- package/assets/icon.svg +9 -0
- package/dist/addon.js +106946 -0
- package/dist/addon.mjs +106940 -0
- package/dist/index.js +8 -0
- package/dist/index.mjs +2 -0
- package/i18n/en.json +31 -0
- package/i18n/it.json +31 -0
- package/package.json +90 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this package are documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- First release: one broker per ESPHome board over the native API (Noise or plain), mDNS discovery, and adoption of a connected board as a container with a child per entity (switch, light, cover, button, number, select, event, sensor, text sensor, binary sensor, power meter).
|
|
13
|
+
- Bounded reconnect backoff; a refused key or password is reported as `auth-failed` and not retried.
|
package/README.md
CHANGED
|
@@ -1,3 +1,53 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @camstack/addon-provider-esphome
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
ESPHome device-provider addon for CamStack. It speaks the board's native API (Noise-encrypted or plain) with `esphome-client` and turns a board into one container device with a child per entity.
|
|
4
|
+
|
|
5
|
+
## What it does
|
|
6
|
+
|
|
7
|
+
- **ESPHome** (`provider-esphome`): one broker per board (host, port 6053, encryption key, optional legacy password), a LAN scan that proposes boards, and adoption of a connected board.
|
|
8
|
+
- Node placement: `hub-only`.
|
|
9
|
+
- Capabilities: `device-provider`, `broker`, `device-adoption`.
|
|
10
|
+
|
|
11
|
+
## Mapping
|
|
12
|
+
|
|
13
|
+
A board is one container device. Its entities become children:
|
|
14
|
+
|
|
15
|
+
| ESPHome entity | CamStack child |
|
|
16
|
+
| --- | --- |
|
|
17
|
+
| switch | switch |
|
|
18
|
+
| light | switch + brightness (colour is not mapped yet) |
|
|
19
|
+
| cover | cover (open, close, stop, position) |
|
|
20
|
+
| button | button |
|
|
21
|
+
| number, select | control |
|
|
22
|
+
| event | event emitter (a replayed state never fires) |
|
|
23
|
+
| sensor | numeric sensor, converted to the base unit of its quantity |
|
|
24
|
+
| text sensor | enum sensor |
|
|
25
|
+
| binary sensor | contact (door, window, opening, garage door), flood (moisture), smoke, motion (motion, occupancy, presence), otherwise binary |
|
|
26
|
+
| power, energy, voltage, current, apparent power, power factor sensors | one `power-meter` child |
|
|
27
|
+
|
|
28
|
+
Entities the board marks diagnostic or disabled by default, and its status binary sensor, are not adopted.
|
|
29
|
+
|
|
30
|
+
## Behaviour
|
|
31
|
+
|
|
32
|
+
- Live state arrives by subscription; there is no polling.
|
|
33
|
+
- A lost connection is retried with a bounded backoff (1 s doubling to 60 s, with jitter). A key or password the board refuses is not retried: the broker shows `auth-failed` until the operator edits it.
|
|
34
|
+
- An unreachable board is offline, never zero: its children keep the last reading and the container goes offline.
|
|
35
|
+
- The encryption key and the legacy password are keychain secrets. They are never returned by a read, never logged, and a save that leaves the field empty keeps the stored value.
|
|
36
|
+
- The addon only reads state and sends the commands an operator triggers on an adopted device. It never guesses or tries keys.
|
|
37
|
+
|
|
38
|
+
## Where to find the key
|
|
39
|
+
|
|
40
|
+
In the board's ESPHome YAML under `api: encryption: key:`. In the ESPHome dashboard open the device and choose Edit; in Home Assistant it is stored in the ESPHome integration entry for that device. Paste it into the broker dialog's "Encryption key" field.
|
|
41
|
+
|
|
42
|
+
## Known limits
|
|
43
|
+
|
|
44
|
+
- Light colour and colour temperature are not mapped.
|
|
45
|
+
- Entities of an ESPHome sub-device (firmware 2025.7 and later) are not separated from the board's own.
|
|
46
|
+
- Firmware older than 2024.4 is untested.
|
|
47
|
+
- A board allows only a few simultaneous API clients (ESP8266 especially); Home Assistant holds one of them.
|
|
48
|
+
- Two controllers can write the same relay; CamStack follows the state the board reports.
|
|
49
|
+
|
|
50
|
+
## Requirements
|
|
51
|
+
|
|
52
|
+
- Peer packages already on the node: `@camstack/types`, `zod`.
|
|
53
|
+
- A CamStack hub. This addon does not run on an agent.
|
package/assets/icon.svg
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="ESPHome board">
|
|
2
|
+
<rect x="10" y="14" width="44" height="36" rx="5" fill="#1f2933"/>
|
|
3
|
+
<rect x="16" y="20" width="14" height="10" rx="2" fill="#9aa5b1"/>
|
|
4
|
+
<circle cx="42" cy="25" r="3" fill="#3ddc97"/>
|
|
5
|
+
<circle cx="50" cy="25" r="2" fill="#f0b429"/>
|
|
6
|
+
<rect x="16" y="36" width="32" height="3" rx="1.5" fill="#52606d"/>
|
|
7
|
+
<rect x="16" y="42" width="22" height="3" rx="1.5" fill="#52606d"/>
|
|
8
|
+
<path d="M20 14v-5M28 14v-5M36 14v-5M44 14v-5" stroke="#9aa5b1" stroke-width="2" stroke-linecap="round"/>
|
|
9
|
+
</svg>
|