feat: Add support for IOTBT segment-based devices with new commands and effects

Helps: Zengge IOTBT65C "unavailable"
Fixes #69

Author: 8none1

custom_components/lednetwf_ble/const.py

@@ -92,6 +92,7 @@ class EffectType(IntEnum):
     SYMPHONY = 2            # 0x38 command WITH checksum (5 bytes)
     ADDRESSABLE_0x53 = 3    # 0x38 command NO checksum (4 bytes), brightness in byte 3
     IOTBT = 4               # 0xE0 0x02 command, effects 1-12 (Telink BLE Mesh based)
+    IOTBT_SEGMENT = 5       # 0xE1 0x01 command, segment-based with palette (newer IOTBT)
 
 
 class ValueScale(IntEnum):
@@ -397,6 +398,14 @@ class ValueScale(IntEnum):
     0xD00: "Music 13",  # 13 << 8
 }
 
+# IOTBT Segment-based effects (0xE1 0x01 command)
+# Source: User protocol capture (Dec 2025) - IOTBT devices with addressable segments
+# These devices use 0xE1 0x03 for color, 0xE1 0x01 for effects, 0x3B for power
+# Effects are numbered 1-99 (similar to addressable strip effects)
+IOTBT_SEGMENT_EFFECTS: Final = {
+    i: f"Effect {i}" for i in range(1, 100)
+}
+
 # Product IDs with special speed encoding (inverted 0x01-0x1F scale)
 # Source: model_0x54.py, protocol_docs/07a_effect_commands_by_device.md
 # These devices use inverted speed where 0x01=fastest, 0x1F=slowest
@@ -644,6 +653,9 @@ def get_effect_list(
         # Plus 8 music reactive effects via 0xE1 0x05 command
         effects = list(IOTBT_EFFECTS.values())
         effects.extend(list(IOTBT_MUSIC_EFFECTS.values()))
+    elif effect_type == EffectType.IOTBT_SEGMENT:
+        # IOTBT Segment-based devices have 99 effects via 0xE1 0x01 command
+        effects = list(IOTBT_SEGMENT_EFFECTS.values())
 
     # Add sound reactive option for devices with built-in microphone (non-IOTBT)
     # IOTBT devices have specific music effects listed above instead
@@ -744,6 +756,11 @@ def get_effect_id(
         for eid, name in IOTBT_MUSIC_EFFECTS.items():
             if name == effect_name:
                 return eid  # Already encoded (e.g., 0x100 for Music 1)
+    elif effect_type == EffectType.IOTBT_SEGMENT:
+        # Segment-based effects (1-99) via 0xE1 0x01 command
+        for eid, name in IOTBT_SEGMENT_EFFECTS.items():
+            if name == effect_name:
+                return eid
     return None
 
 

custom_components/lednetwf_ble/device.py

@@ -109,6 +109,13 @@ def __init__(
         self._firmware_ver: int | None = None  # Combined firmware version (hi << 8 | lo)
         self._firmware_flag: int | None = None  # Feature flags from service data (bits 0-4)
 
+        # IOTBT segment variant detection
+        # Segment-based IOTBT devices use 0x5A00 service UUID and require different commands:
+        # - Power: 0x3B (standard LEDnetWF, not 0x71 Telink)
+        # - Color: 0xE1 0x03 (segment-based HSB, not 0xE2 hue)
+        # - Effects: 0xE1 0x01 (palette-based, not 0xE0 0x02)
+        self._is_iotbt_segment: bool = False
+
         # Callbacks for state updates
         self._callbacks: list[Callable[[], None]] = []
 
@@ -221,6 +228,10 @@ def effect_speed(self) -> int:
     @property
     def effect_type(self) -> EffectType:
         """Return the effect type as proper enum (handles int conversion)."""
+        # IOTBT segment-based variant uses different effect commands
+        if self._is_iotbt_segment:
+            return EffectType.IOTBT_SEGMENT
+
         val = self._capabilities.get("effect_type", EffectType.NONE)
         return EffectType(val) if isinstance(val, int) else val
 
@@ -443,6 +454,21 @@ def is_iotbt(self) -> bool:
         # Also check product_id directly for backwards compatibility
         return self._capabilities.get("is_iotbt", False) or self._product_id == 0x00
 
+    @property
+    def is_iotbt_segment(self) -> bool:
+        """Return True if device is an IOTBT segment-based variant.
+
+        Segment-based IOTBT devices (detected by 0x5A00 service UUID) use
+        different commands than standard Telink-based IOTBT:
+        - Power: 0x3B command (standard LEDnetWF, NOT 0x71 Telink)
+        - Color: 0xE1 0x03 command with segment-based HSB (NOT 0xE2)
+        - Effect: 0xE1 0x01 command with palette (NOT 0xE0 0x02)
+        - State query: Still uses 0xEA 0x81 format
+
+        Source: User protocol capture (Dec 2025) - IOTBT65C device
+        """
+        return self._is_iotbt_segment
+
     @property
     def color_order(self) -> int | None:
         """Return current color order (1=RGB, 2=GRB, 3=BRG)."""
@@ -1190,6 +1216,10 @@ def _effect_id_to_name(self, effect_id: int) -> str | None:
             elif effect_id in IOTBT_MUSIC_EFFECTS:
                 return IOTBT_MUSIC_EFFECTS[effect_id]
             return None
+        elif eff_type == EffectType.IOTBT_SEGMENT:
+            # IOTBT segment-based variant: 99 effects (1-99)
+            from .const import IOTBT_SEGMENT_EFFECTS
+            return IOTBT_SEGMENT_EFFECTS.get(effect_id)
         return None
 
     async def _send_command(self, packet: bytearray, with_response: bool = False) -> bool:
@@ -1226,8 +1256,11 @@ async def _send_command(self, packet: bytearray, with_response: bool = False) ->
 
     async def turn_on(self) -> bool:
         """Turn on the device."""
-        if self.is_iotbt:
-            # IOTBT devices use different power command format
+        if self.is_iotbt_segment:
+            # IOTBT segment-based variant uses standard 0x3B power command
+            packet = protocol.build_power_command_0x3B(turn_on=True)
+        elif self.is_iotbt:
+            # Standard IOTBT devices use 0x71 power command format
             packet = protocol.build_iotbt_power_command(turn_on=True)
         else:
             packet = protocol.build_power_command_0x3B(turn_on=True)
@@ -1239,8 +1272,11 @@ async def turn_on(self) -> bool:
 
     async def turn_off(self) -> bool:
         """Turn off the device."""
-        if self.is_iotbt:
-            # IOTBT devices use different power command format
+        if self.is_iotbt_segment:
+            # IOTBT segment-based variant uses standard 0x3B power command
+            packet = protocol.build_power_command_0x3B(turn_on=False)
+        elif self.is_iotbt:
+            # Standard IOTBT devices use 0x71 power command format
             packet = protocol.build_iotbt_power_command(turn_on=False)
         else:
             packet = protocol.build_power_command_0x3B(turn_on=False)
@@ -1322,8 +1358,19 @@ async def set_rgb_color(self, rgb: tuple[int, int, int], brightness: int = 255)
 
         # Standard color command (exits effect mode)
         eff_type = self.effect_type
-        if self.is_iotbt:
-            # IOTBT devices use 0xE2 command with hue-based color (not RGB)
+        if self.is_iotbt_segment:
+            # IOTBT segment-based variant uses 0xE1 0x03 command with segment HSB data
+            # Source: User protocol capture (Dec 2025) - IOTBT65C device
+            brightness_pct = max(1, round(brightness * 100 / 255)) if brightness > 0 else 0
+            packet = protocol.build_iotbt_segment_color_command(
+                rgb[0], rgb[1], rgb[2], brightness_pct
+            )
+            _LOGGER.debug(
+                "IOTBT segment device: RGB=(%d,%d,%d), brightness=%d%% -> segment HSB",
+                rgb[0], rgb[1], rgb[2], brightness_pct
+            )
+        elif self.is_iotbt:
+            # Standard IOTBT devices use 0xE2 command with hue-based color (not RGB)
             # Source: protocol_docs/17_device_configuration.md - Color Command (0xE2)
             brightness_pct = max(1, round(brightness * 100 / 255)) if brightness > 0 else 0
             packet = protocol.build_iotbt_color_command(
@@ -1977,6 +2024,19 @@ def update_from_advertisement(
                 "[%s] Service data UUIDs available: %s",
                 self._name, list(service_data.keys())
             )
+
+            # Detect IOTBT segment-based variant
+            # Standard IOTBT: status byte 0x80 → Telink protocol (default)
+            # Segment variant: status byte 0x56 → segment-based protocol
+            if self.is_iotbt and protocol.is_iotbt_segment_variant(service_data):
+                if not self._is_iotbt_segment:
+                    self._is_iotbt_segment = True
+                    _LOGGER.info(
+                        "[%s] IOTBT segment-based variant detected (status=0x56). "
+                        "Using 0x3B power, 0xE1 0x03 color, 0xE1 0x01 effects.",
+                        self._name
+                    )
+
             sd_bytes = protocol.get_service_data_from_advertisement(service_data)
             if sd_bytes:
                 _LOGGER.debug(

custom_components/lednetwf_ble/protocol.py

@@ -385,6 +385,122 @@ def build_iotbt_state_query() -> bytearray:
     return wrap_command(raw_cmd, cmd_family=0x0a)
 
 
+# =============================================================================
+# IOTBT SEGMENT-BASED COMMANDS (IOTBT devices with addressable segments)
+# These devices use 0xE1 0x03 for color (not 0xE2) and 0x3B for power (not 0x71)
+# =============================================================================
+
+def build_iotbt_segment_color_command(
+    r: int, g: int, b: int, brightness: int = 100, segment_count: int = 20
+) -> bytearray:
+    """
+    Build IOTBT segment-based color command (0xE1 0x03 format).
+
+    Source: User protocol capture (Dec 2025) - IOTBT devices with addressable segments.
+
+    Format: [0xE1, 0x03, 0x00, segment_count, 0x00, 0x00, segment_count, ...segment_data...]
+
+    Each segment (4 bytes): [0xA1, hue, saturation, brightness]
+    - 0xA1: Segment marker
+    - hue: 0-255 (0=red, 85=green, 170=blue, wrapping)
+    - saturation: 0-100 (0=white, 100=full color)
+    - brightness: 0-100 (0=off, 100=full)
+
+    This sets all segments to the same color. For individual segment control,
+    the segment_data would contain different values per segment.
+
+    Args:
+        r, g, b: RGB color values (0-255)
+        brightness: Overall brightness percentage (0-100)
+        segment_count: Number of segments (default 20)
+
+    Returns:
+        Wrapped command packet
+    """
+    # Convert RGB to HSV
+    h, s, v = rgb_to_hsv(r, g, b)
+
+    # Convert hue from 0-360 to 0-255 scale (device uses 256-step hue)
+    # 0=red, ~85=green, ~170=blue
+    hue_255 = int(h * 255 / 360) & 0xFF
+
+    # Saturation stays 0-100
+    sat = max(0, min(100, s))
+
+    # Combine brightness from both sources
+    # RGB value gives us "color intensity", brightness param is overall
+    combined_bright = max(1, min(100, int(brightness * v / 100)))
+
+    # Build header: E1 03 00 {segment_count} 00 00 {segment_count}
+    raw_cmd = bytearray([
+        0xE1, 0x03,
+        0x00,                       # Unknown/reserved
+        segment_count & 0xFF,       # Segment count (first occurrence)
+        0x00, 0x00,                 # Reserved
+        segment_count & 0xFF,       # Segment count (repeated)
+    ])
+
+    # Add segment data - all segments get same color
+    for _ in range(segment_count):
+        raw_cmd.extend([
+            0xA1,                    # Segment marker
+            hue_255 & 0xFF,          # Hue (0-255)
+            sat & 0xFF,              # Saturation (0-100)
+            combined_bright & 0xFF   # Brightness (0-100)
+        ])
+
+    # No checksum for this command format
+    return wrap_command(raw_cmd, cmd_family=0x0a)
+
+
+def build_iotbt_segment_effect_command(
+    effect_id: int, speed: int = 50, brightness: int = 100, segment_count: int = 20
+) -> bytearray:
+    """
+    Build IOTBT segment-based effect command (0xE1 0x01 format).
+
+    Source: User protocol capture (Dec 2025) - IOTBT segment-based effects.
+
+    Format: [0xE1, 0x01, effect_id, speed, brightness, 0x00, ...palette_data...]
+
+    The palette data contains color entries for the effect. For simplicity,
+    we use a rainbow palette (7 colors) which works for most effects.
+
+    Args:
+        effect_id: Effect number (1-99)
+        speed: Effect speed (0-100)
+        brightness: Effect brightness (0-100)
+        segment_count: Number of segments
+
+    Returns:
+        Wrapped command packet
+    """
+    effect_id = max(1, min(99, effect_id))
+    speed = max(0, min(100, speed))
+    brightness = max(1, min(100, brightness))
+
+    # Build header
+    raw_cmd = bytearray([
+        0xE1, 0x01,
+        effect_id & 0xFF,
+        speed & 0xFF,
+        brightness & 0xFF,
+        0x00,  # Reserved
+    ])
+
+    # Add rainbow palette (7 colors, similar to user's capture)
+    # Format: [0xA1, hue, saturation, brightness] per color
+    # Rainbow hues at roughly: 0, 43, 85, 128, 170, 213, 255 (wrapping)
+    rainbow_hues = [0, 43, 85, 128, 170, 213, 240]
+    for hue in rainbow_hues:
+        raw_cmd.extend([0xA1, hue, 100, brightness])
+
+    # Pad remaining palette slots if needed (usually 7 is enough)
+
+    # No checksum for this command format
+    return wrap_command(raw_cmd, cmd_family=0x0a)
+
+
 # =============================================================================
 # COLOR COMMANDS
 # =============================================================================
@@ -864,8 +980,12 @@ def build_effect_command(
         - Music effects (encoded as effect_num << 8): 0xE1 0x05 command format
           Speed parameter is used as mic sensitivity for music mode
     """
-    if effect_type == EffectType.IOTBT:
-        # IOTBT devices use different commands for regular effects vs music effects
+    if effect_type == EffectType.IOTBT_SEGMENT:
+        # IOTBT segment-based variant uses 0xE1 0x01 command with palette
+        # Source: User protocol capture (Dec 2025) - IOTBT65C device
+        return build_iotbt_segment_effect_command(effect_id, speed, brightness)
+    elif effect_type == EffectType.IOTBT:
+        # Standard IOTBT devices use different commands for regular effects vs music effects
         if effect_id >= 0x100:
             # Music reactive effect (encoded as effect_num << 8)
             # Decode the effect ID and use music command
@@ -2130,3 +2250,40 @@ def get_service_data_from_advertisement(
             return service_data_dict[key]
 
     return None
+
+
+def is_iotbt_segment_variant(service_data_dict: dict[str, bytes]) -> bool:
+    """
+    Check if device is an IOTBT segment-based variant.
+
+    Segment-based IOTBT devices are identified by:
+    - Service UUID 0x5A00 (ZengGe manufacturer-specific)
+    - Status byte (byte 0) is 0x56
+
+    Standard IOTBT devices (status byte 0x80) use Telink mesh protocol.
+    Unknown status bytes default to standard Telink protocol for safety.
+
+    Segment-based variants (status 0x56) use different commands:
+    - Power: 0x3B (standard LEDnetWF, not 0x71 Telink)
+    - Color: 0xE1 0x03 (segment-based HSB, not 0xE2 hue)
+    - Effects: 0xE1 0x01 (palette-based, not 0xE0 0x02)
+
+    Args:
+        service_data_dict: Dict from BluetoothServiceInfoBleak.service_data
+
+    Returns:
+        True if segment-based IOTBT variant (status 0x56), False otherwise
+    """
+    uuid_5a00 = "00005a00-0000-1000-8000-00805f9b34fb"
+    if uuid_5a00 not in service_data_dict:
+        return False
+
+    data = service_data_dict[uuid_5a00]
+    if len(data) < 1:
+        return False
+
+    # Status byte 0x80 = standard IOTBT (Telink mesh protocol) - DEFAULT
+    # Status byte 0x56 = segment-based variant
+    # Unknown values default to standard Telink for safety
+    status_byte = data[0] & 0xFF
+    return status_byte == 0x56