aioescea 0.1.0__tar.gz
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.
- aioescea-0.1.0/.github/workflows/ci.yml +48 -0
- aioescea-0.1.0/.github/workflows/release.yml +76 -0
- aioescea-0.1.0/.gitignore +10 -0
- aioescea-0.1.0/CHANGELOG.md +20 -0
- aioescea-0.1.0/LICENSE +29 -0
- aioescea-0.1.0/PKG-INFO +189 -0
- aioescea-0.1.0/README.md +157 -0
- aioescea-0.1.0/docs/protocol.md +155 -0
- aioescea-0.1.0/pyproject.toml +70 -0
- aioescea-0.1.0/src/aioescea/__init__.py +71 -0
- aioescea-0.1.0/src/aioescea/__main__.py +151 -0
- aioescea-0.1.0/src/aioescea/discovery.py +66 -0
- aioescea-0.1.0/src/aioescea/exceptions.py +41 -0
- aioescea-0.1.0/src/aioescea/fireplace.py +187 -0
- aioescea-0.1.0/src/aioescea/ncapi.py +258 -0
- aioescea-0.1.0/src/aioescea/protocol.py +175 -0
- aioescea-0.1.0/src/aioescea/py.typed +0 -0
- aioescea-0.1.0/src/aioescea/transport.py +226 -0
- aioescea-0.1.0/src/aioescea/web.py +359 -0
- aioescea-0.1.0/tests/__init__.py +0 -0
- aioescea-0.1.0/tests/conftest.py +52 -0
- aioescea-0.1.0/tests/fake_fire.py +83 -0
- aioescea-0.1.0/tests/fake_web.py +127 -0
- aioescea-0.1.0/tests/test_fireplace.py +190 -0
- aioescea-0.1.0/tests/test_ncapi.py +210 -0
- aioescea-0.1.0/tests/test_protocol.py +88 -0
- aioescea-0.1.0/tests/test_web.py +133 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
pull_request:
|
|
6
|
+
workflow_dispatch:
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: read
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
lint:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: actions/setup-python@v5
|
|
17
|
+
with:
|
|
18
|
+
python-version: "3.14"
|
|
19
|
+
- run: pip install -e ".[lint]"
|
|
20
|
+
- run: ruff check .
|
|
21
|
+
- run: ruff format --check .
|
|
22
|
+
- run: mypy
|
|
23
|
+
|
|
24
|
+
test:
|
|
25
|
+
runs-on: ubuntu-latest
|
|
26
|
+
strategy:
|
|
27
|
+
fail-fast: false
|
|
28
|
+
matrix:
|
|
29
|
+
python: ["3.12", "3.13", "3.14"]
|
|
30
|
+
steps:
|
|
31
|
+
- uses: actions/checkout@v4
|
|
32
|
+
- uses: actions/setup-python@v5
|
|
33
|
+
with:
|
|
34
|
+
python-version: ${{ matrix.python }}
|
|
35
|
+
# The tests run a fake fire on 127.0.0.2, which Linux routes to loopback.
|
|
36
|
+
- run: pip install -e ".[test]"
|
|
37
|
+
- run: pytest -q --cov=aioescea --cov-report=term-missing
|
|
38
|
+
|
|
39
|
+
build:
|
|
40
|
+
runs-on: ubuntu-latest
|
|
41
|
+
steps:
|
|
42
|
+
- uses: actions/checkout@v4
|
|
43
|
+
- uses: actions/setup-python@v5
|
|
44
|
+
with:
|
|
45
|
+
python-version: "3.14"
|
|
46
|
+
- run: pip install build twine
|
|
47
|
+
- run: python -m build
|
|
48
|
+
- run: twine check dist/*
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
# Bump __version__ in src/aioescea/__init__.py, add its CHANGELOG.md section,
|
|
4
|
+
# then push a tag "v<version>" (or publish a GitHub release with that tag).
|
|
5
|
+
# PyPI publishing uses trusted publishing: no token is stored in GitHub.
|
|
6
|
+
|
|
7
|
+
on:
|
|
8
|
+
push:
|
|
9
|
+
tags: ["v*"]
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
build:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
permissions:
|
|
15
|
+
contents: read
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: actions/setup-python@v5
|
|
19
|
+
with:
|
|
20
|
+
python-version: "3.14"
|
|
21
|
+
- name: Tag matches the package version
|
|
22
|
+
run: |
|
|
23
|
+
version=$(python -c "import re,pathlib;print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('src/aioescea/__init__.py').read_text())[1])")
|
|
24
|
+
test "v$version" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v$version"; exit 1; }
|
|
25
|
+
- run: pip install build
|
|
26
|
+
- run: python -m build
|
|
27
|
+
- uses: actions/upload-artifact@v4
|
|
28
|
+
with:
|
|
29
|
+
name: dist
|
|
30
|
+
path: dist/
|
|
31
|
+
|
|
32
|
+
pypi:
|
|
33
|
+
needs: build
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
environment:
|
|
36
|
+
name: pypi
|
|
37
|
+
url: https://pypi.org/project/aioescea/
|
|
38
|
+
permissions:
|
|
39
|
+
id-token: write
|
|
40
|
+
steps:
|
|
41
|
+
- uses: actions/download-artifact@v4
|
|
42
|
+
with:
|
|
43
|
+
name: dist
|
|
44
|
+
path: dist/
|
|
45
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
46
|
+
|
|
47
|
+
github:
|
|
48
|
+
needs: pypi
|
|
49
|
+
runs-on: ubuntu-latest
|
|
50
|
+
permissions:
|
|
51
|
+
contents: write
|
|
52
|
+
steps:
|
|
53
|
+
- uses: actions/checkout@v4
|
|
54
|
+
- uses: actions/download-artifact@v4
|
|
55
|
+
with:
|
|
56
|
+
name: dist
|
|
57
|
+
path: dist/
|
|
58
|
+
- name: Release notes from CHANGELOG.md
|
|
59
|
+
run: |
|
|
60
|
+
version="${GITHUB_REF_NAME#v}"
|
|
61
|
+
awk -v v="## $version" '$0==v{f=1;next} /^## /{f=0} f' CHANGELOG.md > notes.md
|
|
62
|
+
# Publishing a release on GitHub creates the tag that starts this
|
|
63
|
+
# workflow, so the release may already exist: then attach the files and
|
|
64
|
+
# fill in empty notes instead of creating it.
|
|
65
|
+
- env:
|
|
66
|
+
GH_TOKEN: ${{ github.token }}
|
|
67
|
+
run: |
|
|
68
|
+
if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
|
|
69
|
+
gh release upload "$GITHUB_REF_NAME" dist/* --clobber
|
|
70
|
+
body=$(gh release view "$GITHUB_REF_NAME" --json body --jq .body)
|
|
71
|
+
if [ -z "$(echo "$body" | tr -d '[:space:]')" ] && [ -s notes.md ]; then
|
|
72
|
+
gh release edit "$GITHUB_REF_NAME" --notes-file notes.md
|
|
73
|
+
fi
|
|
74
|
+
else
|
|
75
|
+
gh release create "$GITHUB_REF_NAME" dist/* --title "$GITHUB_REF_NAME" --notes-file notes.md
|
|
76
|
+
fi
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- UDP control: status, on, off, target temperature, and normal, boost and
|
|
8
|
+
flame effect modes, with retries and one request per fire at a time.
|
|
9
|
+
- Never sends a command it wasn't asked for, so it can't re-light a fire
|
|
10
|
+
turned off with the remote or app.
|
|
11
|
+
- Refuses commands during the 66 s lighting window (except turning off), and
|
|
12
|
+
refuses a mode change that would light a fire that's off unless asked.
|
|
13
|
+
- Discovery by broadcast on any list of broadcast addresses, and finding one
|
|
14
|
+
fire by serial number after its IP address changes.
|
|
15
|
+
- Web page client: the fire's clock, both timers (read and write) and the
|
|
16
|
+
diagnostics page.
|
|
17
|
+
- Generation 3 Wi-Fi fires through Escea's NCAPI (HTTP and JSON): state,
|
|
18
|
+
room temperature, remote presence, stored errors, and on/off, boost, flame
|
|
19
|
+
effect and target temperature in one request.
|
|
20
|
+
- `aioescea` command-line tool.
|
aioescea-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Oliver Maller and the aioescea contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
Portions are derived from these MIT-licensed projects:
|
|
26
|
+
|
|
27
|
+
- escea (https://github.com/snikch/escea), Copyright (c) 2016 Mal Curtis
|
|
28
|
+
- ha-escea (https://github.com/derekclapham/ha-escea), Copyright (c) 2026
|
|
29
|
+
Derek Clapham: the web page (timers and diagnostics) request formats
|
aioescea-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aioescea
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Async local-network client for Escea gas fireplaces
|
|
5
|
+
Project-URL: Homepage, https://github.com/olliemaller/aioescea
|
|
6
|
+
Project-URL: Issues, https://github.com/olliemaller/aioescea/issues
|
|
7
|
+
Project-URL: Changelog, https://github.com/olliemaller/aioescea/blob/main/CHANGELOG.md
|
|
8
|
+
Author: Oliver Maller
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: asyncio,escea,fireplace,home-assistant,udp
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Framework :: AsyncIO
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Home Automation
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: aiohttp>=3.9
|
|
24
|
+
Provides-Extra: lint
|
|
25
|
+
Requires-Dist: mypy>=1.13; extra == 'lint'
|
|
26
|
+
Requires-Dist: ruff>=0.8; extra == 'lint'
|
|
27
|
+
Provides-Extra: test
|
|
28
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
29
|
+
Requires-Dist: pytest-cov>=5; extra == 'test'
|
|
30
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# aioescea
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/aioescea/)
|
|
36
|
+
[](https://github.com/olliemaller/aioescea/actions/workflows/ci.yml)
|
|
37
|
+
[](LICENSE)
|
|
38
|
+
|
|
39
|
+
**Async Python client for Escea gas fireplaces on your local network.** No cloud.
|
|
40
|
+
|
|
41
|
+
It supports both generations of Escea network controller:
|
|
42
|
+
|
|
43
|
+
| | Generation 2 (Ethernet) | Generation 3 (Wi-Fi, from 2024) |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| Control | UDP port 3300 | NCAPI: HTTP and JSON on port 80 |
|
|
46
|
+
| On/off, temperature, boost, flame effect | ✓ (4-30 °C) | ✓ (10-38 °C, 0.1 °C steps) |
|
|
47
|
+
| Room temperature | ✓ | ✓ |
|
|
48
|
+
| What the fire is doing (starting, igniting, heating, shutting down, error) | | ✓ |
|
|
49
|
+
| Remote present, stored errors | | ✓ |
|
|
50
|
+
| Found by broadcast | ✓ | needs its IP address |
|
|
51
|
+
| Built-in timers, clock, diagnostics | ✓ (from its web page) | |
|
|
52
|
+
|
|
53
|
+
It powers the [Escea Fireplace](https://github.com/olliemaller/ha-escea-fireplace)
|
|
54
|
+
integration for Home Assistant.
|
|
55
|
+
|
|
56
|
+
> [!IMPORTANT]
|
|
57
|
+
> **Unofficial.** Not affiliated with or endorsed by Escea. "Escea" is a
|
|
58
|
+
> trademark of its owner, used here only to describe compatibility.
|
|
59
|
+
|
|
60
|
+
## Install
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
pip install aioescea
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Python 3.12 or later.
|
|
67
|
+
|
|
68
|
+
## Use it
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
import asyncio
|
|
72
|
+
from aioescea import EsceaFireplace, EsceaTransport, FireMode, async_discover
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
async def main() -> None:
|
|
76
|
+
async with EsceaTransport() as transport:
|
|
77
|
+
for found in await async_discover(transport):
|
|
78
|
+
print(found.host, found.serial, found.pin)
|
|
79
|
+
|
|
80
|
+
fire = EsceaFireplace("192.168.1.50", transport)
|
|
81
|
+
status = await fire.async_get_status()
|
|
82
|
+
print(status.is_on, status.room_temperature, status.target_temperature)
|
|
83
|
+
|
|
84
|
+
await fire.async_turn_on() # lights the fire
|
|
85
|
+
# The fire ignores commands for 66 s while it lights. Commands sent
|
|
86
|
+
# in that time raise EsceaBusyError; turning off is always allowed.
|
|
87
|
+
await asyncio.sleep(fire.busy_remaining)
|
|
88
|
+
await fire.async_set_temperature(22)
|
|
89
|
+
await fire.async_set_mode(FireMode.BOOST)
|
|
90
|
+
await fire.async_turn_off()
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
asyncio.run(main())
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Generation 3 (Wi-Fi) fires
|
|
97
|
+
|
|
98
|
+
Turn on **Escea NCAPI Settings** under Fire Settings in the Escea Smartheat
|
|
99
|
+
app first (fire firmware 1.5.9 or later), and give the fire a DHCP
|
|
100
|
+
reservation.
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
import aiohttp
|
|
104
|
+
from aioescea import EsceaNcapiClient
|
|
105
|
+
|
|
106
|
+
async with aiohttp.ClientSession() as session:
|
|
107
|
+
fire = EsceaNcapiClient(session, "192.168.1.60")
|
|
108
|
+
status = await fire.async_get_status()
|
|
109
|
+
print(status.state, status.room_temperature, status.remote_present)
|
|
110
|
+
await fire.async_set(on=True, flame_effect=True, target_temperature=22.5)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### The web page (Generation 2: timers, clock, diagnostics)
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
import aiohttp
|
|
117
|
+
from datetime import time
|
|
118
|
+
from aioescea import EsceaWebClient, Timer
|
|
119
|
+
|
|
120
|
+
async with aiohttp.ClientSession() as session:
|
|
121
|
+
web = EsceaWebClient(session, "192.168.1.50", username="123456", password="1234")
|
|
122
|
+
page = await web.async_get_home_page() # no login needed
|
|
123
|
+
print(page.clock, page.timers)
|
|
124
|
+
print(await web.async_get_diagnostics()) # login needed
|
|
125
|
+
|
|
126
|
+
await web.async_set_timer(
|
|
127
|
+
Timer(number=1, on_time=time(6, 30), off_time=time(8, 0), enabled=True),
|
|
128
|
+
fire_is_on=False, # must be the fire's real power state right now
|
|
129
|
+
current=page.timers,
|
|
130
|
+
)
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
On most fires the web login is the **serial number** and the **PIN**, both of
|
|
134
|
+
which discovery returns.
|
|
135
|
+
|
|
136
|
+
### Command line
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
aioescea discover
|
|
140
|
+
aioescea status 192.168.1.50
|
|
141
|
+
aioescea on 192.168.1.50
|
|
142
|
+
aioescea temp 192.168.1.50 22
|
|
143
|
+
aioescea mode 192.168.1.50 boost
|
|
144
|
+
aioescea off 192.168.1.50
|
|
145
|
+
aioescea timers 192.168.1.50
|
|
146
|
+
aioescea diagnostics 192.168.1.50 --username 123456 --password 1234
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## How it behaves
|
|
150
|
+
|
|
151
|
+
- **It never sends anything you didn't ask for.** No background loop, no
|
|
152
|
+
buffered commands. A missed reply can't cause an old command to be re-sent,
|
|
153
|
+
so it can't re-light a fire someone turned off with the remote or the app.
|
|
154
|
+
([The bug this avoids](https://github.com/lazdavila/pescea/issues/8).)
|
|
155
|
+
- **Changing the mode while the fire is off would light it**, because that's
|
|
156
|
+
how the fire works. `async_set_mode` refuses unless you pass
|
|
157
|
+
`allow_ignite=True`.
|
|
158
|
+
- **Turning off is never refused**, even during the 66 s lighting window.
|
|
159
|
+
- **One request per fire at a time, retried**, because the controller is
|
|
160
|
+
single threaded and UDP drops packets.
|
|
161
|
+
- **Port 3300 is not shared.** Fires always reply to port 3300, so only one
|
|
162
|
+
program per computer can talk to them. If another program has the port,
|
|
163
|
+
`EsceaPortInUseError` says so instead of silently missing replies.
|
|
164
|
+
- **The web page is fragile.** It answers one connection at a time and can
|
|
165
|
+
stop answering until the fire is power cycled. The client sends one request
|
|
166
|
+
at a time with `Connection: close`; poll it every few minutes at most.
|
|
167
|
+
|
|
168
|
+
## Protocol
|
|
169
|
+
|
|
170
|
+
- [Fireplace LAN Communications Protocol Specification v0.3](docs/protocol.md)
|
|
171
|
+
(Kamahi Electronics for Escea, 2014): the UDP protocol.
|
|
172
|
+
- [NCAPI](docs/protocol.md#generation-3-ncapi) (Escea document 640051_0,
|
|
173
|
+
2024): the Generation 3 Wi-Fi HTTP API.
|
|
174
|
+
- [Network summary](docs/protocol.md#controller-network-summary) (Tussock
|
|
175
|
+
Innovation for Escea, 2016): the controller's ports, DHCP behaviour and
|
|
176
|
+
MAC address prefix (`AC:DE:48`).
|
|
177
|
+
|
|
178
|
+
## Credits
|
|
179
|
+
|
|
180
|
+
- [snikch/escea](https://github.com/snikch/escea) by Mal Curtis: the first
|
|
181
|
+
Python client, and the captured frames used in the tests.
|
|
182
|
+
- [lazdavila/pescea](https://github.com/lazdavila/pescea) by Laz Davila: the
|
|
183
|
+
66 s busy window and the flame-effect quirk.
|
|
184
|
+
- [derekclapham/ha-escea](https://github.com/derekclapham/ha-escea) by Derek
|
|
185
|
+
Clapham: the web page's login, timer and diagnostics formats.
|
|
186
|
+
|
|
187
|
+
## Licence
|
|
188
|
+
|
|
189
|
+
[MIT](LICENSE)
|
aioescea-0.1.0/README.md
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# aioescea
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/aioescea/)
|
|
4
|
+
[](https://github.com/olliemaller/aioescea/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
**Async Python client for Escea gas fireplaces on your local network.** No cloud.
|
|
8
|
+
|
|
9
|
+
It supports both generations of Escea network controller:
|
|
10
|
+
|
|
11
|
+
| | Generation 2 (Ethernet) | Generation 3 (Wi-Fi, from 2024) |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Control | UDP port 3300 | NCAPI: HTTP and JSON on port 80 |
|
|
14
|
+
| On/off, temperature, boost, flame effect | ✓ (4-30 °C) | ✓ (10-38 °C, 0.1 °C steps) |
|
|
15
|
+
| Room temperature | ✓ | ✓ |
|
|
16
|
+
| What the fire is doing (starting, igniting, heating, shutting down, error) | | ✓ |
|
|
17
|
+
| Remote present, stored errors | | ✓ |
|
|
18
|
+
| Found by broadcast | ✓ | needs its IP address |
|
|
19
|
+
| Built-in timers, clock, diagnostics | ✓ (from its web page) | |
|
|
20
|
+
|
|
21
|
+
It powers the [Escea Fireplace](https://github.com/olliemaller/ha-escea-fireplace)
|
|
22
|
+
integration for Home Assistant.
|
|
23
|
+
|
|
24
|
+
> [!IMPORTANT]
|
|
25
|
+
> **Unofficial.** Not affiliated with or endorsed by Escea. "Escea" is a
|
|
26
|
+
> trademark of its owner, used here only to describe compatibility.
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
pip install aioescea
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Python 3.12 or later.
|
|
35
|
+
|
|
36
|
+
## Use it
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
import asyncio
|
|
40
|
+
from aioescea import EsceaFireplace, EsceaTransport, FireMode, async_discover
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
async def main() -> None:
|
|
44
|
+
async with EsceaTransport() as transport:
|
|
45
|
+
for found in await async_discover(transport):
|
|
46
|
+
print(found.host, found.serial, found.pin)
|
|
47
|
+
|
|
48
|
+
fire = EsceaFireplace("192.168.1.50", transport)
|
|
49
|
+
status = await fire.async_get_status()
|
|
50
|
+
print(status.is_on, status.room_temperature, status.target_temperature)
|
|
51
|
+
|
|
52
|
+
await fire.async_turn_on() # lights the fire
|
|
53
|
+
# The fire ignores commands for 66 s while it lights. Commands sent
|
|
54
|
+
# in that time raise EsceaBusyError; turning off is always allowed.
|
|
55
|
+
await asyncio.sleep(fire.busy_remaining)
|
|
56
|
+
await fire.async_set_temperature(22)
|
|
57
|
+
await fire.async_set_mode(FireMode.BOOST)
|
|
58
|
+
await fire.async_turn_off()
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
asyncio.run(main())
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Generation 3 (Wi-Fi) fires
|
|
65
|
+
|
|
66
|
+
Turn on **Escea NCAPI Settings** under Fire Settings in the Escea Smartheat
|
|
67
|
+
app first (fire firmware 1.5.9 or later), and give the fire a DHCP
|
|
68
|
+
reservation.
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
import aiohttp
|
|
72
|
+
from aioescea import EsceaNcapiClient
|
|
73
|
+
|
|
74
|
+
async with aiohttp.ClientSession() as session:
|
|
75
|
+
fire = EsceaNcapiClient(session, "192.168.1.60")
|
|
76
|
+
status = await fire.async_get_status()
|
|
77
|
+
print(status.state, status.room_temperature, status.remote_present)
|
|
78
|
+
await fire.async_set(on=True, flame_effect=True, target_temperature=22.5)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### The web page (Generation 2: timers, clock, diagnostics)
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
import aiohttp
|
|
85
|
+
from datetime import time
|
|
86
|
+
from aioescea import EsceaWebClient, Timer
|
|
87
|
+
|
|
88
|
+
async with aiohttp.ClientSession() as session:
|
|
89
|
+
web = EsceaWebClient(session, "192.168.1.50", username="123456", password="1234")
|
|
90
|
+
page = await web.async_get_home_page() # no login needed
|
|
91
|
+
print(page.clock, page.timers)
|
|
92
|
+
print(await web.async_get_diagnostics()) # login needed
|
|
93
|
+
|
|
94
|
+
await web.async_set_timer(
|
|
95
|
+
Timer(number=1, on_time=time(6, 30), off_time=time(8, 0), enabled=True),
|
|
96
|
+
fire_is_on=False, # must be the fire's real power state right now
|
|
97
|
+
current=page.timers,
|
|
98
|
+
)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
On most fires the web login is the **serial number** and the **PIN**, both of
|
|
102
|
+
which discovery returns.
|
|
103
|
+
|
|
104
|
+
### Command line
|
|
105
|
+
|
|
106
|
+
```sh
|
|
107
|
+
aioescea discover
|
|
108
|
+
aioescea status 192.168.1.50
|
|
109
|
+
aioescea on 192.168.1.50
|
|
110
|
+
aioescea temp 192.168.1.50 22
|
|
111
|
+
aioescea mode 192.168.1.50 boost
|
|
112
|
+
aioescea off 192.168.1.50
|
|
113
|
+
aioescea timers 192.168.1.50
|
|
114
|
+
aioescea diagnostics 192.168.1.50 --username 123456 --password 1234
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## How it behaves
|
|
118
|
+
|
|
119
|
+
- **It never sends anything you didn't ask for.** No background loop, no
|
|
120
|
+
buffered commands. A missed reply can't cause an old command to be re-sent,
|
|
121
|
+
so it can't re-light a fire someone turned off with the remote or the app.
|
|
122
|
+
([The bug this avoids](https://github.com/lazdavila/pescea/issues/8).)
|
|
123
|
+
- **Changing the mode while the fire is off would light it**, because that's
|
|
124
|
+
how the fire works. `async_set_mode` refuses unless you pass
|
|
125
|
+
`allow_ignite=True`.
|
|
126
|
+
- **Turning off is never refused**, even during the 66 s lighting window.
|
|
127
|
+
- **One request per fire at a time, retried**, because the controller is
|
|
128
|
+
single threaded and UDP drops packets.
|
|
129
|
+
- **Port 3300 is not shared.** Fires always reply to port 3300, so only one
|
|
130
|
+
program per computer can talk to them. If another program has the port,
|
|
131
|
+
`EsceaPortInUseError` says so instead of silently missing replies.
|
|
132
|
+
- **The web page is fragile.** It answers one connection at a time and can
|
|
133
|
+
stop answering until the fire is power cycled. The client sends one request
|
|
134
|
+
at a time with `Connection: close`; poll it every few minutes at most.
|
|
135
|
+
|
|
136
|
+
## Protocol
|
|
137
|
+
|
|
138
|
+
- [Fireplace LAN Communications Protocol Specification v0.3](docs/protocol.md)
|
|
139
|
+
(Kamahi Electronics for Escea, 2014): the UDP protocol.
|
|
140
|
+
- [NCAPI](docs/protocol.md#generation-3-ncapi) (Escea document 640051_0,
|
|
141
|
+
2024): the Generation 3 Wi-Fi HTTP API.
|
|
142
|
+
- [Network summary](docs/protocol.md#controller-network-summary) (Tussock
|
|
143
|
+
Innovation for Escea, 2016): the controller's ports, DHCP behaviour and
|
|
144
|
+
MAC address prefix (`AC:DE:48`).
|
|
145
|
+
|
|
146
|
+
## Credits
|
|
147
|
+
|
|
148
|
+
- [snikch/escea](https://github.com/snikch/escea) by Mal Curtis: the first
|
|
149
|
+
Python client, and the captured frames used in the tests.
|
|
150
|
+
- [lazdavila/pescea](https://github.com/lazdavila/pescea) by Laz Davila: the
|
|
151
|
+
66 s busy window and the flame-effect quirk.
|
|
152
|
+
- [derekclapham/ha-escea](https://github.com/derekclapham/ha-escea) by Derek
|
|
153
|
+
Clapham: the web page's login, timer and diagnostics formats.
|
|
154
|
+
|
|
155
|
+
## Licence
|
|
156
|
+
|
|
157
|
+
[MIT](LICENSE)
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Escea fireplace protocol notes
|
|
2
|
+
|
|
3
|
+
A summary of what Escea's documents say and what has been learned from real
|
|
4
|
+
fires since. Escea's own PDFs are not reproduced here.
|
|
5
|
+
|
|
6
|
+
## UDP protocol
|
|
7
|
+
|
|
8
|
+
Source: *Fireplace LAN Communications Protocol Specification*, Kamahi
|
|
9
|
+
Electronics Ltd for Escea, version 0.3, 11 March 2014.
|
|
10
|
+
|
|
11
|
+
- UDP, port 3300, both ways. Fires reply to port 3300 whatever port the
|
|
12
|
+
request came from.
|
|
13
|
+
- Discovery: broadcast `SEARCH_FOR_FIRES` on the local subnet. Each fire
|
|
14
|
+
answers `I_AM_A_FIRE` with its serial number and PIN. Replies usually take
|
|
15
|
+
under 3 seconds.
|
|
16
|
+
- The spec suggests a remote shows the user the serial number and asks for
|
|
17
|
+
the PIN before talking to the fire.
|
|
18
|
+
|
|
19
|
+
### Frame (15 bytes)
|
|
20
|
+
|
|
21
|
+
| Byte (from 0) | Meaning |
|
|
22
|
+
|---|---|
|
|
23
|
+
| 0 | Start, `0x47` ("G") |
|
|
24
|
+
| 1 | Command or response id |
|
|
25
|
+
| 2 | Data size |
|
|
26
|
+
| 3-12 | Data, zero filled |
|
|
27
|
+
| 13 | CRC: sum of bytes 1-12, modulo 256 |
|
|
28
|
+
| 14 | End, `0x46` ("F") |
|
|
29
|
+
|
|
30
|
+
### Commands
|
|
31
|
+
|
|
32
|
+
| Command | Id | Data | Reply |
|
|
33
|
+
|---|---|---|---|
|
|
34
|
+
| `STATUS_PLEASE` | `0x31` | none | `STATUS` `0x80` |
|
|
35
|
+
| `POWER_ON` | `0x39` | none | `0x8D` |
|
|
36
|
+
| `POWER_OFF` | `0x3A` | none | `0x8F` |
|
|
37
|
+
| `SEARCH_FOR_FIRES` | `0x50` | none | `I_AM_A_FIRE` `0x90` |
|
|
38
|
+
| `FAN_BOOST_ON` | `0x37` | none | `0x89` |
|
|
39
|
+
| `FAN_BOOST_OFF` | `0x38` | none | `0x8B` |
|
|
40
|
+
| `FLAME_EFFECT_ON` | `0x56` | none | `0x61` |
|
|
41
|
+
| `FLAME_EFFECT_OFF` | `0x55` | none | `0x60` |
|
|
42
|
+
| `NEW_SET_TEMP` | `0x57` | 1 byte, °C, 4-30 | `0x66` |
|
|
43
|
+
|
|
44
|
+
### `STATUS` data (6 bytes)
|
|
45
|
+
|
|
46
|
+
| Data byte | Meaning |
|
|
47
|
+
|---|---|
|
|
48
|
+
| 0 | Fire has new timers |
|
|
49
|
+
| 1 | Fire is on |
|
|
50
|
+
| 2 | Fan boost is on |
|
|
51
|
+
| 3 | Flame effect is on |
|
|
52
|
+
| 4 | Target temperature, °C |
|
|
53
|
+
| 5 | Room temperature, °C |
|
|
54
|
+
|
|
55
|
+
### `I_AM_A_FIRE` data
|
|
56
|
+
|
|
57
|
+
Bytes 0-3: serial number (unsigned, big endian). Bytes 4-5: PIN (unsigned,
|
|
58
|
+
big endian). Real firmware reports a data size of 4 here, not 6, but both
|
|
59
|
+
values are present.
|
|
60
|
+
|
|
61
|
+
### Learned from real fires
|
|
62
|
+
|
|
63
|
+
- After `POWER_ON` or `POWER_OFF`, the fire ignores commands for about
|
|
64
|
+
**66 seconds** while it lights or purges (pescea, measured with the Escea
|
|
65
|
+
remote).
|
|
66
|
+
- Turning **flame effect or fan boost on while the fire is off lights it**.
|
|
67
|
+
- The fire can also be changed by its RF remote and the Escea app, so a
|
|
68
|
+
client must never assume its last command is still in effect.
|
|
69
|
+
|
|
70
|
+
## Controller network summary
|
|
71
|
+
|
|
72
|
+
Source: *Escea Controller Network Communications Summary*, Mark Butler,
|
|
73
|
+
Tussock Innovation, 16 March 2016.
|
|
74
|
+
|
|
75
|
+
- Microchip ENC28J60, 10 Mbit Ethernet. No Wi-Fi.
|
|
76
|
+
- **MAC address `AC:DE:48:xx:xx:xx`.** The last three bytes come from the RF
|
|
77
|
+
remote address, which is derived from the serial number.
|
|
78
|
+
- Listens on: DHCP client UDP 68, NBNS UDP 137, mDNS UDP 5353, app
|
|
79
|
+
protocol UDP 3300, web page TCP 80.
|
|
80
|
+
- Connects out to Escea's Smart Heat server on TCP 8001 (source ports
|
|
81
|
+
29152-29202), for the app away from home. It reconnects every 20 s if that
|
|
82
|
+
fails.
|
|
83
|
+
- DHCP: 5 attempts 10 s apart, then a fallback static address, then one
|
|
84
|
+
attempt every 2 minutes. Renews 20 s before the lease runs out.
|
|
85
|
+
- mDNS name `escea-<serial>.local`; NBNS name `ESCEA-<serial>`.
|
|
86
|
+
- **Network monitor: it pings the default gateway every 50 s and resets its
|
|
87
|
+
network stack if there's no reply within 5 s.** If the router doesn't answer
|
|
88
|
+
pings from the LAN, the fire keeps dropping off the network.
|
|
89
|
+
|
|
90
|
+
## Web page (port 80)
|
|
91
|
+
|
|
92
|
+
Reverse engineered by Derek Clapham (derekclapham/ha-escea).
|
|
93
|
+
|
|
94
|
+
- `GET /index.html`, no login: the fire's clock, room and target
|
|
95
|
+
temperature, both timers' on and off times and whether each is on.
|
|
96
|
+
- `POST /doLogin.html` with `user` and `password` set to the **MD5 hex** of
|
|
97
|
+
the username and password. The reply page holds a `token` input; send it
|
|
98
|
+
back as a `token` cookie. Usually username = serial, password = PIN.
|
|
99
|
+
- `GET /diagnostics.html` (login): processor temperature, duct temperature
|
|
100
|
+
(DX only), pilot valve, thermal cut-out, ignition, fan and gas drive, and
|
|
101
|
+
valve currents.
|
|
102
|
+
- `POST /index.html` (login) saves both timers at once with
|
|
103
|
+
`ON_OFF_SWITCH`, `TIMER1_ON_TIME`, `TIMER1_OFF_TIME`, `TIMER2_ON_TIME`,
|
|
104
|
+
`TIMER2_OFF_TIME`, `TIMER1_SW`, `TIMER2_SW`, in that order. `ON_OFF_SWITCH`
|
|
105
|
+
is the fire's power and is applied, so send the current state.
|
|
106
|
+
- The web server handles one connection at a time and can stop answering
|
|
107
|
+
under load until the fire is power cycled.
|
|
108
|
+
|
|
109
|
+
## Generation 3 NCAPI
|
|
110
|
+
|
|
111
|
+
Source: *ESCEA Network Communication API Protocol (NCAPI)*, Escea document
|
|
112
|
+
640051_0, 26 September 2024. Escea confirmed in November 2026 that the
|
|
113
|
+
version 0.3 UDP protocol above is still current for Generation 2 fires.
|
|
114
|
+
|
|
115
|
+
- Generation 3 controllers (from March 2024) have **Wi-Fi only** (2.4 GHz,
|
|
116
|
+
WPA/WPA2), no Ethernet, and no UDP protocol.
|
|
117
|
+
- The API is **off by default**: Escea Smartheat app, Fire Settings, "Escea
|
|
118
|
+
NCAPI Settings". Needs fire firmware 1.5.9 or later (update over the air
|
|
119
|
+
from the same page).
|
|
120
|
+
- The fire always uses DHCP and **needs a DHCP reservation**. Its MAC and IP
|
|
121
|
+
are on the app's Wi-Fi settings page.
|
|
122
|
+
- HTTP on port 80, fixed.
|
|
123
|
+
|
|
124
|
+
### `GET /`
|
|
125
|
+
|
|
126
|
+
No parameters (any gives 400). Returns JSON:
|
|
127
|
+
|
|
128
|
+
| Key | Value |
|
|
129
|
+
|---|---|
|
|
130
|
+
| `state` | `off`, `starting`, `retrying`, `igniting`, `heating`, `burn_off`, `cool_down`, `gas_adjust`, `pilot_only`, `shutting_down`, `error` |
|
|
131
|
+
| `fan_boost`, `flame_effect` | true/false |
|
|
132
|
+
| `target_temp_deci_c` | 100-380 (10.0-38.0 °C) |
|
|
133
|
+
| `room_temp_deci_c` | -1000 to 1000. From the remote, about every 30 s. -1000 until the fire first hears the remote; stale if `remote_present` is false |
|
|
134
|
+
| `remote_present` | Remote seen recently. Must be true for the fire to start |
|
|
135
|
+
| `errors` | The fire has stored errors needing attention (separate from `state: error`) |
|
|
136
|
+
| `serial_number` | String, up to 6 characters |
|
|
137
|
+
| `fire_type` | `gas` or `electric` |
|
|
138
|
+
| `protocol_version` | `1` |
|
|
139
|
+
|
|
140
|
+
Normal sequence: off, starting (pre-start tests, flue purge), igniting
|
|
141
|
+
(pilot, then main burners), heating (burners modulating), shutting down (fans
|
|
142
|
+
run about 10 minutes after off). `pilot_only` drops to the pilot when the room
|
|
143
|
+
stays above target at minimum input. `retrying` follows a failed ignition or
|
|
144
|
+
lost flame, and leads to `error` after several tries.
|
|
145
|
+
|
|
146
|
+
### `POST /?param=value&...`
|
|
147
|
+
|
|
148
|
+
Parameters (case insensitive, combinable, each once): `on`, `fan_boost`
|
|
149
|
+
(gas only), `flame_effect` (gas only), `target_temp_deci_c` (100-380). Any
|
|
150
|
+
invalid parameter rejects the whole request with 400. Fan boost and flame
|
|
151
|
+
effect are exclusive: turning one on turns the other off, and asking for both
|
|
152
|
+
on is a 400.
|
|
153
|
+
|
|
154
|
+
Return codes: 200, 400 (bad parameters), 408 (asked too often), 414 (longer
|
|
155
|
+
than 511 characters), 500, 503 (not initialised yet).
|