Embedded Linux devices

Codename One runs on embedded Linux boards — Raspberry Pi, NXP i.MX, Rockchip, NVIDIA Jetson, BeagleBoard, RISC-V boards — as the same single native binary the native Linux port builds, with the desktop layer swapped out. There is no X11, no Wayland compositor, no GTK and no JVM on the device: the application takes the screen directly through the kernel, reads touch, keys and rotary encoders straight from the input devices, and starts from boot as a service.

The same source is also the phone, tablet and desktop companion application. A form, a theme, an entity model or a REST client written for the device builds for iOS and Android unchanged, and the simulator runs it on the desktop with a virtual board attached.

At start-up the port picks the first display back end that works, in this order, and every board renders through at least the last two:

Rendering is in software, by a renderer built into the port, which needs no GPU driver and is fast enough for a full-screen HMI at 60 frames per second on a Raspberry Pi class board. Text is drawn with FreeType and images are decoded with libpng and libjpeg; nothing of a desktop stack (X11, GLib, Cairo, Pango or FontConfig) is loaded, so the application starts in a few tens of milliseconds. Images are PNG or JPEG.

Fonts are found by file name, without FontConfig: in the directories listed in CN1_FONT_PATH, then in a fonts directory beside the executable, then under /usr/share/fonts and /usr/local/share/fonts. The default face is DejaVu Sans, or Liberation, Noto, FreeFont, Roboto or Open Sans when DejaVu is absent. Fonts an application bundles work the same as on every other platform. The CN1_DISPLAY environment variable forces a back end (drm, fbdev, memory or headless); the others are listed in the table below.

Input comes from every /dev/input/event* device, including devices plugged in later: multi-touch panels (with pinch), mice, keyboards and rotary encoders, which move the focus like the arrow keys. Text fields open an on-screen keyboard, since a device seldom has a physical one. SIGTERM closes the application cleanly and the console is restored on exit.

Boards with a dependable OpenGL ES 2 driver can draw through the GPU instead. The same renderer still decides what every operation covers — shapes, clips, glyphs and antialiasing are computed exactly as in software — and the GPU then composites the result: fills, gradients, images and text become textured quads, images are uploaded once and kept on the GPU, and the finished frame is flipped to the display with no copy. The pointer moves on the display’s cursor plane. Frames are identical to the software renderer’s; the CPU time a frame costs is what drops, which matters most for large images, full-screen animation and high-resolution panels.

The linux.embedded.renderer build hint chooses: gpu or software. Without it, the board profile decides: gpu for the Raspberry Pi profiles, imx8, imx6, rk3588, jetson and generic-x64, and software for the rest. A software build links no GPU library at all.

A gpu build never fails to show a picture for want of a GPU. When the device has no usable driver, or the driver can’t draw the window, the application logs the reason and continues with the software renderer. The first log line names the renderer in use (renderer gpu or renderer software). The device needs Mesa’s GBM, EGL and GLES 2 libraries (libgbm1, libegl1, libgles2 on Debian and Raspberry Pi OS), or the board vendor’s equivalents.

Add the linux.embedded build hint to a native Linux build and name the board, and the builder picks the architecture, the display defaults and the libraries to link:

linux.embedded.display, linux.embedded.rotation and linux.embedded.dpi set the defaults the binary starts with; the environment variables override them on the device. linux.sysroot points a cross build at a Yocto or Buildroot SDK sysroot, so the binary links against exactly the libraries the image carries.

The device needs FreeType, libpng, libjpeg, zlib, a font and, for DRM/KMS, libdrm. OpenSSL 3 and libcurl are loaded only when the application first uses cryptography or the network. Raspberry Pi OS Lite has most of them; the scripts/embedded/pios/setup-device.sh script installs the rest and prepares the device to start the application at boot.

The deploy-device goal copies the binary to the device over SSH, installs it as a systemd service that starts at boot and restarts if it exits, and restarts it:

It uses the system’s ssh, so keys, agents and ~/.ssh/config aliases work as they do in a terminal. cn1.device.env passes environment variables to the service (CN1_ROTATION=90,CN1_DISPLAY=fbdev), and cn1.device.logs=true follows its log after the restart.

A project’s backend module can run in the cloud and on a board, and each side usually needs some controllers the other doesn’t. The deployed service runs with CN1_PROFILE=device, so @Profile("device") beans and application-device.properties are active only on the board, and @Profile("!device") keeps cloud-only beans off it. cn1.device.profile names a different profile, and an empty value sets none.

For a production image, scripts/embedded/yocto/meta-codenameone is a Yocto layer and scripts/embedded/buildroot/package/codenameone-app a Buildroot package. Both build the translated application with the image’s own toolchain and start it at boot.

com.codename1.hardware.Hardware is the entry point. On a device it drives the kernel’s own interfaces — the GPIO character device, i2c-dev, spidev, termios, sysfs PWM and backlight, SocketCAN and /dev/watchdog — with no extra library. On a phone it reports no support, so the same code runs everywhere:

Listeners run on the event dispatch thread. Reads that wait for data — a serial port, a CAN frame — take a timeout and belong off the event dispatch thread.

The simulator attaches a virtual board: gpiochip0 with 32 lines, a TMP102 temperature sensor at 0x48 and an EEPROM at 0x50 on I2C bus 1, loopback SPI, serial and CAN devices, two PWM channels, a watchdog and a backlight. Hardware code therefore runs, and can be unit tested, before a board is on the desk.

Nfc.getInstance().readTag(options) works with a USB contactless reader through PC/SC. The device needs the pcscd service and its libpcsclite library, which Codename One loads the first time NFC is used; without them isSupported() returns false. A card on the reader is reported as an ISO-DEP tag whose getId() is the UID the reader returns, and getIsoDep().transceive(apdu) exchanges APDUs with it. The connection stays open until the next readTag call. Reading NDEF, writing tags and host card emulation aren’t available on Linux.

A gateway, a sensor hub or a controller with no screen runs the backend instead: a native REST and WebSocket server, built the same way and as small. Hardware.getInstance() works there too, through the same kernel code as the UI port, and listener callbacks run on the pin’s own thread. The device then serves its API, the phone application is the client, and both share the entity classes.

Devices, phones and servers on one network find each other over multicast DNS (Bonjour), so nobody types an address. The Linux port implements BonjourBrowser and BonjourPublisher itself, on a plain UDP socket, so a Buildroot image needs no Avahi. The backend has the same protocol as com.codename1.backend.Discovery:

A phone, a Mac or a Linux desktop sees the device in its own Bonjour browser too. When another device already uses the name, the second one gets a numeric suffix, Hall Thermostat (2). Discovery listeners on the backend run on the discovery thread, because a server has no event dispatch thread.

A device in a field, a truck or a basement loses its network for minutes or days and has to keep working. com.codename1.io.outbox.Outbox is a queue of outgoing messages kept in the application’s own database. The device enqueues what it has to report, and the outbox sends it in order once the link is back. The same class works in a UI application and on the backend.

The table sits in the database of the ORM session the outbox was opened on. An enqueue inside one of that session’s transactions belongs to the transaction, so a reading and the message announcing it commit together or not at all:

postToServer stands for the application’s own request: Rest on a client, Web on the backend, or anything else that can carry bytes. A message stays at the head of the queue until the transport answers DELIVERED. While it’s retried, with a backoff that doubles up to five minutes by default, nothing overtakes it. REJECTED drops a message the server will never accept.

Delivery is at least once. If the acknowledgement is lost, the same message goes out again with the same getKey(), so the server records the keys it has applied and acknowledges a repeat without applying it twice. When many devices report to one server, put the device identity in the outbox name, which is the first half of every key. setCapacity(limit, true) bounds a telemetry queue by discarding the oldest readings. setMaxAttempts gives up on a message after that many failures.

A fleet server has to know which device is calling, and a shared password compiled into every unit isn’t an answer. Instead, each device generates its own key pair on first boot and asks a certificate authority for a client certificate. The key never leaves the device. The request is a PKCS#10 certificate signing request, which com.codename1.security.CertificateRequest builds:

From then on the device presents the certificate on every request, and the server identifies it from the TLS handshake:

ConnectionRequest.isClientCertificateSupported() is true on Linux devices, on Android and in the simulator. A headless device on the backend signs the request with Crypto.sign and presents the certificate through WebClient.setClientCertificate. Keep the private key in SecureStorage, or in a file only the application’s user can read on a board without one.

A connected product is seldom one program: it’s a device, the phone application that controls it and often a cloud service that sees every unit. In Codename One all three are targets of one project, laid out like any full-stack application:

These pieces combine into five common shapes:

Each standard is folded into the build only when the application uses it: an application that never browses Bonjour or opens a Bluetooth connection carries none of that code.

The same workload ran in each framework: an 800 by 480 pixel gauge (a filled arc that sweeps, a needle and a bold percentage) redrawn for every frame, capped at 60 frames per second, rendered in software into memory. Each ran three times for ten seconds, from a cold start and then a warm one, in the same Debian bookworm arm64 container on an Apple Silicon host. The table shows the median. A board is slower than that host and its storage is slower still, so read the columns against each other rather than as a board’s figures.

Codename One and Slint start fastest, Codename One uses the least memory, Slint needs the least on disk, and the three native toolkits land close together in frame rate and CPU. Codename One and Slint need far less on disk than Qt. JavaFX, the other way to put a Java UI on a board, needs about six times Codename One’s memory and seven times its disk, and a kiosk browser about twenty times both.

The table leaves out flutter-pi and Android (AOSP): flutter-pi needs an OpenGL ES GPU and AOSP needs a board support package, so neither runs in this harness.

A gateway or sensor hub has no screen, so the GUI comparison says little about it. The same small JSON service ran in each runtime: GET /json answering a short object. The server was pinned to two cores, a small board’s share, and the load generator (oha) ran on the remaining cores. Each runtime ran four rounds, from a cold start and then a warm one, in the same Debian bookworm arm64 container. The first round pages the container image in and is left out, so the table shows the median of the other six runs.

Codename One starts as fast as the compiled runtimes and serves the most requests of any of them: 1.3 times Rust’s peak and 2.1 times Go’s, at the lowest p99, with a steady-load CPU the same as Rust’s. Like Rust’s, the server makes two system calls per request, one read and one write, and a request allocates nothing but the object the handler returns. Rust and Go use less memory: a Codename One process grows to about 23 MB at peak load, against Go’s 12 MB and Rust’s 2 MB. Against the managed runtimes, it starts 33 times faster than Spring Boot, uses an eighteenth of its memory and serves over 11 times its peak.

Every change to the backend runtime or the translator reruns this comparison in continuous integration, against Rust and Go on an arm64 machine. The build fails if Codename One’s peak throughput falls below Rust’s, if its latency, start or CPU falls too far behind, if its memory passes 12 MB idle or 32 MB at peak, or if a request allocates anything beyond the object its handler returns.