| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973 |
- from decimal import ROUND_HALF_UP, Decimal
- from enum import Enum
- from typing import Any, TypeVar
- from ..const.meter_pro import (
- MeterProAlarmMode,
- MeterProAlarmVolume,
- MeterProCO2AlarmMode,
- MeterProCO2AlarmStatus,
- MeterProComfortStatus,
- MeterProDateFormat,
- MeterProDisplaySource,
- MeterProDisplayZone,
- MeterProTemperatureHumidityAlarmMode,
- MeterProTemperatureHumidityAlarmStatus,
- MeterProWeatherIcon,
- MeterProZoneIcon,
- )
- from ..helpers import parse_uint24_be
- from .device import SwitchbotDevice, SwitchbotOperationError
- _E = TypeVar("_E", bound=Enum)
- COMMAND_SET_TIME_OFFSET = "570f680506"
- COMMAND_GET_TIME_OFFSET = "570f690506"
- MAX_TIME_OFFSET = (1 << 24) - 1
- COMMAND_GET_DEVICE_DATETIME = "570f6901"
- COMMAND_SET_DEVICE_DATETIME = "57000503"
- COMMAND_SET_DISPLAY_FORMAT = "570f680505"
- COMMAND_GET_WEATHER = "570f6906"
- COMMAND_SET_WEATHER = "570f680601"
- COMMAND_GET_COMFORT_LEVEL = "570f69020101"
- COMMAND_GET_TEMPERATURE_HUMIDITY_ALARM = "570f69020100"
- COMMAND_SET_TEMPERATURE_HUMIDITY_LIMITS = "570f680201"
- COMMAND_GET_ALARM_SETTINGS = "570f690204"
- COMMAND_SET_ALARM_SETTINGS = "570f680204"
- COMMAND_GET_CALIBRATION = "570f6903"
- COMMAND_SET_CALIBRATION = "570f6803"
- COMMAND_GET_DISPLAY_SETTINGS = "570f690701"
- COMMAND_SET_DISPLAY_ZONE = "570f680701"
- COMMAND_SET_ZONE_ICONS = "570f68070103"
- COMMAND_SET_DATA_UPDATE_INTERVAL = "570f68070105"
- COMMAND_GET_BUTTON_FUNCTIONS = "570f690704"
- COMMAND_SET_BUTTON_FUNCTIONS = "570f68070106"
- COMMAND_SET_DATE_FORMAT = "570f68070107"
- COMMAND_SET_BATTERY_ICON = "570f68070108"
- COMMAND_SET_TEMPERATURE_UNIT = "570f68070109"
- MAX_HUMIDITY_CALIBRATION = 99
- MAX_DATA_UPDATE_INTERVAL = 0xFFFF
- NO_MAC = "000000000000"
- # "Keep current value" differs between the single-zone and two-icon commands.
- KEEP_ZONE_ICON = 0xFF
- KEEP_ICON = 0x0F
- KEEP_BUTTON_FUNCTION = 0xFF
- KEEP_ALARM_VOLUME = 0xFF
- TEMPERATURE_HUMIDITY_ALARM_MASK = 0x77
- SOURCES_WITHOUT_MAC = {MeterProDisplaySource.NONE, MeterProDisplaySource.NETWORK}
- COMMAND_TRIGGER_CO2_SAMPLING = "570f680b04"
- COMMAND_START_CO2_CALIBRATION = "570f680b02"
- COMMAND_GET_USB_POWER_STATE = "570f690b02"
- COMMAND_GET_CO2_USB_UPDATE_INTERVAL = "570f690b03"
- COMMAND_SET_CO2_USB_UPDATE_INTERVAL = "570f680b01"
- COMMAND_GET_CO2_BATTERY_UPDATE_INTERVAL = "570f690b04"
- COMMAND_SET_CO2_BATTERY_UPDATE_INTERVAL = "570f680b06"
- COMMAND_GET_CO2_ALARM = "570f69020301"
- COMMAND_SET_CO2_ALARM = "570f68020301"
- COMMAND_GET_CO2_LEVEL_THRESHOLDS = "570f69020302"
- COMMAND_SET_CO2_LEVEL_THRESHOLDS = "570f68020302"
- def _weather_decimal(value: float | Decimal, name: str) -> Decimal:
- if isinstance(value, bool):
- raise TypeError(f"{name} must be a number, not a boolean")
- if not isinstance(value, (int, float, Decimal)):
- raise TypeError(f"{name} must be a number")
- number = value if isinstance(value, Decimal) else Decimal(str(value))
- if not number.is_finite():
- raise ValueError(f"{name} must be finite")
- return number
- def _encode_weather_temperature(temperature_c: float | Decimal) -> bytes:
- temperature = _weather_decimal(temperature_c, "Temperature")
- if abs(temperature) > Decimal("127.9"):
- raise ValueError("Temperature must be -127.9..127.9 C")
- temperature = temperature.quantize(Decimal("0.1"), rounding=ROUND_HALF_UP)
- integer, decimal = divmod(int(abs(temperature) * 10), 10)
- return bytes((decimal, integer | (0x80 if temperature >= 0 else 0)))
- def _decode_threshold_temperature(signed_degrees: int, tenths: int) -> float:
- magnitude = (signed_degrees & 0x7F) * 10 + tenths
- return (magnitude if signed_degrees & 0x80 else -magnitude) / 10
- def _decode_temperature_humidity_limits(data: bytes) -> tuple[float, float, int, int]:
- high, humid, decimals, low, dry = data
- high_tenths, low_tenths = decimals >> 4, decimals & 0x0F
- humid &= 0x7F
- dry &= 0x7F
- if max(high_tenths, low_tenths) > 9 or max(humid, dry) > 99:
- raise ValueError("Invalid temperature or humidity limits")
- return (
- _decode_threshold_temperature(low, low_tenths),
- _decode_threshold_temperature(high, high_tenths),
- dry,
- humid,
- )
- def _encode_temperature_humidity_limits(
- temperature_low_c: float | Decimal,
- temperature_high_c: float | Decimal,
- humidity_low: int,
- humidity_high: int,
- ) -> bytes:
- low_tenths, low = _encode_weather_temperature(temperature_low_c)
- high_tenths, high = _encode_weather_temperature(temperature_high_c)
- if any(
- isinstance(limit, bool) or not isinstance(limit, int) or not 0 <= limit <= 99
- for limit in (humidity_low, humidity_high)
- ):
- raise ValueError("Humidity limits must be integers from 0 to 99")
- return bytes(
- (high, humidity_high, (high_tenths << 4) | low_tenths, low, humidity_low)
- )
- def _encode_weather_humidity(humidity: float | Decimal) -> int:
- relative_humidity = _weather_decimal(humidity, "humidity")
- if not 1 <= relative_humidity <= 99:
- raise ValueError("humidity must be 1..99%")
- return int(relative_humidity.quantize(Decimal(1), rounding=ROUND_HALF_UP))
- def _coerce_enum(enum_cls: type[_E], value: _E | int, name: str) -> _E:
- """Return value as enum_cls; accept the enum or its integer value."""
- if isinstance(value, enum_cls):
- return value
- if isinstance(value, bool) or not isinstance(value, int):
- raise TypeError(f"{name} must be a {enum_cls.__name__} or integer")
- return enum_cls(value)
- def _mac_hex(mac: str | None) -> str:
- """Return a MAC address as 12 hex digits, all zeros when empty."""
- if not mac:
- return NO_MAC
- cleaned = mac.replace(":", "").replace("-", "").lower()
- if len(cleaned) != 12 or any(c not in "0123456789abcdef" for c in cleaned):
- raise ValueError(f"Invalid MAC address {mac!r}")
- return cleaned
- def _format_mac(raw: bytes) -> str | None:
- """Return "AA:BB:CC:DD:EE:FF", or None for an empty MAC."""
- if not any(raw):
- return None
- return ":".join(f"{b:02X}" for b in raw)
- class SwitchbotMeterPro(SwitchbotDevice):
- """Implement the shared protocol for SwitchBot Meter Pro and Meter Pro CO2."""
- async def get_time_offset(self) -> int:
- """
- Get the current display time offset from the device.
- Returns:
- int: The time offset in seconds. Max 24 bits.
- """
- # Response Format: 5 bytes, where
- # - byte 0: "01" (success)
- # - byte 1: "00" (plus offset) or "80" (minus offset)
- # - bytes 2-4: int24, number of seconds to offset.
- # Example response: 01-80-00-10-00 -> subtract 4096 seconds.
- result = await self._send_command(COMMAND_GET_TIME_OFFSET)
- result = self._validate_result("get_time_offset", result, min_length=5)
- is_negative = bool(result[1] & 0b10000000)
- offset = parse_uint24_be(result, 2)
- return -offset if is_negative else offset
- async def set_time_offset(self, offset_seconds: int) -> None:
- """
- Set the display time offset on the device. This is what happens when
- you adjust display time in the Switchbot app. The displayed time is
- calculated as the internal device time (usually comes from the factory
- settings or set by the Switchbot app upon syncing) + offset. The offset
- is provided in seconds and can be positive or negative.
- Args:
- offset_seconds (int): 2^24 maximum, can be negative.
- """
- abs_offset = abs(offset_seconds)
- if abs_offset > MAX_TIME_OFFSET:
- raise SwitchbotOperationError(
- f"{self.name}: Requested to set_time_offset of {offset_seconds} seconds, allowed +-{MAX_TIME_OFFSET} max."
- )
- sign_byte = "80" if offset_seconds < 0 else "00"
- # Example: 57-0f-68-05-06-80-00-10-00 -> subtract 4096 seconds.
- payload = f"{COMMAND_SET_TIME_OFFSET}{sign_byte}{abs_offset:06x}"
- result = await self._send_command(payload)
- self._validate_result("set_time_offset", result)
- async def get_datetime(self) -> dict[str, Any]:
- """
- Get the current device time and settings as it is displayed. Contains
- a time offset, if any was applied (see set_time_offset).
- Doesn't include the current time zone.
- Returns:
- dict: Dictionary containing:
- - 12h_mode (bool): True if 12h mode, False if 24h mode.
- - year (int)
- - month (int)
- - day (int)
- - hour (int)
- - minute (int)
- - second (int)
- """
- # Response Format: 13 bytes, where
- # - byte 0: "01" (success)
- # - bytes 1-4: temperature, ignored here.
- # - byte 5: time display format:
- # - "80" - 12h (am/pm)
- # - "00" - 24h
- # - bytes 6-12: yyyy-MM-dd-hh-mm-ss
- # Example: 01-e4-02-94-23-00-07-e9-0c-1e-08-37-01 contains
- # "year 2025, 30 December, 08:55:01, displayed in 24h format".
- result = await self._send_command(COMMAND_GET_DEVICE_DATETIME)
- result = self._validate_result("get_datetime", result, min_length=13)
- return {
- # Whether the time is displayed in 12h(am/pm) or 24h mode.
- "12h_mode": bool(result[5] & 0b10000000),
- "year": (result[6] << 8) + result[7],
- "month": result[8],
- "day": result[9],
- "hour": result[10],
- "minute": result[11],
- "second": result[12],
- }
- async def set_datetime(
- self, timestamp: int, utc_offset_hours: int = 0, utc_offset_minutes: int = 0
- ) -> None:
- """
- Set the device internal time and timezone. Similar to how the
- Switchbot app does it upon syncing with the device.
- Pay attention to calculating UTC offset hours and minutes, see
- examples below.
- Args:
- timestamp (int): Unix timestamp in seconds.
- utc_offset_hours (int): UTC offset in hours, floor()'ed,
- within [-12; 14] range.
- Examples: -5 for UTC-05:00, -6 for UTC-05:30,
- 5 for UTC+05:00, 5 for UTC+5:30.
- utc_offset_minutes (int): UTC offset minutes component, always
- positive, complements utc_offset_hours.
- Examples: 45 for UTC+05:45, 15 for UTC-5:45.
- """
- if not (-12 <= utc_offset_hours <= 14):
- raise SwitchbotOperationError(
- f"{self.name}: utc_offset_hours must be between -12 and +14 inclusive, got {utc_offset_hours}"
- )
- if not (0 <= utc_offset_minutes < 60):
- raise SwitchbotOperationError(
- f"{self.name}: utc_offset_minutes must be between 0 and 59 inclusive, got {utc_offset_minutes}"
- )
- # The device doesn't automatically add offset minutes, it expects them
- # to come as a part of the timestamp.
- adjusted_timestamp = timestamp + utc_offset_minutes * 60
- # The timezone is encoded as 1 byte, where 00 stands for UTC-12.
- # TZ with minute offset gets floor()ed: 4:30 yields 4, -4:30 yields -5.
- utc_byte = utc_offset_hours + 12
- payload = (
- f"{COMMAND_SET_DEVICE_DATETIME}{utc_byte:02x}"
- f"{adjusted_timestamp:016x}{utc_offset_minutes:02x}"
- )
- result = await self._send_command(payload)
- self._validate_result("set_datetime", result)
- async def set_time_display_format(self, is_12h_mode: bool = False) -> None:
- """
- Set the time display format on the device: 12h(AM/PM) or 24h.
- Args:
- is_12h_mode (bool): True for 12h (AM/PM) mode, False for 24h mode.
- """
- mode_byte = "80" if is_12h_mode else "00"
- payload = f"{COMMAND_SET_DISPLAY_FORMAT}{mode_byte}"
- result = await self._send_command(payload)
- self._validate_result("set_time_display_format", result)
- async def get_comfort_level(
- self,
- ) -> dict[str, float | int | bool | MeterProComfortStatus]:
- """Read the comfort mode, Celsius and %RH limits, and current status."""
- result = await self._send_command(COMMAND_GET_COMFORT_LEVEL)
- data = self._validate_result("get_comfort_level", result, min_length=8)
- mode = data[1]
- if mode not in (0, 1):
- raise SwitchbotOperationError(
- f"{self.name}: Invalid comfort level response (result={data.hex()})"
- )
- try:
- low, high, dry, humid = _decode_temperature_humidity_limits(data[2:7])
- except ValueError as exc:
- raise SwitchbotOperationError(
- f"{self.name}: Invalid comfort level response (result={data.hex()})"
- ) from exc
- return {
- "custom": mode == 1,
- "temperature_low_c": low,
- "temperature_high_c": high,
- "humidity_low": dry,
- "humidity_high": humid,
- "status": MeterProComfortStatus(data[7] & 0x03),
- }
- async def set_comfort_level(
- self,
- temperature_low_c: float | Decimal,
- temperature_high_c: float | Decimal,
- humidity_low: int,
- humidity_high: int,
- *,
- custom: bool = True,
- ) -> None:
- """Set comfort limits in °C (half-up to tenths) and %RH, or select default mode."""
- try:
- limits = _encode_temperature_humidity_limits(
- temperature_low_c, temperature_high_c, humidity_low, humidity_high
- )
- except (TypeError, ValueError) as exc:
- raise SwitchbotOperationError(f"{self.name}: {exc}") from exc
- if not isinstance(custom, bool):
- raise SwitchbotOperationError(f"{self.name}: custom must be a boolean")
- if custom:
- low, high, dry, humid = _decode_temperature_humidity_limits(limits)
- if low >= high or dry >= humid:
- raise SwitchbotOperationError(
- f"{self.name}: Lower comfort limits must be below upper limits"
- )
- flags = 0x88 if custom else 0x80
- result = await self._send_command(
- f"{COMMAND_SET_TEMPERATURE_HUMIDITY_LIMITS}{flags:02x}{limits.hex()}"
- )
- self._validate_result("set_comfort_level", result)
- async def get_temperature_humidity_alarm(
- self,
- ) -> dict[
- str,
- float
- | int
- | MeterProTemperatureHumidityAlarmMode
- | MeterProTemperatureHumidityAlarmStatus,
- ]:
- """Read local alarm conditions, thresholds in °C and %RH, and both states."""
- result = await self._send_command(COMMAND_GET_TEMPERATURE_HUMIDITY_ALARM)
- data = self._validate_result(
- "get_temperature_humidity_alarm", result, min_length=8
- )
- try:
- low, high, dry, humid = _decode_temperature_humidity_limits(data[2:7])
- except ValueError as exc:
- raise SwitchbotOperationError(
- f"{self.name}: Invalid temperature and humidity alarm response (result={data.hex()})"
- ) from exc
- # The latest confirmed protocol uses bits 5:4 for the temperature alarm
- # state and bits 1:0 for the humidity alarm state.
- status = data[7]
- temperature_status = MeterProTemperatureHumidityAlarmStatus(
- (status >> 4) & 0x03
- )
- humidity_status = MeterProTemperatureHumidityAlarmStatus(status & 0x03)
- return {
- "mode": MeterProTemperatureHumidityAlarmMode(data[1]),
- "temperature_low_c": low,
- "temperature_high_c": high,
- "humidity_low": dry,
- "humidity_high": humid,
- "temperature_status": temperature_status,
- "humidity_status": humidity_status,
- }
- async def set_temperature_humidity_alarm(
- self,
- mode: MeterProTemperatureHumidityAlarmMode,
- temperature_low_c: float | Decimal,
- temperature_high_c: float | Decimal,
- humidity_low: int,
- humidity_high: int,
- ) -> None:
- """Set both sets of local alarm limits and the enabled conditions together."""
- # Bit 7 selects comfort settings on the shared write command.
- if (
- not isinstance(mode, MeterProTemperatureHumidityAlarmMode)
- or mode.value & ~TEMPERATURE_HUMIDITY_ALARM_MASK
- ):
- raise SwitchbotOperationError(
- f"{self.name}: Invalid temperature and humidity alarm mode {mode!r}"
- )
- try:
- limits = _encode_temperature_humidity_limits(
- temperature_low_c, temperature_high_c, humidity_low, humidity_high
- )
- except (TypeError, ValueError) as exc:
- raise SwitchbotOperationError(f"{self.name}: {exc}") from exc
- low, high, dry, humid = _decode_temperature_humidity_limits(limits)
- if (
- mode & MeterProTemperatureHumidityAlarmMode.TEMPERATURE_IN_RANGE
- and low > high
- ) or (
- mode & MeterProTemperatureHumidityAlarmMode.HUMIDITY_IN_RANGE
- and dry > humid
- ):
- raise SwitchbotOperationError(
- f"{self.name}: Lower in-range alarm limits must not exceed upper limits"
- )
- result = await self._send_command(
- f"{COMMAND_SET_TEMPERATURE_HUMIDITY_LIMITS}{mode.value:02x}{limits.hex()}"
- )
- self._validate_result("set_temperature_humidity_alarm", result)
- async def get_alarm_settings(
- self,
- ) -> dict[str, MeterProAlarmMode | MeterProAlarmVolume | None]:
- """Read the local alarm mode and volume, with None for an unrecognized volume."""
- result = await self._send_command(COMMAND_GET_ALARM_SETTINGS)
- data = self._validate_result("get_alarm_settings", result, min_length=3)
- try:
- mode = MeterProAlarmMode(data[2])
- except ValueError as exc:
- raise SwitchbotOperationError(
- f"{self.name}: Unknown alarm mode {data[2]:02x}"
- ) from exc
- volume = next(
- (level for level in MeterProAlarmVolume if level.value == data[1]), None
- )
- return {"mode": mode, "volume": volume}
- async def set_alarm_settings(
- self, mode: MeterProAlarmMode, volume: MeterProAlarmVolume | None = None
- ) -> None:
- """Set the local alarm mode and optionally change the buzzer volume."""
- if not isinstance(mode, MeterProAlarmMode):
- raise SwitchbotOperationError(
- f"{self.name}: mode must be a MeterProAlarmMode"
- )
- if volume is not None and not isinstance(volume, MeterProAlarmVolume):
- raise SwitchbotOperationError(
- f"{self.name}: volume must be a MeterProAlarmVolume or None"
- )
- volume_byte = KEEP_ALARM_VOLUME if volume is None else volume.value
- result = await self._send_command(
- f"{COMMAND_SET_ALARM_SETTINGS}{volume_byte:02x}{mode.value:02x}"
- )
- self._validate_result("set_alarm_settings", result)
- async def get_calibration(self) -> dict[str, Any]:
- """Get the temperature (C) and humidity (%RH) corrections."""
- # [status][temp sign|int][hum sign|value][temp tenths]; sign bit = positive
- result = await self._send_command(COMMAND_GET_CALIBRATION)
- result = self._validate_result("get_calibration", result, min_length=4)
- tenths = result[3] & 0x0F
- humidity = result[2] & 0x7F
- if tenths > 9 or humidity > MAX_HUMIDITY_CALIBRATION:
- raise SwitchbotOperationError(
- f"{self.name}: Invalid calibration response "
- f"(result={result.hex()} rssi={self.rssi})"
- )
- temperature = round((result[1] & 0x7F) + tenths / 10, 1)
- # A zero correction comes back with the sign bit cleared.
- return {
- "temperature": temperature if result[1] & 0x80 else -temperature or 0.0,
- "humidity": humidity if result[2] & 0x80 else -humidity,
- }
- async def set_calibration(
- self, temperature: float | Decimal, humidity: int
- ) -> None:
- """Set the temperature (C, rounded half-up to tenths) and humidity corrections."""
- try:
- decimal, temperature_byte = _encode_weather_temperature(temperature)
- except (TypeError, ValueError) as exc:
- raise SwitchbotOperationError(f"{self.name}: {exc}") from exc
- if (
- isinstance(humidity, bool)
- or not isinstance(humidity, int)
- or abs(humidity) > MAX_HUMIDITY_CALIBRATION
- ):
- raise SwitchbotOperationError(
- f"{self.name}: Humidity calibration must be an integer within "
- f"±{MAX_HUMIDITY_CALIBRATION}, got {humidity!r}"
- )
- humidity_byte = abs(humidity) | (0x80 if humidity >= 0 else 0)
- payload = (
- f"{COMMAND_SET_CALIBRATION}{temperature_byte:02x}"
- f"{humidity_byte:02x}{decimal:02x}"
- )
- result = await self._send_command(payload)
- self._validate_result("set_calibration", result)
- async def get_display_settings(self) -> dict[str, Any]:
- """
- Get the zones, data update interval, date format and battery icon.
- Missing fields and unknown date or battery icon values are None.
- Each zone has "icon" (None when unset or held), "source", and "source_mac"
- (None when the zone shows this device or network data). Other unknown icon
- and source codes are returned as raw ints for inspection.
- """
- # [status][icons mid|bot][sources mid|bot][mac mid x6][mac bot x6]
- # [data update interval u16][date format][reserved][battery icon]
- result = await self._send_command(COMMAND_GET_DISPLAY_SETTINGS)
- result = self._validate_result("get_display_settings", result, min_length=15)
- def zone(icon: int, source: int, mac: bytes) -> dict[str, Any]:
- return {
- "icon": (
- next((i for i in MeterProZoneIcon if i.value == icon), icon)
- if icon not in (0, KEEP_ICON)
- else None
- ),
- "source": next(
- (s for s in MeterProDisplaySource if s.value == source), source
- ),
- "source_mac": _format_mac(mac),
- }
- return {
- "middle": zone(result[1] >> 4, result[2] >> 4, result[3:9]),
- "bottom": zone(result[1] & 0x0F, result[2] & 0x0F, result[9:15]),
- "data_update_interval": (
- int.from_bytes(result[15:17], "big") if len(result) >= 17 else None
- ),
- "date_format": (
- MeterProDateFormat(result[17])
- if len(result) >= 18 and result[17] in (0x00, 0x01)
- else None
- ),
- "battery_icon_always": (
- bool(result[19])
- if len(result) >= 20 and result[19] in (0x00, 0x01)
- else None
- ),
- }
- async def set_display_zone(
- self,
- zone: MeterProDisplayZone | int,
- source: MeterProDisplaySource | int,
- source_mac: str | None = None,
- icon: MeterProZoneIcon | int | None = None,
- ) -> None:
- """
- Choose what a screen zone shows; icon None keeps the current icon.
- The device reads the source thermometer over BLE itself. NETWORK shows
- the values written by set_weather. METER_PRO without a MAC is this
- device. The screen applies it at the next data update.
- """
- try:
- zone = _coerce_enum(MeterProDisplayZone, zone, "Display zone")
- source = _coerce_enum(MeterProDisplaySource, source, "Display source")
- if icon is not None:
- icon = _coerce_enum(MeterProZoneIcon, icon, "Zone icon")
- mac = _mac_hex(source_mac)
- except (TypeError, ValueError) as err:
- raise SwitchbotOperationError(f"{self.name}: {err}") from err
- if mac != NO_MAC and source in SOURCES_WITHOUT_MAC:
- raise SwitchbotOperationError(
- f"{self.name}: {source.name} display source takes no MAC address"
- )
- if mac == NO_MAC and source not in (
- *SOURCES_WITHOUT_MAC,
- MeterProDisplaySource.METER_PRO,
- ):
- raise SwitchbotOperationError(
- f"{self.name}: {source.name} display source needs a MAC address"
- )
- icon_byte = KEEP_ZONE_ICON if icon is None else icon.value
- payload = (
- f"{COMMAND_SET_DISPLAY_ZONE}{zone.value:02x}{icon_byte:02x}"
- f"{source.value:02x}{mac}"
- )
- result = await self._send_command(payload)
- self._validate_result("set_display_zone", result)
- async def set_zone_icons(
- self,
- middle: MeterProZoneIcon | int | None = None,
- bottom: MeterProZoneIcon | int | None = None,
- ) -> None:
- """Set the indoor/outdoor icons of both zones; None keeps an icon."""
- try:
- if middle is not None:
- middle = _coerce_enum(MeterProZoneIcon, middle, "Middle icon")
- if bottom is not None:
- bottom = _coerce_enum(MeterProZoneIcon, bottom, "Bottom icon")
- except (TypeError, ValueError) as err:
- raise SwitchbotOperationError(f"{self.name}: {err}") from err
- middle_byte = KEEP_ICON if middle is None else middle.value
- bottom_byte = KEEP_ICON if bottom is None else bottom.value
- payload = f"{COMMAND_SET_ZONE_ICONS}{middle_byte:02x}{bottom_byte:02x}"
- result = await self._send_command(payload)
- self._validate_result("set_zone_icons", result)
- async def set_data_update_interval(self, seconds: int) -> None:
- """Set the temperature and humidity update interval; the app offers 300, 600 and 1800 s."""
- if (
- isinstance(seconds, bool)
- or not isinstance(seconds, int)
- or not 1 <= seconds <= MAX_DATA_UPDATE_INTERVAL
- ):
- raise SwitchbotOperationError(
- f"{self.name}: Data update interval must be an integer from "
- f"1 to {MAX_DATA_UPDATE_INTERVAL} seconds, got {seconds!r}"
- )
- payload = COMMAND_SET_DATA_UPDATE_INTERVAL + seconds.to_bytes(2, "big").hex()
- result = await self._send_command(payload)
- self._validate_result("set_data_update_interval", result)
- async def set_date_format(self, date_format: MeterProDateFormat | int) -> None:
- """Set the date format; the app offers it from firmware 1.5."""
- try:
- date_format = _coerce_enum(MeterProDateFormat, date_format, "Date format")
- except (TypeError, ValueError) as err:
- raise SwitchbotOperationError(f"{self.name}: {err}") from err
- payload = f"{COMMAND_SET_DATE_FORMAT}{date_format.value:02x}"
- result = await self._send_command(payload)
- self._validate_result("set_date_format", result)
- async def set_battery_icon(self, always: bool) -> None:
- """Show the battery icon always, or only when the battery is low."""
- self._check_bool(always, "always")
- payload = f"{COMMAND_SET_BATTERY_ICON}{'01' if always else '00'}"
- result = await self._send_command(payload)
- self._validate_result("set_battery_icon", result)
- async def set_temperature_unit(self, fahrenheit: bool) -> None:
- """Set the default temperature unit shown on the screen (F or C)."""
- self._check_bool(fahrenheit, "fahrenheit")
- payload = f"{COMMAND_SET_TEMPERATURE_UNIT}{'01' if fahrenheit else '00'}"
- result = await self._send_command(payload)
- self._validate_result("set_temperature_unit", result)
- async def get_button_functions(self) -> dict[str, bool | None]:
- """Read button functions, with None for reserved or unknown values."""
- result = await self._send_command(COMMAND_GET_BUTTON_FUNCTIONS)
- result = self._validate_result("get_button_functions", result, min_length=3)
- # The protocol enables unit switching with 0x00 and source switching with 0x01.
- return {
- "unit_switch": result[1] == 0x00 if result[1] in (0x00, 0x01) else None,
- "source_switch": result[2] == 0x01 if result[2] in (0x00, 0x01) else None,
- }
- async def set_button_functions(
- self, unit_switch: bool | None = None, source_switch: bool | None = None
- ) -> None:
- """Allow or forbid the button actions; None keeps one as is."""
- for flag, name in (
- (unit_switch, "unit_switch"),
- (source_switch, "source_switch"),
- ):
- if flag is not None:
- self._check_bool(flag, name)
- unit_byte = (
- KEEP_BUTTON_FUNCTION
- if unit_switch is None
- else (0x00 if unit_switch else 0x01)
- )
- source_byte = (
- KEEP_BUTTON_FUNCTION
- if source_switch is None
- else (0x01 if source_switch else 0x00)
- )
- payload = f"{COMMAND_SET_BUTTON_FUNCTIONS}{unit_byte:02x}{source_byte:02x}"
- result = await self._send_command(payload)
- self._validate_result("set_button_functions", result)
- def _check_bool(self, value: object, name: str) -> None:
- if not isinstance(value, bool):
- raise SwitchbotOperationError(
- f"{self.name}: {name} must be a boolean, got {value!r}"
- )
- def _validate_result(
- self, op_name: str, result: bytes | None, min_length: int | None = None
- ) -> bytes:
- if not self._check_command_result(result, 0, {1}):
- raise SwitchbotOperationError(
- f"{self.name}: Unexpected response code for {op_name} (result={result.hex() if result else 'None'} rssi={self.rssi})"
- )
- assert result is not None
- if min_length is not None and len(result) < min_length:
- raise SwitchbotOperationError(
- f"{self.name}: Unexpected response len for {op_name}, wanted at least {min_length} (result={result.hex() if result else 'None'} rssi={self.rssi})"
- )
- return result
- def _parse_weather(self, result: bytes | None) -> tuple[MeterProWeatherIcon, bytes]:
- result = self._validate_result("get_weather", result, min_length=5)
- # Only the first five bytes are documented; firmware may append other data.
- try:
- icon = MeterProWeatherIcon(result[1])
- except ValueError as exc:
- raise SwitchbotOperationError(
- f"{self.name}: Unknown weather icon {result[1]} "
- f"(result={result.hex()} rssi={self.rssi})"
- ) from exc
- if result[2] & 0x0F > 9 or result[4] & 0x7F > 99:
- raise SwitchbotOperationError(
- f"{self.name}: Invalid weather measurements "
- f"(result={result.hex()} rssi={self.rssi})"
- )
- return icon, bytes(result[2:5])
- async def get_weather(self) -> dict[str, Any]:
- """Read network weather; unset humidity is None, temperature is independent."""
- icon, network_data = self._parse_weather(
- await self._send_command(COMMAND_GET_WEATHER)
- )
- magnitude = (network_data[1] & 0x7F) + (network_data[0] & 0x0F) / 10
- temperature = magnitude if network_data[1] & 0x80 else -magnitude
- return {
- "icon": icon,
- "temperature_c": temperature if magnitude else 0.0,
- "humidity": (network_data[2] & 0x7F) or None,
- "fahrenheit_display": bool(network_data[2] & 0x80),
- }
- async def _weather_command_locked(self, key: str, retry: int) -> bytes | None:
- command = bytearray.fromhex(self._commandkey(key))
- return await self._send_command_locked_with_retry(
- key, command, retry, retry + 1
- )
- async def set_weather(
- self,
- icon: MeterProWeatherIcon | int | None = None,
- *,
- temperature_c: float | Decimal | None = None,
- humidity: float | Decimal | None = None,
- ) -> None:
- """
- Set supplied weather fields and verify them; preserve omitted fields.
- This does not change display sources or paired external sensor data.
- Updates from other clients can race with the read/write sequence.
- """
- if icon is None and temperature_c is None and humidity is None:
- raise SwitchbotOperationError(
- f"{self.name}: Supply at least one weather field"
- )
- try:
- if icon is not None:
- icon = _coerce_enum(MeterProWeatherIcon, icon, "Weather icon")
- temperature = (
- _encode_weather_temperature(temperature_c)
- if temperature_c is not None
- else None
- )
- relative_humidity = (
- _encode_weather_humidity(humidity) if humidity is not None else None
- )
- except (ValueError, TypeError) as exc:
- raise SwitchbotOperationError(f"{self.name}: {exc}") from exc
- async with self._operation_lock:
- current_icon, network_data = self._parse_weather(
- await self._weather_command_locked(
- COMMAND_GET_WEATHER, self._retry_count
- )
- )
- icon = current_icon if icon is None else icon
- network = bytearray(network_data)
- if temperature is not None:
- network[0] = (network[0] & 0xF0) | temperature[0]
- network[1] = temperature[1]
- if relative_humidity is not None:
- network[2] = (network[2] & 0x80) | relative_humidity
- # Six-byte writes reset network readings; omit only external blocks.
- payload = f"{COMMAND_SET_WEATHER}{icon.value:02x}{network.hex()}"
- # A lost ACK can follow a successful write; do not replay stale readings.
- self._validate_result(
- "set_weather", await self._weather_command_locked(payload, 0)
- )
- updated_icon, updated_network = self._parse_weather(
- await self._weather_command_locked(
- COMMAND_GET_WEATHER, self._retry_count
- )
- )
- if updated_icon != icon or updated_network != network:
- raise SwitchbotOperationError(
- f"{self.name}: Weather readback mismatch; no rollback attempted "
- f"(expected_icon={icon.value} expected_network={network.hex()} "
- f"actual_icon={updated_icon.value} actual_network={updated_network.hex()} "
- f"rssi={self.rssi})"
- )
- class SwitchbotMeterProCO2(SwitchbotMeterPro):
- """Control the CO2 variant of the SwitchBot Meter Pro."""
- async def trigger_co2_sampling(self) -> None:
- """Request a CO2 sample and wait for the device to acknowledge the request."""
- result = await self._send_command(COMMAND_TRIGGER_CO2_SAMPLING, retry=0)
- self._validate_result("trigger_co2_sampling", result)
- async def start_co2_calibration(self) -> None:
- """
- Start manual calibration and wait for acknowledgement.
- Place the meter outdoors in a well-ventilated area for one minute first.
- Keep it still during the five-minute calibration.
- """
- result = await self._send_command(COMMAND_START_CO2_CALIBRATION, retry=0)
- self._validate_result("start_co2_calibration", result)
- async def is_usb_powered(self) -> bool:
- """Read whether USB-C power is connected."""
- result = await self._send_command(COMMAND_GET_USB_POWER_STATE)
- data = self._validate_result("is_usb_powered", result, min_length=2)
- if data[1] not in (0, 1):
- raise SwitchbotOperationError(
- f"{self.name}: Unexpected USB power state {data[1]:02x}"
- )
- return data[1] == 1
- async def get_co2_battery_update_interval(self) -> int:
- """Read the battery-powered CO2 update interval in seconds."""
- return await self._get_co2_update_interval(
- COMMAND_GET_CO2_BATTERY_UPDATE_INTERVAL, "get_co2_battery_update_interval"
- )
- async def set_co2_battery_update_interval(self, seconds: int) -> None:
- """Set the battery-powered CO2 update interval in seconds."""
- await self._set_co2_update_interval(
- COMMAND_SET_CO2_BATTERY_UPDATE_INTERVAL,
- "set_co2_battery_update_interval",
- seconds,
- )
- async def get_co2_usb_update_interval(self) -> int:
- """Read the USB-powered CO2 update interval in seconds."""
- return await self._get_co2_update_interval(
- COMMAND_GET_CO2_USB_UPDATE_INTERVAL, "get_co2_usb_update_interval"
- )
- async def set_co2_usb_update_interval(self, seconds: int) -> None:
- """Set the USB-powered CO2 update interval in seconds."""
- await self._set_co2_update_interval(
- COMMAND_SET_CO2_USB_UPDATE_INTERVAL, "set_co2_usb_update_interval", seconds
- )
- async def _get_co2_update_interval(self, command: str, operation: str) -> int:
- result = await self._send_command(command)
- data = self._validate_result(operation, result, min_length=3)
- return int.from_bytes(data[1:3], "big")
- async def _set_co2_update_interval(
- self, command: str, operation: str, seconds: int
- ) -> None:
- if (
- isinstance(seconds, bool)
- or not isinstance(seconds, int)
- or not 1 <= seconds <= 0xFFFF
- ):
- raise SwitchbotOperationError(
- f"{self.name}: CO2 update interval must be an integer from 1 to 65535 seconds"
- )
- result = await self._send_command(command + seconds.to_bytes(2, "big").hex())
- self._validate_result(operation, result)
- async def get_co2_alarm(
- self,
- ) -> dict[str, MeterProCO2AlarmMode | MeterProCO2AlarmStatus | int]:
- """Read CO2 alarm conditions, limits in ppm, and current alarm status."""
- result = await self._send_command(COMMAND_GET_CO2_ALARM)
- data = self._validate_result("get_co2_alarm", result, min_length=7)
- return {
- "mode": MeterProCO2AlarmMode(data[1]),
- "high_ppm": int.from_bytes(data[2:4], "big"),
- "low_ppm": int.from_bytes(data[4:6], "big"),
- "status": MeterProCO2AlarmStatus(data[6] & 0x03),
- }
- async def set_co2_alarm(
- self, mode: MeterProCO2AlarmMode, low_ppm: int, high_ppm: int
- ) -> None:
- """
- Set CO2 alarm conditions and limits in ppm.
- Pass the existing limits when disabling an alarm to keep them configured.
- """
- if not isinstance(mode, MeterProCO2AlarmMode) or mode.value & ~0x0F:
- raise SwitchbotOperationError(
- f"{self.name}: Invalid CO2 alarm mode {mode!r}"
- )
- if any(
- isinstance(limit, bool)
- or not isinstance(limit, int)
- or not 0 <= limit <= 0xFFFF
- for limit in (low_ppm, high_ppm)
- ):
- raise SwitchbotOperationError(
- f"{self.name}: CO2 alarm limits must be unsigned 16-bit integers"
- )
- if low_ppm > high_ppm:
- raise SwitchbotOperationError(
- f"{self.name}: Lower CO2 alarm limit must not exceed the upper limit"
- )
- payload = (
- bytes((mode.value,))
- + high_ppm.to_bytes(2, "big")
- + low_ppm.to_bytes(2, "big")
- )
- result = await self._send_command(COMMAND_SET_CO2_ALARM + payload.hex())
- self._validate_result("set_co2_alarm", result)
- async def get_co2_level_thresholds(self) -> tuple[int, int]:
- """Read the green-to-yellow and yellow-to-red CO2 thresholds in ppm."""
- result = await self._send_command(COMMAND_GET_CO2_LEVEL_THRESHOLDS)
- data = self._validate_result("get_co2_level_thresholds", result, min_length=5)
- return int.from_bytes(data[1:3], "big"), int.from_bytes(data[3:5], "big")
- async def set_co2_level_thresholds(
- self, green_to_yellow_ppm: int, yellow_to_red_ppm: int
- ) -> None:
- """Set the green-to-yellow and yellow-to-red CO2 thresholds in 100 ppm steps."""
- if any(
- isinstance(threshold, bool)
- or not isinstance(threshold, int)
- or not 0 <= threshold <= 0xFFFF
- or threshold % 100
- for threshold in (green_to_yellow_ppm, yellow_to_red_ppm)
- ):
- raise SwitchbotOperationError(
- f"{self.name}: CO2 level thresholds must be unsigned 16-bit integers in 100 ppm steps"
- )
- if green_to_yellow_ppm >= yellow_to_red_ppm:
- raise SwitchbotOperationError(
- f"{self.name}: The green-to-yellow CO2 threshold must be below the yellow-to-red threshold"
- )
- payload = (
- COMMAND_SET_CO2_LEVEL_THRESHOLDS
- + (
- green_to_yellow_ppm.to_bytes(2, "big")
- + yellow_to_red_ppm.to_bytes(2, "big")
- ).hex()
- )
- result = await self._send_command(payload)
- self._validate_result("set_co2_level_thresholds", result)
|