# SmartThings Hub v2 — Device Specification
# Copyright 2026 Pigs Can Fly Labs LLC
# SPDX-License-Identifier: Apache-2.0

device:
  name: "SmartThings Hub v2"
  manufacturer: "Samsung SmartThings"
  manufacturer_status: "active"
  protocol: "wifi"
  transport: "websocket"
  notes: >
    SmartThings Hub v2 advertises local SmartThings, Edge driver, and Matter
    bridge services via mDNS. The primary identity is the _smartthings._tcp TXT
    id value. _smartthings-hedge._tcp on port 8766 exposes Edge driver control
    features, and _matter._tcp advertises the Matter bridge endpoint.
  identification:
    mdns_service_type: "_smartthings._tcp.local."
    default_port: 8081
    identity_keys:
      primary: "hub_id"
      display: "name"

  discovery:
    methods:
      - type: "mdns"
        mdns:
          service_type: "_smartthings._tcp.local."
          port: 8081
          txt_record_keys: ["id", "type", "path"]
          identity_mapping:
            stable_keys:
              - source: "txt:id"
                key: "hub_id"
            display:
              source: "name"
      - type: "mdns"
        mdns:
          service_type: "_smartthings-hedge._tcp.local."
          port: 8766
          identity_mapping:
            stable_keys:
              - source: "txt:id"
                key: "hub_id"
            display:
              source: "name"
    identity:
      stable_keys: ["hub_id"]
      display: "name"
    static_ip_required: false

  setup:
    required: true
    confidence: "low"
    notes: >
      The hub is Ethernet-only and its onboarding is entirely cloud-mediated:
      the welcome code printed on the underside is redeemed against Samsung's
      service, and the hub receives its identity and driver set from there.
      Local Edge drivers run on the hub afterwards, but there is no documented
      way to claim an unclaimed hub without the cloud, which is the key risk if
      the service is retired.
    methods:
      - type: "wired"
        verified: false
        description: "Ethernet to the router; the hub takes a DHCP lease and advertises _smartthings._tcp.local."
        steps:
          - action: "Connect Ethernet, insert the batteries if fitted, and apply power."
            actor: "user"
            expect: "Status LED settles to solid green once the hub reaches the service."
            timeout_seconds: 300
      - type: "cloud_account"
        verified: false
        description: "The welcome code on the hub is redeemed in the vendor app, which binds the hub to a Samsung account and provisions its drivers."
        cloud:
          provider: "Samsung SmartThings"
          local_alternative: >
            None known. Edge drivers execute locally once installed, but the
            claim step and driver distribution both require the cloud.
        steps:
          - action: "Redeem the welcome code printed on the underside of the hub in the vendor app."
            actor: "user"
    factory_reset:
      confidence: "low"
      effect: "Unclaims the hub and clears its ZigBee/Z-Wave networks; every paired radio device must be re-joined afterwards."
      procedures:
        - name: "Reset button held while powering on"
          hold_seconds: 30
          indicator: "Status LED turns yellow and flashes."
          steps:
            - action: "Remove power and batteries."
              actor: "user"
            - action: "Hold the recessed reset button on the back while restoring power, and keep holding until the LED flashes yellow."
              actor: "user"
              notes: "Vendor-documented; verify before use — this drops every paired ZigBee and Z-Wave device."
    rejoin:
      in_place_supported: true
      requires_factory_reset: false
      notes: "Moving the hub to a different router is a cable move; the cloud claim is unaffected."
    credentials:
      wifi_passphrase_protection: "not_applicable"
      stored_on_device:
        - "Account binding token"
        - "ZigBee and Z-Wave network keys"
      issued_to_client: []

smartthings_local_protocol:
  primary_service:
    service_type: "_smartthings._tcp.local."
    port: 8081
  edge_driver_service:
    service_type: "_smartthings-hedge._tcp.local."
    port: 8766
    transport: "WebSocket"
    txt:
      feat: "ctrl"
  matter_bridge:
    service_type: "_matter._tcp.local."
    port: 49722
    txt:
      T: 6

evidence:
  live_lan_probe:
    date: "2026-07-16"
    address: "10.69.199.162"
    hostname: "hubv2-0d052a8a662bc0001.local"
    mdns_services:
      - service_type: "_smartthings._tcp"
        port: 8081
        type: "hubv2"
        id: "D052A8A662BC0001"
      - service_type: "_smartthings-hedge._tcp"
        port: 8766
        feat: "ctrl"
      - service_type: "_matter._tcp"
        port: 49722
        T: 6

http_endpoints:
  - method: "GET"
    path: "/"
    name: "SmartThings Local Service Root"
    description: "Primary _smartthings._tcp service endpoint on port 8081. Edge control is advertised separately on the hedge WebSocket service."

entities:
  - platform: "sensor"
    name: "Hub Status"
    state_topic: "smartthings://{hub_id}"
  - platform: "binary_sensor"
    name: "Matter Bridge"
    state_topic: "matter://{hub_id}"