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.
@@ -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,10 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ .coverage
5
+ .pytest_cache/
6
+ .mypy_cache/
7
+ .ruff_cache/
8
+ dist/
9
+ build/
10
+ *.egg-info/
@@ -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
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/aioescea?style=for-the-badge&color=FFFFFF&labelColor=000000)](https://pypi.org/project/aioescea/)
36
+ [![Checks](https://img.shields.io/github/actions/workflow/status/olliemaller/aioescea/ci.yml?branch=main&style=for-the-badge&label=checks&labelColor=000000)](https://github.com/olliemaller/aioescea/actions/workflows/ci.yml)
37
+ [![Licence](https://img.shields.io/github/license/olliemaller/aioescea?style=for-the-badge&color=FFFFFF&labelColor=000000)](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)
@@ -0,0 +1,157 @@
1
+ # aioescea
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/aioescea?style=for-the-badge&color=FFFFFF&labelColor=000000)](https://pypi.org/project/aioescea/)
4
+ [![Checks](https://img.shields.io/github/actions/workflow/status/olliemaller/aioescea/ci.yml?branch=main&style=for-the-badge&label=checks&labelColor=000000)](https://github.com/olliemaller/aioescea/actions/workflows/ci.yml)
5
+ [![Licence](https://img.shields.io/github/license/olliemaller/aioescea?style=for-the-badge&color=FFFFFF&labelColor=000000)](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).