aermatic 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,29 @@
1
+ # ---- reverse-engineering artifacts (DO NOT PUBLISH) ----
2
+ # Third-party app code, firmware, and anything containing personal device addresses.
3
+ jadx-out/
4
+ apk/
5
+ *.xapk
6
+ *.apk
7
+ *.bin
8
+ AER_NOTES.md
9
+ aermatic-devices.toml
10
+ devices.toml
11
+
12
+ # ---- Python ----
13
+ .venv/
14
+ venv/
15
+ __pycache__/
16
+ *.py[cod]
17
+ *.egg-info/
18
+ .eggs/
19
+ build/
20
+ dist/
21
+ .pytest_cache/
22
+ .mypy_cache/
23
+ .ruff_cache/
24
+
25
+ # ---- OS / editor ----
26
+ .DS_Store
27
+ .idea/
28
+ .vscode/
29
+ *.swp
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format is based on
4
+ [Keep a Changelog](https://keepachangelog.com/) and this project adheres to
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] - 2026-11-23
8
+
9
+ ### Added
10
+ - Initial release.
11
+ - Async BLE client (`AerDevice`) and `scan()` built on `bleak` (macOS / Linux / Windows).
12
+ - Commands: status, spray (single + 10/20/40 min intervals), stop, LED test, set-time,
13
+ get-time, refill-complete, get-uid, add/retrieve/remove schedules.
14
+ - Pure protocol layer (`aermatic.protocol`) with a deterministic CBOR encoder that is
15
+ byte-identical to the device's app, including the set-time 8-byte-epoch quirk.
16
+ - `aermatic` command-line tool with device aliases (config file / env var) and auto-scan.
17
+ - Reverse-engineered protocol documentation (`docs/PROTOCOL.md`).
18
+ - Hardware-free test suite.
aermatic-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 stacknix
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.
@@ -0,0 +1,291 @@
1
+ Metadata-Version: 2.5
2
+ Name: aermatic
3
+ Version: 0.1.0
4
+ Summary: Independent Python library and CLI to control Godrej Aer Smart Matic BLE air fresheners
5
+ Project-URL: Homepage, https://github.com/stacknix/aermatic
6
+ Project-URL: Repository, https://github.com/stacknix/aermatic
7
+ Project-URL: Issues, https://github.com/stacknix/aermatic/issues
8
+ Project-URL: Documentation, https://github.com/stacknix/aermatic/blob/main/docs/PROTOCOL.md
9
+ Author: stacknix
10
+ License: MIT License
11
+
12
+ Copyright (c) 2026 stacknix
13
+
14
+ Permission is hereby granted, free of charge, to any person obtaining a copy
15
+ of this software and associated documentation files (the "Software"), to deal
16
+ in the Software without restriction, including without limitation the rights
17
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18
+ copies of the Software, and to permit persons to whom the Software is
19
+ furnished to do so, subject to the following conditions:
20
+
21
+ The above copyright notice and this permission notice shall be included in all
22
+ copies or substantial portions of the Software.
23
+
24
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30
+ SOFTWARE.
31
+ License-File: LICENSE
32
+ Keywords: aer,air-freshener,ble,bleak,bluetooth,godrej,home-automation,iot,smart-matic
33
+ Classifier: Development Status :: 4 - Beta
34
+ Classifier: Environment :: Console
35
+ Classifier: Intended Audience :: Developers
36
+ Classifier: License :: OSI Approved :: MIT License
37
+ Classifier: Operating System :: OS Independent
38
+ Classifier: Programming Language :: Python :: 3
39
+ Classifier: Programming Language :: Python :: 3 :: Only
40
+ Classifier: Topic :: Home Automation
41
+ Classifier: Topic :: System :: Hardware
42
+ Requires-Python: >=3.9
43
+ Requires-Dist: bleak>=0.21
44
+ Requires-Dist: cbor2>=5.4
45
+ Provides-Extra: dev
46
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
47
+ Requires-Dist: pytest>=7; extra == 'dev'
48
+ Description-Content-Type: text/markdown
49
+
50
+ # aermatic
51
+
52
+ An independent, open-source Python library and command-line tool to control
53
+ **Godrej Aer Smart Matic** Bluetooth Low Energy (BLE) air fresheners directly —
54
+ no phone app, no account, no cloud. Works on macOS, Linux (including Raspberry
55
+ Pi), and Windows.
56
+
57
+ > **Unofficial.** Not affiliated with or endorsed by Godrej. "Godrej" and "Aer"
58
+ > are trademarks of their respective owners. This project was built independently
59
+ > for interoperability with devices you own. Use at your own risk.
60
+
61
+ ---
62
+
63
+ ## What it can do
64
+
65
+ - **Discover** nearby Smart Matic devices
66
+ - **Read status** — firmware, battery voltage, spray counts, refill % remaining
67
+ - **Spray now**, or set an **auto-spray interval** (every 10 / 20 / 40 min)
68
+ - **Stop** an active spray/schedule
69
+ - **Create / read / delete schedules** (per-weekday, start/end time, interval)
70
+ - **Set the device clock**, blink the **LED**, mark a **refill** as replaced
71
+
72
+ Everything runs locally over BLE. No internet connection is used.
73
+
74
+ ---
75
+
76
+ ## Requirements
77
+
78
+ - Python **3.9+**
79
+ - A machine with **Bluetooth LE** (any modern laptop, or a Raspberry Pi 3/4/5 / Zero 2 W)
80
+ - The devices must be **in Bluetooth range**
81
+
82
+ Platform notes:
83
+
84
+ - **macOS** — grant your terminal app Bluetooth permission the first time
85
+ (System Settings → Privacy & Security → Bluetooth).
86
+ - **Linux / Raspberry Pi** — uses BlueZ (preinstalled on Raspberry Pi OS). If scanning
87
+ needs elevated privileges, either run with `sudo` or grant the Python binary the
88
+ capability: `sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f $(which python3))`.
89
+
90
+ ---
91
+
92
+ ## Install
93
+
94
+ ```bash
95
+ pip install aermatic
96
+ ```
97
+
98
+ That's it — this pulls in `bleak` (cross-platform BLE) and `cbor2`. A console
99
+ command `aermatic` is installed.
100
+
101
+ <details>
102
+ <summary>Install from source (for development)</summary>
103
+
104
+ ```bash
105
+ git clone https://github.com/stacknix/aermatic
106
+ cd aermatic
107
+ python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
108
+ pip install -e ".[dev]"
109
+ ```
110
+ </details>
111
+
112
+ ---
113
+
114
+ ## Quick start
115
+
116
+ **1. Find your devices:**
117
+
118
+ ```bash
119
+ aermatic scan
120
+ ```
121
+
122
+ ```
123
+ AA:BB:CC:DD:EE:FF rssi=-65 name='Smart Matic'
124
+ 11:22:33:44:55:66 rssi=-70 name='Smart Matic'
125
+ ```
126
+
127
+ (On macOS the address is a CoreBluetooth UUID like `1A2B3C4D-...`; on Linux it's a
128
+ MAC address like `AA:BB:CC:DD:EE:FF`. Both work the same way below.)
129
+
130
+ **2. Read status** (pass the address you saw):
131
+
132
+ ```bash
133
+ aermatic status AA:BB:CC:DD:EE:FF
134
+ ```
135
+
136
+ ```
137
+ [AA:BB:CC:DD:EE:FF]
138
+ firmware : 3.0.8-IN
139
+ battery : 3.005 V
140
+ state : 0 (0 = idle)
141
+ spray-now : 0s/10s/20s/40s = [34, 126, 0, 0]
142
+ scheduled : [0, 0, 0]
143
+ button-press : [57, 31, 27]
144
+ total sprays : 275 -> refill ~88% left
145
+ ```
146
+
147
+ **3. Spray once:**
148
+
149
+ ```bash
150
+ aermatic spray AA:BB:CC:DD:EE:FF
151
+ ```
152
+
153
+ ---
154
+
155
+ ## Device aliases (type `1` / `2` / `all` instead of addresses)
156
+
157
+ Addresses are long and differ per computer. Define short aliases once and reuse them.
158
+
159
+ Create `~/.config/aermatic/devices.toml` (or `aermatic-devices.toml` in your working
160
+ directory):
161
+
162
+ ```toml
163
+ [devices]
164
+ 1 = "AA:BB:CC:DD:EE:FF"
165
+ 2 = "11:22:33:44:55:66"
166
+ bedroom = "22:33:44:55:66:77"
167
+ ```
168
+
169
+ Now:
170
+
171
+ ```bash
172
+ aermatic status all # every configured device
173
+ aermatic status 1 # just device 1
174
+ aermatic spray bedroom
175
+ ```
176
+
177
+ Or set them inline without a file:
178
+
179
+ ```bash
180
+ export AERMATIC_DEVICES="1=AA:BB:CC:DD:EE:FF,2=11:22:33:44:55:66"
181
+ aermatic status all
182
+ ```
183
+
184
+ If you run a command with no device and have none configured, `aermatic` scans and
185
+ targets whatever it finds.
186
+
187
+ ---
188
+
189
+ ## Command reference
190
+
191
+ | Command | Example | Description |
192
+ |---|---|---|
193
+ | `scan` | `aermatic scan` | List nearby devices |
194
+ | `status` | `aermatic status all` | Firmware, battery, counts, refill % |
195
+ | `spray` | `aermatic spray 1` / `aermatic spray 1 20` | Spray once, or auto every 10/20/40 min |
196
+ | `stop` | `aermatic stop 1` | Stop active spray/schedule |
197
+ | `led` | `aermatic led 1` | Blink the LED (handy to identify a unit) |
198
+ | `settime` | `aermatic settime all` | Push your computer's clock + timezone |
199
+ | `get-time` | `aermatic get-time 1` | Read the device clock |
200
+ | `refill` | `aermatic refill 1` | Mark the can replaced (reset counter) |
201
+ | `schedules` | `aermatic schedules 1` | Read stored schedules |
202
+ | `schedule` | `aermatic schedule 1 weekdays 08:00 22:00 20` | Create a schedule |
203
+ | `remove-schedules` | `aermatic remove-schedules 1` | Delete **all** schedules |
204
+
205
+ **Scheduling:** `aermatic schedule DEVICE DAYS START END INTERVAL`
206
+ - `DAYS` — `mon,tue,wed` or `all` / `weekdays` / `weekend`
207
+ - `START` / `END` — `HH:MM` (24-hour)
208
+ - `INTERVAL` — `10`, `20` or `40` minutes
209
+
210
+ Example — spray every 20 minutes, 8am–10pm, Monday to Friday:
211
+
212
+ ```bash
213
+ aermatic schedule 1 weekdays 08:00 22:00 20
214
+ ```
215
+
216
+ ---
217
+
218
+ ## Use it as a library
219
+
220
+ ```python
221
+ import asyncio
222
+ from aermatic import AerDevice, scan
223
+
224
+ async def main():
225
+ # discover
226
+ for d in await scan():
227
+ print(d.address, d.name, d.rssi)
228
+
229
+ # connect and control
230
+ async with AerDevice("AA:BB:CC:DD:EE:FF") as dev:
231
+ status = await dev.status()
232
+ print(status.firmware, status.battery_volts, f"{status.refill_percent}% left")
233
+
234
+ await dev.spray() # spray once
235
+ await dev.add_schedule("weekdays", "08:00", "22:00", 20)
236
+
237
+ asyncio.run(main())
238
+ ```
239
+
240
+ The reply objects are plain dicts (`{'mT': 154, 'mN': 154, 'ack': 200}`); `ack == 200`
241
+ means success. `status()` returns a typed `Status` with `.firmware`, `.battery_volts`,
242
+ `.total_sprays`, `.refill_percent`, etc.
243
+
244
+ ---
245
+
246
+ ## How it works / protocol
247
+
248
+ The device exposes a Nordic-UART-style GATT service. Commands are small CBOR maps
249
+ written to a characteristic; the device replies with a notification. The full
250
+ reverse-engineered protocol — UUIDs, message types, CBOR fields, status layout,
251
+ schedule format — is documented in **[docs/PROTOCOL.md](docs/PROTOCOL.md)**.
252
+
253
+ One portability detail handled for you: the device's reply characteristic has no
254
+ CCCD descriptor, so macOS CoreBluetooth needs a specific subscribe sequence to
255
+ receive notifications. `aermatic` does this automatically.
256
+
257
+ ---
258
+
259
+ ## Troubleshooting
260
+
261
+ - **No devices in `scan`** — make sure Bluetooth is on and a device is in range;
262
+ on macOS grant the terminal Bluetooth permission; on Linux check `bluetoothctl`
263
+ sees adapters.
264
+ - **Connects but no reply / times out** — weak signal units occasionally time out;
265
+ just retry (the CLI already retries 3×). Move closer if persistent.
266
+ - **`BleakError: ... attribute could not be found`** — harmless on macOS; it's the
267
+ expected error from the reply characteristic and is swallowed internally.
268
+
269
+ ---
270
+
271
+ ## Firmware updates (OTA)
272
+
273
+ The devices support Telink OTA, but this library deliberately does **not** flash
274
+ firmware: there is no public newer image, and a bad flash can brick the unit. See
275
+ `docs/PROTOCOL.md` for the OTA details if you want to build this yourself.
276
+
277
+ ---
278
+
279
+ ## Contributing
280
+
281
+ Issues and PRs welcome — especially test reports from different devices, firmware
282
+ versions, and platforms. Run the (hardware-free) tests with:
283
+
284
+ ```bash
285
+ pip install -e ".[dev]"
286
+ pytest
287
+ ```
288
+
289
+ ## License
290
+
291
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,242 @@
1
+ # aermatic
2
+
3
+ An independent, open-source Python library and command-line tool to control
4
+ **Godrej Aer Smart Matic** Bluetooth Low Energy (BLE) air fresheners directly —
5
+ no phone app, no account, no cloud. Works on macOS, Linux (including Raspberry
6
+ Pi), and Windows.
7
+
8
+ > **Unofficial.** Not affiliated with or endorsed by Godrej. "Godrej" and "Aer"
9
+ > are trademarks of their respective owners. This project was built independently
10
+ > for interoperability with devices you own. Use at your own risk.
11
+
12
+ ---
13
+
14
+ ## What it can do
15
+
16
+ - **Discover** nearby Smart Matic devices
17
+ - **Read status** — firmware, battery voltage, spray counts, refill % remaining
18
+ - **Spray now**, or set an **auto-spray interval** (every 10 / 20 / 40 min)
19
+ - **Stop** an active spray/schedule
20
+ - **Create / read / delete schedules** (per-weekday, start/end time, interval)
21
+ - **Set the device clock**, blink the **LED**, mark a **refill** as replaced
22
+
23
+ Everything runs locally over BLE. No internet connection is used.
24
+
25
+ ---
26
+
27
+ ## Requirements
28
+
29
+ - Python **3.9+**
30
+ - A machine with **Bluetooth LE** (any modern laptop, or a Raspberry Pi 3/4/5 / Zero 2 W)
31
+ - The devices must be **in Bluetooth range**
32
+
33
+ Platform notes:
34
+
35
+ - **macOS** — grant your terminal app Bluetooth permission the first time
36
+ (System Settings → Privacy & Security → Bluetooth).
37
+ - **Linux / Raspberry Pi** — uses BlueZ (preinstalled on Raspberry Pi OS). If scanning
38
+ needs elevated privileges, either run with `sudo` or grant the Python binary the
39
+ capability: `sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f $(which python3))`.
40
+
41
+ ---
42
+
43
+ ## Install
44
+
45
+ ```bash
46
+ pip install aermatic
47
+ ```
48
+
49
+ That's it — this pulls in `bleak` (cross-platform BLE) and `cbor2`. A console
50
+ command `aermatic` is installed.
51
+
52
+ <details>
53
+ <summary>Install from source (for development)</summary>
54
+
55
+ ```bash
56
+ git clone https://github.com/stacknix/aermatic
57
+ cd aermatic
58
+ python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
59
+ pip install -e ".[dev]"
60
+ ```
61
+ </details>
62
+
63
+ ---
64
+
65
+ ## Quick start
66
+
67
+ **1. Find your devices:**
68
+
69
+ ```bash
70
+ aermatic scan
71
+ ```
72
+
73
+ ```
74
+ AA:BB:CC:DD:EE:FF rssi=-65 name='Smart Matic'
75
+ 11:22:33:44:55:66 rssi=-70 name='Smart Matic'
76
+ ```
77
+
78
+ (On macOS the address is a CoreBluetooth UUID like `1A2B3C4D-...`; on Linux it's a
79
+ MAC address like `AA:BB:CC:DD:EE:FF`. Both work the same way below.)
80
+
81
+ **2. Read status** (pass the address you saw):
82
+
83
+ ```bash
84
+ aermatic status AA:BB:CC:DD:EE:FF
85
+ ```
86
+
87
+ ```
88
+ [AA:BB:CC:DD:EE:FF]
89
+ firmware : 3.0.8-IN
90
+ battery : 3.005 V
91
+ state : 0 (0 = idle)
92
+ spray-now : 0s/10s/20s/40s = [34, 126, 0, 0]
93
+ scheduled : [0, 0, 0]
94
+ button-press : [57, 31, 27]
95
+ total sprays : 275 -> refill ~88% left
96
+ ```
97
+
98
+ **3. Spray once:**
99
+
100
+ ```bash
101
+ aermatic spray AA:BB:CC:DD:EE:FF
102
+ ```
103
+
104
+ ---
105
+
106
+ ## Device aliases (type `1` / `2` / `all` instead of addresses)
107
+
108
+ Addresses are long and differ per computer. Define short aliases once and reuse them.
109
+
110
+ Create `~/.config/aermatic/devices.toml` (or `aermatic-devices.toml` in your working
111
+ directory):
112
+
113
+ ```toml
114
+ [devices]
115
+ 1 = "AA:BB:CC:DD:EE:FF"
116
+ 2 = "11:22:33:44:55:66"
117
+ bedroom = "22:33:44:55:66:77"
118
+ ```
119
+
120
+ Now:
121
+
122
+ ```bash
123
+ aermatic status all # every configured device
124
+ aermatic status 1 # just device 1
125
+ aermatic spray bedroom
126
+ ```
127
+
128
+ Or set them inline without a file:
129
+
130
+ ```bash
131
+ export AERMATIC_DEVICES="1=AA:BB:CC:DD:EE:FF,2=11:22:33:44:55:66"
132
+ aermatic status all
133
+ ```
134
+
135
+ If you run a command with no device and have none configured, `aermatic` scans and
136
+ targets whatever it finds.
137
+
138
+ ---
139
+
140
+ ## Command reference
141
+
142
+ | Command | Example | Description |
143
+ |---|---|---|
144
+ | `scan` | `aermatic scan` | List nearby devices |
145
+ | `status` | `aermatic status all` | Firmware, battery, counts, refill % |
146
+ | `spray` | `aermatic spray 1` / `aermatic spray 1 20` | Spray once, or auto every 10/20/40 min |
147
+ | `stop` | `aermatic stop 1` | Stop active spray/schedule |
148
+ | `led` | `aermatic led 1` | Blink the LED (handy to identify a unit) |
149
+ | `settime` | `aermatic settime all` | Push your computer's clock + timezone |
150
+ | `get-time` | `aermatic get-time 1` | Read the device clock |
151
+ | `refill` | `aermatic refill 1` | Mark the can replaced (reset counter) |
152
+ | `schedules` | `aermatic schedules 1` | Read stored schedules |
153
+ | `schedule` | `aermatic schedule 1 weekdays 08:00 22:00 20` | Create a schedule |
154
+ | `remove-schedules` | `aermatic remove-schedules 1` | Delete **all** schedules |
155
+
156
+ **Scheduling:** `aermatic schedule DEVICE DAYS START END INTERVAL`
157
+ - `DAYS` — `mon,tue,wed` or `all` / `weekdays` / `weekend`
158
+ - `START` / `END` — `HH:MM` (24-hour)
159
+ - `INTERVAL` — `10`, `20` or `40` minutes
160
+
161
+ Example — spray every 20 minutes, 8am–10pm, Monday to Friday:
162
+
163
+ ```bash
164
+ aermatic schedule 1 weekdays 08:00 22:00 20
165
+ ```
166
+
167
+ ---
168
+
169
+ ## Use it as a library
170
+
171
+ ```python
172
+ import asyncio
173
+ from aermatic import AerDevice, scan
174
+
175
+ async def main():
176
+ # discover
177
+ for d in await scan():
178
+ print(d.address, d.name, d.rssi)
179
+
180
+ # connect and control
181
+ async with AerDevice("AA:BB:CC:DD:EE:FF") as dev:
182
+ status = await dev.status()
183
+ print(status.firmware, status.battery_volts, f"{status.refill_percent}% left")
184
+
185
+ await dev.spray() # spray once
186
+ await dev.add_schedule("weekdays", "08:00", "22:00", 20)
187
+
188
+ asyncio.run(main())
189
+ ```
190
+
191
+ The reply objects are plain dicts (`{'mT': 154, 'mN': 154, 'ack': 200}`); `ack == 200`
192
+ means success. `status()` returns a typed `Status` with `.firmware`, `.battery_volts`,
193
+ `.total_sprays`, `.refill_percent`, etc.
194
+
195
+ ---
196
+
197
+ ## How it works / protocol
198
+
199
+ The device exposes a Nordic-UART-style GATT service. Commands are small CBOR maps
200
+ written to a characteristic; the device replies with a notification. The full
201
+ reverse-engineered protocol — UUIDs, message types, CBOR fields, status layout,
202
+ schedule format — is documented in **[docs/PROTOCOL.md](docs/PROTOCOL.md)**.
203
+
204
+ One portability detail handled for you: the device's reply characteristic has no
205
+ CCCD descriptor, so macOS CoreBluetooth needs a specific subscribe sequence to
206
+ receive notifications. `aermatic` does this automatically.
207
+
208
+ ---
209
+
210
+ ## Troubleshooting
211
+
212
+ - **No devices in `scan`** — make sure Bluetooth is on and a device is in range;
213
+ on macOS grant the terminal Bluetooth permission; on Linux check `bluetoothctl`
214
+ sees adapters.
215
+ - **Connects but no reply / times out** — weak signal units occasionally time out;
216
+ just retry (the CLI already retries 3×). Move closer if persistent.
217
+ - **`BleakError: ... attribute could not be found`** — harmless on macOS; it's the
218
+ expected error from the reply characteristic and is swallowed internally.
219
+
220
+ ---
221
+
222
+ ## Firmware updates (OTA)
223
+
224
+ The devices support Telink OTA, but this library deliberately does **not** flash
225
+ firmware: there is no public newer image, and a bad flash can brick the unit. See
226
+ `docs/PROTOCOL.md` for the OTA details if you want to build this yourself.
227
+
228
+ ---
229
+
230
+ ## Contributing
231
+
232
+ Issues and PRs welcome — especially test reports from different devices, firmware
233
+ versions, and platforms. Run the (hardware-free) tests with:
234
+
235
+ ```bash
236
+ pip install -e ".[dev]"
237
+ pytest
238
+ ```
239
+
240
+ ## License
241
+
242
+ MIT — see [LICENSE](LICENSE).