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.

  • TargetsiosArm64, 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

No Swift package yet

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

  1. 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.

  2. Link the framework into Xcode

    Connect the Shared framework to your Xcode project the way the Kotlin Multiplatform documentation describes, for example with the Gradle task embedAndSignAppleFrameworkForXcode in 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 and F_FULLFSYNC, in Application Support and excluded from backups, never in NSUserDefaults. 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 IllegalArgumentException that the @Throws lists of CoapClient leave out. If Swift calls kcoap directly, parse the URI first with CoapUri.parse, whose @Throws lists that exception, or keep the call behind a wrapper of your own, as above.
Could not find dev.kcoap:kcoap-coap-iosarm64 or a similar artifact
Check that mavenCentral() is in the shared module’s repositories, or in dependencyResolutionManagement when the settings file declares them.
No variant for an Intel Mac or the Intel simulator
kcoap builds only iosArm64, iosSimulatorArm64 and macosArm64. 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