Get started
Get started with kcoap
kcoap 0.1.0 is on Maven Central. Add the modules you need through the bill of materials, then follow the guide for your platform.
- Version
0.1.0 - Released6 November 2026
- Group
dev.kcoap - RepositoryMaven Central
Platforms
Choose your platform
The protocol code is the same everywhere. Each guide lists the modules for that target, a first client and server, and what works there today.
Before you start
Prerequisites
What your project needs to use kcoap.
- Repository
- Maven Central, which also has every library kcoap depends on. kcoap needs no other repository and no token.
- JVM bytecode
- Java 17. Your project compiles to Java 17 or newer.
- Kotlin
- 2.3 or newer in your project, as the versioning policy says. kcoap is built with Kotlin 2.4.21, and the samples use it.
- Android
- API level 26 (Android 8.0) or later.
- iOS and macOS
- A Mac with Apple silicon and Xcode. No minimum OS version is set yet.
- Browsers and Node.js
- No minimum version is set. Kotlin/Wasm needs a browser with WebAssembly garbage collection.
Install
Two steps, on every platform
These steps are the same for every target. The platform guides repeat them with the build file that target needs.
-
Add the modules you need
kcoap comes from
mavenCentral(). Import the bill of materials,kcoap-bom, and name the modules without a version: they share internal plumbing, so a build uses one version for all of them, and the BOM sets it, also for the modules they bring along and when a library brings a newer kcoap.Kotlin DSL
build.gradle.kts
repositories { mavenCentral() } dependencies { implementation(platform("dev.kcoap:kcoap-bom:0.1.0")) implementation("dev.kcoap:kcoap-coap") // client, server implementation("dev.kcoap:kcoap-transport-ktor") // UDP, TCP implementation("dev.kcoap:kcoap-crypto-default") // cryptography implementation("dev.kcoap:kcoap-oscore") // OSCORE implementation("dev.kcoap:kcoap-edhoc-oscore") // EDHOC, OSCORE }Version catalog
gradle/libs.versions.toml
[versions] 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-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-crypto-default", "kcoap-oscore", "kcoap-edhoc-oscore", ]build.gradle.kts
repositories { mavenCentral() } dependencies { implementation(platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap) }In a Kotlin Multiplatform project the BOM and the same coordinates go into
commonMain.dependencies, the BOM asimplementation(project.dependencies.platform(...)), except the adapters a target lacks: browsers and Node.js usekcoap-transport-ktor-websocketinstead ofkcoap-transport-ktor. Maven builds import the BOM with<scope>import</scope>and name the-jvmartifacts (kcoap-bom). -
Follow the guide for your platform
Each guide has the build file for its target, a first client and server, and the notes that matter there: transports, the crypto backend, minimum versions and what is not done yet.
The coordinates are dev.kcoap:<module>:0.1.0 from mavenCentral(), under the verified dev.kcoap namespace, and the release key signs every artifact. Each release also goes to GitHub Packages, which needs a GitHub token to read. Releases lists the versions.
Modules
Which modules to add
Seventeen modules are published. An application usually needs four or five of them; the rest come in as dependencies.
| Module | Add it for | Targets |
|---|---|---|
kcoap-coap | CoapClient and CoapServer; brings the message model, the transport interfaces and kotlinx.coroutines | all |
kcoap-crypto-default | The platform’s cryptography. No other module brings it: every app adds it, or a classical backend of its own | all |
kcoap-transport-ktor | UDP (coap) and TCP (coap+tcp) sockets on ktor-network; on the JVM, also a TLS client (coaps+tcp) | JVM, Android, Apple, Linux |
kcoap-transport-ktor-websocket | The WebSocket client (coap+ws; coaps+ws on Apple platforms and the web, or on an HTTP client you pass whose engine checks host names, such as OkHttp, not CIO) | all |
kcoap-transport-ktor-websocket-server | The WebSocket server, with a ktor server engine you add, such as io.ktor:ktor-server-cio | JVM, Apple, Linux |
kcoap-oscore | OSCORE with pre-shared keys; add kcoap-coap too to run it through the client and server | all |
kcoap-edhoc-oscore | EDHOC over CoAP, into OSCORE, with the combined request; brings kcoap-edhoc, kcoap-oscore and kcoap-coap | all |
kcoap-crypto-bc | Post-quantum EDHOC: ML-KEM and ML-DSA on Bouncy Castle, around a classical backend you pass, usually DefaultCryptoBackend() from kcoap-crypto-default | JVM, Android |
kcoap-testkit | Tests without a network: a lossy in-memory network and in-memory connections on virtual time | all |
The other published modules (kcoap-common, kcoap-crypto, kcoap-cbor, kcoap-cose, kcoap-transport, kcoap-coap-message, kcoap-edhoc) come in through these, and kcoap-crypto-testsuite is for the tests of a CryptoBackend of your own. kcoap-dtls is built and tested but not published until its engine exists. All modules in the README.
Compare
What works where
The protocol code is common, so CoAP, OSCORE and EDHOC behave the same on every target. What differs is the transports a runtime allows, the cryptography underneath and how much has been tested there.
| JVM | Android | iOS and macOS | Linux | Browsers | Node.js | |
|---|---|---|---|---|---|---|
| Kotlin target | jvm | jvm, from API level 26 | iosArm64, iosSimulatorArm64, macosArm64 | linuxX64 | js, wasmJs | js, wasmJs |
| UDP and TCP | yes | yes | yesBSD sockets | yes | nobrowsers have neither | deferredno adapter yet |
| WebSocket client | yesCIO engine | yesCIO engine | yesURLSession | yesCIO engine | yesthe browser’s WebSocket | yesnpm ws |
| TLS client | yescoaps+tcp; coaps+ws on an HTTP client you pass whose engine checks host names | not runas on the JVM | partialcoaps+ws on URLSession; no coaps+tcp | nono TLS in ktor on native | yescoaps+ws, the browser’s wss | yescoaps+ws |
| WebSocket server | yes | nonot for apps | yes | yes | no | no |
| Cryptography | JCA | JCA | CryptoKit, CommonCrypto | OpenSSL 3, linked in | WebCrypto | WebCrypto |
| EDHOC suites | 0–6, 240, 2, 4, 24 cross-tested; −24 with kcoap-crypto-bc | not run yetthe device’s providers decide; −24 with kcoap-crypto-bc | in CI onlythe macOS job’s capability report | 0–6, 24OpenSSL 3 | 0–3, 6, 24where X25519 and Ed25519 exist, else 2, 3, 24; no ChaCha20-Poly1305 | 0–3, 6, 24no ChaCha20-Poly1305 |
| Post-quantum EDHOC | yeskcoap-crypto-bc | buildskcoap-crypto-bc; not run on a device | to do | to do | to do | to do |
| Tested in CI | common tests, real sockets, interop with libcoap and libedhoc | API level 26 checks; a sample app built with R8 and lint; no device run yet | common tests on macOS and the iOS simulator; a Swift smoke test; no iPhone run yet | common tests as native code; WebSocket loopback | common tests on Node.js; the js WebSocket client in headless Chrome | common tests; the WebSocket client against an npm ws server |
| Guide | JVM | Android | iOS and macOS | Linux | Browsers | Node.js |
Servers terminate TLS at a reverse proxy on every platform: kcoap has no TLS listener of its own (TLS per runtime). EDHOC asks the backend which suites it can run and offers only those, so a suite that a platform lacks is never offered there. The algorithms each target reports, and the suites that follow, are in algorithms and EDHOC suites per target.
Help
If the build cannot find kcoap
- Could not find
dev.kcoap:…:0.1.0 - Check that
mavenCentral()is in your repositories. In a settings file withdependencyResolutionManagement, the repositories go there.kcoap-dtlsis not published, so no build finds it. - Some kcoap classes are missing at runtime
- Check that every kcoap module has the same version: import
kcoap-bomand leave the version off the modules../gradlew dependenciesshows the version each one resolved to. - Still stuck
- SUPPORT.md says where to ask. Each platform guide has its own troubleshooting list.