Add wifi_mac_to_bluetooth_mac() helper for ESP32 MAC address conversion (#1392)

Author: bdraco

aioesphomeapi/__init__.py

@@ -22,6 +22,7 @@
     EncryptionHelloAPIError,
     SocketAPIError,
     BadMACAddressAPIError,
+    wifi_mac_to_bluetooth_mac,
 )
 from .model import *
 from .reconnect_logic import ReconnectLogic

aioesphomeapi/core.py

@@ -304,6 +304,45 @@ def to_human_readable_address(address: int) -> str:
     return ":".join(TWO_CHAR.findall(f"{address:012X}"))
 
 
+def wifi_mac_to_bluetooth_mac(wifi_mac: str) -> str:
+    """Convert a WiFi MAC address to a Bluetooth MAC address.
+
+    ESP32 devices use a single base MAC address and derive other interface
+    MAC addresses from it. The Bluetooth MAC is calculated as base_mac + 2
+    to the last octet.
+
+    Args:
+        wifi_mac: WiFi MAC address in format "AABBCCDDEEFF" or "aa:bb:cc:dd:ee:ff"
+
+    Returns:
+        Bluetooth MAC address in uppercase with colons (e.g., "AA:BB:CC:DD:EE:01")
+
+    Examples:
+        >>> wifi_mac_to_bluetooth_mac("AABBCCDDEEFF")
+        "AA:BB:CC:DD:EE:01"
+        >>> wifi_mac_to_bluetooth_mac("aa:bb:cc:dd:ee:ff")
+        "AA:BB:CC:DD:EE:01"
+        >>> wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:FE")
+        "AA:BB:CC:DD:EE:00"
+    """
+    # Remove colons and convert to uppercase
+    clean_mac = wifi_mac.replace(":", "").upper()
+
+    # Validate MAC address format
+    if len(clean_mac) != 12 or not all(c in "0123456789ABCDEF" for c in clean_mac):
+        raise ValueError(f"Invalid MAC address format: {wifi_mac}")
+
+    # Extract the last octet and add 2
+    last_octet = int(clean_mac[-2:], 16)
+    new_last_octet = (last_octet + 2) % 256
+
+    # Build the new MAC address
+    bt_mac = clean_mac[:-2] + f"{new_last_octet:02X}"
+
+    # Always return with colons
+    return ":".join(TWO_CHAR.findall(bt_mac))
+
+
 def to_human_readable_gatt_error(error: int) -> str:
     """Convert a GATT error to a human readable format."""
     return ESPHOME_GATT_ERRORS.get(error, "Unknown error")

tests/test_core.py

@@ -1,9 +1,53 @@
 from __future__ import annotations
 
-from aioesphomeapi.core import MESSAGE_TYPE_TO_PROTO
+import pytest
+
+from aioesphomeapi.core import MESSAGE_TYPE_TO_PROTO, wifi_mac_to_bluetooth_mac
 
 
 def test_order_and_no_missing_numbers_in_message_type_to_proto():
     """Test that MESSAGE_TYPE_TO_PROTO has no missing numbers."""
     for idx, (k, v) in enumerate(MESSAGE_TYPE_TO_PROTO.items()):
         assert idx + 1 == k
+
+
+def test_wifi_mac_to_bluetooth_mac():
+    """Test converting WiFi MAC address to Bluetooth MAC address."""
+    # Test with uppercase MAC without colons
+    assert wifi_mac_to_bluetooth_mac("AABBCCDDEEFF") == "AA:BB:CC:DD:EE:01"
+
+    # Test with lowercase MAC with colons
+    assert wifi_mac_to_bluetooth_mac("aa:bb:cc:dd:ee:ff") == "AA:BB:CC:DD:EE:01"
+
+    # Test with uppercase MAC with colons
+    assert wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:FF") == "AA:BB:CC:DD:EE:01"
+
+    # Test with mixed case
+    assert wifi_mac_to_bluetooth_mac("Aa:Bb:Cc:Dd:Ee:Ff") == "AA:BB:CC:DD:EE:01"
+
+    # Test rollover (FE + 2 = 00, wraps around)
+    assert wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:FE") == "AA:BB:CC:DD:EE:00"
+
+    # Test edge case with FF (FF + 2 = 01, wraps around)
+    assert wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:FF") == "AA:BB:CC:DD:EE:01"
+
+    # Test with 00
+    assert wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:00") == "AA:BB:CC:DD:EE:02"
+
+    # Test with FD (FD + 2 = FF)
+    assert wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE:FD") == "AA:BB:CC:DD:EE:FF"
+
+
+def test_wifi_mac_to_bluetooth_mac_invalid():
+    """Test wifi_mac_to_bluetooth_mac with invalid inputs."""
+    # Test with invalid length
+    with pytest.raises(ValueError, match="Invalid MAC address format"):
+        wifi_mac_to_bluetooth_mac("AA:BB:CC:DD:EE")
+
+    # Test with invalid characters
+    with pytest.raises(ValueError, match="Invalid MAC address format"):
+        wifi_mac_to_bluetooth_mac("GG:BB:CC:DD:EE:FF")
+
+    # Test with completely invalid input
+    with pytest.raises(ValueError, match="Invalid MAC address format"):
+        wifi_mac_to_bluetooth_mac("not a mac address")