Coder Legion - Recent posts tagged embedded

Building aegis-filter: Why Standard Kalman Filters Fail in Adversarial Environments

Fri, 09 Oct 2026 05:45:50 +0000

When building telemetry filters for autonomous drones or robotics, the textbook recommendation is always the same: “Just slap a Kalman Filter on it.”

In theory, the linear Kalman filter is mathematically optimal under Gaussian white noise. In the real world, however, physical sensors do not live in textbook conditions:

Adversarial GPS/Baro Spoofing: A rogue transmitter or RF jammer injects sudden, massive delta jumps (e.g., +150 meters in a single millisecond).
Numerical Covariance Degeneracy: Floating-point round-off errors over millions of iterations cause the error covariance matrix $P$ to lose its positive-definiteness ($P \not\succ 0$), producing negative variances and exploding state estimates.
Severe Non-Linearities: Radar range calculations ($r = \sqrt{x^2 + y^2}$) and orientation quaternions break linear assumptions; Extended Kalman Filters (EKF) require calculating brittle analytical Jacobian matrices that drift rapidly.

To solve these mission-critical vulnerabilities, we built and open-sourced aegis-filter under Exploidus—a cyber-resilient, #![no_std], hard real-time estimation engine written from scratch in pure Rust.

Here is the engineering breakdown of how it works and what the simulation numbers prove.

1. The Core Architecture

aegis-filter is engineered with three core defenses:

A. Joseph-Stabilized Covariance Update

Standard Kalman filters update covariance using $P_k = (I - K_k Hk) P{k|k-1}$. In finite-precision IEEE 754 floating-point arithmetic, subtraction can yield asymmetric, non-positive-definite matrices.

aegis-filter enforces the Joseph Stabilized Form:
\[P_k = (I - K_k H_k) P_{k|k-1} (I - K_k H_k)^T + K_k R_k K_k^T\]

Because both terms are quadratic forms ($A P A^T + B R B^T$), positive-definiteness is mathematically guaranteed across infinite operational lifetimes.

B. Chi-Square / 3-Sigma Outlier Rejection Gating

Before any raw measurement is allowed to alter the state vector, the innovation $\tilde{y}_k = z_k - Hk \hat{x}{k|k-1}$ is evaluated against the innovation covariance $S_k = Hk P{k|k-1} H_k^T + R_k$:
\[\text{Reject if } |\tilde{y}_k| > \gamma \sqrt{S_k}\]

If an adversary transmits a spoofed altitude or an IMU glitches, the reading is gated at line-rate. The filter falls back safely to its physical state propagation without corrupting the state.

C. Unscented Kalman Filtering (UKF) & $H_\infty$ Robust Minimax

UKF (Merwe Scaled Sigma Points): Replaces brittle Jacobian derivations by propagating $2n + 1$ deterministic sigma points through non-linear observation closures.
$H_\infty$ Minimax: Optimizes state estimation against the worst-case disturbance rather than assuming well-behaved Gaussian noise.

2. Flight Telemetry & Spoofing Resilience Simulation

To prove real-world resilience, we simulated a quadcopter ascending at $1.5\text{ m/s}$ subjected to atmospheric turbulence, normal sensor noise, and deliberate adversarial spoofing:

Step 12: Instantaneous $+150\text{m}$ GPS spoofing attack.
Step 22: Severe $-80\text{m}$ sensor hardware dropout glitch.

Here is the telemetry log produced by running cargo run --example flight_telemetry:

===============================================================================
  AEGIS-FILTER :: FLIGHT TELEMETRY & ADVERSARIAL RESILIENCE SIMULATION
  Developed under Exploidus (https://github.com/Exploidus)
===============================================================================

Step   | True Alt (m) | Sensor Raw (m) | Aegis Est (m)  | Abs Error    | Status    
-------+--------------+----------------+----------------+--------------+-----------
1      | 1.50         | 1.79           | 1.75           | 0.254        | VALID     
2      | 3.00         | 3.22           | 3.24           | 0.238        | VALID     
3      | 4.50         | 3.46           | 4.31           | 0.187        | VALID     
4      | 6.00         | 6.74           | 6.06           | 0.057        | VALID     
5      | 7.50         | 7.67           | 7.58           | 0.081        | VALID     
6      | 9.00         | 8.90           | 9.04           | 0.045        | VALID     
7      | 10.50        | 9.68           | 10.39          | 0.113        | VALID     
8      | 12.00        | 12.98          | 12.08          | 0.075        | VALID     
9      | 13.50        | 13.41          | 13.55          | 0.047        | VALID     
10     | 15.00        | 14.69          | 14.99          | 0.009        | VALID     
11     | 16.50        | 16.04          | 16.42          | 0.080        | VALID     
12     | 18.00        | 168.00         | 17.92          | 0.080        | SPOOF REJECT
13     | 19.50        | 19.08          | 19.36          | 0.138        | VALID     
14     | 21.00        | 20.65          | 20.83          | 0.172        | VALID     
15     | 22.50        | 22.43          | 22.34          | 0.156        | VALID     
16     | 24.00        | 24.93          | 24.01          | 0.012        | VALID     
17     | 25.50        | 24.79          | 25.40          | 0.099        | VALID     
18     | 27.00        | 26.78          | 26.88          | 0.116        | VALID     
19     | 28.50        | 28.76          | 28.44          | 0.060        | VALID     
20     | 30.00        | 30.64          | 30.04          | 0.044        | VALID     
21     | 31.50        | 30.61          | 31.41          | 0.095        | VALID     
22     | 33.00        | -47.00         | 32.91          | 0.095        | SPOOF REJECT
23     | 34.50        | 34.96          | 34.50          | 0.003        | VALID     
24     | 36.00        | 36.25          | 36.04          | 0.036        | VALID     
25     | 37.50        | 36.60          | 37.39          | 0.110        | VALID     
26     | 39.00        | 39.34          | 38.96          | 0.041        | VALID     
27     | 40.50        | 40.99          | 40.54          | 0.039        | VALID     
28     | 42.00        | 41.84          | 42.01          | 0.009        | VALID     
29     | 43.50        | 42.78          | 43.40          | 0.100        | VALID     
30     | 45.00        | 45.60          | 45.00          | 0.003        | VALID     

-------------------------------------------------------------------------------
  SIMULATION SUMMARY:
  - Total Steps Processed      : 30
  - Valid Readings Fused       : 28
  - Adversarial Spikes Blocked : 2 (100% Gated)
  - Final Variance Confidence  : 0.1185
===============================================================================

Key Takeaways from the Data:

Millimeter Tracking Precision: Under normal noisy conditions (Step 10, Step 30), estimation error dropped to 0.003–0.009 meters (3–9 mm).
Flawless Spoof Rejection: When the raw altitude leaped to $168\text{m}$ at Step 12, the filter isolated the anomaly, kept the aircraft altitude at $17.92\text{m}$ (error: $0.080\text{m}$), and prevented a fatal motor cut.

3. Quick Start (Rust)

Add aegis-filter to your Cargo.toml:

[dependencies]
aegis-filter = "0.1.0"

For bare-metal Cortex-M/RISC-V embedded targets:

[dependencies]
aegis-filter = { version = "0.1.0", default-features = false }

1D Outlier-Gated Fusion Example:

use aegis_filter::{ScalarKalmanFilter, FilterError};

fn main() -> Result<(), FilterError> {
    // Initial state: 0.0m, Initial variance: 5.0, Process noise: 0.02, Measurement noise: 0.8
    let mut filter = ScalarKalmanFilter::new(0.0, 5.0, 0.02, 0.8)?;

    let sensor_stream = [1.5, 3.1, 4.4, 168.0 /* Spoofed spike */, 6.0];

    for &raw_reading in &sensor_stream {
        filter.predict(1.5)?; // Predict forward by 1.5m climb

        match filter.update(raw_reading, Some(3.0)) { // 3-sigma gate
            Ok(estimated_alt) => println!("Estimated Altitude: {:.2}m", estimated_alt),
            Err(FilterError::MeasurementGated) => {
                println!("Spoofed sensor reading ({:.1}m) rejected! Holding state.", raw_reading);
            }
            Err(e) => return Err(e),
        }
    }

    Ok(())
}

4. Open Source Links

The engine is open-source under dual MIT/Apache-2.0 licenses:

Crates.io: crates.io/crates/aegis-filter
GitHub Repository: Exploidus/aegis-filter
Documentation: docs.rs/aegis-filter

Feedback, issues, and PRs from control engineers and systems developers are warmly welcome!

RS232 vs RS485 in a Vehicle: Which Serial Port for Which Peripheral

Fri, 09 Oct 2026 02:19:45 +0000

RS232 and RS485 both turn up on the same vehicle-terminal spec sheet, and integrators routinely wire the wrong one. The choice is not about speed or age. It comes down to two questions: how many devices are on the line, and how far does the cable run?

The actual difference: single-ended vs differential

RS232 sends each signal as a voltage measured against a shared ground. That works over a short cable in a quiet electrical environment.

RS485 sends over a twisted pair and reads the difference between the two wires. Interference that hits the cable hits both wires roughly equally, and cancels out when the receiver subtracts one from the other.

Distance, device count and noise immunity all follow from that one design difference.

	RS232	RS485
Signalling	Single-ended (vs ground)	Differential (twisted pair)
Topology	Point-to-point	Multidrop bus
Devices per port	1	Up to 32 (more with repeaters)
Practical cable run	~15 m	~1200 m
Noise immunity	Low	High
Termination	No	Yes, 120 ohm at both bus ends
Addressing	Not needed	Required (each node needs an ID)

Which one for which peripheral

Anything within arm's reach of the operator and connecting to exactly one port goes on RS232. Anything that leaves the cab, down a boom, along a trailer or across a yard, goes on RS485, even if it is the only device on that line, because the distance alone rules RS232 out.

Where RS232 fails quietly

The failure that catches people out is not a dead link, it is an intermittent one. An RS232 run of 20 to 30 m will often work on a bench, and work on the machine while it is parked. Then it starts dropping characters once the hydraulics engage or a motor starts nearby.

Because the fault only appears under load, it usually gets blamed on software or the peripheral for weeks before anyone re-examines the cable. If a serial link is flaky on a working machine but fine in the workshop, check cable length and signalling type first.

RS485 wiring that people skip

Termination: a 120 ohm resistor at each end of the bus, not at every node. Missing termination causes reflections that look identical to random data corruption.
Daisy-chain, not star: RS485 is a linear bus. Branching it into a star causes reflections even with correct termination.
Unique node addresses: two devices sharing an address will both answer and corrupt each other's replies.
Twisted pair, not any two conductors: the noise cancellation depends on both wires following the same physical path.

Neither replaces CAN bus

CAN bus reads the vehicle's own network (engine data, fault codes, implement messages under J1939 or ISOBUS). Serial ports connect peripherals the vehicle maker never installed: scanners, printers, weigh scales, third-party sensors. A typical deployment uses all of them at once, which is why interface count, not just interface type, decides whether a terminal fits a job.

A real example

A contractor fitting terminals to self-propelled sprayers needed three things per machine: a cab-mounted barcode scanner for chemical batch logging, a legacy GNSS receiver, and four tank-level probes spread along a 28 m boom.

The first install put everything on RS232 with extended cables. The scanner and receiver worked. The boom probes dropped readings whenever the pump ran. Rewiring the four probes as a single RS485 bus with 120 ohm termination at both ends fixed it. The scanner and receiver stayed on RS232, where their short runs were never the problem.

FAQ

Can I convert RS232 to RS485 with an adapter? Yes, but each converter adds a powered component and a connection point that can fail in a vibrating vehicle. A native port avoids both.

Is RS485 faster than RS232? Not inherently at short distances. The real advantage is that RS485 holds its data rate over long runs where RS232 degrades.

Do I need termination on a short RS485 bus? Under a few metres it often works without, but termination costs nothing and removes an intermittent fault that is hard to diagnose later.

How many RS485 devices can share one bus? The standard allows 32 nodes. In practice, polling time becomes the limit before the electrical limit does, since the terminal queries each address in turn.

Which should I specify on a new build? Default to RS485 unless you have a specific reason not to. One device under 15 m can use either. More than one device, or any run past 15 m, and RS485 is the one that works reliably in a vehicle.

I work on rugged vehicle-mount terminals at CF-Device. The full write-up, including the spec-sheet checklist, is on our site: RS232 vs RS485 for Rugged Vehicle Tablets.

CAN Bus and J1939 Integration on Rugged Vehicle Tablets: A Practical Guide

Fri, 09 Oct 2026 01:59:22 +0000

Rugged vehicle-mount tablets are only as useful as the data they can read from the machine they're bolted into. On heavy-duty vehicles — tractors, excavators, trucks — that data comes off the CAN bus, and interpreting it correctly means supporting J1939 on top. Here's how the layers fit together and what to check when specifying hardware.

CAN Bus: the physical layer

CAN (Controller Area Network) is the internal wiring protocol most commercial vehicles and heavy machinery use so their onboard components — ECUs, transmission modules, sensors — can talk to each other without a dedicated wire per signal. A vehicle terminal taps into this same network and reads the same data the dashboard uses.

J1939: the messaging layer on top

CAN defines how bytes move; J1939 (SAE) defines what they mean — engine temperature, fuel rate, diagnostic trouble codes — in a standardized format across manufacturers. A terminal with native J1939 interprets that data correctly whether it's in a tractor, an excavator, or a delivery truck, with no per-brand integration work.

ISO 11783 (ISOBUS) and ISO 15765

ISO 11783 / ISOBUS VT extends J1939 for agricultural implement control — one terminal runs any compliant implement's interface.
ISO 15765 covers diagnostics.

Supporting all three on the same CAN channels means one hardware platform serves a mixed fleet without separate firmware per vehicle type.

What to check when specifying hardware

Native CAN, not a USB/serial adapter — an external dongle adds a powered component and a connection point that fails under vibration.
Channel count — a machine with multiple buses needs multiple channels, and this cannot be added later.
CAN FD support — larger payloads at higher speed, backward-compatible with classic CAN.
Kernel-level access — real-time, low-latency CAN needs SocketCAN at the kernel, not just an app-layer library.

A practical note

Interface count, not processor speed, is usually the spec that decides whether a terminal fits a job. A unit two CAN channels short is unusable no matter how fast its CPU is.

Full technical write-up, with the specification sequence and model-by-model channel counts, is on our site: CAN Bus and J1939 Integration for Rugged Vehicle Tablets

I'm with CF-Device, a manufacturer of rugged vehicle-mount tablets with native CAN bus, J1939 and ISOBUS support.

Exploiting "Trust-by-Default": How I transformed an ESP32-S3 into a BadUSB

Sat, 12 Sep 2026 14:58:38 +0000

The first tool I decided to arm my Swiss army knife with was a BadUSB emulator. First and foremost, this extremely powerful tool (provided you have physical access to the target machine) relies on an inherent vulnerability of the USB protocol (born in 1996), originally designed to make connecting peripherals as simple and invisible as possible.

Practically, when we plug a USB device into a computer, a rigorous process called Enumeration begins. This is divided into several phases: the device is physically connected, its communication speed is identified, and immediately after, the device sends its Descriptors. These descriptors are a set of vital information that defines how the host machine will communicate with the device; subsequently, the device is reset, an address is assigned to it, the interfaces are loaded, and finally, the drivers.

(If you want to delve deeper into the enumeration phase, I recommend this article by TotalPhase).

Having defined this, it's easy to guess that if we alter the descriptors via software, we can disguise an ordinary flash drive (or in our case, an M5Stick) making it appear as a keyboard or a mouse.

And this is where the "Trust-by-Default" vulnerability comes into play: all operating systems blindly trust an HID (Human Interface Device) like a keyboard, as it is an essential input tool. Generic drivers are already pre-installed in the kernel (zero incompatibilities or warning popups) and, moreover, antiviruses have no say in the matter, since they are not designed to scan hardware inputs sent via electrical impulses.

The architectural choice: Dynamic Parser vs Hardcoding

Initially, for "simplicity", I thought about hardcoding the payloads directly in the C source code. But thinking about it carefully, the use cases in pentesting are infinite: the end-user must have the ability to modify scripts on the fly, without having to recompile or flash the ESP32 firmware every time.

For this reason, I decided to implement a dynamic Parser for DuckyScript. This allows the user to upload their own plain text scripts (.txt) onto the device's LittleFS memory and have the microcontroller interpret them on the fly.

For those unfamiliar with it, DuckyScript is a macro language created by Hak5 that abstracts interaction with the victim machine. It's simple and easily readable.
To better explain what I mean by "abstract": if I were to write a payload directly in low-level C or Bash, I would have to carefully calculate every single delay between one command and the next to give the PC time to open windows, and I would have to manually map the hexadecimal codes (HID Keycodes) of every single key to "press". DuckyScript, combined with my parser, automates all of this.

Originally, to use Rubber Ducky scripts, they had to be transformed from simple text files into binary files; this conversion was performed by a PC tool called Ducky Encoder, which converted them into inject.bin. This tool was used because many older devices lacked the computational power to analyze text during runtime, a problem that the ESP32-S3 has now overcome.

So I decided to integrate a native parser into my code: this way, a user can simply upload a file from their phone (via the dedicated internal HTML page) or from a computer and execute it immediately, without having to use an external tool for the conversion. Practically, this is done using standard C functions to separate the actual command from the argument at runtime:

char *cmd = strtok(line, " ");
char *arg = strtok(NULL, "");

if (strcmp(cmd, "DELAY") == 0 && arg) {
    int delay_ms = atoi(arg); 
    if (delay_ms > 0) { 
        vTaskDelay(pdMS_TO_TICKS(delay_ms)); 
    }
}

RAM Security: O(1) Space Complexity

But we all know that C doesn't joke around when it comes to memory allocation, so I tried to make the script reading phase as secure as possible. The underlying problem is that if a user decided to use a very long script (for example, uploading an entire binary file encoded in text), the M5Stick S3 would risk running out of the memory designated for the SRAM, resulting in a Kernel Panic followed by a crash and a device reboot.

To bypass this hardware limit, I thought of allocating a buffer that reads the uploaded file in small, controlled blocks with the help of the fgets() function, which is memory-safe by nature. This mathematically prevents a Buffer Overflow from occurring: even if the user uploads a malicious or malformed file with a single line 10,000 characters long, fgets will still only read the first 255 characters per cycle, safeguarding the microcontroller's stack.

If we look at the reading process from a space-complexity perspective, you can see that the way I decided to implement this mechanic has a space complexity of O(1); whereas the classic implementation would have had a complexity of O(N), as it would have loaded the entire file into RAM simultaneously.

// RAM consumption locked at only 256 bytes
char line[256];

// The file is strictly read and processed line by line
while (fgets(line, sizeof(line), f)) {
    trim_trailing(line); 
    if (strlen(line) == 0) continue;
    
    // ... start parsing for this specific line ...
}

Beyond abstraction: USB Protocol and Polling Rate

Despite all the numerous advantages that come from using the ESP32-S3, one "limit" remains: not being able to use libraries that allow a high level of abstraction, such as Arduino's Keyboard.h. This is a problem because, in the USB standard, a keyboard must regularly build and send 8-byte raw packets (divided into modifier mask, protocol byte, and key array) known as HID Reports.

Sending these reports falls under the polling operation, which is a mechanism by which the Host (the PC) cyclically queries the USB device to check if there have been any state changes. Specifically, I handle these cyclic requests with tud_hid_ready(), which checks if the USB Endpoint is free and if the PC has confirmed the reception of the previous packet. Through the while (!tud_hid_ready()) vTaskDelay(...) block, I prevent the ESP32 from overwriting its own buffer before the packets have actually traveled across the cable. Without this blocking check, the keystrokes would be "dropped" (lost), and a DuckyScript command like STRING powershell would be read by the victim PC as an incomprehensible pwsel.

State-Based Logic and the Auto-Repeat Trap

Added to this strict temporal "dance" of polling is one last huge engineering pitfall related to the nature of 8-byte reports. The most common cognitive error people run into is thinking that USB sends "print commands" (e.g., "type the letter R"). In reality, the USB architecture imposes a State-Based logic: the keyboard only communicates its electromechanical state to the PC at that precise moment.

When we send a report with a specific key, we are not telling it to print it, but we are communicating: "Right now, the user is physically pressing this key".

The operating system's driver receives this state. If the microcontroller were to immediately move to the next command without doing anything else, the PC would think the user's finger was glued to the key, triggering the operating system's Auto-Repeat (which would endlessly open dozens of windows or print RRRRRRRR...). To solve this problem, my firmware is forced to close the cycle by always sending a subsequent "zeroed" HID Report (passing the NULL array to TinyUSB). This tricks the PC, communicating that the key's physical contacts have finally been released (Key Release), allowing us to safely move on to the next letter.

Conclusion

Developing a low-level BadUSB emulator using esp_tinyusb is an immensely more educational challenge compared to using "pre-built" libraries. It forces you to study the anatomy of USB packets, understand how operating systems handle polling, and deal with the physical limits of a microcontroller's memory.

Now our digital "Swiss Army Knife" has its first real weapon, capable of uploading and launching payloads on the fly in total safety.

But a multi-tool isn't just a keyboard. What if we used the ESP32's antenna to intercept the invisible data floating in the air? In the next article, I'll show you how I configured the network interface in promiscuous mode to turn the ESP32 into a Wi-Fi Sniffer, capable of capturing raw packets and saving them directly to the file system in .pcap format, ready to be analyzed on Wireshark.

AArch64 Register Conventions: What Survives a Function Call—and Why

Thu, 03 Sep 2026 20:13:24 +0000

What happens to a register when you call a function?

On AArch64, the answer isn't "the CPU saves it." When you call a function, the CPU doesn't look at a register table and decide what to preserve. BL doesn't know about caller-saved or callee-saved registers. Those are ABI rules imposed on software, not behavior baked into the hardware.

Once you understand that distinction, the rest of the calling convention becomes much easier to reason about: the ABI tells the caller and callee who is responsible for preserving what. That's why some registers are caller-saved, some are callee-saved, and why a register's ABI category says nothing about how long a particular value will live.

When you write C++ code, the compiler decides whether a value lives in a register, on the stack, or nowhere at all after optimization. But under the hood, most scalar arithmetic and logical operations operate on register operands - and understanding the calling convention can make the difference between code that runs and code that performs.

If you've ever looked at compiler output for AArch64 and wondered why the compiler chose specific registers for specific values, this post is for you.

AArch64 vs ARM64: what's in a name?

AArch64 is Arm's official name for the 64-bit execution state and instruction set architecture introduced with Armv8-A. ARM64 is the colloquial term used in operating systems, toolchains, and developer communities (Linux refers to it as aarch64 in kernel sources, Apple calls it arm64). They refer to the same thing. This post uses AArch64 to match the official architecture documentation, but you'll encounter both names in the wild.

The big picture

AArch64 has 31 general-purpose registers (X0–X30), plus the special-purpose stack pointer SP and 32 128-bit SIMD/floating-point registers. That's a lot of registers - and beginners often see "32" in architecture documentation, so it's worth clarifying up front: there are 31 general-purpose registers, plus SP, which is a special-purpose register rather than an ordinary GPR (more on that later).

But not all registers are created equal. The calling convention - the set of rules that govern how functions pass arguments and return values - assigns specific roles to specific registers. Understanding this convention requires a key distinction that underpins everything else.

Caller-saved vs callee-saved: the conceptual key

The ABI divides registers into two categories based on what happens across a function call:

Caller-saved (also called caller-clobbered): The caller cannot assume these registers survive a call. If the caller needs a value in one of these registers after a call, it must save the value before the call and restore it afterward. The called function is free to overwrite them.
Callee-saved: If the callee modifies one of these registers, it must save the original value and restore it before returning. The caller can safely assume these registers are preserved across the call.

Keep these names in mind as obligations, not characteristics:

"Caller-saved" means the caller must protect a value if it needs it after a call.
"Callee-saved" means the callee must restore the incoming value before returning if it modifies the register.

Caller-saved and callee-saved are ABI properties, not hardware properties. The processor does not enforce these conventions; they are rules that separately compiled functions agree to follow. The CPU is perfectly happy to let any function overwrite X19 - it's the calling convention that says "if you modify it, you must restore it before returning."

A common misconception

A callee-saved register isn't inherently a "long-lived register." It is simply a register whose incoming value must survive a call if the callee modifies it. The compiler can put a short-lived value in X19, and it can put a long-lived value in X9 if that value doesn't cross a call. Register allocation is driven by liveness, register pressure, call boundaries, and cost models - not by which category a register falls into.

To make this precise, keep three separate concepts in mind:

Register volatility: what happens to the register across a call (caller-clobbered vs callee-saved).
Value liveness: whether a particular value is needed again later in the code.
Register allocation: which physical register the compiler chooses for a value.

These are three different concepts. A register can be caller-clobbered while holding a long-lived value, provided no call occurs while that value is live. A callee-saved register can hold a short-lived value. "Callee-saved" describes the register's contract, not the lifetime of the value stored in it.

Scope: what this article covers

This article focuses on the core AArch64 GPR and SIMD/FP register conventions used in ordinary AAPCS64 code. The current AAPCS64 also defines calling conventions for SVE and SME state - the Z0–Z31 scalable vector registers, P0–P15 predicate registers, the FFR, and the SME ZA/ZT0/FPMR state. These are outside the scope of this introduction.

The calling-convention register map

Here's the calling-convention register map as a quick overview. We'll walk through each group in detail below - remember, the full reference table lives in the cheat sheet at the end:

X0–X7 — Caller-clobbered: integer/pointer arguments and results
X8 — Caller-clobbered: indirect result location
X9–X15 — Caller-clobbered: temporary/scratch
X16–X17 — Caller-clobbered: IP0/IP1, linker/veneer scratch
X18 — Platform-dependent: platform register or caller-clobbered
X19–X28 — Callee-saved: general-purpose preserved state
X29 — Callee-saved: frame pointer / general-purpose register
X30 — Special: link register
SP — Callee-saved / special: stack pointer
V0–V7 — Caller-clobbered: FP/SIMD args and results
V8–V15 — Callee-saved, low 64 bits only: preserved FP/SIMD state
V16–V31 — Caller-clobbered: temporary FP/SIMD state
NZCV — Undefined: condition flags

X0–X7: arguments and results

X0–X7 are the primary general-purpose argument and result registers. For integer, pointer, and other appropriately classified arguments, the first eight argument-register slots use X0–X7 - note that "eight registers" does not necessarily mean "eight source-level arguments," because the AAPCS64 argument classification rules can cause arguments to be packed or passed differently. Floating-point and vector arguments normally go in V0–V7 instead, and aggregates can have more complex treatment depending on the ABI and argument types.

These registers are caller-saved (caller-clobbered). If a function wants to preserve their values across a call, it must save them itself. They aren't just arguments - they can also hold intermediate values between calls.

The following example is deliberately simplified to illustrate the calling convention; real compiler output will look different, but the register assignment principle is the same:

// Simplified illustration of argument passing
MOV     X0, #42        // first integer argument
MOV     X1, #100       // second integer argument
BL      my_function    // call - X0-X7 may be modified
// X0 contains the return value

This convention means that short, simple functions can be very efficient - no need to save and restore registers if you're just doing a quick computation.

X8: indirect results

X8 is not an ordinary ninth argument register. It is specifically used by AAPCS64 to carry the address of caller-allocated storage when a function result is returned indirectly. For example, a result that cannot be returned in the normal result registers may use indirect result return — the caller allocates the result memory and passes its address in X8. There is no requirement for the callee to preserve X8, and X8 is not part of the normal argument sequence.

The caller never passes X8 as an explicit argument in source code - the compiler handles it automatically when the return type requires it:

// Simplified illustration of indirect result
// Caller has allocated storage for the result.
// X8 points to that storage.
BL      get_large_struct
// The result has been written to the caller-provided storage.

X9–X15: caller-clobbered scratch registers

These are caller-clobbered registers available for any intermediate use. The important nuance: "caller-saved" doesn't mean "temporary" in the sense that they can only hold short-lived values. It means the caller cannot assume their values survive a call. A compiler may allocate a long-lived value to X9 if it can prove that no call occurs before the value is consumed - there's nothing in the ABI that prevents it.

// Simplified illustration of scratch register use
ADD     X9, X0, X1     // intermediate result
LSL     X10, X9, #3    // another intermediate
// X9 and X10 are caller-clobbered - a called function may overwrite them

X16–X17: IP0/IP1 and linker scratch

X16 and X17 are known as IP0 and IP1 - intra-procedure-call scratch registers. They have a special relationship with the linker and dynamic loader. The current AAPCS64 explicitly says X16/X17 can be used by call veneers and PLT code.

The important consequence is that X16 and X17 are not safe places to keep values across calls. A linker-generated veneer or PLT sequence may use them even when the source-level callee doesn't. If you're writing hand-written assembly that calls external functions, treat these registers as clobbered.

X18: platform register

X18 is the platform register. Its preservation and usage rules are defined by the platform ABI rather than by the base AAPCS64.

AAPCS64 says that a platform may reserve X18 for interprocedural state such as thread context. If the platform has no such requirement, X18 is an additional caller-saved register. Arm advises that platform-independent developers avoid X18 if possible.

For example, Windows reserves X18 for the Thread Environment Block (TEB), and in user mode it points to the TEB. Android reserves X18 for the Shadow Call Stack (SCS) pointer in hardened binaries - a security mechanism that keeps return addresses on a separate, protected shadow stack. Apple platforms assign their own role to X18 as well. Other platforms have their own rules, so don't assume X18 is freely available without checking the target ABI.

Portable assembly rule: don't use X18 unless you know the target platform ABI.

X19–X28: callee-saved registers

These registers are callee-saved - if a function modifies any of them, it must save their original values and restore them before returning. This is the opposite of the caller-saved convention.

The nuance: "callee-saved" doesn't mean the callee must use these registers. It means if it does use them, it must preserve them. The compiler decides whether to allocate a value to a callee-saved register based on liveness analysis, register pressure, and cost models - not because the ABI mandates it.

If a function keeps a value live across calls, the compiler may choose a callee-saved register. The called function is then required to preserve that register, so the caller doesn't need to save the value around every individual call. The trade-off is that the callee may need to save and restore it in its own prologue and epilogue:

// One possible prologue/epilogue pattern; real compiler-generated
// prologues vary with frame layout, optimization level, unwind
// requirements, and security features.
my_function:
    STP     X29, X30, [SP, #-16]!    // save frame pointer and link register
    STP     X19, X20, [SP, #-16]!    // save callee-saved registers we'll use

    // Because this function modifies X19/X20,
    // it must restore their incoming values before returning.
    MOV     X19, X0                   // preserve first argument across calls
    MOV     X20, X1                   // preserve second argument across calls

    BL      some_other_function       // X19 and X20 survive this call
    // ...

    LDP     X19, X20, [SP], #16      // restore callee-saved registers
    LDP     X29, X30, [SP], #16      // restore frame pointer and link register
    RET

To see why this matters, compare the two paths for a value you need again after a call:

Using caller-saved X9 means you must explicitly save the value before the call and restore it afterward.
Using callee-saved X19 means the responsibility moves into the callee: if the current function itself needs to use X19, it saves it once in its prologue. But any function you call must also preserve X19, so your value survives.

That distinction is the heart of why the ABI has both classes. Values that remain live across calls are often good candidates for callee-saved registers, but the compiler may instead spill, recompute, or otherwise transform the value depending on its cost model.

X29 and X30: frame pointer and link register

X29: frame pointer

X29 is conventionally used as the frame pointer (FP) when a frame pointer is maintained. Optimized code may omit the frame pointer and use X29 as a general-purpose callee-saved register instead - this depends on compiler options (-fno-omit-frame-pointer), debugging and unwinding requirements, and platform rules.

X30: link register

X30 is the link register (LR), and it gets a special role rather than a simple caller/callee classification. When BL (branch with link) executes, the CPU writes the return address into X30 before branching to the target. When the function returns with RET, it jumps to the address in X30.

The practical rule: a function that needs its incoming LR after making another call must preserve that LR. If a function makes another call, that call overwrites X30, so the function must save its incoming return address somewhere else - typically on the stack - if it still needs it to return.

A leaf function that makes no calls can often leave X30 untouched and return directly with RET, avoiding an LR save/restore.

When a frame pointer is used, X29 and X30 are commonly saved together.

Pointer Authentication and X30 security

In modern AArch64 environments (iOS, macOS, and hardened Linux builds), you will often see X30 handled with two additional instructions: PACIASP and AUTIASP. These are part of Armv8.3-A Pointer Authentication (PAC), a hardware security feature designed to prevent Return-Oriented Programming (ROP) and stack-smashing attacks.

Because X30 holds the return address, an attacker who overwrites the saved X30 on the stack can hijack execution when the function returns. PAC solves this by signing the pointer in X30 using a secret key and the current stack pointer (SP) as context before pushing it to memory:

my_function:
    PACIASP                         // Sign X30 using A-key and SP
    STP     X29, X30, [SP, #-16]!   // Push frame pointer and signed X30

    // ... function body ...

    LDP     X29, X30, [SP], #16     // Restore signed X30 from stack
    AUTIASP                         // Authenticate X30 against SP
    RET                             // Return to verified address

PACIASP (prologue): Computes a cryptographic signature from the value in X30 and SP, inserting it into the normally-unused upper bits of X30.
AUTIASP (epilogue): Re-computes the signature using the current SP and validates X30. If the stack was corrupted and the saved X30 was modified, AUTIASP replaces the signature with an invalid address pattern. When RET then attempts to execute, the CPU triggers an immediate translation fault rather than jumping to malicious code.

Crucially for backward compatibility, PACIASP and AUTIASP execute as NOP instructions on legacy Armv8.0 hardware, so binaries built with PAC enabled can still run safely on older AArch64 processors.

SP, XZR, and W registers

SP: stack pointer

SP is a special architectural register rather than an ordinary GPR, and it is not interchangeable with X0–X30. The AAPCS64 requires the stack pointer to be 16-byte aligned at public interfaces, and also requires alignment whenever memory is accessed via SP. AArch64 imposes additional restrictions on how SP can be used by instructions.

Importantly, this 16-byte SP alignment isn't only an ABI convention. The CPU itself enforces an architectural SP Alignment Check whenever SP is used as the base register in a load or store: if SP isn't 16-byte aligned at such an access, the hardware raises an alignment fault regardless of what the ABI says. The ABI rule and the architectural rule work together - the calling convention keeps SP aligned so the hardware check never trips on ordinary code.

AAPCS64 groups SP with the callee-saved registers, but that doesn't mean the callee must restore the exact incoming SP value instruction-for-instruction. The useful rule is: a function must restore SP to the required value before returning, and SP must remain properly aligned.

XZR: the zero register

XZR is the architectural zero register. Reads return zero; writes are discarded. Many instructions use register encoding 31 to mean either SP or XZR, depending on the instruction class: data-processing instructions treat encoding 31 as XZR, while memory instructions and branches treat it as SP.

There is therefore no X31 register you can use like X0–X30; encoding 31 is interpreted as SP or XZR depending on the instruction. This eliminates a common beginner question - there is no architectural X31 general-purpose register.

W registers: the 32-bit view

Each X register also has a 32-bit W-register view. For example, W0 refers to the low 32 bits of X0.

A key AArch64 rule is that writing a W register zeroes the upper 32 bits of the corresponding X register:

MOV     W0, #42
// X0 is now 0x000000000000002A

This is worth remembering when reading compiler output: W0 and X0 aren't separate physical registers. You'll encounter w0, w1, and so on constantly in disassembly.

SIMD and floating-point registers

The V0-V31 registers are 128-bit SIMD/vector registers that also serve as floating-point registers. The calling convention divides them similarly to the general-purpose registers.

Each V register has several aliases depending on the width you're accessing:

V0: Full 128-bit register
Q0: Same 128 bits (quadword)
D0: Low 64 bits (doubleword)
S0: Low 32 bits (singleword)
H0: Low 16 bits (halfword)
B0: Low 8 bits (byte)

V0–V7: argument and return registers

These are the primary SIMD/floating-point argument and return registers. Like their general-purpose counterparts, they're caller-clobbered.

// Simplified illustration: assume S0 and S1 already contain the arguments
BL      my_float_func
// S0 (low 32 bits of V0) contains the return value

V8–V15: partially preserved

Only the low 64 bits of V8–V15 (D8–D15) are callee-saved. That means: if a function modifies the bottom 64 bits of one of these registers, it must restore them before returning; larger values are the caller's responsibility. If you need a full 128-bit value to survive a call, you can't simply put it in V8–V15 and rely on the ABI - you must preserve the upper 64 bits yourself.

V16–V31: temporary registers

These are fully caller-clobbered, like the general-purpose scratch registers. Use them for intermediate SIMD computations that don't need to survive function calls.

Condition flags: NZCV

NZCV is the condition flags register. It holds four single-bit flags:

N (Negative): Set to 1 if the result of the last operation was negative
Z (Zero): Set to 1 if the result was zero
C (Carry): Set to 1 if the last operation produced a carry out
V (Overflow): Set to 1 if the last operation produced a signed overflow

NZCV is modified by flag-setting instructions such as ADDS, SUBS, ANDS, and by comparison instructions such as CMP, CMN, and TST. Ordinary arithmetic instructions such as ADD and SUB do not modify NZCV - you must explicitly use the flag-setting variant.

NZCV is not preserved across a function call; its values are undefined at a public interface. It's also ordinary scratch state within a function: any flag-setting instruction can replace the previous condition flags.

This matters for inline assembly: if your inline assembly modifies condition flags in a way the compiler must not assume is preserved, declare the appropriate "cc" clobber (in GCC/Clang extended inline assembly). Conversely, if your assembly reads condition flags, you need to ensure they've been set appropriately before your block.

// Simplified illustration of NZCV in inline asm
CMP     X0, #0          // flag-setting comparison: sets NZCV
B.NE    is_nonzero       // conditional branch based on Z flag
// ...

What this looks like in compiler output

When you examine compiler output, these conventions explain the register allocation patterns you see. Compilers often use caller-clobbered registers for values that don't need to survive a call, because doing so avoids unnecessary save/restore work. Values that are live across call boundaries may end up in callee-saved registers, but the compiler may instead spill to the stack, recompute the value, or transform the code entirely - register allocation is driven by a cost model, not a simple rule.

Consider a concrete example:

int bar(int);

int foo(int a, int b) {
    int x = a + b;
    return bar(x) + x;
}

x is live across the call to bar() - it's used again afterward. Therefore, the compiler needs some way to preserve its value across the call. It might use a callee-saved register, spill it to the stack, recompute it, or transform the expression. So conceptually:

a, b → x0, x1
x → may move to x19, because x is live across the call to bar()

A complete, valid implementation using a callee-saved register would also have to preserve the caller's incoming X19 in its prologue:

foo:
    STP     X19, X30, [SP, #-16]!     // preserve caller's X19 and our LR

    ADD     W19, W0, W1               // x = a + b, kept in W19
    MOV     W0, W19                   // pass x as the argument
    BL      bar                       // call - x survives in W19
    ADD     W0, W0, W19               // result + x

    LDP     X19, X30, [SP], #16       // restore X19 and LR
    RET

Note what this makes explicit: using a callee-saved register doesn't make the register free. It transfers the preservation responsibility to the current function, which must save and restore X19 around its own body. That's the heart of the distinction between the two classes.

Also notice how the stack is managed: STP X19, X30, [SP, #-16]! pushes two 64-bit registers at once (16 bytes total, hence the #-16 offset), and LDP pops them back together. Storing registers in pairs of 64-bit registers is the standard AArch64 idiom - it's precisely how the code keeps SP moving in 16-byte units, maintaining the required alignment without extra padding. Because the pair takes exactly 16 bytes, the compiler never has to insert alignment holes.

The compiler can also use caller-saved registers for long-lived values when it can prove no call intervenes. "Caller-saved" describes what happens across calls, not how long a value lives.

Writing inline assembly

With GCC/Clang-style extended inline assembly, ABI rules are only part of the contract. You must also tell the compiler which registers, memory, and condition flags your assembly modifies. An instruction sequence can obey the AArch64 ABI and still be invalid inline assembly if its clobbers and operands are incorrectly declared.

Important distinction: in inline assembly the compiler - not your assembly code - is responsible for allocating registers around the asm block. This is fundamentally different from standalone assembly, where you own every register decision.

Specifically:

Describe inputs, outputs, and clobbers using operands and constraints, allowing the compiler to allocate registers unless a specific register is genuinely required.
Use the "cc" clobber if your assembly modifies condition flags.
List any registers your assembly clobbers, or let the compiler allocate them via operand constraints.
Declare memory effects if your assembly accesses memory the compiler doesn't know about.

Don't manually save a caller-saved register in inline asm just because it is caller-saved. Your job is to describe the inputs, outputs, and clobbers accurately. If you need a particular register preserved, model that requirement through operands/constraints rather than silently saving and restoring arbitrary registers.

If your asm modifies a register that the compiler has allocated for something else and you don't tell the compiler, you can break the program even though you didn't violate the ABI. This is the key distinction between standalone assembly and inline assembly embedded in compiler-generated code.

AAPCS64 vs platform ABI

The register conventions described above come from the Arm Procedure Call Standard for AArch64 (AAPCS64), which defines the core calling convention. But AAPCS64 is the base layer - not the whole story. The hierarchy looks like this:

AArch64 architecture
        ↓
    AAPCS64
        ↓
    platform ABI
        ↓
language/runtime/toolchain conventions

Every platform builds on AAPCS64 with its own platform ABI that adds rules specific to the operating system or runtime:

Linux / ELF: AArch64 Linux user-space ABIs generally build on AAPCS64, with additional ELF and platform conventions. The exact ABI also depends on the toolchain and ABI variant being used.
Windows on AArch64: Defines additional ABI rules, including reserving X18 for platform use and requiring specific unwind information.
Apple platforms: Apple platforms build on AAPCS64 with additional platform and toolchain conventions. Apple platforms may also add security-related conventions such as pointer authentication, depending on the target and execution environment. If you're writing hand-written assembly, consult the ABI documentation for the specific Apple target rather than assuming that base AAPCS64 is the entire contract.

Beyond the platform ABI, C++ adds additional ABI requirements beyond plain C argument passing, and things like exception handling, TLS, unwind information, and toolchain-specific conventions can introduce further platform-specific rules.

The practical consequence: when writing hand-written assembly or inline assembly, you need to know not just the AAPCS64 register rules, but also the platform-specific additions. Code that works on one platform may break on another if platform-specific register conventions are violated.

Practical cheat sheet

Here's the compact cheat sheet - the part you'll want to bookmark:

Register	Across a call	Main purpose
X0–X7	❌	Arguments/results
X8	❌	Indirect result address
X9–X15	❌	Scratch
X16–X17	❌	Linker/veneer scratch
X18	Platform-dependent	Platform register or caller-clobbered
X19–X28	✅	Callee-saved
X29	✅	Frame pointer / callee-saved GPR
X30	Special	Link register
SP	✅ (special)	Stack pointer
V0–V7	❌	FP/SIMD args/results
V8–V15	⚠️	Low 64 bits callee-saved
V16–V31	❌	FP/SIMD scratch
NZCV	❌	Condition flags; values are undefined across public interfaces

Conclusion

So what survives a function call?

X19–X29 survive, because the callee must preserve them.
Only the low 64 bits of V8–V15 are guaranteed to survive.
X0–X17 and V0–V7/V16–V31 are generally caller-clobbered.
X30 must be preserved by a non-leaf function if it needs its incoming return address.
NZCV is not something you can carry across a public call - its values are undefined there.

But the deeper lesson is that the ABI describes register obligations, not value lifetimes. The compiler decides where a live value actually goes, choosing between callee-saved registers, spilling, or recomputation based on a cost model. And none of this is enforced by the hardware - it's a contract between separately compiled functions.

Next time you look at compiler output for AArch64, you'll know why certain registers are chosen and what happens to them across function boundaries.

Official documentation and further reading

The ABI specification is a moving target - the current AAPCS64 is the 2025Q4 release, issued in January 2026. Link to the current Arm ABI repository rather than an old developer.arm.com PDF:

Arm ABI repository — AAPCS64 - The authoritative home of the current AAPCS64 and other Arm ABIs
Arm Architecture Reference Manual for AArch64 - The authoritative source for the instruction set and register definitions
Arm System V ABI for AArch64 - The ELF/generic System V conventions that build on AAPCS64
Microsoft ARM64 ABI conventions - Microsoft's platform-specific conventions, including X18 and unwind requirements
Apple Platform ABI for AArch64 - Apple's platform-specific conventions
Linux kernel AArch64 architecture - Platform-specific details for Linux on AArch64

Why the Power-of-Two Trick Works for Binary Fractions (And Why It Breaks for Everything Else)

Sat, 11 Jul 2026 13:03:17 +0000

As a 300-level Mechatronics Engineering student studying Digital Electronics, I came across something that changed the way I think about binary conversions — not just as steps to memorize, but as operations with real mathematical meaning underneath them.

Understanding Binary Coded Decimal (BCD) First

Before getting to the trick, it helps to understand Binary Coded Decimal (BCD), specifically the weight codes assigned to binary digits. In a 4-bit system, the weights are 8, 4, 2, 1 (the 8421 code). In a 3-bit system, they are 4, 2, 1 (the 421 code). These codes make binary-to-decimal conversion straightforward.

For example, converting 1111 in base 2 to decimal is simply:

8 + 4 + 2 + 1 = 15

The same logic extends to binary numbers with a fractional part. To convert 1111.0111 from base 2 to decimal, you group the digits in 4-bit sections and apply the weights:

Whole part:      1111 → 8 + 4 + 2 + 1 = 15
Fractional part: 0111 → 0 + 4 + 2 + 1 = 7
Result: 15.7 in decimal

This direction — binary to decimal — is fairly intuitive once you understand BCD weights. The real challenge comes when you go the other way.

The Problem with Decimal to Binary Conversion

Converting a decimal fraction to binary using the standard repeated multiplication method works, but it is long and error-prone. The method requires you to multiply the fractional part by 2 repeatedly, recording the integer part each time and discarding it, until nothing remains. For some numbers this goes on for many steps, and one mistake anywhere gives you a wrong answer.

That frustration is what sparked the idea I want to share here.

The Fraction Shortcut

What if instead of using repeated multiplication, you convert the decimal fraction to a fraction first, then use BCD weight codes to handle the conversion? This connects directly to the concept of fixed-point arithmetic used in embedded systems.

Example 1: Converting 0.25 to Binary

0.25 as a fraction is 1/4. Assuming a 4-bit operation:

Numerator: 1 in binary (using 8421 BCD) → 0001
Denominator: 4 in binary → 0100

Dividing 0001 by 0100 in binary gives 0.01₂.

Tip: Dividing by a power of 2 in binary is equivalent to shifting the binary point to the left — the same way dividing by 100 in decimal shifts the decimal point two places left.

Using the standard multiplication method on 0.25 gives the same answer: 0.01₂. But the fraction method shows why — it is not magic, it is a point shift.

Example 2: Converting 0.625 to Binary

0.625 as a fraction is 5/8.

Numerator: 5 in binary → 101
Denominator: 8 in binary → 1000

Dividing 101 by 1000 gives 0.101₂.

Verified with the multiplication method: 0.101₂ ✓

Example 3: Converting 0.4375 to Binary

0.4375 as a fraction is 7/16.

Numerator: 7 in binary → 0111
Denominator: 16 in binary → 10000

Using BCD weights (16, 8, 4, 2, 1), dividing gives 0.0111₂.

Verified with the multiplication method: 0.0111₂ ✓

Where This Breaks Down

This shortcut works if and only if the denominator is a power of 2 — that is, 2, 4, 8, 16, 32, and so on.

Try it with 0.2, which as a fraction is 1/5. The denominator is 5, and 5 in binary is 101. Since 101 is not a power of 2, there is no clean point shift. You would have to perform full binary long division, and the result never terminates — it repeats forever as 0.00110011...

Note: This is the same reason 0.1 + 0.2 does not exactly equal 0.3 in most programming languages. The decimal 0.1 is 1/10, and since 10 is not a power of 2, it cannot be represented exactly in binary. This is not a bug — it is a structural limitation of representing base-10 fractions in a base-2 system. Learn more about this in the IEEE 754 floating-point standard.

Conclusion

The power-of-two fraction shortcut offers a clearer, more intuitive path for converting certain decimal fractions to binary. Rather than blindly following the repeated multiplication algorithm, converting the decimal to a fraction and applying BCD weight codes reveals the actual mathematical operation taking place — a simple binary point shift. This works cleanly for denominators that are powers of 2 (such as 2, 4, 8, 16), giving the same result as the standard method while making the reason visible. However, it has a clear limitation: denominators that are not powers of 2 produce non-terminating binary fractions, requiring long division instead. Understanding this boundary does more than just solve conversion problems — it explains one of the most well-known quirks in floating-point arithmetic. The goal of this article was never to introduce a new method, but to show that understanding the structure behind an algorithm is always more powerful than memorizing its steps.

8 Arduino coding habits that separate hobby sketches from real products

Tue, 26 May 2026 05:54:48 +0000

Most Arduino tutorials teach you to blink an LED and stop there. The jump from "it works on my desk" to "it ran for 6 months without crashing" is where most hobby projects die. Here are eight habits that get you across that gap - most of them I learned the hard way.

1. Stop using `delay()`

delay(1000) halts your entire program for a full second. Nothing else runs - not your buttons, not your sensor reads, not your serial output. Use millis() instead:

unsigned long lastBlink = 0;
const unsigned long BLINK_INTERVAL = 1000;

void loop() {
  if (millis() - lastBlink >= BLINK_INTERVAL) {
    lastBlink = millis();
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
  }
  // your other code keeps running here
}

Once you internalize this pattern, every project gets better.

2. Avoid the `String` class on AVR boards

String fragments the tiny heap on Uno/Nano/Mega. Your sketch runs fine for an hour, then crashes mysteriously at 3 AM. Use fixed-size char buffers:

char buf[32];
snprintf(buf, sizeof(buf), "Temp: %d C", temperature);
Serial.println(buf);

On ESP32 with megabytes of RAM, String is fine. On a 2KB AVR, it's a timebomb.

3. Wrap string literals in `F()`

Every Serial.println("Hello world") copies that string into precious RAM at boot. The F() macro keeps it in flash:

Serial.println(F("System ready"));  // costs 0 bytes of RAM

On a 2KB Uno, this single change can free hundreds of bytes.

4. Be explicit about integer sizes

int is 16 bits on AVR and 32 bits on ESP32/SAMD. Code that works on an Uno silently breaks on an ESP32 (or vice versa) because of overflow. Use <stdint.h> types:

uint8_t  pin = 7;
uint16_t adcValue;
uint32_t timestamp;
int16_t  signedTemp;

Your future self porting between boards will thank you.

5. Use `INPUT_PULLUP` instead of external resistors

You almost never need a physical pull-up resistor for a button. The AVR/ESP32 has them built in:

pinMode(BUTTON_PIN, INPUT_PULLUP);
// button pressed = LOW, released = HIGH

Less wiring, fewer parts, fewer things to debug.

6. Keep ISRs tiny and mark shared variables `volatile`

Interrupt service routines should set a flag and exit. Do the real work in loop():

volatile bool buttonPressed = false;

void IRAM_ATTR onButton() {   // IRAM_ATTR for ESP32; omit on AVR
  buttonPressed = true;
}

void loop() {
  if (buttonPressed) {
    buttonPressed = false;
    handleButton();
  }
}

Calling Serial.print() inside an ISR is a common rookie mistake - it can deadlock the whole board.

7. Model state machines explicitly

If your project has modes - idle, recording, transmitting, error - don't nest five if statements. Use an enum:

enum class State { Idle, Recording, Transmitting, Error };
State state = State::Idle;

void loop() {
  switch (state) {
    case State::Idle:         handleIdle(); break;
    case State::Recording:    handleRecording(); break;
    case State::Transmitting: handleTransmitting(); break;
    case State::Error:        handleError(); break;
  }
}

This one habit makes debugging an order of magnitude easier.

8. Enable the watchdog for anything deployed

A device sitting in your garage with no debugger needs to recover from its own bugs. On AVR:

#include <avr/wdt.h>
void setup() { wdt_enable(WDTO_8S); }
void loop()  { wdt_reset(); /* your code */ }

If loop() hangs for more than 8 seconds, the chip reboots itself. Beats driving across town to power-cycle.

A bonus: `setup()` and `loop()` are just `main()`

The Arduino IDE hides it, but underneath it's plain C++. You can - and should - define classes, split code across .h/.cpp files, and use namespaces. The .ino file is just convention.

If you want to go deeper on the jump from hobby projects to real embedded products, that's what we write about over at Make-it.ai. Tools for hardware design, project breakdowns, and lessons from makers actually shipping things in the wild.

What's the Arduino habit you wish you'd picked up earlier? Drop it in the comments - I'm curious which of these resonate and which ones people disagree with.

Ditch the Clunky GUIs: Meet ComChan, the Blazingly Fast Rust Serial Monitor

Fri, 15 May 2026 15:58:16 +0000

If you spend any significant amount of time doing embedded systems development, you know the drill. You write your firmware, flash the microcontroller, and then… you stare at a serial monitor.

For years, the options have been a bit of a mixed bag. You have the classic Arduino IDE Serial Monitor (which is functional but basic), bloated GUI protocol analyzers that eat up RAM, or simple CLI tools like minicom that get the job done but lack modern developer quality-of-life features.

As someone who lives in the terminal—relying on tools like Neovim and terminal multiplexers—I wanted a serial monitor that actually fit into a keyboard-driven, modern workflow. I wanted something lightweight, visually clean, and capable of handling complex data without breaking a sweat.

So, I built ComChan (Communication Channel).

What is ComChan?

ComChan is a minimal, blazingly fast serial monitor and plotter built entirely in Rust. It’s designed specifically for embedded systems engineers who want powerful data visualization and logging without leaving the command line.

Because it's written in Rust, it’s memory-safe, incredibly fast, and runs natively across Linux, Windows, and macOS.

Here is a look at the features that make ComChan stand out from the crowd.

1. The Terminal-Based Serial Plotter

Sometimes, raw text isn't enough. When you are debugging an IMU, reading ADC values, or tracking temperature sensors, you need to see the data visually.

Instead of exporting data to Excel or firing up a heavy GUI application, ComChan features a built-in TUI (Terminal User Interface) plotter. You simply pass the --plot flag, and ComChan will automatically parse your incoming numeric data, assign legends, and graph multiple sensor channels in real-time—right inside your terminal.

Found a spike you want to investigate? You can hit Ctrl+S to instantly export the current plot frame as a clean SVG file.

Here is how it'll look like

2. Time Travel with Session Replay

This is perhaps my favorite feature. Debugging intermittent hardware anomalies is a nightmare because you can't always recreate the exact physical conditions that caused the bug.

ComChan introduces Session Replay. You can log your raw serial output to a .log or .csv file during a test run. Later, you can run comchan --replay <file> and the tool will parse the timestamps and play the data back to you in real-time.

It perfectly recreates the exact timing of the original hardware run. You can even replay a log file directly into the visual Plotter to analyze the anomaly visually, without needing the physical microcontroller plugged in.

3. Continuous CSV Streaming

If you are doing data collection for research or analysis, ComChan can automatically parse your incoming numeric telemetry and stream it directly into a clean, multi-column .csv file on the fly.

The best part? This works concurrently. You can stream to a CSV in the background while actively watching the data on the TUI Plotter.

4. Built for the Modern Embedded Workflow

ComChan includes several smaller features designed specifically to remove friction from the embedded workflow:

Auto-Detection: Tired of typing /dev/ttyUSB0 or COM3? Just use comchan --auto and it will automatically find and connect to your active USB serial device.
Zephyr RTOS Support: If you work with Zephyr, ComChan has a dedicated --zephyr shell mode that handles its specific echo and prompt behaviors cleanly.
Auto-Recovery: If you accidentally unplug your device or reset the power, ComChan won't crash. It detects the broken pipe and gracefully waits to reconnect when the hardware comes back online.
Configuration Files: Save your favorite baud rates, data bits, and parity settings in a .toml file so you don't have to pass a dozen flags every time you launch.

The "Brain Made" Philosophy

While AI tools are great for scaffolding tests or micro-optimizations, the core architecture, TUI design, and feature logic of ComChan are entirely human-crafted. It’s built to solve real pain points that I experience daily when working with memory-safe embedded development on ESP32s and RP2040s.

Try It Out

If you are ready to upgrade your embedded debugging workflow, ComChan is incredibly easy to install.

If you have Cargo installed:

cargo install comchan

For Arch Linux users, it's available on the AUR:

yay -S comchan

You can check out the full source code, read the documentation, and contribute on GitHub: Vaishnav-Sabari-Girish/ComChan

Drop a star if you find it useful, and let me know what features you’d like to see next (a Hex Dump mode is already on the roadmap!). Happy debugging!

Interrupt Management in ARM Cortex-M

Mon, 06 Apr 2026 15:15:30 +0000

Interrupts is the must-known concept in embedded programming. So I wanna explain the interrupt management in ARM Cortex-M in this tutorial.

ARM architecture distinguishes between the two types: interrupt and system exception. Interrupts are primarily sourced by external hardware like UART that warns about arrival of data. System exceptions are more software-related and caused by ARM Cortex internal.

Interrupts and system exceptions are exchangeably used. But even if both of these do same thing (especially in programming), the differences are important for us, engineers!

I'll use "interrupt" word for both terms further, if otherwise declared.

Before diving into interrupts, you need to understand the general execution workflow of ARM Cortex. There are two types of execution modes: thread and interrupt. After resetting the microcontroller, execution flow starts in thread mode so that if you want to use interrupts, you need to enter the interrupt mode. But how?

When you flash your firmware into microcontroller (base address of 0x08000000, in case), ARM Cortex starts to execute the firmware's machine instructions in thread mode. If you want to use any interrupt, you have to explicitly say it to ARM Cortex by using Interrupt Service Routines (ISRs). ISRs are actually standard C functions, but have the special signatures. I'm gonna explain it later.

The most important question about interrupts is that why do we need interrupts?

The answer: Interrupts are the source of multiprogramming!

Interrupts give us second execution flow besides the main flow (executed in thread mode by default). It also gives the context switch mechanism for RTOS. I will explain it lastly.

ARM Cortex has a special hardware called Nested Vectored Interrupt Controller (NVIC). It handles and manages the all interrupt usage. Below is the its simple schematic:

Another important dedicated hardware is the EXTI Controller. The peripheral interrupts in the microcontroller directly are connected to NVIC. But If you want to use interrupts over microcontroller pins (like detecting rising or falling edge of a button), you have to use EXTI lines. Microcontroller pins are grouped and tied to specific EXTI lines. Please look at the reference manual to find it.

We have many different types of interrupts. For now, let's look at these:

ARM Cortex has defined 15 fixed system exceptions (coming from internal of Cortex). But microcontroller vendors specify also variable-length interrupts (coming from external of Cortex). For example, STM32 series microcontrollers allow up to 256 interrupts.

But where are located these interrupts? The answer is the at vector table.

The vector table is an array of word data inside the system
memory, each representing the starting address of one exception type [1].

If you've flashed any firmware into microcontroller over OpenOCD + GDB, you've seen probably the this vector table. If you've not, let's see it exactly.

I have STM32F446RE microcontroller and ST-LINK connection. I've compiled a firmware (firmware.elf) to flash it. Open a terminal and type:

$ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

And open the second terminal and type:

$ arm-none-eabi-gdb firmware.elf

Lastly, type these into GDB session:

(gdb) target remote localhost:3333
(gdb) monitor reset halt
(gdb) load

After flashed the firmware into microcontroller, you will see:

Loading section .isr_vector, size 0x1c4 lma 0x8000000
Loading section .text, size 0x1080 lma 0x80001d0
Loading section .rodata, size 0x10 lma 0x8001250
Loading section .init_array, size 0x4 lma 0x8001260
Loading section .fini_array, size 0x4 lma 0x8001264
Loading section .data, size 0x10 lma 0x8001268
Start address 0x80011d0, load size 4716
Transfer rate: 9 KB/sec, 786 bytes/write.

Yeah! You see the interrupt vector table (_.isr_vector_) section was flashed at the base address of flash memory and other sections after the vector table. If you use any type of interrupt, the ARM Cortex gets the corresponding ISR handler from there so that ARM Cortex exactly knows the ISR handler addresses. You just need to select the required ISR handler function!

As I said before, ISR handlers are special type of C functions. But why? Because the handlers have predefined function prototypes. You have to use these function prototypes. Otherwise, ARM Cortex cannot find it and treated as normal C functions, not the ISR handlers.

These predefined handler prototypes are stored in the startup code. For STM32F446RE, it is _startup_stm32f446xx.S_ file. Below is a part of this startup code:

(...)

  .word  Reset_Handler
  .word  NMI_Handler
  .word  HardFault_Handler
  .word  MemManage_Handler
  .word  BusFault_Handler

(...)

  .word     CAN1_TX_IRQHandler                /* CAN1 TX                      */                         
  .word     CAN1_RX0_IRQHandler               /* CAN1 RX0                     */                          
  .word     CAN1_RX1_IRQHandler               /* CAN1 RX1                     */                          
  .word     CAN1_SCE_IRQHandler               /* CAN1 SCE                     */                          
  .word     EXTI9_5_IRQHandler                /* External Line[9:5]s          */                          
  .word     TIM1_BRK_TIM9_IRQHandler          /* TIM1 Break and TIM9          */         
  .word     TIM1_UP_TIM10_IRQHandler          /* TIM1 Update and TIM10        */         
  .word     TIM1_TRG_COM_TIM11_IRQHandler     /* TIM1 Trigger and Commutation and TIM11 */
  .word     TIM1_CC_IRQHandler                /* TIM1 Capture Compare         */                          
  .word     TIM2_IRQHandler                   /* TIM2                         */                   
  .word     TIM3_IRQHandler                   /* TIM3                         */                   
  .word     TIM4_IRQHandler                   /* TIM4                         */                   
  .word     I2C1_EV_IRQHandler                /* I2C1 Event                   */                          
  .word     I2C1_ER_IRQHandler                /* I2C1 Error                   */                          
  .word     I2C2_EV_IRQHandler                /* I2C2 Event                   */                          
  .word     I2C2_ER_IRQHandler                /* I2C2 Error                   */          

(...)

At the beginning, I've stated that interrupts are the source of multiprogramming. This is core logic behind the RTOS!

RTOSes use the interrupts to create many tasks. In classic firmware written with RTOS, there are many tasks that the RTOS kernel have to handle and manage. You can think that task in the firmware corresponds to process in the computers.

The RTOS kernel needs to execute these tasks in order and with same time-slice so that the kernel cuts the one task execution and passes to the next task execution using context switches. This is done by using interrupts. For example, FreeRTOS kernel uses SVC and PendSV interrupts specificly to make the contex switch. Apart from that, the RTOS kernel uses also the SysTick interrupt to give the equal execution time to each task.

Got it. I've explain the interrupt management in ARM Cortex-M in general. I put the some references below. You can look at the interrupts and similar topics in there.

References:

[1]. Yiu J., The Definitive Guide to The ARM Cortex-M3, Second Edition, Newnes, page 36.
Noviello C., Mastering STM32, 0.26 Release, Leanpub

How to build a firmware using Makefile?

Mon, 06 Apr 2026 15:13:09 +0000

In embedded programming, we trust IDEs like STM32CubeIDE, Keil or so on. These IDEs give us just some buttons and UIs to build, flash, and debug the source code that we've written for a MCU. But, I think that every engineer that works on this field have to know that how these steps are made by hand.

In this tutorial, I will show building a firmware written for STM32F446RE MCU with just using a single Makefile.

Below is the project directory:

$ tree
.
├── bin/
├── drivers/
│   ├── CMSIS/
│   ├── STM32F446RETX_FLASH.ld
│   └── STM32F4xx_HAL_Driver/
├── lib/
├── Makefile
└── src/
    ├── it.c
    ├── main.c
    ├── main.h
    └── peripheral.c

Firstly, which libraries do we need to have?

HAL library
CMSIS library
Linker script
Startup/system code
arm-none-eabi-* tools

I've put the all required libraries/scripts into /drivers directory. Please download these using:

$ git clone --recurse-submodules https://github.com/STMicroelectronics/STM32CubeF4.git
$ sudo apt install gcc-arm-none-eabi

In here, HAL library is used to program the peripherals and CMSIS for ARM-Cortex itself. These are the most important libraries that we have to get.

Apart from that, we also need some special files. First is the linker script. It includes the memory layout of microcontroller. Sometimes, it comes from above command. But if you cannot find it there, please install it externally. Another file is the startup code. It's written in Assembly language. As its name suggests, it's the first code that runs in microcontroller. Basically, it includes the Reset_Handler and a branch that jumps into main() function in your source code. Also system code includes the some generic and general definitions.

After downloaded and explained the required ones, Let's write the Makefile step by step:

1. Toolchain definitions

CC        := arm-none-eabi-gcc
OBJCOPY:= arm-none-eabi-objcopy
SIZE:= arm-none-eabi-size
RM        := rm -f
FILE:= file

2. MCU-specific definitions

DEVICE_FAMILY     := STM32F4xx
DEVICE_MODEL     := STM32F446xx
DEVICE_VARIANT     := STM32F446RETx

3. Compiler and linker flags

CORTEX_FLAGS     := -mthumb -mcpu=cortex-m4 -mfpu=fpv4-sp-d16 -mfloat-abi=hard
COMMON_FLAGS     := -g3 -Os -ffunction-sections -fdata-sections -Wall
AS_FLAGS             := -x assembler-with-cpp

In here, we've defined some flags:

-mthumb means that the firmware uses thumb (16-bit) instruction set.
-mcpu=cortex-m4 means the ARM-Cortex series itself.
-mfpu=fpv4-sp-d16 and -mfloat-abi=hard means that floating-point operations can be done in the firmware.

4. Include paths

MAIN_INC:= ./src
CMSIS_INC:= ./drivers/CMSIS/Include
CMSIS_DEV_INC:= ./drivers/CMSIS/Device/ST/STM32F4xx/Include
HAL_INC:= ./drivers/STM32F4xx_HAL_Driver/Inc
CMSIS_DSP_INC:= ./drivers/CMSIS/DSP/Include

In here, we specified the header files that are used in the source code.

5. Source and special files

MAIN_SRC:= $(wildcard ./src/*.c)
HAL_SRC:= $(wildcard ./drivers/STM32F4xx_HAL_Driver/Src/*.c)
SYSTEM_SRC:= ./drivers/CMSIS/Device/ST/STM32F4xx/Source/Templates/system_stm32f4xx.c
STARTUP_CODE:= ./drivers/CMSIS/Device/ST/STM32F4xx/Source/Templates/gcc/startup_stm32f446xx.S
LINKER_SCRIPT:= ./drivers/STM32F446RETX_FLASH.ld

6. Sorthands and build definitions

DEFINES:= -D$(DEVICE_FAMILY) -D$(DEVICE_MODEL) -D$(DEVICE_VARIANT) \
-DUSE_HAL_DRIVER

SOURCES:= $(MAIN_SRC) $(HAL_SRC) $(SYSTEM_SRC)
OBJECTS:= $(notdir $(patsubst %.c,%.o,$(SOURCES))) startup_stm32f446xx.o
INCLUDES:= -I$(MAIN_INC) -I$(CMSIS_DEV_INC) -I$(CMSIS_INC) -I$(HAL_INC) \
-I$(CMSIS_DSP_INC)

CFLAGS:= $(CORTEX_FLAGS) $(COMMON_FLAGS) $(DEFINES) $(INCLUDES)
AFLAGS:= $(CORTEX_FLAGS) $(AS_FLAGS) $(DEFINES) $(INCLUDES)
LDFLAGS:= $(CORTEX_FLAGS) -T $(LINKER_SCRIPT) \
-Wl,--gc-sections,--relax --specs=nano.specs --specs=nosys.specs \
   -Wl,--start-group -lc -lm -lnosys -Wl,--end-group

In here, I mostly did the string operations and manipulations. But some points are interesting and need some explanations:

Firstly, I've grouped the sources and libraries and converted the source file suffixes into object file formats.
Also, I've created three total flags that will be used for compiling, assembling, and linking phases.
In linker flags, I put the linker script. As you noticed, this step will be done after the compiling the source files. I also linked the some libraries. -lc is the standard C library. In firmware, we use often string manipulation functions (strlen(), strcat(), strcpy() or so on), snprint(), memset(), or similar ones. -lm is the math library as you know. -lnosys means that I'm just implementing the bare-metal firmware, there is no such as kernel or fully OS.

7. Output files

FIRMWARE_ELF:= firmware.elf
FIRMWARE_BIN:= firmware.bin

Generally, we use the ELF file when flashing and debugging. ELF executable includes the both machine code, metadata, debug information, symbol table or similar stuffs. In contrast, BIN executable just includes the machine code. If you look at the size of both, you will use the ELF executable is much bigger!

8. The recipe

.PHONY: all

all:
@echo "-------------------------------------"
@echo "----- Building the source files -----"
@echo "-------------------------------------"
@$(CC) $(AFLAGS) -c $(STARTUP_CODE)
@$(CC) $(CFLAGS) -c $(SOURCES)

@echo "\n------------------------------------"
@echo "----- Linking the object files -----"
@echo "------------------------------------"
@$(CC) $(LDFLAGS) $(OBJECTS) -o $(FIRMWARE_ELF)
@$(OBJCOPY) -O binary $(FIRMWARE_ELF) $(FIRMWARE_BIN)
@$(RM) $(OBJECTS)

@echo "\n-------------------------------------"
@echo "----- The firmware memory usage -----"
@echo "-------------------------------------"
@$(SIZE) $(FIRMWARE_ELF)

@echo "\n-------------------------------------"
@echo "----- The firmware binary format ----"
@echo "-------------------------------------"
@$(FILE) $(FIRMWARE_ELF)

Lastly, run the Makefile:

$ make

That's it . You've built the both firmware.elf and firmware.bin.

You are ready to flash the built firmware into microcontroller with this or similar command (over ST-Link connection):

$ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program firmware.elf verify reset exit"

I've also published a repository for that. You can look at it from here: https://github.com/CanGulmez/Embedded-Firmware-with-Makefile

Flashing and Debugging A Firmware in Detail

Mon, 06 Apr 2026 14:53:30 +0000

In this tutorial, I will inspect, flash and debug a firmware written for STM32F446RE microcontroller. To accomplish this, we need some dedicated tools:

openocd
arm-none-eabi-*
gdb-multiarch

openocd is the primarily tool that we have to get. It's used as bridge between your host machine and debugger hardware. (I'm using use ST-Link hardware in this time). I will use it to connect to the debugger hardware. arm-none-eabi-* tools are the ARM toolchain used in development of the firmware. gdb-multiarch is the debugger too.

You can get these tools:

$ sudo apt install openocd gcc-arm-none-eabi gdb-multiarch

Note: I'm on Ubuntu 24.04, gcc-arm-none-eabi tools don't include the gdb debugger like arm-none-eabi-gdb. So that gdb-multiarch is being installed externally. On some distribution, the gdb debugger comes with gcc-arm-none-eabi.

Suppose that I have a firmware called "firmware.elf" and wanna inspect it as first step.

The first thing that you should do probably is to determine the firmware itself:

$ file firmware.elf
firmware.elf: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped

The file command simply outputs the firmware properties like the endiannes, architecture, or so on. You can see easily that this firmware was written for 32-bit ARM Cortex.

We can see also the section sizes (in bytes) of the firmware with arm-none-eabi-size command:

$ arm-none-eabi-size firmware.elf
   text   data    bss    dec    hexfilename
   5252     20   1732   7004   1b5cfirmware.elf

If you are not familiar with sections of the executables, I've wrote many tutorials that explains the ELF executable. You can look at there.

If you exactly wanna see the contents of the firmware, arm-none-eabi-objdump is the primarily tool for that:

$ arm-none-eabi-objdump -j .text -d firmware.elf

firmware.elf:     file format elf32-littlearm


Disassembly of section .text:

(...)

0800079c <main>:
 800079c:b500      push{lr}
 800079e:b091      subsp, #68@ 0x44
 80007a0:f000 f8ac bl80008fc <HAL_Init>
 80007a4:f000 f82c bl8000800 <configOscClk>
 80007a8:f000 f844 bl8000834 <configDebugPort>
 80007ac:4911      ldrr1, [pc, #68]@ (80007f4 <main+0x58>)
 80007ae:4d12      ldrr5, [pc, #72]@ (80007f8 <main+0x5c>)
 80007b0:4c12      ldrr4, [pc, #72]@ (80007fc <main+0x60>)
 80007b2:4668      movr0, sp
 80007b4:f7ff ff08 bl80005c8 <strcpy>
 80007b8:4668      movr0, sp
 80007ba:f7ff ff81 bl80006c0 <strlen>
 80007be:f04f 33ff mov.wr3, #4294967295@ 0xffffffff
 80007c2:b282      uxthr2, r0
 80007c4:4669      movr1, sp
 80007c6:480d      ldrr0, [pc, #52]@ (80007fc <main+0x60>)
 80007c8:f000 fdc2 bl8001350 <HAL_UART_Transmit>
 80007cc:4629      movr1, r5
 80007ce:4668      movr0, sp
 80007d0:f7ff fefa bl80005c8 <strcpy>
 80007d4:4668      movr0, sp
 80007d6:f7ff ff73 bl80006c0 <strlen>
 80007da:f04f 33ff mov.wr3, #4294967295@ 0xffffffff
 80007de:b282      uxthr2, r0
 80007e0:4669      movr1, sp
 80007e2:4620      movr0, r4
 80007e4:f000 fdb4 bl8001350 <HAL_UART_Transmit>
 80007e8:f44f 707a mov.wr0, #1000@ 0x3e8
 80007ec:f000 f8b2 bl8000954 <HAL_Delay>
 80007f0:e7ec      b.n80007cc <main+0x30>
 80007f2:bf00      nop
 80007f4:0800146c .word0x0800146c
 80007f8:08001489 .word0x08001489
 80007fc:20000084 .word0x20000084

(...)

For example, you see the main() function in .text section of the firmware. At left, the address of the machine code were being displayed. At center, you see the machine code corresponding to assembly instructions that is at right side.

Inspecting the contents of ELF executable is huge topic. It has many variants and view-of-points in there.

"Flashing" term means writing the dedicated sections of the firmware into the flash memory area of the microcontroller. It's done with many different ways. But I will show you openocd tool.

In here, I have to define that how exactly does openocd work. It actually creates a server into the host machine with given configuration files. After starting the server session, you need to connect to that server over telnet or gdb.

Let's do it. Firstly, connect the microcontroller to the host machine. Then open a terminal session and type this command:

$ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg

In here, I gave the two configuration files. First is the interface. As I said, I use the ST-Link connection. Second is the target file. It defines the target architecture. The openocd comes a bunch of configuration files. So search it and find the appropriate configuration files.

You will see something like this:

Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 2000 kHz
Info : STLINK V2J33M25 (API v2) VID:PID 0483:374B
Info : Target voltage: 3.224656
Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected
Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints
Info : starting gdb server for stm32f4x.cpu on 3333
Info : Listening on port 3333 for gdb connections

The openocd attached the 4444 port to telnet and 3333 port to gdb. So that I will bind the 3333 port in the gdb session.

Secondly, open the second terminal and type:

$ gdb-multiarch firmware.elf

At the moment, you are in the gdb session. In here, bind to the 3333 port:

(gdb) target remote localhost:3333

For now, you are in the control and responsible for the all flashing and debugging operations.

To flash the firmware, use these commands:

(gdb) monitor reset halt
(gdb) load
(gdb) monitor reset halt

There are tons of commands you can type in the gdb session. We can split these commands in two categories. monitor <command-name> commands directly are run by the openocd command. Other commands are run by the gdb itself.

load is the main command to flash the firmware. Before and after that command, resetting and halting the CPU execution is good practice. Output will be like:

Loading section .isr_vector, size 0x1c4 lma 0x8000000
Loading section .text, size 0x126c lma 0x8000200
Loading section .rodata, size 0x4c lma 0x800146c
Loading section .ARM, size 0x8 lma 0x80014b8
Loading section .init_array, size 0x4 lma 0x80014c0
Loading section .fini_array, size 0x4 lma 0x80014c4
Loading section .data, size 0xc lma 0x80014c8
Start address 0x08001400, load size 5272
Transfer rate: 9 KB/sec, 753 bytes/write.

That means that the firmware successfully was flashed .

If you just wanna flash the firmware and not debugging, this following command is enough:

$ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg -c "program firmware.elf verify reset exit"

Instead of dealing with two terminal sessions, above command is just the one-step operation.

The main reason opening the second gdb session is to make the debugging. If you did the debugging previously, you will be familiar with these commands:

(gdb) break main
(gdb) continue
(gdb) next
(gdb) finish
(gdb) print var
(gdb) x/16wx *ptr
(gdb) set var
(gdb) list

The debugging operations are huge and will not fit into a single tutorial as you guest. So that I don't wanna dive into the these and other operations. But I wanna give you a good reference: The Art of Debugging with GDB, DDD, and Eclipse written by Norman Matloff and Peter Jay Salzman.

Until here, I gave a overall explanation the end-to-end pipeline. I'll explain the other stuffs in further.

JsonX: Lightweight JSON to C struct mapping for Embedded Systems

Fri, 17 Oct 2025 20:51:57 +0000

JsonX: Lightweight JSON → C struct mapping for Embedded Systems

JsonX is a lightweight C library for embedded developers who need to map JSON directly into structs — without dynamic memory or code generators.

JSON is everywhere - from web APIs to IoT devices.

But on microcontrollers, most JSON libraries feel like elephants in a china shop: they assume megabytes of RAM, malloc on every step, and a friendly OS.

Typical JSON libraries for embedded systems fall into two extremes:

Full-featured giants (e.g. ArduinoJson, jansson): powerful but memory-hungry.
Bare parsers (e.g. JSMN, cJSON, jfes): no mapping, just tokenization.

The Problem with JSON on Embedded Devices

When you work with RTOS or bare-metal firmware where every byte and cycle counts.
That’s where JsonX comes in - a lightweight layer over cJSON designed specifically for MCU + RTOS environments, where predictable memory and simplicity matter most.

So you either waste RAM or write tons of manual traversal code:

// classical pain
value = cJSON_GetObjectItem(root, "config");
param = cJSON_GetObjectItem(value, "baudrate");
baudrate = param->valueint;

JsonX in One Sentence

A thin mapping layer that turns JSON into C structs using a declarative table, not hand-written traversal.

Example structure:

typedef struct
{
    char      device_name[32];
    double    baudrate;
    bool      debug;
} config_t;

config_t config;

Mapping:

JX_ELEMENT config_desc[] =
{
    JX_PROPERTY_STRING("device_name", config.device_name),
    JX_PROPERTY_NUMBER("baudrate", config.baudrate),
    JX_PROPERTY_BOOLEAN("debug", config.debug),
};

const size_t config_desc_size = sizeof(config_desc)/sizeof(config_desc[0]);

And that’s it - one call:

const char *config_json_str = "{\"device_name\":\"sensor1\",\"baudrate\":9600,\"debug\":true}";

if(jx_json_to_struct(char *buffer, config_desc, config_desc_size, JX_MODE_STRICT) == JX_SUCCESS)
{
    jx_log("Configuration loaded: %s @ %lu\n", config.device_name, (uint32_t)config.baudrate);
}

No malloc() surprises, no deep tree traversal.

Core Benefits

✅ Predictable Memory
- All allocations go through RTOS pools or a static buffer.
- No hidden malloc/free. Works under ThreadX, FreeRTOS, or bare-metal.
✅ Automatic Struct Mapping
- Define once → parse many.
- Shared parsing engine for all schemas.
✅ Optional / Ignored Fields
- Unknown keys ignored automatically.
- Optional fields can have defaults.
- Makes firmware tolerant to JSON changes.
✅ Readable and Debuggable
- You still get readable JSON in logs - easier to verify on target or
  via serial output.

⚖️ JsonX vs Binary Formats

When NOT to use JsonX:

You control both ends and need max bandwidth (LoRa, NB-IoT)
You rely on schema versioning (protobuf/flatbuffers)

When JsonX shines:

You want human-readable logs
You interface with web APIs
You want deterministic memory use
You prefer C-only solution

Example: Parsing an Array of Coordinates

    #define JX_USER_BUFFER_SIZE    1024    
    // Initialize JsonX (using standard malloc/free)
    jx_init();
    
    // Define point structure
    typedef struct {
        double x;
        double y;
    } Point_t;
        
    // Define square structure with array of 4 points
    typedef struct {
        Point_t points[4];
    } Square_t;
        
        
    // Create square data structure
    Square_t square = {
        .points = {
            {0, 0},
            {1, 0},
            {1, 1},
            {0, 1}
        }
    };
        
    // Define JSON mapping for a single point object
    JX_ELEMENT point_0[] = {
        JX_PROPERTY_NUMBER("x", square.points[0].x),
        JX_PROPERTY_NUMBER("y", square.points[0].y)
    };
    
    JX_ELEMENT point_1[] = {
        JX_PROPERTY_NUMBER("x", square.points[1].x),
        JX_PROPERTY_NUMBER("y", square.points[1].y)
    };
    
    JX_ELEMENT point_2[] = {
        JX_PROPERTY_NUMBER("x", square.points[2].x),
        JX_PROPERTY_NUMBER("y", square.points[2].y)
    };
    
    JX_ELEMENT point_3[] = {
        JX_PROPERTY_NUMBER("x", square.points[3].x),
        JX_PROPERTY_NUMBER("y", square.points[3].y)
    };
    
    // Define array of point objects
    JX_ELEMENT square_array[] = {
        JX_OBJECT_VAL(point_0),
        JX_OBJECT_VAL(point_1),
        JX_OBJECT_VAL(point_2),
        JX_OBJECT_VAL(point_3)
    };
    
    // Define root object with "square" property
    JX_ELEMENT root[] = {
        JX_PROPERTY_ARRAY("square", square_array)
    };
    
    // ===== SERIALIZATION: C struct -> JSON =====
    char *json_output = jx_alloc_memory(JX_USER_BUFFER_SIZE);
    if (json_output != NULL) {
        jx_struct_to_json(root, 1, json_output, JX_USER_BUFFER_SIZE, JX_FORMATTED);
        jx_log("Serialized JSON:\n%s\n\n", json_output);
        jx_free_memory(json_output);
    }
        
    // ===== DESERIALIZATION: JSON -> C struct =====
    const char *json_input =
    "{"
        "  \"square\": ["
            "    {\"x\": 5, \"y\": 6},"
            "    {\"x\": 7, \"y\": 8},"
            "    {\"x\": 9, \"y\": 10},"
            "    {\"x\": 11, \"y\": 12}"
        "  ]"
    "}";
    
    
    // Parse JSON
    jx_json_to_struct((char*)json_input, root, 1, JX_MODE_STRICT);
    
    // Print parsed data
    jx_log("Parsed square points:\n");
    for (int i = 0; i < 4; i++) {
        jx_log("  Point %d: x=%d, y=%d\n",
                    i,
                    (int)square.points[i].x,
                    (int)square.points[i].y);
        }
    // Cleanup
    jx_parser_deinit();

Tested Configuration: STM32H7 + ThreadX (-Os, GCC 12)

⚙️ Memory & Code Footprint

Verified on STM32H7 (GCC 12, -Os, ThreadX)

jx_parser.o — 2228 B code, 4 B static RAM
Core parser and mapping logic.

jx_static_allocator.o — 248 B code, 4 B static RAM
Implements static allocator for bare-metal mode.

jx_version.o — 68 B code, 0 B RAM
Simple version string helper.

example.o (demo) — 765 B code, 1076 B RAM
Demo test including a 1 KB byte pool for ThreadX.

➡ Core only: ≈ 2.5 KB code + 8 B static RAM

➡ With example: ≈ 3.2 KB code + 1.06 KB RAM

The demo includes a 1 KB jx_byte_pool_buffer for ThreadX, but the actual pool size is user-defined.
JsonX itself has no hidden heap allocations - all memory management is deterministic.

The static allocator consumes only ≈ 12–16 bytes of header overhead inside the provided buffer.

Open Source and Final Thoughts

GitHub: https://github.com/embedmind/JsonX

JsonX is lightweight, open-source (MIT), and built purely in C for portability across RTOSes and MCU families.

Final Thoughts

This library isn’t about inventing a new protocol - it’s about making life easier for embedded developers who already have to deal with JSON.

Working with JSON on MCUs? I'd love to hear your use case - especially if you've battled with JSMN, Jansson, or ArduinoJson before.

Join the Discussion

⭐ Star on GitHub if this solves your problem
Found a bug? Open an issue

Coder Legion - Recent posts tagged embedded

Building aegis-filter: Why Standard Kalman Filters Fail in Adversarial Environments

1. The Core Architecture

A. Joseph-Stabilized Covariance Update

B. Chi-Square / 3-Sigma Outlier Rejection Gating

C. Unscented Kalman Filtering (UKF) & $H_\infty$ Robust Minimax

2. Flight Telemetry & Spoofing Resilience Simulation

Key Takeaways from the Data:

3. Quick Start (Rust)

1D Outlier-Gated Fusion Example:

4. Open Source Links

RS232 vs RS485 in a Vehicle: Which Serial Port for Which Peripheral

The actual difference: single-ended vs differential

Which one for which peripheral

Where RS232 fails quietly

RS485 wiring that people skip

Neither replaces CAN bus

A real example

FAQ

CAN Bus and J1939 Integration on Rugged Vehicle Tablets: A Practical Guide

CAN Bus: the physical layer

J1939: the messaging layer on top

ISO 11783 (ISOBUS) and ISO 15765

What to check when specifying hardware

A practical note

Exploiting "Trust-by-Default": How I transformed an ESP32-S3 into a BadUSB

The architectural choice: Dynamic Parser vs Hardcoding

RAM Security: O(1) Space Complexity

Beyond abstraction: USB Protocol and Polling Rate

State-Based Logic and the Auto-Repeat Trap

Conclusion

AArch64 Register Conventions: What Survives a Function Call—and Why

AArch64 vs ARM64: what's in a name?

The big picture

Caller-saved vs callee-saved: the conceptual key

A common misconception

Scope: what this article covers

The calling-convention register map

X0–X7: arguments and results

X8: indirect results

X9–X15: caller-clobbered scratch registers

X16–X17: IP0/IP1 and linker scratch

X18: platform register

X19–X28: callee-saved registers

X29 and X30: frame pointer and link register

X29: frame pointer

X30: link register

Pointer Authentication and X30 security

SP, XZR, and W registers

SP: stack pointer

XZR: the zero register

W registers: the 32-bit view

SIMD and floating-point registers

V0–V7: argument and return registers

V8–V15: partially preserved

V16–V31: temporary registers

Condition flags: NZCV

What this looks like in compiler output

Writing inline assembly

AAPCS64 vs platform ABI

Practical cheat sheet

Conclusion

Official documentation and further reading

Why the Power-of-Two Trick Works for Binary Fractions (And Why It Breaks for Everything Else)

Understanding Binary Coded Decimal (BCD) First

The Problem with Decimal to Binary Conversion

The Fraction Shortcut

Example 1: Converting 0.25 to Binary

Example 2: Converting 0.625 to Binary

Example 3: Converting 0.4375 to Binary

Where This Breaks Down

Conclusion

8 Arduino coding habits that separate hobby sketches from real products

1. Stop using delay()

2. Avoid the String class on AVR boards

3. Wrap string literals in F()

4. Be explicit about integer sizes

5. Use INPUT_PULLUP instead of external resistors

6. Keep ISRs tiny and mark shared variables volatile

7. Model state machines explicitly

1. Stop using `delay()`

2. Avoid the `String` class on AVR boards

3. Wrap string literals in `F()`

5. Use `INPUT_PULLUP` instead of external resistors

6. Keep ISRs tiny and mark shared variables `volatile`

A bonus: `setup()` and `loop()` are just `main()`