Developer preview

SDK reference

Explore illustrative Android and iOS API patterns. Expand an operation to view a proposed native signature.

Requests, events and tasks

Signal	Meaning
Request ID	Identifies a call; await its documented result or failure event.
Completed / data event	Interpret according to the operation. Stopping a recording can be acknowledged before its file finishes saving.
TaskStarted	A long operation has been accepted locally; store taskID and keep listening.
TaskProgress	Intermediate progress. A percentage alone does not establish completion.
TaskFinished	Inspect the task’s terminal outcome: success, failure, cancellation, or unknown.

Register one event handler and retain the client on the main thread. Do not associate every incoming event with the most recent button tap. Unsolicited notifications can use request ID 0.

Native integration examples

Illustrative Kotlin · discovery and battery events

// Import path and client names are illustrative and subject to change.

// Create and retain one client, on the main thread.
val sdk = ArmorDeviceClient(context.applicationContext)
sdk.onEvent = { event ->
    when (event) {
        is ArmorEvent.Discovered -> showDevice(event.device)
        is ArmorEvent.Connection -> {
            if (event.state == "ready") sdk.readBattery()
        }
        is ArmorEvent.Battery -> showBattery(event.percent)
        is ArmorEvent.Failure ->
            showError(event.error.code, event.error.operation)
        else -> Unit
    }
}

// After runtime permission approval:
sdk.startScan()
// When the user selects a discovered device:
// sdk.connect(deviceID = selectedDeviceID)
// On owner teardown, call sdk.close().

Illustrative Swift · discovery and battery events

// Import path and client names are illustrative and subject to change.

// Create and retain one client, on the main thread.
let sdk = ArmorDeviceClient()
sdk.onEvent = { event in
    switch event {
    case .discovered(let device): showDevice(device)
    case .battery(_, let percent): showBattery(percent)
    case .failure(let error): showError(error.code, error.operation)
    default: break
    }
}

// Wait for Bluetooth availability, then scan.
sdk.startScan()
// When the user selects a discovered device:
// sdk.connect(deviceID: selectedDeviceID)
// After .connection("ready"), request sdk.readBattery().
// On owner teardown, call sdk.close().

Base APIs

startScan()Planned API

Explicit scan; case-insensitive name filter.

Kotlin · signature

fun startScan(nameContains: String = "")

Swift · signature

func startScan(nameContains: String = "")

stopScan()Planned API

Stop scanning.

Kotlin · signature

fun stopScan()

Swift · signature

func stopScan()

connect()Planned API

Use a local scan ID; pass an app-stored expectedSerial to verify a historical target. Ready follows protocol, model and nonempty serial validation; a mismatch reports IDENTITY_MISMATCH and disconnects. Auto-reconnect defaults off; when enabled it retries only this selection up to 5 times after 1/2/4/8/16 seconds. Disconnect an existing selection first.

Kotlin · signature

fun connect(deviceID: String, autoReconnect: Boolean = false, expectedSerial: String? = null)

Swift · signature

func connect(deviceID: String, autoReconnect: Bool = false, expectedSerial: String? = nil)

disconnect()Planned API

Disconnect and stop retries for the selected device; outstanding requests fail.

Kotlin · signature

fun disconnect()

Swift · signature

func disconnect()

readInfo()Planned API

After ready, use InfoKey for protocol/model, serial, hardware or chip versions; KM is Pro only.

Kotlin · signature

fun readInfo(key: InfoKey): Long

Swift · signature

func readInfo(key: InfoKey) -> UInt32

readBattery()Planned API

Read battery after ready.

Kotlin · signature

fun readBattery(): Long

Swift · signature

func readBattery() -> UInt32

readDeviceState()Planned API

Read power/charging/wear after ready.

Kotlin · signature

fun readDeviceState(): Long

Swift · signature

func readDeviceState() -> UInt32

playLocator()Planned API

Trigger one fixed short locator tone after ready.

Kotlin · signature

fun playLocator(): Long

Swift · signature

func playLocator() -> UInt32

close()Planned API

Idempotent release; create a new client for further use.

Kotlin · signature

fun close()

Swift · signature

func close()

EQ

readEqPresets()Planned API

Read the actual preset list; never invent IDs.

Result: EqPresets

Kotlin · signature

fun readEqPresets(): Long

Swift · signature

func readEqPresets() -> UInt32

readEqState()Planned API

Read EQ availability and the current preset ID.

Result: EqState

Kotlin · signature

fun readEqState(): Long

Swift · signature

func readEqState() -> UInt32

selectEqPreset()Planned API

ID must occur in the actual list; confirm selection by readback.

Result: EqState

Kotlin · signature

fun selectEqPreset(presetID: Int): Long

Swift · signature

func selectEqPreset(presetID: Int) -> UInt32

readEqCurve()Planned API

Read only the currently selected curve; never switch presets. Explicitly select the target with selectEqPreset first.

Result: EqCurveRead

Kotlin · signature

fun readEqCurve(): Long

Swift · signature

func readEqCurve() -> UInt32

writeEqCurve()Planned API

Write only the selected 63/64, which must match expectedPresetID; never switch implicitly. Five finite gains, quantized to 1/60 dB, written together and read back.

Result: EqCurveRead

Kotlin · signature

fun writeEqCurve(expectedPresetID: Int, gainsDb: List<Double>): Long

Swift · signature

func writeEqCurve(expectedPresetID: Int, gainsDb: [Double]) -> UInt32

Connection and settings

setAutoReconnect()Planned API

Control bounded disconnect retries for this client's selected device only; off by default. Disabling cancels retries without disconnecting. disconnect/close stop retries; no cross-launch restoration.

Result: Completed

Kotlin · signature

fun setAutoReconnect(enabled: Boolean): Long

Swift · signature

func setAutoReconnect(enabled: Bool) -> UInt32

readConnectionDetails()Planned API

Does not require ready; returns actual known control, pairing, and audio-input state.

Target result: ConnectionDetails

Kotlin · signature

fun readConnectionDetails(): Long

Swift · signature

func readConnectionDetails() -> UInt32

readCapabilities()Planned API

Requires ready; reports which capabilities apply to a model and are supported by the SDK release.

Target result: Capabilities

Kotlin · signature

fun readCapabilities(): Long

Swift · signature

func readCapabilities() -> UInt32

readName()Planned API

Requires ready; read the display or advertised name separately.

Target result: Name

Kotlin · signature

fun readName(kind: NameKind): Long

Swift · signature

func readName(kind: NameKind) -> UInt32

setName()Planned API

Requires ready; 1–32 UTF-8 bytes, without truncation. Display name applies immediately; broadcast name applies on the next advertising cycle.

Target result: Completed

Kotlin · signature

fun setName(kind: NameKind, name: String): Long

Swift · signature

func setName(kind: NameKind, name: String) -> UInt32

readGameMode()Planned API

Requires ready; read the actual low-latency switch.

Target result: GameMode

Kotlin · signature

fun readGameMode(): Long

Swift · signature

func readGameMode() -> UInt32

setGameMode()Planned API

Requires ready; update the local value only after device acknowledgement.

Target result: Completed

Kotlin · signature

fun setGameMode(enabled: Boolean): Long

Swift · signature

func setGameMode(enabled: Bool) -> UInt32

readLanguage()Planned API

Requires ready; read the device prompt language.

Target result: Language

Kotlin · signature

fun readLanguage(): Long

Swift · signature

func readLanguage() -> UInt32

setLanguage()Planned API

Requires ready; EN/ES/FR/DE only; does not change the app UI language.

Target result: Completed

Kotlin · signature

fun setLanguage(language: DeviceLanguage): Long

Swift · signature

func setLanguage(language: DeviceLanguage) -> UInt32

factoryReset()Planned API

Requires ready and no recording/transfer/update; the app obtains user confirmation first. Success means only that the device accepted reset.

Target result: Completed

Kotlin · signature

fun factoryReset(): Long

Swift · signature

func factoryReset() -> UInt32

readLed()Planned API

Requires ready and the LED model; read decorative LED settings.

Target result: Led

Kotlin · signature

fun readLed(): Long

Swift · signature

func readLed() -> UInt32

setLed()Planned API

Requires ready and the LED model; only existing product steps/modes are allowed; recording indicators are unaffected.

Target result: Completed

Kotlin · signature

fun setLed(settings: LedSettings): Long

Swift · signature

func setLed(settings: LedSettings) -> UInt32

Voice notes

startVoiceNote()Planned API

Requires ready, microphone permission, onPcm, and no other SDK audio task; SDK assigns noteID=taskID.

Target result: TaskStarted

Kotlin · signature

fun startVoiceNote(): Long

Swift · signature

func startVoiceNote() -> UInt32

stopVoiceNote()Planned API

Stop capture and drain SDK PCM callbacks, then request app file finalization; not final save success.

Target result: Completed

Kotlin · signature

fun stopVoiceNote(noteID: Long): Long

Swift · signature

func stopVoiceNote(noteID: UInt32) -> UInt32

finishVoiceNote()Planned API

Call only after FinalizationRequired to report the actual file-save outcome; the local session can still finalize after disconnection.

Target result: Completed

Kotlin · signature

fun finishVoiceNote(noteID: Long, result: NoteSaveResult): Long

Swift · signature

func finishVoiceNote(noteID: UInt32, result: NoteSaveResult) -> UInt32

readVoiceNoteState()Planned API

Requires ready; query current/latest device note and local session state.

Target result: VoiceNote

Kotlin · signature

fun readVoiceNoteState(): Long

Swift · signature

func readVoiceNoteState() -> UInt32

Camera

takePhoto()Planned API

Requires Pro, ready, and idle camera/AP/update resources; taskID is the nonzero actionID.

Target result: TaskStarted

Kotlin · signature

fun takePhoto(): Long

Swift · signature

func takePhoto() -> UInt32

startVideo()Planned API

Same prerequisites as photo capture; no duration parameter; runs until stopped or ended by the device.

Target result: TaskStarted

Kotlin · signature

fun startVideo(): Long

Swift · signature

func startVideo() -> UInt32

stopVideo()Planned API

Nonzero selects the current SDK recording; 0 means the current device-initiated recording only. Success means stop accepted; file finalization may continue.

Target result: Completed

Kotlin · signature

fun stopVideo(actionID: Long): Long

Swift · signature

func stopVideo(actionID: UInt32) -> UInt32

readCameraState()Planned API

Requires Pro and ready; returns current/latest capture state.

Target result: Camera

Kotlin · signature

fun readCameraState(): Long

Swift · signature

func readCameraState() -> UInt32

Media

openMediaSession()Planned API

Requires Pro, ready, and no capture/update; a reusable media session remains after the task succeeds.

Target result: TaskStarted

Kotlin · signature

fun openMediaSession(joinMode: WifiJoinMode = WifiJoinMode.SYSTEM_ASSISTED): Long

Swift · signature

func openMediaSession(joinMode: WifiJoinMode = .systemAssisted) -> UInt32

continueWifiJoin()Planned API

After manual joining, trigger actual supported network readiness; success means the check was submitted, then wait for the original task.

Target result: Completed

Kotlin · signature

fun continueWifiJoin(taskID: Long): Long

Swift · signature

func continueWifiJoin(taskID: UInt32) -> UInt32

closeMediaSession()Planned API

Finish/cancel downloads and deletions first; close the transfer session; do not force the phone onto another network.

Target result: Completed

Kotlin · signature

fun closeMediaSession(sessionID: Long): Long

Swift · signature

func closeMediaSession(sessionID: UInt32) -> UInt32

readMediaSession()Planned API

Requires Pro and ready; query network and media-session readiness.

Target result: MediaSession

Kotlin · signature

fun readMediaSession(): Long

Swift · signature

func readMediaSession() -> UInt32

listMedia()Planned API

Requires a ready media session; enumerate completed files and return category counts.

Target result: MediaList

Kotlin · signature

fun listMedia(sessionID: Long, category: MediaCategory = MediaCategory.ALL): Long

Swift · signature

func listMedia(sessionID: UInt32, category: MediaCategory = .all) -> UInt32

readStorage()Planned API

Requires Pro and control ready; a network connection is not required.

Target result: Storage

Kotlin · signature

fun readStorage(): Long

Swift · signature

func readStorage() -> UInt32

downloadMedia()Planned API

The app supplies a nonempty device-file list and writable directory. The SDK manages only this transfer and partial files, verifies and returns them; no gallery import, archiving, synchronization or automatic deletion.

Target result: TaskStarted

Kotlin · signature

fun downloadMedia(sessionID: Long, files: List<MediaFile>, directory: String): Long

Swift · signature

func downloadMedia(sessionID: UInt32, files: [MediaFile], directory: URL) -> UInt32

resumeMediaDownload()Planned API

The app supplies recovery data and the writable directory containing partial files. Verify device, remote identity and local partial content before starting a new task; reject mismatches.

Target result: TaskStarted

Kotlin · signature

fun resumeMediaDownload(recovery: RecoveryData, sessionID: Long, directory: String): Long

Swift · signature

func resumeMediaDownload(recovery: RecoveryData, sessionID: UInt32, directory: URL) -> UInt32

deleteMedia()Planned API

The app must explicitly pass true to confirm durable save/sync of these exact files; no default confirmation. No receipts or app-database access. Verify device/file identity before deletion and reconcile uncertain outcomes.

Target result: TaskStarted

Kotlin · signature

fun deleteMedia(sessionID: Long, files: List<MediaFile>, syncConfirmed: Boolean): Long

Swift · signature

func deleteMedia(sessionID: UInt32, files: [MediaFile], syncConfirmed: Bool) -> UInt32

Firmware update

startFirmwareUpdate()Planned API

Recheck all conditions and start the selected chip only; the app supplies the local package; KM uses the selected join mode.

Target result: TaskStarted

Kotlin · signature

fun startFirmwareUpdate(target: FirmwareTarget, packageFile: String, manifest: FirmwareManifest, joinMode: WifiJoinMode = WifiJoinMode.SYSTEM_ASSISTED): Long

Swift · signature

func startFirmwareUpdate(target: FirmwareTarget, packageFile: URL, manifest: FirmwareManifest, joinMode: WifiJoinMode = .systemAssisted) -> UInt32

readFirmwareUpdateState()Planned API

Requires a live client; query native state/actual versions when reachable, otherwise return a local record explicitly marked unknown; never treat cache as a fresh device query.

Target result: FirmwareUpdate

Kotlin · signature

fun readFirmwareUpdateState(target: FirmwareTarget): Long

Swift · signature

func readFirmwareUpdateState(target: FirmwareTarget) -> UInt32

resumeFirmwareUpdate()Planned API

The app returns recovery data, the same native package and manifest. Query actual state before native-supported recovery; never blindly reinstall or read a hidden task store.

Target result: TaskStarted

Kotlin · signature

fun resumeFirmwareUpdate(recovery: RecoveryData, packageFile: String, manifest: FirmwareManifest, joinMode: WifiJoinMode = WifiJoinMode.SYSTEM_ASSISTED): Long

Swift · signature

func resumeFirmwareUpdate(recovery: RecoveryData, packageFile: URL, manifest: FirmwareManifest, joinMode: WifiJoinMode = .systemAssisted) -> UInt32

validateFirmwarePackage()Planned API

Requires control ready and complete information; validate local package/model/hardware/current pair/order without starting an update.

Target result: FirmwareValidated

Kotlin · signature

fun validateFirmwarePackage(target: FirmwareTarget, packageFile: String, manifest: FirmwareManifest): Long

Swift · signature

func validateFirmwarePackage(target: FirmwareTarget, packageFile: URL, manifest: FirmwareManifest) -> UInt32

Logs

configureLogging()Planned API

Configure this client's onLog output to the app. No log files, database, rotation or ZIP; device logs are unaffected.

Result: Completed

Kotlin · signature

fun configureLogging(configuration: LogConfiguration): Long

Swift · signature

func configureLogging(configuration: LogConfiguration) -> UInt32

exportDeviceLogs()Planned API

Requires ready; model support will be stated in the SDK documentation; read firmware-exposed wireless logs and verify integrity.

Target result: TaskStarted

Kotlin · signature

fun exportDeviceLogs(target: FirmwareTarget, directory: String): Long

Swift · signature

func exportDeviceLogs(target: FirmwareTarget, directory: URL) -> UInt32

Tasks

cancelTask()Planned API

Request task cancellation under the task-specific rules. Success means cancellation took effect; the task also emits its terminal event.

Target result: Completed

Kotlin · signature

fun cancelTask(taskID: Long): Long

Swift · signature

func cancelTask(taskID: UInt32) -> UInt32

Error handling

Handle errors using the types and guidance documented for the SDK release. Design the app to distinguish retryable failures, final failures and uncertain outcomes, and reconcile device state before repeating actions with side effects.

Packages and source

SDK packages, examples and distribution terms will be announced through Lucyd’s developer channels. SDK packages, usage terms and final API names will be announced through Lucyd’s developer channels.

Explore planned capability areas →