Git Product home page Git Product logo

python-ember-mug's Introduction

Python Ember Mug

pypi python Build Status codecov Project Maintenance Maintainer License pre-commit

Python Library for interacting with Ember Mugs, Cups, and Travel Mugs via Bluetooth

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.

All known Ember Mugs, Cups, Tumblers and Travel Mugs have been tested and seem to work well. If I missed one, or you have new feature ideas or issues, please create an issue, if it isn't already there, and we'll figure it out.

Device Tested
Mug
Mug 2
Cup
Tumbler
Travel Mug
Travel Mug 2

Features

  • Finding devices
  • Connecting to devices
  • Reading/Writing most values
  • Poll for changes

Attributes by device:

Attribute Mug Cup Tumbler Travel Mug Description
Name R/W N/A N/A R Name to give device
LED Colour R/W R/W R/W N/A Colour of front LED
Current Temperature R R R R Current temperature of the liquid in the mug
Target Temperature R/W R/W R/W R/W Desired temperature for the liquid
Temperature Unit R/W R/W R/W R/W Internal temperature unit for the app (C/F)
Liquid Level R R R R Approximate level of the liquid in the device
Volume level N/A N/A N/A R/W Volume of the button press beep
Battery Percent R R R R Current battery level
On Charger R R R R Device is on it's charger

Note Writing may only work if the devices has been set up in the app previously

Usage

Python

from ember_mug.scanner import find_device, discover_devices
from ember_mug.utils import get_model_info_from_advertiser_data
from ember_mug.mug import EmberMug

# if first time with mug in pairing
devices = await discover_devices()

# after paired you can simply use
device, advertisement = await find_device()
model_info = get_model_info_from_advertiser_data(advertisement)
mug = EmberMug(device, model_info)
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 devices in pairing mode
find Find one already paired devices
info Connect to one device and print its current state
poll Connect to one device 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 device

Example:

$ ember-mug poll
Found device: C9:0F:59:D6:33:F9: Ember Ceramic Mug
Connecting...
Connected.
Fetching Info
Device Data
+--------------+----------------------+
| Device Name  | Jesse's Mug          |
+--------------+----------------------+
| Meta         | None                 |
+--------------+----------------------+
| Battery      | 64.0%                |
|              | not on charging base |
+--------------+----------------------+
| Firmware     | None                 |
+--------------+----------------------+
| LED Colour   | #ff0fbb              |
+--------------+----------------------+
| Liquid State | Empty                |
+--------------+----------------------+
| Liquid Level | 0.00%                |
+--------------+----------------------+
| Current Temp | 24.50°C              |
+--------------+----------------------+
| Target Temp  | 55.00°C              |
+--------------+----------------------+
| Use Metric   | True                 |
+--------------+----------------------+

Watching for changes
Current Temp changed from "24.50°C" to "25.50°"
Battery changed from "64.0%, on charging base" to "65.5%, on charging base"

Caveats

  • Since this api is not public, a lot of guesswork and reverse engineering is involved, so it's not perfect.
  • If the device 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 device 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, but they are not very useful anyway.

Troubleshooting

Systematic timeouts or le-connection-abort-by-local

If your mug gets stuck in a state where it refuses to connect, you get constant reconnects, timeouts, and/or le-connection-abort-by-local messages in the debug logs, you may need to remove your mug via bluetoothctl remove my-mac-address and factory reset your device. It should reconnect correctly afterward. You may also need to re-add it to the app in order to make it writable again as well.

'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 device is in pairing mode (ie the light is flashing blue or says "PAIR") and run the bluetoothctl command. You don't need to type anything. run it and wait until the mug connects.

Development

Install:

pip install hatch
# Use CLI interface
hatch run ember-mug --help
# Run Tests
hatch run test:cov
# View docs
hatch docs:serve
# Lint code
pre-commit run --all-files

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.

python-ember-mug's People

Contributors

dependabot[bot] avatar sopelj avatar thelegendofbrian avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

python-ember-mug's Issues

Error with discovering mugs

  • Python Ember Mug version: 1.0.0
  • Python version: 3.11.6
  • Operating System: macOS 14.2.1 (23C71)

Description

The software stopped working, probably due to changed in the Bleak Library.
I have runned "ember-mug discover" and got an error.

ember-mug discover

Traceback (most recent call last):
  File "/opt/homebrew/bin/ember-mug", line 8, in <module>
    sys.exit(run_cli())
             ^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/ember_mug/cli/__init__.py", line 13, in run_cli
    asyncio.run(cli.run())
  File "/opt/homebrew/Cellar/[email protected]/3.11.6_1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/asyncio/runners.py", line 190, in run
    return runner.run(main)
           ^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.11.6_1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.11.6_1/Frameworks/Python.framework/Versions/3.11/lib/python3.11/asyncio/base_events.py", line 653, in run_until_complete
    return future.result()
           ^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/ember_mug/cli/commands.py", line 257, in run
    await self._commands[args.command](args)
  File "/opt/homebrew/lib/python3.11/site-packages/ember_mug/cli/commands.py", line 64, in discover
    mugs = await discover_mugs(mac=args.mac)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/homebrew/lib/python3.11/site-packages/ember_mug/scanner.py", line 47, in discover_mugs
    return [
           ^
  File "/opt/homebrew/lib/python3.11/site-packages/ember_mug/scanner.py", line 49, in <listcomp>
    for (d, a) in scanner.discovered_devices_and_advertisement_data
        ^^^^^^
ValueError: too many values to unpack (expected 2)

Staying connected (pi4) with HA integration

  • Python Ember Mug version: Unknown Apologies for my ignorance. I'm using your (sopelj's) ember mug integration for home assistant.

  • Python version: 3.9

  • Operating System: Raspberry Pi OS

Description

I can only get readings for my mug (v1) when it's freshly paired.

I was expecting a "live" view in HA.

I've read the point about re-pairing in the integration's repo. I don't really want to do this all the time to use my mug in HA (however it is not unusual, the android app needs constant re-pairing)

I was hoping the integration would solve the connectivity issues these mugs have with the android app.

My log shows:

2023-01-08 20:23:00.218 ERROR (MainThread) [custom_components.ember_mug.coordinator] EMBER ([MyEmberMAC]) - [MyEmberMAC]: Failed to connect: 

What I Did

Followed the setup instructions on the repo:

  • setup in app (done ages ago)
  • unpaired from my phone
  • pairing mode activated once HA found the device.

Could you add the Tumbler?

  • Python Ember Mug version: 0.8.3
  • Python version: 3.11.6
  • Operating System: MacOS Ventura

Description

Could you add the new Ember Tumbler?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.