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.
- aermatic-0.1.0/.gitignore +29 -0
- aermatic-0.1.0/CHANGELOG.md +18 -0
- aermatic-0.1.0/LICENSE +21 -0
- aermatic-0.1.0/PKG-INFO +291 -0
- aermatic-0.1.0/README.md +242 -0
- aermatic-0.1.0/docs/PROTOCOL.md +131 -0
- aermatic-0.1.0/pyproject.toml +49 -0
- aermatic-0.1.0/src/aermatic/__init__.py +15 -0
- aermatic-0.1.0/src/aermatic/cli.py +155 -0
- aermatic-0.1.0/src/aermatic/client.py +177 -0
- aermatic-0.1.0/src/aermatic/config.py +59 -0
- aermatic-0.1.0/src/aermatic/protocol.py +245 -0
- aermatic-0.1.0/tests/test_protocol.py +87 -0
|
@@ -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.
|
aermatic-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|
aermatic-0.1.0/README.md
ADDED
|
@@ -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).
|