SpeedTester SDK

Overview

The SpeedTester SDK wraps the IPC layer between your app and the SpeedTester TV service. Under the hood it uses AIDL, but you never touch it — the SDK handles service binding, reconnection, and marshalling automatically.

Authentication

Every call into the SpeedTester service is authorised. Two mechanisms are available — whichever passes first is used.

Setup

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://maven.3ss.tv/releases") }
    }
}

// app/build.gradle.kts
dependencies {
    implementation("tv.threess:speedtest-sdk:1.3.1")
}

<!-- AndroidManifest.xml -->
<queries>
    <package android:name="tv.threess.speedtester" />
</queries>

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        SpeedTesterSdk.init(
            context = this,
            apiKey  = "YOUR_TENANT_API_KEY"  // omit if using package allowlist
        )
    }
}

// right after init(), once per app start
SpeedTesterSdk.wakeInBackground(this)

// or, from a coroutine: returns false (never throws) if the app is unreachable
val awake = SpeedTesterSdk.wake(context)

Speed test

Use SpeedTestClient to trigger a test and observe progress as a Flow. Cancelling the coroutine automatically cancels the test. The service runs one measurement at a time: a startTest() while a test is already in flight joins it and receives the same result, and a single engine run is capped at 90 s, after which the flow ends with an Error event.

val client = SpeedTestClient(context)

client.startTest().collect { event ->
    when (event) {
        is SpeedTestClient.Event.Progress   -> showProgress(event.downloadMbps, event.percent)
        is SpeedTestClient.Event.Completed -> showResult(event.result)
        is SpeedTestClient.Event.Error     -> showError(event.message)
    }
}

client.release() // call in onDestroy / onCleared

Network status

Observe live network conditions as a Flow. Emits immediately with the current state, then on every change.

val client = NetworkStatusClient(context)

client.networkStatus().collect { status ->
    println("${status.connectionType} — ${status.ssid} (${status.signalStrengthDbm} dBm)")
}

Wi-Fi

val client = WifiClient(context)

when (val result = client.connect("MyNetwork", "password123")) {
    is WifiConnectResult.Connected -> println("Connected to ${result.ssid}")
    is WifiConnectResult.Failed    -> println("Failed: ${result.reason}")
}

Connection quality

ConnectionQualityClient is the one-call source for a connection status card: it grades the last speed test against the live network and returns a ConnectionQuality — headline grade, the dominant issue, the numbers behind it, per-resolution streaming status (480p→4K: available / unstable / unavailable), suggested actions, and isStale. Everything is enums — your app owns all copy and localisation.

val client = ConnectionQualityClient(context)

// Render from the last test, no waiting; null = no test has run yet
val quality = client.get()

// Or measure fresh, streaming progress into the card
client.measure().collect { event ->
    when (event) {
        is ConnectionQualityClient.Event.Progress -> showProgress(event.percent)
        is ConnectionQualityClient.Event.Ready    -> renderCard(event.quality)
        is ConnectionQualityClient.Event.Failed   -> showError(event.message)
    }
}

client.release()

Composes the network status and speed test services — no new IPC surface, so it works against any SpeedTester app build that serves those two. The same verdict is available to AI consumers as the quality.summary signal.

Handling failures

Every client call fails fast — it either returns or throws a SpeedTesterException; nothing blocks waiting for a service that will not arrive. Handle the three subtypes at your integration boundary:

try {
    val snapshot = client.getSnapshot()
} catch (e: SpeedTesterException.AppMissing) {
    // SpeedTester app not installed (or service unresolvable) — prompt to install
} catch (e: SpeedTesterException.BindTimeout) {
    // installed but did not bind within 5 s — retry later
} catch (e: SpeedTesterException.NotAuthorised) {
    // not on the allowlist and no valid API key — fix tenant config
}

Transient IPC noise (dead binder, malformed payload) is degraded to null / empty results instead of an exception. If you use NetworkAiBridge, you don't catch anything — these surface as the app_missing / bind_timeout / not_authorised error codes below.

AI integration — NetworkAiBridge

NetworkAiBridge exposes the whole SDK as three generic JSON-in / JSON-out functions designed for LLM tool-calling (e.g. an AI assistant in your launcher). Register them as tools with your model — the bridge handles capability discovery, batched signal reads and action dispatch on top of the typed clients, and every return value is a JSON string you can feed straight back to the model.

val bridge = NetworkAiBridge(context)

// 1. Tell the model what it can see and do
val manifest = bridge.getAdvancedNetworkContext()

// 2. Read the signals the model asked for
val values = bridge.getNetworkSignals(listOf("wifi.signalDbm", "speedtest.downloadMbps"))

// 3. Execute an action the model chose
val result = bridge.networkAction("wifi.connect", mapOf("ssid" to "MyAp", "passphrase" to "secret"))

bridge.release() // call in onDestroy / onCleared

getAdvancedNetworkContext()

Returns a manifest of every signal id and action id (with parameter schemas and an available flag — Wi-Fi actions are marked unavailable on devices without a Wi-Fi radio), plus a live network snapshot and the last speed test result so the model has immediate context without a follow-up call.

getNetworkSignals(signalIds)

Batch-reads signal values by id. Returns {"signals": {id: value}, "errors": {id: message}}. Unknown ids land in errors; a signal with no value yet (e.g. no speed test has run) is null.

networkAction(actionId, params)

Dispatches an action by id with string key-value params. Returns {"ok": true, "result": …} on success or {"ok": false, "code": …, "error": …} on failure.

Error codes

Live progress — speedTestEvents

networkAction("speedtest.run") only returns when the test is over, but the bridge also exposes speedTestEvents: SharedFlow<SpeedTestClient.Event> so your UI can show the numbers while they are being measured. Collect it from the same NetworkAiBridge instance you hand the tool calls to: you get Started once with the engine ("ookla" / "librespeed" — pick the "Powered by" logo here; SpeedTester app 1.3.0+), then Progress roughly once a second (download Mbps during the download phase, upload Mbps during the upload phase, percent capped at 99), then exactly one Completed or Error. A bridge timeout arrives as an Error too, so the collector never hangs. The most recent event is replayed to new collectors — treat a replayed terminal event as "last known result", not as a running test.

// once, when the assistant session starts
scope.launch {
    bridge.speedTestEvents.collect { event ->
        when (event) {
            is SpeedTestClient.Event.Started   -> widget.showPoweredBy(event.engine)
            is SpeedTestClient.Event.Progress  -> widget.showMeasuring(event.downloadMbps, event.uploadMbps)
            is SpeedTestClient.Event.Completed -> widget.showResult(event.result)
            is SpeedTestClient.Event.Error     -> widget.showLastKnown()
        }
    }
}

Data models

SpeedTestResult

NetworkStatus

Error reference

Permissions

All sensitive permissions are held by the SpeedTester app. Your AndroidManifest.xml does not need ACCESS_FINE_LOCATION, ACCESS_WIFI_STATE, CHANGE_WIFI_STATE, or INTERNET. You only need the <queries> entry from step 2.

Wi-Fi name (SSID) availability. Android 10+ only discloses the SSID and BSSID to a process that is foreground-for-location. From SDK 1.1.1 the binding passes your app's foreground capabilities to the SpeedTester process (BIND_INCLUDE_CAPABILITIES), so NetworkStatus.ssid is populated while your app is on screen. It is null (never a raw <unknown ssid>) when the SpeedTester app has no location permission, location services are off, or the read happened with no client on screen. Signal strength, frequency and link speed are unaffected.

Version history