wac-discovery
0.2.2indexedDiscovers smart TVs, speakers, routers and IoT devices via SSDP and mDNS concurrently, deduplicates results, resolves UPnP metadata, with preset and custom filtering.
0
Stars
—
Used by
dependents
—
Health
/ 100
📡 WAC Discovery
Kotlin Multiplatform library for network device discovery
Discover smart TVs, speakers, routers, and IoT devices on your local network
using SSDP and mDNS — from a single, unified API.
Table of Contents
🚀 Quick Start
Discover all devices on your local network in 3 lines:
val discovery = NetworkDiscovery()
discovery.discover().collect { device ->
println("${device.name} — ${device.address}:${device.port}")
}
discovery.close()
That's it. The library scans via both SSDP (UPnP) and mDNS simultaneously, deduplicates results, and emits them as a Kotlin Flow.
📥 Installation
Maven Central
// build.gradle.kts (your KMP module)
kotlin {
sourceSets {
commonMain.dependencies {
implementation("io.github.waclabs:wac-discovery:0.2.2")
}
}
}
Note: The library is published to Maven Central — no extra repository configuration needed. All platforms (Android, iOS, JVM) are available as auto-resolved KMP artifacts.
📱 Supported Platforms
🧩 Core Concepts
NetworkDiscovery
The main entry point. Call discover() to get a Flow<DiscoveredDevice> and close() when done.
DiscoveredDevice
Every discovered device is represented as:
data class DiscoveredDevice(
val name: String, // e.g. "Samsung-Linux/4.1, UPnP/1.0"
val address: String, // e.g. "192.168.50.190"
val port: Int,
protocol: DiscoveryProtocol,
properties: Map<String, String>,
rawData: String,
deviceInfo: DeviceInfo?,
)
DiscoveryConfig
Controls how discovery works:
discovery.discover(
DiscoveryConfig(
protocols = setOf(DiscoveryProtocol.SSDP, DiscoveryProtocol.MDNS),
timeout = 10.seconds,
)
)
📺 Device Info Resolution
By default, the library only returns what SSDP/mDNS responses contain (name, IP, port, headers). To get rich device metadata — friendly name, manufacturer, model, serial number, icon — enable device info resolution:
Auto-resolve (all devices)
discovery.discover(
DiscoveryConfig(
resolveDeviceInfo = true, // fetch UPnP device description
resolveTimeout = 3.seconds, // HTTP timeout per device (default: 5s)
)
).collect { device ->
device.deviceInfo?.let { info ->
println()
println()
println()
println()
println()
}
}
Manual resolve (per device)
discovery.discover().collect { device ->
// Only resolve devices you care about
if ("samsung" in device.name.lowercase()) {
val resolved = device.resolveDeviceInfo(timeoutMs = 3000)
println(resolved.deviceInfo?.friendlyName)
}
}
What DeviceInfo contains
| Field | Example | |-------|---------|| | | | | | | | | | | | | | | | | | | | | (if available) | | | | | | | | | | | | Any additional XML fields as |
Note: Device info resolution works via HTTP GET to the SSDP
LOCATIONURL. Not all devices expose a description XML — mDNS-only devices typically will not havedeviceInfo.
🎯 Filtering Devices
Preset Filters
Filter by manufacturer or device type using built-in presets:
// Samsung TVs only
discovery.discover(
DiscoveryConfig(filter = DeviceFilters.SAMSUNG_TV)
).collect { println(it.name) }
Combining Filters
Use and, or, not to build complex filter expressions:
// Smart TVs that are NOT LG
val filter = DeviceFilters.SMART_TV and !DeviceFilters.LG
discovery.discover(DiscoveryConfig(filter = filter))
// Samsung OR Sony
val filter = DeviceFilters.SAMSUNG or DeviceFilters.SONY
discovery.discover(DiscoveryConfig(filter = filter))
Custom Keyword Filter
For brands not in the presets:
// Match by keyword (case-insensitive, searches name + address + properties)
val filter = DeviceFilter.byKeyword("my-custom-brand", "variant-2")
// Simple string match
val filter = DeviceFilter.byString("obscure-device-v3")
Custom Lambda Filter
Full control with a lambda:
val filter = DeviceFilter.custom { device ->
device.port == 8080 && device.address.startsWith("192.168.1.")
}
Other Filter Factories
// Match by SSDP search target
DeviceFilter.bySearchTarget("urn:schemas-upnp-org:device:MediaRenderer:1")
// Match by IP pattern
DeviceFilter.byAddress(Regex("192\\.168\\.50\\..*"))
⚙️ Advanced Configuration
Custom Configuration
discovery.discover(
DiscoveryConfig(
protocols = setOf(DiscoveryProtocol.SSDP, DiscoveryProtocol.MDNS),
timeout = 15.seconds, // discovery duration
resolveDeviceInfo = true, // fetch UPnP descriptions
resolveTimeout = 3.seconds, // HTTP timeout per device
ssdpSearchTarget = SsdpSearchTargets.ROOT_DEVICE,
ssdpMx = 5,
)
)
SSDP-Only Scan
discovery.discover(
DiscoveryConfig(
protocols = setOf(DiscoveryProtocol.SSDP),
timeout = 15.seconds,
ssdpSearchTarget = SsdpSearchTargets.ROOT_DEVICE,
ssdpMx = 5,
)
)
mDNS-Only Scan
discovery.discover(
DiscoveryConfig(
protocols = setOf(DiscoveryProtocol.MDNS),
timeout = 12.seconds,
mdnsServiceTypes = listOf(
MdnsServiceTypes.SAMSUNG_SMART_VIEW,
MdnsServiceTypes.GOOGLE_CAST,
MdnsServiceTypes.APPLE_AIRPLAY,
),
)
)
Android ViewModel Integration
class DevicesViewModel : ViewModel() {
private val discovery = NetworkDiscovery()
val devices = discovery.discover(
DiscoveryConfig(resolveDeviceInfo = true)
)
.scan(emptyList<DiscoveredDevice>()) { acc, device -> acc + device }
.stateIn(viewModelScope, SharingStarted.Lazily, emptyList())
override fun onCleared() {
discovery.close()
}
}
Using Raw Data for Custom Parsing
Some devices use custom protocols beyond standard UPnP. Access the full raw response:
discovery.discover().collect { device ->
// Parse the raw SSDP response yourself
val raw = device.rawData
val customField = raw.lines()
.find { it.startsWith("X-CUSTOM-HEADER:") }
?.substringAfter(":")?.trim()
}
📋 Preset Constants Reference
Device Filters (DeviceFilters)
By Manufacturer
By Device Type
Combined
mDNS Service Types (MdnsServiceTypes)
SSDP Search Targets (SsdpSearchTargets)
📄 API Reference
DiscoveredDevice
| Method | Description |
|---|---|
resolveDeviceInfo(timeoutMs) | Fetches UPnP description XML and returns a new device with deviceInfo populated |
DiscoveryConfig
DeviceFilter
| Combinator | Usage |
|---|---|
filter1 and filter2 | Match both |
filter1 or filter2 |
🔒 Platform-Specific Setup
Android
Permissions — add to AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
mDNS Context — initialize in your Application class:
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
MdnsContextHolder.init(applicationContext)
}
}
MulticastLock — required for SSDP on some devices:
val wifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager
val lock = wifiManager.createMulticastLock("discovery").apply {
setReferenceCounted(true)
acquire()
}
// ... run discovery ...
lock.release()
iOS
No additional setup required. The library uses POSIX sockets (SSDP) and NSNetServiceBrowser (mDNS) natively.
JVM
No additional setup required. mDNS uses the bundled JmDNS library.
📜 License
Copyright 2025 WacLabs
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.