Running Kotlin® on bare-metal microcontrollers, built by the official compiler.
kmicro runs the output of the unmodified Kotlin/Native 2.4.21 compiler on a Cortex-M with no operating system and 64 KB of RAM. It replaces the Kotlin/Native runtime with one written for a single thread and a heap of a few kilobytes: a precise garbage collector, exceptions, coroutines, strings, and cinterop to call C.
// hello.kt
fun main() {
val names = List(3) { "Kotlin #${it + 1}" }
println("Hello from ${names.joinToString()} on a bare Cortex-M")
}$ python tools/kbuild.py build/hello hello.kt
kotlinc-native: compiling 1 file...
single-core: 113 init-state loads made plain
build\hello\k.o
$ python tools/qbuild.py build/hello/hello.elf targets/common/kotlin_main.c build/hello/k.o --run
qbuild: hello.elf text 72996 data 80 bss 18740 stack 40960
Hello from Kotlin #1, Kotlin #2, Kotlin #3 on a bare Cortex-M
qemu: exit 0
kbuild compiles the Kotlin code for the Cortex-M4F, the default core; qbuild links it with the kmicro runtime and
runs it on QEMU's emulated STM32L475. --cpu on both chooses another core, from the Cortex-M0 to the Cortex-M85,
a Cortex-A or a Cortex-R core:
docs/roadmap.md lists them with what was checked on each.
examples/hello does the same from a C main, the way a firmware written in C starts calling
Kotlin.
kmicro is experimental. It grew out of a real device firmware (Origin): 24 modules written in Kotlin on an STM32L431 with 64 KB of RAM and 256 KB of flash. That firmware is not part of this repository; the examples, tests and the board run of the self-test are.
Most of the language and the standard library behave exactly as on stock Kotlin/Native: tools/difftest.py builds
the same program for the host and for kmicro and compares the output byte for byte. The full list, feature by
feature, is in docs/kotlin-support.md.
| Works | Notes |
|---|---|
| classes, interfaces, generics, lambdas, objects, data/sealed/enum/value classes, delegation | |
a Kotlin-only program with fun main(), or Kotlin functions called from a C main |
C names through --c-api or @CName |
| garbage collection | precise mark-sweep in a fixed arena (KM_HEAP_BYTES), non-moving |
strings, StringBuilder, println, readln |
UTF-16; text goes out through your kmicro_puts and comes in through kmicro_getc |
exceptions, try/catch/finally, cause chains, runCatching, setUnhandledExceptionHook |
ARM EHABI unwinding; the uncaught-exception report prints the causes and the suppressed exceptions |
coroutines (kotlin.coroutines) |
suspend, resume, sequence builders, your own event loop |
collections, sequences, Regex, number formatting and parsing |
output byte-identical to stock Kotlin/Native; Regex needs a large heap (below) |
kotlin.random, kotlin.time, Uuid, Platform, exitProcess |
clocks and entropy come from board hooks; the QEMU targets provide the clocks |
| atomics, including the atomic arrays | atomic against interrupt handlers |
cinterop: scalars, pointers, strings, globals, enums, structs by value, staticCFunction callbacks, varargs, StableRef |
kbuild runs cinterop for you (--def) |
| interrupt handlers in Kotlin | they must not allocate; they may store references and use the atomics: docs/writing-kotlin.md, examples/irq |
Every standard-library function that calls into the runtime is implemented, or stops the program with
"... is not supported on kmicro" where it needs threads or an OS (python tools/missing_natives.py -v lists them).
The short list; docs/kotlin-support.md has every case.
- Regex is big: the first pattern keeps 11.5 KB of the heap, three small patterns need a 20 KB heap, and a
program that creates about 30 patterns in one function runs out of memory even at 64 KB. A program that uses
Regexis about 369 KB of flash (243 KB with--size), against the STM32L431's 256 KB (what features cost). Deep backtracking over long input overflows the stack.RegexOption.CANON_EQthrowsIllegalArgumentException. - Running out of memory stops the program: heap exhaustion ends with an out-of-memory report, not a catchable
OutOfMemoryError(one request larger than the whole heap does throw). Kotlin/Native puts constant-size local arrays on the stack; kbuild warns about those above 512 bytes. - Faults are not exceptions: a stack overflow or a null-pointer read stops the program with a fault report
(exit 99). The QEMU target
qemu-l475catches both with the MPU; the STM32L431 example reports faults but has no stack guard. - Board hooks: without them the clocks (
measureTime,TimeSource.Monotonic,Clock.System) andUuid.random()stop the program naming the missing hook,Random.Defaultrepeats its sequence after every reset, andreadln()sees the end of the input. runtime/kmicro.h lists the hooks. - Stack traces: addresses, at most 12 frames; tools/symbolize.py turns them into function
names, with file and line when the code is built with
-g. Functions that LTO inlines fold into their callers (reading a stack trace). - Smaller limits:
kotlin.mathresults are within 2 ulp of stock (newlib's libm);nativeHeap,memScopedandcstrshare a 1 KB arena (KM_INTEROP_BYTES); a public function whose backtick name contains a space cannot be exported to C (make itinternalorprivate); on Windows, a file name with characters outside the ANSI code page fails in the xPack tools.
Limits by design:
- One compiler version. kmicro reads the IR of Kotlin/Native 2.4.21. It builds on the
linux_arm32_hfptarget, which JetBrains has deprecated, so a later compiler may not offer it. - 32-bit ARM, and mostly Cortex-M. kmicro builds for the cores from the Cortex-M0 to the Cortex-M85, with or
without an FPU, and for one core each of the A and the R profile, the Cortex-A7 and the Cortex-R52, which have run
on QEMU only (
--cpu; the cores and what was checked on each). The other Cortex-R and 32-bit Cortex-A cores are not supported. 64-bit ARM is out of reach: kmicro reads the IR of the compiler's 32-bit ARM target. - One thread. Interrupts are fine, with the rules in docs/writing-kotlin.md. There are
no threads:
Workeris not supported. - The standard library only. kotlinx libraries are untested.
- Install the tools listed in BUILDING.md: Kotlin/Native 2.4.21 and a Java runtime to run it (its first compile downloads LLVM), the xPack Arm GCC (for newlib and libgcc), QEMU for Arm, Python 3.10 or later.
python toolchain/paths.pyshows what it found.python tests/run_all.pybuilds every test and example and runs them on an emulated STM32L475, andpython -m unittest discover -s tests/unittests the tools. The first run compiles each program with kotlinc-native, about a minute each.
Your own program is the hello world above: kbuild takes Kotlin files or a folder of them, and fun main() can be in
any package (--main makes a missing one a build error).
Calling C. Name the C headers in a cinterop .def file. kbuild runs cinterop and also writes a bridges.o,
which is linked with k.o:
python tools/kbuild.py build/app app.kt --def sensor.def -I include
python tools/qbuild.py build/app/app.elf targets/common/kotlin_main.c sensor.c build/app/k.o build/app/bridges.o -I include --run
@file:OptIn(kotlinx.cinterop.ExperimentalForeignApi::class)
import sensor.* // sensor.def: headers = sensor.h, package = sensor
fun main() {
val mv = List(sensor_count()) { sensor_read(it) }
println("sensors: ${mv.joinToString { "$it mV" }}, average ${mv.average()} mV")
}tests/cinterop_shapes shows structs by value, callbacks, globals, varargs and static inline header functions. examples/irq uses support/hw.def for register access and handles SysTick in Kotlin.
C calling Kotlin. --c-api app.h --package app gives the Kotlin functions of package app the C names of the
prototypes in app.h, so a C main can call them after kmicro_init(): examples/hello.
On a real board, link k.o (and bridges.o) with runtime/, your startup code and a linker script.
docs/porting.md explains each piece: the functions the board provides, the start-up, the
runtime's compiler flags (clang, -fexceptions -funwind-tables, without which runtime/eh.c stops the build), the
linker-script sections and the libraries. examples/selftest/stm32l431 does this for
an STM32L431.
examples/selftest on an STM32L431 at 16 MHz, 16 KB Kotlin heap. The times are from the board
run recorded on 2026-10-16 (full report), made with earlier versions of the
runtime, of board.c and of the build steps, before release 0.1.0. The run has not been repeated with the
current runtime:
| Check | Time on 2026-10-16 |
|---|---|
| runtime start (module initializers) | 111 µs |
| classes, interface, virtual calls | 53 µs |
| garbage collection: 6000+ objects through the 16 KB heap | 161 ms |
strings: 10 checks, UTF-16, JVM hashCode |
1.5 ms |
one throw + catch |
1.6 ms* |
| coroutine: 300 suspend/resume cycles | 49 ms |
| one full collection | 1.8 ms |
* The runtime of that run visited the same frame several times when it walked the stack for a stack trace; #3 stopped that. On QEMU a throw that the same small function catches now executes about 9,450 instructions: 7,150 to create the exception with its message and stack trace, 2,300 from the throw to the catch (more).
| Folder | Contents |
|---|---|
| runtime/ | the Kotlin runtime, in C and C++; kmicro.h is its contract with the board |
| toolchain/ | the build steps: paths.py finds the tools (tested versions in versions.txt), kn.py runs the pipeline, retarget.py, aapcs.py and bridges.py adapt the compiler's IR, binutils.py runs nm, objdump and the like on an image |
| support/ | hw.h, hw.c, hw.def: volatile register access, barriers, interrupt masks for Kotlin |
| targets/ | startup code and linker scripts for QEMU (qemu-l475 for programs, with a linker script for each machine the cores run on; qemu-an386 through qbuild --target an386 for programs that need more memory), and common/kotlin_main.c for fun main() |
| tools/ | kbuild.py, qbuild.py, gen_regs.py (CMSIS to Kotlin), isr_check.py, symbolize.py, frames.py, insn_check.py, missing_natives.py, difftest.py, measure.py, irstat.py, port_dtoa.py |
| examples/ | hello, irq (a Kotlin SysTick handler on registers), selftest (with its STM32L431 board files) |
| tests/ | run_all.py and one folder per feature, expected/ (the outputs run_all compares), diff/ (the differential tests), unit/ for the tools |
| docs/ | Kotlin support, how it works, writing Kotlin for a microcontroller, porting to a board, roadmap, design notes |
Bug reports, fixes and tests are welcome: CONTRIBUTING.md says how to build, test and send a change, and docs/roadmap.md where the open work is and how releases are numbered. CHANGELOG.md lists what each release contains. Report a security problem privately, as SECURITY.md describes.
kmicro started inside its author's own hardware project: a board that the author, Masahiro Obara, designed and built, with firmware the author wrote, first in C and then module by module in Kotlin (24 modules on an STM32L431). kmicro is the runtime and toolchain that made the Kotlin part possible; it was split out of that project and is developed on its own.
That firmware is a separate, unpublished project. It is not part of this repository, and nothing here licenses
it; it uses kmicro like any other program. support/hw.h and tools/gen_regs.py were first written for it and
are part of kmicro, under the same Apache License 2.0. kmicro and the firmware were made on the author's own time
and equipment and are not related to the author's employer.
Copyright 2026 Masahiro Obara (masa002) and the kmicro contributors.
Apache License 2.0: LICENSE. Parts follow Kotlin/Native and Apache Harmony sources: NOTICE.
kmicro is an independent project, not affiliated with or endorsed by JetBrains or the Kotlin Foundation. "Kotlin" refers to the Kotlin® programming language.
