aiomoulinex 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.
- aiomoulinex-0.1.0/.gitignore +126 -0
- aiomoulinex-0.1.0/LICENSE.md +21 -0
- aiomoulinex-0.1.0/PKG-INFO +236 -0
- aiomoulinex-0.1.0/README.md +206 -0
- aiomoulinex-0.1.0/pyproject.toml +172 -0
- aiomoulinex-0.1.0/src/aiomoulinex/__init__.py +82 -0
- aiomoulinex-0.1.0/src/aiomoulinex/_http.py +84 -0
- aiomoulinex-0.1.0/src/aiomoulinex/api.py +98 -0
- aiomoulinex-0.1.0/src/aiomoulinex/auth.py +251 -0
- aiomoulinex-0.1.0/src/aiomoulinex/client.py +628 -0
- aiomoulinex-0.1.0/src/aiomoulinex/cognito.py +84 -0
- aiomoulinex-0.1.0/src/aiomoulinex/const.py +30 -0
- aiomoulinex-0.1.0/src/aiomoulinex/events.py +76 -0
- aiomoulinex-0.1.0/src/aiomoulinex/exceptions.py +35 -0
- aiomoulinex-0.1.0/src/aiomoulinex/models.py +447 -0
- aiomoulinex-0.1.0/src/aiomoulinex/programs.py +269 -0
- aiomoulinex-0.1.0/src/aiomoulinex/py.typed +0 -0
- aiomoulinex-0.1.0/src/aiomoulinex/regions.py +46 -0
- aiomoulinex-0.1.0/src/aiomoulinex/signing.py +61 -0
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# OSX useful to ignore
|
|
7
|
+
*.DS_Store
|
|
8
|
+
.AppleDouble
|
|
9
|
+
.LSOverride
|
|
10
|
+
|
|
11
|
+
# Thumbnails
|
|
12
|
+
._*
|
|
13
|
+
|
|
14
|
+
# Files that might appear in the root of a volume
|
|
15
|
+
.DocumentRevisions-V100
|
|
16
|
+
.fseventsd
|
|
17
|
+
.Spotlight-V100
|
|
18
|
+
.TemporaryItems
|
|
19
|
+
.Trashes
|
|
20
|
+
.VolumeIcon.icns
|
|
21
|
+
.com.apple.timemachine.donotpresent
|
|
22
|
+
|
|
23
|
+
# Directories potentially created on remote AFP share
|
|
24
|
+
.AppleDB
|
|
25
|
+
.AppleDesktop
|
|
26
|
+
Network Trash Folder
|
|
27
|
+
Temporary Items
|
|
28
|
+
.apdisk
|
|
29
|
+
|
|
30
|
+
# C extensions
|
|
31
|
+
*.so
|
|
32
|
+
|
|
33
|
+
# Distribution / packaging
|
|
34
|
+
.Python
|
|
35
|
+
env/
|
|
36
|
+
build/
|
|
37
|
+
develop-eggs/
|
|
38
|
+
dist/
|
|
39
|
+
downloads/
|
|
40
|
+
eggs/
|
|
41
|
+
.eggs/
|
|
42
|
+
lib/
|
|
43
|
+
lib64/
|
|
44
|
+
parts/
|
|
45
|
+
sdist/
|
|
46
|
+
var/
|
|
47
|
+
*.egg-info/
|
|
48
|
+
.installed.cfg
|
|
49
|
+
*.egg
|
|
50
|
+
|
|
51
|
+
# PyInstaller
|
|
52
|
+
# Usually these files are written by a python script from a template
|
|
53
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
54
|
+
*.manifest
|
|
55
|
+
*.spec
|
|
56
|
+
|
|
57
|
+
# Installer logs
|
|
58
|
+
pip-log.txt
|
|
59
|
+
pip-delete-this-directory.txt
|
|
60
|
+
|
|
61
|
+
# Unit test / coverage reports
|
|
62
|
+
htmlcov/
|
|
63
|
+
.tox/
|
|
64
|
+
.coverage
|
|
65
|
+
.coverage.*
|
|
66
|
+
.cache
|
|
67
|
+
nosetests.xml
|
|
68
|
+
coverage.xml
|
|
69
|
+
*,cover
|
|
70
|
+
.hypothesis/
|
|
71
|
+
.pytest_cache/
|
|
72
|
+
|
|
73
|
+
# Translations
|
|
74
|
+
*.mo
|
|
75
|
+
*.pot
|
|
76
|
+
|
|
77
|
+
# Django stuff:
|
|
78
|
+
*.log
|
|
79
|
+
|
|
80
|
+
# Sphinx documentation
|
|
81
|
+
docs/_build/
|
|
82
|
+
|
|
83
|
+
# pyenv
|
|
84
|
+
.python-version
|
|
85
|
+
|
|
86
|
+
# virtualenv
|
|
87
|
+
.venv
|
|
88
|
+
venv/
|
|
89
|
+
ENV/
|
|
90
|
+
|
|
91
|
+
# mypy
|
|
92
|
+
.mypy_cache/
|
|
93
|
+
|
|
94
|
+
# ruff
|
|
95
|
+
.ruff_cache
|
|
96
|
+
|
|
97
|
+
# Visual Studio Code
|
|
98
|
+
.vscode
|
|
99
|
+
|
|
100
|
+
# IntelliJ Idea family of suites
|
|
101
|
+
.idea
|
|
102
|
+
*.iml
|
|
103
|
+
|
|
104
|
+
## File-based project format:
|
|
105
|
+
*.ipr
|
|
106
|
+
*.iws
|
|
107
|
+
|
|
108
|
+
## mpeltonen/sbt-idea plugin
|
|
109
|
+
.idea_modules/
|
|
110
|
+
|
|
111
|
+
# PyBuilder
|
|
112
|
+
target/
|
|
113
|
+
|
|
114
|
+
# Cookiecutter
|
|
115
|
+
output/
|
|
116
|
+
python_boilerplate/
|
|
117
|
+
|
|
118
|
+
# Node
|
|
119
|
+
node_modules/
|
|
120
|
+
|
|
121
|
+
# Deepcode AI
|
|
122
|
+
.dccache
|
|
123
|
+
|
|
124
|
+
# Login token and captures of scripts/debug.py
|
|
125
|
+
.env
|
|
126
|
+
*.jsonl
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Paul Bottein
|
|
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,236 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: aiomoulinex
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Asynchronous Python client for the Moulinex Cookeo and Companion connected through the Groupe SEB cloud
|
|
5
|
+
Project-URL: Homepage, https://github.com/piitaya/python-moulinex
|
|
6
|
+
Project-URL: Repository, https://github.com/piitaya/python-moulinex
|
|
7
|
+
Project-URL: Documentation, https://github.com/piitaya/python-moulinex
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/piitaya/python-moulinex/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/piitaya/python-moulinex/releases
|
|
10
|
+
Author-email: Paul Bottein <paul.bottein@gmail.com>
|
|
11
|
+
Maintainer-email: Paul Bottein <paul.bottein@gmail.com>
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE.md
|
|
14
|
+
Keywords: asyncio,companion,cookeo,groupe seb,moulinex,mqtt,tefal
|
|
15
|
+
Classifier: Development Status :: 4 - Beta
|
|
16
|
+
Classifier: Framework :: AsyncIO
|
|
17
|
+
Classifier: Intended Audience :: Developers
|
|
18
|
+
Classifier: Natural Language :: English
|
|
19
|
+
Classifier: Programming Language :: Python :: 3
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Topic :: Home Automation
|
|
23
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
24
|
+
Classifier: Typing :: Typed
|
|
25
|
+
Requires-Python: <4,>=3.13
|
|
26
|
+
Requires-Dist: aiohttp>=3.11.0
|
|
27
|
+
Requires-Dist: aiomqtt>=2.5.0
|
|
28
|
+
Requires-Dist: yarl>=1.18.0
|
|
29
|
+
Description-Content-Type: text/markdown
|
|
30
|
+
|
|
31
|
+
# Python: Moulinex
|
|
32
|
+
|
|
33
|
+
[![GitHub Release][releases-shield]][releases]
|
|
34
|
+
[![Python Versions][python-versions-shield]][pypi]
|
|
35
|
+
[![License][license-shield]](LICENSE.md)
|
|
36
|
+
[![Build Status][build-shield]][build]
|
|
37
|
+
|
|
38
|
+
Asynchronous Python client for the Moulinex Cookeo multicookers and Companion cooking robots connected to Wi-Fi.
|
|
39
|
+
|
|
40
|
+
## About
|
|
41
|
+
|
|
42
|
+
The client goes through the same Groupe SEB cloud as the Moulinex app, so the appliance must already be set up in that app. It logs in with the account of the app, then follows what each appliance reports: the cooking state, the program, the remaining time, the recipe in progress, and whether the appliance is turned on.
|
|
43
|
+
|
|
44
|
+
- Fully asynchronous, built on [aiohttp](https://github.com/aio-libs/aiohttp) and [aiomqtt](https://github.com/empicano/aiomqtt). No AWS SDK.
|
|
45
|
+
- Push based: the appliances tell the cloud what changed, and the client tells you.
|
|
46
|
+
- One connection per account, for all its appliances.
|
|
47
|
+
- Renews the tokens and connects again by itself.
|
|
48
|
+
- Typed models and typed errors.
|
|
49
|
+
|
|
50
|
+
The library is read-only. The cloud offers no way to control an appliance, so programs can only be started or stopped on the appliance itself.
|
|
51
|
+
|
|
52
|
+
## Supported appliances
|
|
53
|
+
|
|
54
|
+
| Model | Tested |
|
|
55
|
+
| ---------------------- | ------ |
|
|
56
|
+
| Cookeo Touch WiFi | ✓ |
|
|
57
|
+
| Cookeo Touch Pro WiFi | ✓ |
|
|
58
|
+
| Cookeo Touch Mini WiFi | ✓ |
|
|
59
|
+
| Cookeo Wi-Fi 8-in-1 | |
|
|
60
|
+
| Cookeo Wi-Fi 9-in-1 | |
|
|
61
|
+
| Cookeo Wi-Fi 10-in-1 | |
|
|
62
|
+
| Cookeo Infinity | ✓ |
|
|
63
|
+
| i-Companion Touch XL | |
|
|
64
|
+
|
|
65
|
+
The untested models use the same cloud and should work. Bluetooth-only models such as the Cookeo Connect are not supported, and neither are other Groupe SEB appliances such as the OptiGrill.
|
|
66
|
+
|
|
67
|
+
## Installation
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install aiomoulinex
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Usage
|
|
74
|
+
|
|
75
|
+
### Logging in
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import aiohttp
|
|
79
|
+
|
|
80
|
+
from aiomoulinex import LoginError, Region, login
|
|
81
|
+
|
|
82
|
+
async with aiohttp.ClientSession() as session:
|
|
83
|
+
try:
|
|
84
|
+
tokens = await login(
|
|
85
|
+
session, "jane@example.com", "password", Region.MOULINEX_FR
|
|
86
|
+
)
|
|
87
|
+
except LoginError as err:
|
|
88
|
+
print(err.reason) # invalid_auth, email_not_verified, account_locked, ...
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`Region` is the brand and country of the account, the one picked in the Moulinex app. The library only uses the connections of the session it is given: the cookies of the cloud stay out of it, so it is safe to pass a session that is shared with other code.
|
|
92
|
+
|
|
93
|
+
Store `tokens.to_dict()` and the region, not the password. `Tokens.from_dict()` reads them back, and `tokens.user_id` identifies the account: it stays the same when the email changes.
|
|
94
|
+
|
|
95
|
+
### Following the appliances
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
import asyncio
|
|
99
|
+
|
|
100
|
+
import aiohttp
|
|
101
|
+
|
|
102
|
+
from aiomoulinex import ApplianceUpdated, Event, MoulinexClient, Region, Tokens
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
async def main(tokens: Tokens) -> None:
|
|
106
|
+
async with aiohttp.ClientSession() as session:
|
|
107
|
+
client = MoulinexClient(session, tokens, Region.MOULINEX_FR)
|
|
108
|
+
|
|
109
|
+
def on_event(event: Event) -> None:
|
|
110
|
+
if isinstance(event, ApplianceUpdated):
|
|
111
|
+
status = event.state.status
|
|
112
|
+
print(
|
|
113
|
+
event.appliance.name,
|
|
114
|
+
status.state if status else None,
|
|
115
|
+
event.appliance.program(status),
|
|
116
|
+
)
|
|
117
|
+
|
|
118
|
+
client.add_listener(on_event)
|
|
119
|
+
await client.connect()
|
|
120
|
+
print(client.appliances)
|
|
121
|
+
await asyncio.sleep(3600)
|
|
122
|
+
await client.disconnect()
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`connect()` refreshes the tokens, reads the appliances of the account, connects to the cloud and asks each appliance for its state. It returns once that state is known: the shadow of each appliance, and the cooking status of those that are turned on. An appliance that does not answer within 3 seconds is not waited for any longer. From then on:
|
|
126
|
+
|
|
127
|
+
- `client.appliances` holds the appliances of the account, by `thing_uuid`.
|
|
128
|
+
- `client.states` holds the last known `ApplianceState` of each appliance. Its `status` is what the appliance is cooking, its `shadow` tells whether it is turned on and which firmware it runs.
|
|
129
|
+
- `client.connected` is `False` while the connection is lost. The client keeps trying to connect again, and `client.states` keeps the last known state.
|
|
130
|
+
- `client.error` is why the client is not connected, if that is known.
|
|
131
|
+
- `client.tokens` holds the tokens as last refreshed.
|
|
132
|
+
|
|
133
|
+
Instead of a listener, the events can be read with `async for event in client.events()`. It ends when the client disconnects.
|
|
134
|
+
|
|
135
|
+
An appliance that is turned on needs a few seconds before it answers. The client asks for its status again 4, 10 and 20 seconds after it turned on, until it answers.
|
|
136
|
+
|
|
137
|
+
### Events
|
|
138
|
+
|
|
139
|
+
| Event | Meaning |
|
|
140
|
+
| ---------------------- | ---------------------------------------------------------------------- |
|
|
141
|
+
| `ApplianceUpdated` | The cooking status or the shadow of an appliance changed. |
|
|
142
|
+
| `ApplianceAdded` | An appliance was linked to the account after the client connected. |
|
|
143
|
+
| `ApplianceRemoved` | An appliance is no longer linked to the account. |
|
|
144
|
+
| `ConnectionLost` | The connection is lost. The client keeps trying to connect again. |
|
|
145
|
+
| `ConnectionRestored` | The connection is back. |
|
|
146
|
+
| `AuthenticationFailed` | The cloud refused the refresh token. The client stopped: log in again. |
|
|
147
|
+
| `TokensUpdated` | The refresh token changed. Store the tokens to connect the next time. |
|
|
148
|
+
|
|
149
|
+
The client reads the appliances of the account again each time it renews its credentials, a little less than once an hour. That is when added and removed appliances are noticed.
|
|
150
|
+
|
|
151
|
+
### Cooking status
|
|
152
|
+
|
|
153
|
+
`ApplianceState.status` is a `CookingStatus`, for a Companion as well. Each message of an appliance holds its whole status, so a status is never mixed with the one before: a value that is `None` does not apply at that moment.
|
|
154
|
+
|
|
155
|
+
The status itself is `None` until the appliance reports one, and again each time it turns off. What it was cooking is not shown again when it is turned back on.
|
|
156
|
+
|
|
157
|
+
- `state`: a `CookingState`. `idle` is defined by this library, for an appliance that is turned on and reports no state. The other values are those of the appliance: `stopped`, `ready`, `paused`, `warming`, `cooking`, `depressurization`, `keep_warm`, `done`, `delayed` and `alert`. It is `None` for a value this library does not know, which `raw_state` then holds.
|
|
158
|
+
- `mode`: a `CookingMode`: `manual`, `program`, `recipe` or `ingredient_cooking`.
|
|
159
|
+
- `appliance.program(status)`: the program in use, such as `cooking_high_pressure`. `appliance.programs` lists the programs that kind of appliance can run.
|
|
160
|
+
- `phase_progress`: a percentage, while the appliance warms up or releases pressure. `None` in every other state, like in the Moulinex app. `progress` holds what the appliance sent.
|
|
161
|
+
- `elapsed_time` and `remaining_time`: in seconds. The appliance does not send them every second: count from `received_at`, the time the message came in.
|
|
162
|
+
- `duration` and `temperature`: what the program is set to, in seconds and degrees Celsius.
|
|
163
|
+
- `recipe` and `step`: the recipe in progress and its current step. For an ingredient cooking, the recipe holds the ingredient.
|
|
164
|
+
- `notification`: the code of a message the appliance shows on its screen.
|
|
165
|
+
- `error` and `alert_description`: what the appliance reports when something is wrong.
|
|
166
|
+
- `event_date` and `operation_start`: the dates the appliance sends, read as UTC.
|
|
167
|
+
|
|
168
|
+
`ApplianceState.shadow.connected` tells whether the appliance is turned on and connected to the cloud.
|
|
169
|
+
|
|
170
|
+
### Errors
|
|
171
|
+
|
|
172
|
+
All errors are subclasses of `MoulinexError`:
|
|
173
|
+
|
|
174
|
+
| Error | Meaning |
|
|
175
|
+
| ----------------------------- | -------------------------------------------------------------- |
|
|
176
|
+
| `MoulinexConnectionError` | The cloud could not be reached, or it did not answer in time. |
|
|
177
|
+
| `MoulinexAuthenticationError` | The cloud refused the tokens. The account has to log in again. |
|
|
178
|
+
| `LoginError` | The cloud refused the email and password. `reason` tells why. |
|
|
179
|
+
|
|
180
|
+
`LoginError` is a `MoulinexAuthenticationError`, so catch it first. A plain `MoulinexError` means the cloud answered something this library does not understand.
|
|
181
|
+
|
|
182
|
+
### TLS
|
|
183
|
+
|
|
184
|
+
Creating a TLS context reads files from disk. The client does that in an executor. To reuse a context of your own, pass it as `ssl_context`.
|
|
185
|
+
|
|
186
|
+
## Changelog & Releases
|
|
187
|
+
|
|
188
|
+
This repository keeps a change log using [GitHub's releases][releases] functionality.
|
|
189
|
+
|
|
190
|
+
Releases are based on [Semantic Versioning][semver], and use the format of `MAJOR.MINOR.PATCH`.
|
|
191
|
+
|
|
192
|
+
## Setting up a development environment
|
|
193
|
+
|
|
194
|
+
This Python project is managed with [uv][uv]. You need at least Python 3.13.
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
uv sync
|
|
198
|
+
uv run pytest
|
|
199
|
+
uv run ruff check .
|
|
200
|
+
uv run mypy src tests
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
The checks also run as hooks with `uv run prek run --all-files`. The Prettier hook needs Node.js and `npm install`.
|
|
204
|
+
|
|
205
|
+
The tests run against a fake cloud that is part of the test suite, and need no account. `tests/fixtures/README.md` tells which payloads come from a real account.
|
|
206
|
+
|
|
207
|
+
## Capturing what an appliance sends
|
|
208
|
+
|
|
209
|
+
Some models have not been tested, the Companion among them. To help with yours, capture what it sends:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
uv run python scripts/debug.py capture --seconds 600
|
|
213
|
+
uv run python scripts/debug.py check capture.jsonl
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
`capture` logs in, then writes every message of the appliances of the account to `capture.jsonl`. Start a program on the appliance while it runs. The identifiers of the appliances and of the recipes are replaced, so the file can be shared in an issue. The first run asks for the email and password of the account and keeps a login token in a `.env` file, which git ignores. The password is not stored.
|
|
217
|
+
|
|
218
|
+
`check` prints what the library does not understand in a capture: fields it does not read, and states, modes and programs it does not know.
|
|
219
|
+
|
|
220
|
+
## Disclaimer
|
|
221
|
+
|
|
222
|
+
This library is not affiliated with Groupe SEB, Moulinex or Tefal. It relies on an undocumented cloud API that can change at any time.
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
MIT License, see [LICENSE.md](LICENSE.md).
|
|
227
|
+
|
|
228
|
+
[build-shield]: https://github.com/piitaya/python-moulinex/actions/workflows/tests.yaml/badge.svg
|
|
229
|
+
[build]: https://github.com/piitaya/python-moulinex/actions
|
|
230
|
+
[license-shield]: https://img.shields.io/github/license/piitaya/python-moulinex.svg
|
|
231
|
+
[pypi]: https://pypi.org/project/aiomoulinex/
|
|
232
|
+
[python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomoulinex
|
|
233
|
+
[releases-shield]: https://img.shields.io/github/release/piitaya/python-moulinex.svg
|
|
234
|
+
[releases]: https://github.com/piitaya/python-moulinex/releases
|
|
235
|
+
[semver]: http://semver.org/spec/v2.0.0.html
|
|
236
|
+
[uv]: https://docs.astral.sh/uv/
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
# Python: Moulinex
|
|
2
|
+
|
|
3
|
+
[![GitHub Release][releases-shield]][releases]
|
|
4
|
+
[![Python Versions][python-versions-shield]][pypi]
|
|
5
|
+
[![License][license-shield]](LICENSE.md)
|
|
6
|
+
[![Build Status][build-shield]][build]
|
|
7
|
+
|
|
8
|
+
Asynchronous Python client for the Moulinex Cookeo multicookers and Companion cooking robots connected to Wi-Fi.
|
|
9
|
+
|
|
10
|
+
## About
|
|
11
|
+
|
|
12
|
+
The client goes through the same Groupe SEB cloud as the Moulinex app, so the appliance must already be set up in that app. It logs in with the account of the app, then follows what each appliance reports: the cooking state, the program, the remaining time, the recipe in progress, and whether the appliance is turned on.
|
|
13
|
+
|
|
14
|
+
- Fully asynchronous, built on [aiohttp](https://github.com/aio-libs/aiohttp) and [aiomqtt](https://github.com/empicano/aiomqtt). No AWS SDK.
|
|
15
|
+
- Push based: the appliances tell the cloud what changed, and the client tells you.
|
|
16
|
+
- One connection per account, for all its appliances.
|
|
17
|
+
- Renews the tokens and connects again by itself.
|
|
18
|
+
- Typed models and typed errors.
|
|
19
|
+
|
|
20
|
+
The library is read-only. The cloud offers no way to control an appliance, so programs can only be started or stopped on the appliance itself.
|
|
21
|
+
|
|
22
|
+
## Supported appliances
|
|
23
|
+
|
|
24
|
+
| Model | Tested |
|
|
25
|
+
| ---------------------- | ------ |
|
|
26
|
+
| Cookeo Touch WiFi | ✓ |
|
|
27
|
+
| Cookeo Touch Pro WiFi | ✓ |
|
|
28
|
+
| Cookeo Touch Mini WiFi | ✓ |
|
|
29
|
+
| Cookeo Wi-Fi 8-in-1 | |
|
|
30
|
+
| Cookeo Wi-Fi 9-in-1 | |
|
|
31
|
+
| Cookeo Wi-Fi 10-in-1 | |
|
|
32
|
+
| Cookeo Infinity | ✓ |
|
|
33
|
+
| i-Companion Touch XL | |
|
|
34
|
+
|
|
35
|
+
The untested models use the same cloud and should work. Bluetooth-only models such as the Cookeo Connect are not supported, and neither are other Groupe SEB appliances such as the OptiGrill.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
pip install aiomoulinex
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Usage
|
|
44
|
+
|
|
45
|
+
### Logging in
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import aiohttp
|
|
49
|
+
|
|
50
|
+
from aiomoulinex import LoginError, Region, login
|
|
51
|
+
|
|
52
|
+
async with aiohttp.ClientSession() as session:
|
|
53
|
+
try:
|
|
54
|
+
tokens = await login(
|
|
55
|
+
session, "jane@example.com", "password", Region.MOULINEX_FR
|
|
56
|
+
)
|
|
57
|
+
except LoginError as err:
|
|
58
|
+
print(err.reason) # invalid_auth, email_not_verified, account_locked, ...
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`Region` is the brand and country of the account, the one picked in the Moulinex app. The library only uses the connections of the session it is given: the cookies of the cloud stay out of it, so it is safe to pass a session that is shared with other code.
|
|
62
|
+
|
|
63
|
+
Store `tokens.to_dict()` and the region, not the password. `Tokens.from_dict()` reads them back, and `tokens.user_id` identifies the account: it stays the same when the email changes.
|
|
64
|
+
|
|
65
|
+
### Following the appliances
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
import asyncio
|
|
69
|
+
|
|
70
|
+
import aiohttp
|
|
71
|
+
|
|
72
|
+
from aiomoulinex import ApplianceUpdated, Event, MoulinexClient, Region, Tokens
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
async def main(tokens: Tokens) -> None:
|
|
76
|
+
async with aiohttp.ClientSession() as session:
|
|
77
|
+
client = MoulinexClient(session, tokens, Region.MOULINEX_FR)
|
|
78
|
+
|
|
79
|
+
def on_event(event: Event) -> None:
|
|
80
|
+
if isinstance(event, ApplianceUpdated):
|
|
81
|
+
status = event.state.status
|
|
82
|
+
print(
|
|
83
|
+
event.appliance.name,
|
|
84
|
+
status.state if status else None,
|
|
85
|
+
event.appliance.program(status),
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
client.add_listener(on_event)
|
|
89
|
+
await client.connect()
|
|
90
|
+
print(client.appliances)
|
|
91
|
+
await asyncio.sleep(3600)
|
|
92
|
+
await client.disconnect()
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`connect()` refreshes the tokens, reads the appliances of the account, connects to the cloud and asks each appliance for its state. It returns once that state is known: the shadow of each appliance, and the cooking status of those that are turned on. An appliance that does not answer within 3 seconds is not waited for any longer. From then on:
|
|
96
|
+
|
|
97
|
+
- `client.appliances` holds the appliances of the account, by `thing_uuid`.
|
|
98
|
+
- `client.states` holds the last known `ApplianceState` of each appliance. Its `status` is what the appliance is cooking, its `shadow` tells whether it is turned on and which firmware it runs.
|
|
99
|
+
- `client.connected` is `False` while the connection is lost. The client keeps trying to connect again, and `client.states` keeps the last known state.
|
|
100
|
+
- `client.error` is why the client is not connected, if that is known.
|
|
101
|
+
- `client.tokens` holds the tokens as last refreshed.
|
|
102
|
+
|
|
103
|
+
Instead of a listener, the events can be read with `async for event in client.events()`. It ends when the client disconnects.
|
|
104
|
+
|
|
105
|
+
An appliance that is turned on needs a few seconds before it answers. The client asks for its status again 4, 10 and 20 seconds after it turned on, until it answers.
|
|
106
|
+
|
|
107
|
+
### Events
|
|
108
|
+
|
|
109
|
+
| Event | Meaning |
|
|
110
|
+
| ---------------------- | ---------------------------------------------------------------------- |
|
|
111
|
+
| `ApplianceUpdated` | The cooking status or the shadow of an appliance changed. |
|
|
112
|
+
| `ApplianceAdded` | An appliance was linked to the account after the client connected. |
|
|
113
|
+
| `ApplianceRemoved` | An appliance is no longer linked to the account. |
|
|
114
|
+
| `ConnectionLost` | The connection is lost. The client keeps trying to connect again. |
|
|
115
|
+
| `ConnectionRestored` | The connection is back. |
|
|
116
|
+
| `AuthenticationFailed` | The cloud refused the refresh token. The client stopped: log in again. |
|
|
117
|
+
| `TokensUpdated` | The refresh token changed. Store the tokens to connect the next time. |
|
|
118
|
+
|
|
119
|
+
The client reads the appliances of the account again each time it renews its credentials, a little less than once an hour. That is when added and removed appliances are noticed.
|
|
120
|
+
|
|
121
|
+
### Cooking status
|
|
122
|
+
|
|
123
|
+
`ApplianceState.status` is a `CookingStatus`, for a Companion as well. Each message of an appliance holds its whole status, so a status is never mixed with the one before: a value that is `None` does not apply at that moment.
|
|
124
|
+
|
|
125
|
+
The status itself is `None` until the appliance reports one, and again each time it turns off. What it was cooking is not shown again when it is turned back on.
|
|
126
|
+
|
|
127
|
+
- `state`: a `CookingState`. `idle` is defined by this library, for an appliance that is turned on and reports no state. The other values are those of the appliance: `stopped`, `ready`, `paused`, `warming`, `cooking`, `depressurization`, `keep_warm`, `done`, `delayed` and `alert`. It is `None` for a value this library does not know, which `raw_state` then holds.
|
|
128
|
+
- `mode`: a `CookingMode`: `manual`, `program`, `recipe` or `ingredient_cooking`.
|
|
129
|
+
- `appliance.program(status)`: the program in use, such as `cooking_high_pressure`. `appliance.programs` lists the programs that kind of appliance can run.
|
|
130
|
+
- `phase_progress`: a percentage, while the appliance warms up or releases pressure. `None` in every other state, like in the Moulinex app. `progress` holds what the appliance sent.
|
|
131
|
+
- `elapsed_time` and `remaining_time`: in seconds. The appliance does not send them every second: count from `received_at`, the time the message came in.
|
|
132
|
+
- `duration` and `temperature`: what the program is set to, in seconds and degrees Celsius.
|
|
133
|
+
- `recipe` and `step`: the recipe in progress and its current step. For an ingredient cooking, the recipe holds the ingredient.
|
|
134
|
+
- `notification`: the code of a message the appliance shows on its screen.
|
|
135
|
+
- `error` and `alert_description`: what the appliance reports when something is wrong.
|
|
136
|
+
- `event_date` and `operation_start`: the dates the appliance sends, read as UTC.
|
|
137
|
+
|
|
138
|
+
`ApplianceState.shadow.connected` tells whether the appliance is turned on and connected to the cloud.
|
|
139
|
+
|
|
140
|
+
### Errors
|
|
141
|
+
|
|
142
|
+
All errors are subclasses of `MoulinexError`:
|
|
143
|
+
|
|
144
|
+
| Error | Meaning |
|
|
145
|
+
| ----------------------------- | -------------------------------------------------------------- |
|
|
146
|
+
| `MoulinexConnectionError` | The cloud could not be reached, or it did not answer in time. |
|
|
147
|
+
| `MoulinexAuthenticationError` | The cloud refused the tokens. The account has to log in again. |
|
|
148
|
+
| `LoginError` | The cloud refused the email and password. `reason` tells why. |
|
|
149
|
+
|
|
150
|
+
`LoginError` is a `MoulinexAuthenticationError`, so catch it first. A plain `MoulinexError` means the cloud answered something this library does not understand.
|
|
151
|
+
|
|
152
|
+
### TLS
|
|
153
|
+
|
|
154
|
+
Creating a TLS context reads files from disk. The client does that in an executor. To reuse a context of your own, pass it as `ssl_context`.
|
|
155
|
+
|
|
156
|
+
## Changelog & Releases
|
|
157
|
+
|
|
158
|
+
This repository keeps a change log using [GitHub's releases][releases] functionality.
|
|
159
|
+
|
|
160
|
+
Releases are based on [Semantic Versioning][semver], and use the format of `MAJOR.MINOR.PATCH`.
|
|
161
|
+
|
|
162
|
+
## Setting up a development environment
|
|
163
|
+
|
|
164
|
+
This Python project is managed with [uv][uv]. You need at least Python 3.13.
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
uv sync
|
|
168
|
+
uv run pytest
|
|
169
|
+
uv run ruff check .
|
|
170
|
+
uv run mypy src tests
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
The checks also run as hooks with `uv run prek run --all-files`. The Prettier hook needs Node.js and `npm install`.
|
|
174
|
+
|
|
175
|
+
The tests run against a fake cloud that is part of the test suite, and need no account. `tests/fixtures/README.md` tells which payloads come from a real account.
|
|
176
|
+
|
|
177
|
+
## Capturing what an appliance sends
|
|
178
|
+
|
|
179
|
+
Some models have not been tested, the Companion among them. To help with yours, capture what it sends:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
uv run python scripts/debug.py capture --seconds 600
|
|
183
|
+
uv run python scripts/debug.py check capture.jsonl
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`capture` logs in, then writes every message of the appliances of the account to `capture.jsonl`. Start a program on the appliance while it runs. The identifiers of the appliances and of the recipes are replaced, so the file can be shared in an issue. The first run asks for the email and password of the account and keeps a login token in a `.env` file, which git ignores. The password is not stored.
|
|
187
|
+
|
|
188
|
+
`check` prints what the library does not understand in a capture: fields it does not read, and states, modes and programs it does not know.
|
|
189
|
+
|
|
190
|
+
## Disclaimer
|
|
191
|
+
|
|
192
|
+
This library is not affiliated with Groupe SEB, Moulinex or Tefal. It relies on an undocumented cloud API that can change at any time.
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
|
|
196
|
+
MIT License, see [LICENSE.md](LICENSE.md).
|
|
197
|
+
|
|
198
|
+
[build-shield]: https://github.com/piitaya/python-moulinex/actions/workflows/tests.yaml/badge.svg
|
|
199
|
+
[build]: https://github.com/piitaya/python-moulinex/actions
|
|
200
|
+
[license-shield]: https://img.shields.io/github/license/piitaya/python-moulinex.svg
|
|
201
|
+
[pypi]: https://pypi.org/project/aiomoulinex/
|
|
202
|
+
[python-versions-shield]: https://img.shields.io/pypi/pyversions/aiomoulinex
|
|
203
|
+
[releases-shield]: https://img.shields.io/github/release/piitaya/python-moulinex.svg
|
|
204
|
+
[releases]: https://github.com/piitaya/python-moulinex/releases
|
|
205
|
+
[semver]: http://semver.org/spec/v2.0.0.html
|
|
206
|
+
[uv]: https://docs.astral.sh/uv/
|