python-ember-mug 0.8.1__tar.gz → 0.9.0__tar.gz

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-ember-mug
-Version: 0.8.1
+Version: 0.9.0
 Summary: Python Library for Ember Mugs.
 Project-URL: Documentation, https://sopelj.github.io/python-ember-mug/
 Project-URL: Source code, https://github.com/sopelj/python-ember-mug/
@@ -15,9 +15,11 @@ Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
-Requires-Dist: bleak-retry-connector>=3.0.0
-Requires-Dist: bleak>=0.20.2
+Requires-Dist: async-timeout; python_version < '3.11'
+Requires-Dist: bleak-retry-connector>=3.1.2
+Requires-Dist: bleak>=0.21.0
 Provides-Extra: docs
 Requires-Dist: mkdocs-autorefs; extra == 'docs'
 Requires-Dist: mkdocs-include-markdown-plugin<7.0.0,>=3.6.1; extra == 'docs'
@@ -37,7 +39,7 @@ Description-Content-Type: text/markdown
 [![python](https://img.shields.io/pypi/pyversions/python-ember-mug.svg)](https://pypi.org/project/python-ember-mug/)
 [![Build Status](https://github.com/sopelj/python-ember-mug/actions/workflows/tests.yml/badge.svg)](https://github.com/sopelj/python-ember-mug/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/sopelj/python-ember-mug/branch/main/graphs/badge.svg)](https://codecov.io/github/sopelj/python-ember-mug)
-![Project Maintenance](https://img.shields.io/maintenance/yes/2023.svg)
+![Project Maintenance](https://img.shields.io/maintenance/yes/2024.svg)
 [![Maintainer](https://img.shields.io/badge/maintainer-%40sopelj-blue.svg)](https://github.com/sopelj)
 [![License](https://img.shields.io/github/license/sopelj/python-ember-mug.svg)](LICENSE)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)](https://github.com/pre-commit/pre-commit)
@@ -54,16 +56,17 @@ This is an *unofficial* library to attempt to interact with Ember Mugs via Bluet
 This was created for use with my [Home Assistant integration](https://github.com/sopelj/hass-ember-mug-component),
 but could be useful separately and has a simple CLI interface too.
 
-All known Ember Mugs, Cups and Travel Mugs have been tested and work.
-If I missed one, or you have new feature ideas/issues, please let me know.
+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](https://github.com/sopelj/python-ember-mug/issues), if it isn't already there, and we'll figure it out.
 
-| Device       | Tested  |
-|--------------|---------|
-| Mug          | ✓       |
-| Mug 2        | ✓       |
-| Cup          | ✓       |
-| Travel Mug   | ✓       |
-| Travel Mug 2 | ✓       |
+| Device       | Tested |
+|--------------|--------|
+| Mug          | ✓      |
+| Mug 2        | ✓      |
+| Cup          | ✓      |
+| Tumbler      | ✓      |
+| Travel Mug   | ✓      |
+| Travel Mug 2 | ✓      |
 
 ## Features
 
@@ -74,17 +77,17 @@ If I missed one, or you have new feature ideas/issues, please let me know.
 
 Attributes by device:
 
-| Attribute           | Mug | Cup | Travel Mug | Description                                   |
-|---------------------|-----|-----|------------|-----------------------------------------------|
-| Name                | R/W | N/A | R          | Name to give device                           |
-| LED Colour          | R/W | R/W | N/A        | Colour of front LED                           |
-| Current Temperature | R   | R   | R          | Current temperature of the liquid in the mug  |
-| Target Temperature  | R/W | R/W | R/W        | Desired temperature for the liquid            |
-| Temperature Unit    | R/W | R/W | R/W        | Internal temperature unit for the app (C/F)   |
-| Liquid Level        | R   | R   | R          | Approximate level of the liquid in the device |
-| Volume level        | N/A | N/A | R/W        | Volume of the button press beep               |
-| Battery Percent     | R   | R   | R          | Current battery level                         |
-| On Charger          | R   | R   | R          | Device is on it's charger                     |
+| 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                     |
 
 *** Writing may only work if the devices has been set up in the app previously
 
@@ -148,6 +151,12 @@ Basic options:
 
 ## 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.

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/README.md

@@ -4,7 +4,7 @@
 [![python](https://img.shields.io/pypi/pyversions/python-ember-mug.svg)](https://pypi.org/project/python-ember-mug/)
 [![Build Status](https://github.com/sopelj/python-ember-mug/actions/workflows/tests.yml/badge.svg)](https://github.com/sopelj/python-ember-mug/actions/workflows/tests.yml)
 [![codecov](https://codecov.io/gh/sopelj/python-ember-mug/branch/main/graphs/badge.svg)](https://codecov.io/github/sopelj/python-ember-mug)
-![Project Maintenance](https://img.shields.io/maintenance/yes/2023.svg)
+![Project Maintenance](https://img.shields.io/maintenance/yes/2024.svg)
 [![Maintainer](https://img.shields.io/badge/maintainer-%40sopelj-blue.svg)](https://github.com/sopelj)
 [![License](https://img.shields.io/github/license/sopelj/python-ember-mug.svg)](LICENSE)
 [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen)](https://github.com/pre-commit/pre-commit)
@@ -21,16 +21,17 @@ This is an *unofficial* library to attempt to interact with Ember Mugs via Bluet
 This was created for use with my [Home Assistant integration](https://github.com/sopelj/hass-ember-mug-component),
 but could be useful separately and has a simple CLI interface too.
 
-All known Ember Mugs, Cups and Travel Mugs have been tested and work.
-If I missed one, or you have new feature ideas/issues, please let me know.
+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](https://github.com/sopelj/python-ember-mug/issues), if it isn't already there, and we'll figure it out.
 
-| Device       | Tested  |
-|--------------|---------|
-| Mug          | ✓       |
-| Mug 2        | ✓       |
-| Cup          | ✓       |
-| Travel Mug   | ✓       |
-| Travel Mug 2 | ✓       |
+| Device       | Tested |
+|--------------|--------|
+| Mug          | ✓      |
+| Mug 2        | ✓      |
+| Cup          | ✓      |
+| Tumbler      | ✓      |
+| Travel Mug   | ✓      |
+| Travel Mug 2 | ✓      |
 
 ## Features
 
@@ -41,17 +42,17 @@ If I missed one, or you have new feature ideas/issues, please let me know.
 
 Attributes by device:
 
-| Attribute           | Mug | Cup | Travel Mug | Description                                   |
-|---------------------|-----|-----|------------|-----------------------------------------------|
-| Name                | R/W | N/A | R          | Name to give device                           |
-| LED Colour          | R/W | R/W | N/A        | Colour of front LED                           |
-| Current Temperature | R   | R   | R          | Current temperature of the liquid in the mug  |
-| Target Temperature  | R/W | R/W | R/W        | Desired temperature for the liquid            |
-| Temperature Unit    | R/W | R/W | R/W        | Internal temperature unit for the app (C/F)   |
-| Liquid Level        | R   | R   | R          | Approximate level of the liquid in the device |
-| Volume level        | N/A | N/A | R/W        | Volume of the button press beep               |
-| Battery Percent     | R   | R   | R          | Current battery level                         |
-| On Charger          | R   | R   | R          | Device is on it's charger                     |
+| 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                     |
 
 *** Writing may only work if the devices has been set up in the app previously
 
@@ -115,6 +116,12 @@ Basic options:
 
 ## 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.

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/ember_mug/__init__.py

@@ -5,4 +5,4 @@ __all__ = ("EmberMug",)
 
 __author__ = """Jesse Sopel"""
 __email__ = "jesse.sopel@gmail.com"
-__version__ = "0.8.1"
+__version__ = "0.9.0"

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/ember_mug/cli/commands.py

@@ -7,18 +7,22 @@ import logging
 import re
 import sys
 from argparse import ArgumentParser, ArgumentTypeError, FileType, Namespace
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, ClassVar
 
-from bleak import BleakError
+from bleak import AdvertisementData, BleakError
 
 from ember_mug.consts import ATTR_LABELS, EXTRA_ATTRS, IS_LINUX, VolumeLevel
 from ember_mug.data import Colour
 from ember_mug.mug import EmberMug
 from ember_mug.scanner import discover_mugs, find_mug
 
+from ..formatting import format_capacity
+from ..utils import get_model_info_from_advertiser_data
 from .helpers import CommandLoop, print_changes, print_info, print_table, validate_mac
 
 if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
     from bleak.backends.device import BLEDevice
 
 all_attrs = list(ATTR_LABELS) + list(EXTRA_ATTRS)
@@ -27,29 +31,34 @@ get_attribute_names = [n.replace("_", "-") for n in all_attrs]
 
 async def get_mug(args: Namespace) -> EmberMug:
     """Help to get the mug based on args."""
-    device = await find_device(args)
-    mug = EmberMug(device, use_metric=not args.imperial, include_extra=args.extra, debug=args.debug)
+    device, advertisement = await find_device(args)
+    mug = EmberMug(
+        device,
+        get_model_info_from_advertiser_data(advertisement),
+        use_metric=not args.imperial,
+        debug=args.debug,
+    )
     if not args.raw:
         print("Connecting...")
     return mug
 
 
-async def find_device(args: Namespace) -> BLEDevice:
+async def find_device(args: Namespace) -> tuple[BLEDevice, AdvertisementData]:
     """Find a single device that has already been paired."""
     try:
-        device = await find_mug(mac=args.mac, adapter=args.adapter)
+        device, advertisement = await find_mug(mac=args.mac, adapter=args.adapter)
     except BleakError as e:
         print(f"An error occurred trying to find a mug: {e}")
         sys.exit(1)
-    if not device:
+    if not device or not advertisement:
         print("No mug was found.")
         sys.exit(1)
     if not args.raw:
         print("Found mug:", device)
-    return device
+    return device, advertisement
 
 
-async def discover(args: Namespace) -> list[BLEDevice]:
+async def discover(args: Namespace) -> list[tuple[BLEDevice, AdvertisementData]]:
     """Discover new devices in pairing mode."""
     try:
         mugs = await discover_mugs(mac=args.mac)
@@ -60,11 +69,17 @@ async def discover(args: Namespace) -> list[BLEDevice]:
         print('No mugs were found. Be sure it is in pairing mode. Or use "find" if already paired.')
         sys.exit(1)
 
-    for mug in mugs:
+    for mug, advertisement in mugs:
         if args.raw:
             print(mug.address)
         else:
+            model_info = get_model_info_from_advertiser_data(advertisement)
+            model_number = model_info.model.value if model_info.model else "Unknown Model"
             print("Found mug:", mug)
+            print("Name:", advertisement.local_name)
+            print("Model:", f"{model_info.name} [{model_number}]")
+            print("Colour:", model_info.colour.value if model_info.colour else "Unknown")
+            print("Capacity:", format_capacity(model_info.capacity))
     return mugs
 
 
@@ -119,10 +134,10 @@ async def get_mug_value(args: Namespace) -> None:
 async def set_mug_value(args: Namespace) -> None:
     """Set one or more values on the mug."""
     attrs = ("name", "target_temp", "temperature_unit", "led_colour", "volume_level")
-    values = [(attr, value) for attr in attrs if (value := getattr(args, attr))]
+    values = [(attr, value) for attr in attrs if (value := getattr(args, attr, None))]
     if not values:
         print("Please specify at least one attribute and value to set.")
-        options = [f"--{a}" for a in attrs]
+        options = [f"--{a.replace('_', '-')}" for a in attrs]
         print(f'Options: {", ".join(options)}')
         sys.exit(1)
 
@@ -141,15 +156,19 @@ async def set_mug_value(args: Namespace) -> None:
 def colour_type(value: str) -> Colour:
     """Convert a hex or rgb colour to a Colour object."""
     print(value)
-    if match := re.match(r"#?([0-9a-f]{6})", value, re.IGNORECASE):
-        colour = match.group(1)
-        return Colour(*tuple(int(colour[i : i + 2], 16) for i in (0, 2, 4)))
+    if match := re.match(r"#?([0-9a-f]{6}([0-9a-f]{2})?)", value, re.IGNORECASE):
+        raw_colours = match.group(1)
+        colours = [
+            255 if (colour := raw_colours[i : i + 2]) is None else int(colour, 16)
+            for i in range(0, len(raw_colours), 2)
+        ]
+        return Colour(*colours)
 
     with contextlib.suppress(ValueError, AssertionError):
         colours = [int(v) for v in value.split(",")]
-        if 3 <= len(colours) <= 4:
+        if len(colours) not in (3, 4):
             raise ArgumentTypeError("Three or four values should be specified for colour")
-        if all(0 <= c <= 255 for c in colours):
+        if not all(0 <= c <= 255 for c in colours):
             raise ArgumentTypeError("Colour values must be between 0 and 255")
         return Colour(*colours)
 
@@ -160,7 +179,7 @@ def colour_type(value: str) -> Colour:
 class EmberMugCli:
     """Very simple CLI Interface to interact with a mug."""
 
-    _commands = {
+    _commands: ClassVar[dict[str, Callable[[Namespace], Awaitable]]] = {
         "find": find_device,
         "discover": discover,
         "info": fetch_info,

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/ember_mug/cli/helpers.py

@@ -58,8 +58,8 @@ def print_table(data: list[tuple[str, ...]]) -> None:
 
 def print_info(mug: EmberMug) -> None:
     """Print all mug data."""
-    print("Mug Data")
-    print_table([(k, v) for (k, v) in mug.data.formatted.items()])
+    print("Device Data")
+    print_table(list(mug.data.formatted.items()))
 
 
 def print_changes(changes: list[Change], metric: bool = True) -> None:

{python_ember_mug-0.8.1 → python_ember_mug-0.9.0}/ember_mug/consts.py

@@ -8,26 +8,62 @@ from functools import cached_property
 from typing import Literal
 from uuid import UUID
 
-# Bluetooth names of Ember devices
-EMBER_MUG = "Ember Ceramic Mug"
-EMBER_CUP = "Ember Cup"
-EMBER_CUP_2 = "Ember Cup 2"
-EMBER_TRAVEL_MUG_SHORT = "Ember Travel M"
-EMBER_TRAVEL_MUG = "Ember Travel Mug"
-EMBER_TRAVEL_MUG_2 = "Ember Travel Mug 2"
-
-EMBER_BLUETOOTH_NAMES: tuple[str, ...] = (
-    EMBER_MUG,
-    EMBER_CUP,
-    EMBER_CUP_2,
-    EMBER_TRAVEL_MUG,
-    EMBER_TRAVEL_MUG_SHORT,
-    EMBER_TRAVEL_MUG_2,
-)
-
 # Format for all the mug's Bluetooth UUIDs
 UUID_TEMPLATE = "fc54{:0>4x}-236c-4c94-8fa9-944a3e5353fa"
 
+# Registered SIG for BLE Manufacturer Data
+EMBER_BLE_SIG = 0x03C1
+DEFAULT_NAME = "Ember Device"
+
+
+class DeviceType(str, Enum):
+    """Base device types."""
+
+    CUP = "cup"
+    MUG = "mug"
+    TRAVEL_MUG = "travel_mug"
+    TUMBLER = "tumbler"
+
+
+class DeviceModel(str, Enum):
+    """Know device models."""
+
+    CUP_6_OZ = "CM21S"
+    MUG_1_10_OZ = "CM17"
+    MUG_1_14_OZ = "CM17P"
+    MUG_2_10_OZ = "CM19/CM21M"
+    MUG_2_14_OZ = "CM19P/CM21L"
+    TRAVEL_MUG_12_OZ = "TM19"
+    TUMBLER_16_OZ = "CM21XL"
+    UNKNOWN_DEVICE = "Unknown"
+
+
+DEVICE_MODEL_NAMES: dict[DeviceModel, str] = {
+    DeviceModel.CUP_6_OZ: "Ember Cup",
+    DeviceModel.MUG_1_10_OZ: "Ember Mug (10oz)",
+    DeviceModel.MUG_1_14_OZ: "Ember Mug (14oz)",
+    DeviceModel.MUG_2_10_OZ: "Ember Mug 2 (10oz)",
+    DeviceModel.MUG_2_14_OZ: "Ember Mug 2 (14oz)",
+    DeviceModel.TRAVEL_MUG_12_OZ: "Ember Travel Mug",
+    DeviceModel.TUMBLER_16_OZ: "Ember Tumbler",
+}
+
+
+class DeviceColour(str, Enum):
+    """All colours possible found across models."""
+
+    SAGE_GREEN = "Sage Green"
+    SANDSTONE = "Sandstone"
+    BLACK = "Black"
+    WHITE = "White"
+    GREY = "Grey"
+    BLUE = "Blue"
+    RED = "Red"
+    COPPER = "Copper"
+    GOLD = "Gold"
+    STAINLESS_STEEL = "Stainless Steel"
+    ROSE_GOLD = "Rose Gold"
+
 
 class TemperatureUnit(str, Enum):
     """Temperature Units."""
@@ -80,8 +116,9 @@ class MugCharacteristic(IntEnum):
     # RGBA Colour of LED (Read/Write)
     LED = 20
     # Service
-    TRAVEL_MUG_SERVICE = 13857
     STANDARD_SERVICE = 13858
+    TRAVEL_MUG_SERVICE = 13857
+    TRAVEL_MUG_SERVICE_OTHER = 8609
 
     @cached_property
     def uuid(self) -> UUID:
@@ -93,10 +130,21 @@ class MugCharacteristic(IntEnum):
         return str(self.uuid)
 
 
+TRAVEL_MUG_SERVICE_UUIDS = (
+    str(MugCharacteristic.TRAVEL_MUG_SERVICE),
+    str(MugCharacteristic.TRAVEL_MUG_SERVICE_OTHER),
+)
+
+DEVICE_SERVICE_UUIDS = (
+    str(MugCharacteristic.STANDARD_SERVICE),
+    *TRAVEL_MUG_SERVICE_UUIDS,
+)
+
+
 class LiquidState(IntEnum):
     """Constants for liquid state codes."""
 
-    UNKNOWN = 0
+    STANDBY = 0
     EMPTY = 1
     FILLING = 2
     COLD_NO_TEMP_CONTROL = 3
@@ -149,8 +197,9 @@ class PushEvent(IntEnum):
 
 
 # Labels so liquid states
+LIQUID_STATE_UNKNOWN = "Unknown"
 LIQUID_STATE_LABELS: dict[int, str] = {
-    LiquidState.UNKNOWN: "Unknown",
+    LiquidState.STANDBY: "Standby",
     LiquidState.EMPTY: "Empty",
     LiquidState.FILLING: "Filling",
     LiquidState.COLD_NO_TEMP_CONTROL: "Cold (No control)",
@@ -168,7 +217,7 @@ PUSH_EVENT_BATTERY_IDS = [
 
 # Labels for formatting attributes
 ATTR_LABELS = {
-    "name": "Mug Name",
+    "name": "Device Name",
     "meta": "Meta",
     "battery": "Battery",
     "firmware": "Firmware",
@@ -203,7 +252,7 @@ UPDATE_ATTRS = {
     "liquid_level",
     "liquid_state",
 }
-EXTRA_ATTRS = {"dsk", "udsk", "battery_voltage", "date_time_zone"}
+EXTRA_ATTRS = {"battery_voltage", "date_time_zone", "udsk", "dsk"}
 
 # Validation
 MUG_NAME_REGEX = re.compile(r"^[A-Za-z0-9,.\[\]#()!\"\';:|\-_+<>%= ]{1,16}$")