Facilitates discovery of SSDP devices on a network, supporting unicast and multicast search messages. Offers state management, customizable logging, and adheres to UPnP Device Architecture 2.0 specifications.
Lighthouse is an open-source Android library which facilitates the discovery of SSDP devices connected to your network. It does this by supporting the sending of unicast and multicast search messages, as well as listening to all packets that may be sent to the multicast group. Lighthouse is built in accordance with the UPnP Device Architecture 2.0 specification.
Features at a glance:
Lighthouse is published to mavenCentral(), so you can add it to your Android project like so:
repositories {
mavenCentral()
}
dependencies {
implementation("com.ivanempire:lighthouse:2.2.1")
}
Alternatively, if you're not about that life, feel free to either clone this repository directly or download the source code from the releases page.
To get started with Lighthouse, simply build an instance of LighthouseClient and call the discoverDevices() suspending function:
val lighthouseClient = LighthouseClient
.Builder(context)
.setLogger(object : LighthouseLogger() {...}) // Optional: Setup a custom logging system
.setRetryCount(3) // Optional: Retry sending packets 3 times
.build()
suspend fun startDiscovery() {
lighthouseClient.discoverDevices()
.collect { deviceList: List<AbridgedMediaDevice> ->
Log.d("MyTag", "Got an updated device list: $deviceList")
}
}
There are two types of search messages (also known as M-SEARCH) one may send to a multicast group: unicast and multicast. A unicast message is one that is sent to a specific device on the network since the search criteria is rather narrow. A multicast message, on the other hand, is like an all-points bulletin: every single device that matches the more-generic search criteria will respond.
For example, the default search request, found here,
is a multicast message with a search target of ssdp:all. Lighthouse sets this up as an implicit argument to discoverDevices(). The corresponding string is:
M-SEARCH * HTTP/1.1
HOST:239.255.255.250:1900
MAN:"ssdp:discover"
MX:1
ST:ssdp:all
CPFN.UPNP.ORG:LighthouseClient
CPUUID.UPNP.ORG:747f550a-8dec-33a1-8470-e314bf440695
If you are feeling adventurous, however, you can create your own search requests and pass them into the discover method:
val multicastSearchRequest = MulticastSearchRequest(
hostname = Constants.DEFAULT_MEDIA_HOST,
mx = 1,
searchTarget = "mySearchTarget"
)
lighthouseClient.discoverDevices(multicastSearchRequest).collect { ... }
// Alternatively, here's unicast
val unicastSearchRequest = UnicastSearchRequest(
hostname = DEFAULT_MEDIA_HOST,
searchTarget = "ssdp:all",
)
lighthouseClient.discoverDevices(unicastSearchRequest).collect { ... }
Checkout the documentation for MulticastSearchRequest.kt
and UnicastSearchRequest.kt
to see which parameters are required and what they mean. Some basic network-specific constants are
exposed in Constants.kt.
Unfortunately, SSDP is not an enforced protocol. As a result, every single manufacturer may add or drop headers from the network packets, save for the official HTTP start line. To simplify things somewhat, Lighthouse follows the UPnP Device Architecture 2.0 specification as closely as it can. However, if you are seeing some missing information, or if the device list is not behaving as expected, here are some debugging notes to consider:
By default, Lighthouse does not log anything. This makes it just a little bit difficult to figure
out what's going on during the device discovery process. However, the setLogger() method allows
one to specify their own logging system that will be used by Lighthouse. The demo module implements
a custom logger here as an example, and the
source abstract class is LighthouseLogger.kt.
To re-iterate the comments in the code, the provided methods are:
logStateMessage() - logs main state updates (the resulting device list), useful for inspecting why a certain device is or isn't showing up.logStatusMessage() - logs general status updates, useful for seeing general setup/teardown information.logPacketMessage() - most verbose method, probably shouldn't be used in production - logs and all incoming packets + the results of them getting parsed.logErrorMessage() - logs any and all error messages, if you're seeing issues starting discovery/packets not coming in - implement this.Kotlin Coroutines are, for the most part, absolutely fantastic for asynchronous programming.
However, one area of increased complexity is exception handling. It's worth pointing out that
RealSocketListener.kt
may throw exceptions: IOException or SocketException, depending on what goes wrong when setting up the
MulticastSocket. As a result, it's a good idea to wrap the Lighthouse discovery call in either a
runCatching lambda, or
use a SupervisorJob.
For example:
class MyViewModel: ViewModel() {
private val viewModelJob = SupervisorJob()
private val myScope = CoroutineScope(Dispatchers.Main + viewModelJob)
myScope.launch {
lighthouseClient.discoverDevices()
.collect { backingDeviceList.value = it }
}
}
An easy litmus test is to call this method while your device is in airplane mode - if the exception is not propagated to the very top, then you're all set!
Lighthouse is fully compatible with the standard shrinking tools and does not require any additional rules. The only two dependencies are Kotlin Coroutines and AndroidX Core.
In no particular order, here's a list of incoming features and bug fixes:
AbridgedMediaDevice is replaced in the list. A patch for this may come from the consumer side - implement a custom DiffUtil class. However, it would be preferable for Lighthouse to handle this logic via partial updates, or a built-in differ.Copyright 2026 Lighthouse Contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance the License.
You may obtain a copy of the License at
https:
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.
Thank you to Tyler Nickerson and Yulia Biziaeva for their combined efforts on the Lighthouse logo.
Constants.kt contains all of the default values that Lighthouse will use if a device is not advertising a specific field in an SSDP packet. For example, if an ssdp:alive packet does not contain a bootId, the parser will set a default value of -1. Similarly, cache-control defaults to 1800 seconds (30 minutes), and missing location URLs default to 0.0.0.0. MediaDeviceServer.kt gets a special shoutout due the finicky format required by UPnP. All fields default to N/A, and the error in parsing will be logged as a warning.AbridgedMediaDevice.extraHeaders - they will be located there. Similarly, official headers parsed outside of their proper packets will also be found there. For example, an ssdp:update packet does not typically contain a cache-control field. However, if your devices add it to said packet, the parser will simply put it into extraHeaders.Surfaced from shared tags and platforms — no rankings paid for.