Discovery API Reference

Discovery classes provide device discovery implementations for common protocols.

DiscoveredDevice

ucapi_framework.discovery.DiscoveredDevice dataclass

DiscoveredDevice(identifier: str, name: str, address: str, extra_data: dict[str, Any] | None = None)

Common structure for discovered devices.

All discovery implementations should return this format.

Attributes

identifier instance-attribute

identifier: str

Unique identifier for the device (e.g., MAC address, serial number)

name instance-attribute

name: str

Human-readable device name

address instance-attribute

address: str

Device address (IP address, Bluetooth address, etc.)

extra_data class-attribute instance-attribute

extra_data: dict[str, Any] | None = None

Optional additional data specific to the discovery method

BaseDiscovery

ucapi_framework.discovery.BaseDiscovery

BaseDiscovery(timeout: int = 5)

Bases: ABC

Base class for device discovery.

Provides a common interface for different discovery methods: - SSDP - mDNS/Bonjour - Bluetooth LE - Cloud API - Network scanning

Initialize discovery.

:param timeout: Discovery timeout in seconds

Attributes

devices property

devices: list[DiscoveredDevice]

Get the list of discovered devices from the last discovery run.

This property provides access to devices found by the most recent call to discover(). Useful when implementing create_device_from_discovery() in setup flows.

:return: List of discovered devices

Functions

discover abstractmethod async

discover() -> list[DiscoveredDevice]

Perform device discovery.

:return: List of discovered devices

clear

clear() -> None

Clear the list of discovered devices.

SSDPDiscovery

ucapi_framework.discovery.SSDPDiscovery

SSDPDiscovery(search_target: str = 'ssdp:all', timeout: int = 5, device_filter: Callable | None = None)

Bases: BaseDiscovery

SSDP-based device discovery.

Uses Simple Service Discovery Protocol to find devices on the local network. Good for: UPnP devices, media renderers, smart TVs

Initialize SSDP discovery.

:param search_target: SSDP search target (e.g., "ssdp:all", "urn:schemas-upnp-org:device:MediaRenderer:1") :param timeout: Discovery timeout in seconds :param device_filter: Optional filter function to filter discovered devices

Functions

discover async

discover() -> list[DiscoveredDevice]

Perform SSDP discovery.

:return: List of discovered devices

parse_ssdp_device abstractmethod

parse_ssdp_device(raw_device: dict) -> DiscoveredDevice | None

Parse raw SSDP device data into DiscoveredDevice.

Override this method to extract device information from SSDP response.

:param raw_device: Raw SSDP device data :return: DiscoveredDevice or None if parsing fails

SDDPDiscovery

ucapi_framework.discovery.SDDPDiscovery

SDDPDiscovery(search_pattern: str = '*', timeout: int = 5, multicast_address: str | None = None, multicast_port: int | None = None, bind_addresses: list[str] | None = None, include_loopback: bool = False)

Bases: BaseDiscovery

SDDP-based device discovery.

Uses Simple Device Discovery Protocol (similar to SSDP but with different format). Good for: Samsung TVs and other devices using SDDP protocol

Initialize SDDP discovery.

:param search_pattern: SDDP search pattern (default: "*" for all devices) :param timeout: Discovery timeout in seconds :param multicast_address: SDDP multicast address (uses default if None) :param multicast_port: SDDP multicast port (uses default if None) :param bind_addresses: Optional list of specific addresses to bind to :param include_loopback: Whether to include loopback interface

Functions

discover async

discover() -> list[DiscoveredDevice]

Perform SDDP discovery.

:return: List of discovered devices

parse_sddp_response abstractmethod

parse_sddp_response(datagram: Any, response_info: Any) -> DiscoveredDevice | None

Parse SDDP response into DiscoveredDevice.

Override this method to extract device information from SDDP response. The datagram contains device information in its headers (hdr_from, hdr_type, etc.).

Example implementation

def parse_sddp_response(self, datagram, response_info): return DiscoveredDevice( identifier=datagram.hdr_type, # or other unique field name=datagram.hdr_type, address=datagram.hdr_from[0], # IP address extra_data={ "type": datagram.hdr_type, "datagram": datagram, } )

:param datagram: SDDP datagram with headers (hdr_from, hdr_type, etc.) :param response_info: Full response info object from SDDP client :return: DiscoveredDevice or None if parsing fails

MDNSDiscovery

ucapi_framework.discovery.MDNSDiscovery

MDNSDiscovery(service_type: str, timeout: int = 5)

Bases: BaseDiscovery

mDNS/Bonjour-based device discovery.

Uses multicast DNS to discover devices advertising services. Good for: Apple devices, HomeKit, Chromecast, many IoT devices

Initialize mDNS discovery.

:param service_type: mDNS service type (e.g., "_airplay._tcp.local.", "_googlecast._tcp.local.") :param timeout: Discovery timeout in seconds

Functions

discover async

discover() -> list[DiscoveredDevice]

Perform mDNS discovery.

:return: List of discovered devices

parse_mdns_service abstractmethod

parse_mdns_service(service_info: Any) -> DiscoveredDevice | None

Parse mDNS service info into DiscoveredDevice.

Override this method to extract device information from mDNS service.

:param service_info: mDNS service info object :return: DiscoveredDevice or None if parsing fails

NetworkScanDiscovery

ucapi_framework.discovery.NetworkScanDiscovery

NetworkScanDiscovery(ip_range: str, ports: list[int], timeout: int = 5)

Bases: BaseDiscovery

Network scanning-based device discovery.

Scans IP range for devices responding on specific ports. Good for: Devices without standard discovery protocols

Initialize network scan discovery.

:param ip_range: IP range to scan (e.g., "192.168.1.0/24") :param ports: List of ports to check :param timeout: Discovery timeout in seconds

Functions

discover async

discover() -> list[DiscoveredDevice]

Perform network scan discovery.

:return: List of discovered devices

probe_device abstractmethod async

probe_device(ip: str, port: int) -> DiscoveredDevice | None

Probe a specific IP:port for device information.

Override this method to implement device probing logic.

:param ip: IP address to probe :param port: Port to probe :return: DiscoveredDevice or None if not a valid device