Get started · Apple
iOS and macOS apps
kcoap builds for the iPhone, the iOS simulator and Apple silicon Macs, on CryptoKit and CommonCrypto. Today it is used from a Kotlin Multiplatform shared module in your app: Kotlin code calls kcoap, and Swift calls that module. There is no Swift package yet.
- Targets
iosArm64,iosSimulatorArm64,macosArm64 - TransportsUDP, TCP, WebSocket on URLSession
- CryptographyCryptoKit, CommonCrypto
- From SwiftThrough your shared module
Prerequisites
- A Mac with Apple silicon and Xcode. kcoap has no Intel targets (
iosX64,macosX64), and none for tvOS or watchOS. - A JDK 17 or newer, to run Gradle.
- Kotlin 2.3 or newer in the shared module; the samples use 2.4.21, the version kcoap is built with.
- The build sets no iOS or macOS deployment target yet, so none is documented.
Install status
kcoap 0.1.0 is on Maven Central, its iOS and macOS artifacts included. There is no XCFramework and no Swift Package Manager package. kcoap’s public suspend functions list KcoapException in @Throws, so their failures reach Swift as an NSError; a Swift smoke test in the macOS CI job checks that, and has passed since its first run on 6 November 2026. CI runs the common tests on macOS and the iOS simulator; nothing has run on an iPhone yet.
Set up
-
Add kcoap to the shared module
One framework for the app, built from your shared module. Keep it the only Kotlin framework in the app, and have it
export()the kcoap types your Swift code needs, if any. The bill of materials,kcoap-bom, sets one version for every kcoap module, so the modules name none.Kotlin DSL
shared/build.gradle.kts
plugins { kotlin("multiplatform") version "2.4.21" } repositories { mavenCentral() } kotlin { listOf(iosArm64(), iosSimulatorArm64()).forEach { target -> target.binaries.framework { baseName = "Shared" } } macosArm64() sourceSets { commonMain.dependencies { val bom = "dev.kcoap:kcoap-bom:0.1.0" implementation(project.dependencies.platform(bom)) implementation("dev.kcoap:kcoap-coap") // UDP and TCP, and the WebSocket client on URLSession implementation("dev.kcoap:kcoap-transport-ktor") implementation("dev.kcoap:kcoap-transport-ktor-websocket") implementation("dev.kcoap:kcoap-crypto-default") implementation("dev.kcoap:kcoap-oscore") implementation("dev.kcoap:kcoap-edhoc-oscore") } } }Version catalog
gradle/libs.versions.toml
[versions] kotlin = "2.4.21" kcoap = "0.1.0" [libraries] kcoap-bom = { module = "dev.kcoap:kcoap-bom", version.ref = "kcoap" } kcoap-coap = { module = "dev.kcoap:kcoap-coap" } kcoap-transport-ktor = { module = "dev.kcoap:kcoap-transport-ktor" } kcoap-transport-ktor-websocket = { module = "dev.kcoap:kcoap-transport-ktor-websocket" } kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" } kcoap-oscore = { module = "dev.kcoap:kcoap-oscore" } kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" } [bundles] kcoap = [ "kcoap-coap", "kcoap-transport-ktor", "kcoap-transport-ktor-websocket", "kcoap-crypto-default", "kcoap-oscore", "kcoap-edhoc-oscore", ] [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }shared/build.gradle.kts
plugins { alias(libs.plugins.kotlin.multiplatform) } repositories { mavenCentral() } kotlin { listOf(iosArm64(), iosSimulatorArm64()).forEach { target -> target.binaries.framework { baseName = "Shared" } } macosArm64() sourceSets { commonMain.dependencies { implementation(project.dependencies.platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap) } } }A standard Kotlin Multiplatform build file. kcoap’s coordinates are checked; kcoap’s repository has no Apple app that builds this file.
-
Link the framework into Xcode
Connect the
Sharedframework to your Xcode project the way the Kotlin Multiplatform documentation describes, for example with the Gradle taskembedAndSignAppleFrameworkForXcodein a Run Script build phase.
First client, called from Swift
Put the kcoap calls in a class of the shared module, and give its public functions @Throws. Swift calls your functions, not kcoap’s, and Kotlin/Native ends the process when an exception leaves a function that does not list it: without the annotation, a timeout would crash the Swift caller instead of arriving as an Error.
shared/src/commonMain/kotlin/Lights.kt
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.transport.ktor.KtorUdpTransport
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.cancel
class Lights {
private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
// Swift calls this function, so it lists what may reach Swift:
// kcoap's KcoapException, a socket's exception, a cancellation.
@Throws(Exception::class)
suspend fun state(uri: String): String {
val client = CoapClient(KtorUdpTransport.bind(), scope)
try {
return client.get(uri).payloadAsText()
} finally {
client.close()
}
}
fun close() = scope.cancel()
}Kotlin/Native exports a suspend function with a completion handler, which Swift 5.5 and later calls with async:
ContentView.swift
import Shared
let lights = Lights()
let state = try await lights.state(uri: "coap://192.0.2.1/lights")The kcoap names are checked against the sources, and the client lines are the guide’s. The @Throws wrapper and the Swift call follow Kotlin/Native’s conventions and are not tested; kcoap’s own Swift smoke test calls kcoap directly.
A server works the same way: CoapServer(KtorUdpTransport.bind(port = 5683), scope) { … } in the shared module, as in the JVM guide. The kcoap calls are the same common code on every platform.
Keys and state in an app
- EDHOC needs no durable store: its keys are new for each session. Cipher suite 2 (P-256) runs on every platform.
- Pre-shared OSCORE keys need a durable
SequenceNumberStore. The Apple recipe writes with POSIX calls andF_FULLFSYNC, in Application Support and excluded from backups, never inNSUserDefaults. It is not compiled or tested on Apple yet. - No post-quantum EDHOC on Apple yet: ML-KEM and ML-DSA come only from
kcoap-crypto-bc, which is for the JVM and Android.
Platform notes
Transports
kcoap-transport-ktor runs UDP and TCP on ktor-network’s BSD sockets. BSD sockets do not bring up the cellular radio and do not support VPN On Demand. The WebSocket client runs on the Darwin engine, which uses URLSession and does both, and takes coaps+ws on URLSession’s TLS. There is no coaps+tcp on Apple platforms: ktor has no TLS there. A Network.framework adapter is planned, not built.
Local network
iOS asks the user before an app talks to peers on the local network. Add a usage description for it (NSLocalNetworkUsageDescription in Info.plist) if your app reaches CoAP devices on the LAN.
What CI checks
The macOS job runs every common test on macosArm64 and iosSimulatorArm64, with CryptoKit and CommonCrypto underneath, and the WebSocket loopback test on the Darwin engine. It also builds a KcoapSmoke framework of kcoap-coap and compiles and runs a Swift script against it, which catches a timeout and a malformed URI as NSError; that step has passed since its first run on 6 November 2026. The release workflow compiles iosArm64. CryptoKit signs Ed25519 with randomness, so on Apple the RFC 8032 and RFC 9529 signature checks verify signatures instead of comparing bytes.
Not done yet on Apple
- An XCFramework, a Swift package and a Swift facade with Flow bridging (E4). Swift-only apps wait for that.
- A run on a real iPhone, a durable store tested on Apple, and an iOS guide.
Troubleshooting
- The app crashes when a request times out
- The function Swift calls has no
@Throws. Add@Throws(Exception::class)to every function of your shared module that Swift calls and that can throw. - The app crashes on a malformed URI
- kcoap treats a malformed URI string as the caller’s mistake, an
IllegalArgumentExceptionthat the@Throwslists ofCoapClientleave out. If Swift calls kcoap directly, parse the URI first withCoapUri.parse, whose@Throwslists that exception, or keep the call behind a wrapper of your own, as above. - Could not find
dev.kcoap:kcoap-coap-iosarm64or a similar artifact - Check that
mavenCentral()is in the shared module’s repositories, or independencyResolutionManagementwhen the settings file declares them. - No variant for an Intel Mac or the Intel simulator
- kcoap builds only
iosArm64,iosSimulatorArm64andmacosArm64. Use an Apple silicon Mac. - Requests to a device on the LAN never arrive
- Check the local network permission, and that the device and the iPhone are on the same network. Over cellular, BSD sockets do not bring the radio up.
Next steps
- The client and server guide: the same API on every platform.
- The plan for the Swift-facing API: target architecture, roadmap item E4.
- Features: what kcoap implements and how it is checked.