Python Library for Ember Mugs.
Project description
Python Ember Mug
Python Library for interacting with Ember Mugs over Bluetooth
- Documentation: https://sopelj.github.io/python-ember-mug
- GitHub: https://github.com/sopelj/python-ember-mug
- PyPI: https://pypi.org/project/python-ember-mug/
- Free software: MIT
Summary
This is an unofficial library to attempt to interact with Ember Mugs via Bluetooth. This was created for use with my Home Assistant integration, but could be useful separately and has a simple CLI interface too.
Note: Confirmed working with the standard Ember Mug (1 and 2), Ember Cup (2) and Travel Mug (1). If you have another device, and it works or doesn't, please let me know.
Features
- Finding devices
- Connecting to devices
- Reading Information (Colour, temp, liquid level, etc.)
- Writing (Desired temp, colour, temperature unit)*
- Polling for changes
*** Writing only works if the devices has been set up in the app previously
Usage
Python
from ember_mug.scanner import find_mug, discover_mugs
from ember_mug.mug import EmberMug
# if first time with mug in pairing
mugs = await discover_mugs()
device = mugs[0]
# after paired you can simply use
device = await find_mug()
mug = EmberMug(device)
await mug.update_all()
print(mug.data.formatted)
await mug.disconnect()
# You can also use connection as a context manager
# if you want to ensure connection before starting and cleanup on exit
async with mug.connection():
print('Connected.\nFetching Info')
await mug.update_all()
print(mug.data.formatted)
CLI
It can also be run via command line either directly with ember-mug --help
or as a module with python -m ember_mug --help
There are four options with different subsections. You can see them by specifying them before help. eg ember-mug poll --help
ember-mug discover # Finds the mug in pairing mode for the first time
ember-mug poll # fetches info and keeps listening for notifications
ember-mug get name target-temp # Prints name and target temp of mug
ember-mug set --name "My mug" --target-temp 56.8 # Sets the name and target temp to specified values
Basic options:
Command | Use |
---|---|
discover |
Find/List all detected unpaired mugs in pairing mode |
find |
Find one already paired mugs |
info |
Connect to one mug and print its current state |
poll |
Connect to one mug and print its current state and keep watching for changes |
get |
Get the value(s) of one or more attribute(s) by name |
set |
Set one or more values on the mug |
Caveats
- Since this api is not public, a lot of guesswork and reverse engineering is involved, so it's not perfect.
- If the mug has not been set up in the app since it was reset, writing is not allowed. I don't know what they set in the app, but it changes something, and it doesn't work without it.
- Once that mug has been set up in the app, you should ideally forget the device or at least turn off bluetooth whilst using it here, or you will probably get disconnected often
- I haven't figured out some attributes like udsk, dsk, location and timezone.
Troubleshooting
'Operation failed with ATT error: 0x0e' or another connection error
This seems to be caused by the bluetooth adaptor being in some sort of passive mode. I have not yet figured out how to wake it programmatically so sadly, you need to manually open bluetoothctl
to do so.
Please ensure the mug is in pairing mode (ie the light is flashing blue) and run the bluetoothctl
command. You don,t need to type anything. run it and wait until the mug connects.
Todo
- Test with other devices. Please let me know if you have tried it with others.
Credits
This package was created with Cookiecutter and the waynerv/cookiecutter-pypackage project template.
Notice of Non-Affiliation and Disclaimer
This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Ember.
The name Ember as well as related names, marks, emblems and images are registered trademarks of their respective owners.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file python_ember_mug-0.7.0b5.tar.gz
.
File metadata
- Download URL: python_ember_mug-0.7.0b5.tar.gz
- Upload date:
- Size: 28.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.11.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 2be46bbfb967e8989d9ac92bc45eb42f9a01f774b8c350abe6dacebd3816c3b0 |
|
MD5 | d59336769dae55c53424fb6203d2c2b4 |
|
BLAKE2b-256 | 9b972a09eff28ffd3bf833eca38237494eabf3c0fdb2bcb3a5984d53ab88c514 |
File details
Details for the file python_ember_mug-0.7.0b5-py3-none-any.whl
.
File metadata
- Download URL: python_ember_mug-0.7.0b5-py3-none-any.whl
- Upload date:
- Size: 22.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.11.3
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8f2578ada414e45f5d45381e4944812206a2a50fe32b21f43ab7f4158f9a690e |
|
MD5 | 112474096015adc5d07729877ee0052a |
|
BLAKE2b-256 | dda3d22f82dd5bdbdb4ab9c50e4b9475cd1e38d25a5546c67de3aa3e452cf396 |