DEV Community: Jaya Sai Kishan Chapparam

The data structure that makes real-time charts fast, and the allocation trap hiding inside it

Jaya Sai Kishan Chapparam — Tue, 30 Jun 2026 21:43:00 +0000

If you stream telemetry into a React app the obvious way, you wire each incoming sample to a piece of state and let the component re-render. That works until the data gets fast, and then it falls over, and I wrote a whole separate post about why the rendering falls over. This post is about the layer underneath that: where the samples actually live between arriving and being drawn. It is a smaller question than rendering and it has a cleaner answer, and it also has a trap that I walked straight into and measured my way back out of, which is the part worth your time.

The short version is that the right container is a fixed-size circular buffer, the reason is allocation rather than speed-of-access, and the obvious way to read from it gives back exactly the allocation win it bought you. So the structure is half the story and how you read from it is the other half.

Why not just an array

A telemetry channel is an unbounded stream. Samples arrive at 30, 50, sometimes hundreds of hertz, forever, and a chart shows the last few seconds of them. The naive container is a plain array you push onto and slice the tail off of:

samples.push(value);
if (samples.length > maxPoints) samples.shift();

This is wrong in two ways that both come down to memory, not speed. shift() removes from the front, which is O(n) because every remaining element slides down one slot, and you pay that on every sample. Worse, an array that you grow and trim like this churns the allocator constantly. The engine resizes the backing store, the old one becomes garbage, the collector runs, and at telemetry rates that garbage collection happens often enough to land inside your frame budget. You do not feel it on a fast machine with one chart. You feel it on a slower machine, or with twenty channels, as periodic stutter that has no obvious cause because nothing in your code is obviously slow.

The fix is to stop allocating entirely. Decide up front how many samples you keep, allocate that once, and overwrite the oldest sample in place when you are full. That is a ring buffer, and for numeric telemetry there is a second win sitting right next to it.

A typed array, not an array of numbers

A normal JavaScript array of numbers is an array of boxed values the engine has to chase through pointers. A Float64Array is a flat block of contiguous doubles, no boxing, no pointer chasing, and it is exactly the shape numeric samples want. So the buffer is two parallel Float64Arrays, one for values and one for timestamps, each allocated once at the capacity you choose:

export class RingBuffer {
  private buf: Float64Array;
  private times: Float64Array;
  private head = 0;
  private count = 0;
  readonly capacity: number;

  constructor(capacity: number) {
    if (!Number.isInteger(capacity) || capacity <= 0) {
      throw new RangeError(`RingBuffer capacity must be a positive integer, got ${capacity}`);
    }
    this.capacity = capacity;
    this.buf = new Float64Array(capacity);
    this.times = new Float64Array(capacity);
  }

head is the write index, the slot the next sample lands in. count is how many slots are live, and it climbs until it hits capacity and then stops. There is deliberately no tail pointer, because you can derive where the oldest sample sits: if the buffer is not full yet the oldest is at index 0, and if it is full the oldest is wherever head currently points, since that is the slot about to be overwritten.

The write path does nothing interesting, on purpose

push(value: number, timestamp: number): void {
  this.buf[this.head] = value;
  this.times[this.head] = timestamp;
  this.head = (this.head + 1) % this.capacity;
  if (this.count < this.capacity) this.count++;
}

That is the entire write path, and the most important thing about it is what it does not do. It does not allocate. It does not grow. It does not box anything. Two indexed stores into pre-allocated Float64Arrays, one modulo to advance the write index, one conditional increment that stops mattering once the buffer fills. The numbers go straight into slots as unboxed doubles. Once the buffer is full, head keeps wrapping and each write overwrites the oldest sample in place, which is why there is no branch for full-versus-not-full on this path. The buffer reaches a steady state and stays there, allocating nothing, for the entire life of the stream. This is the property the whole structure exists to have.

This is also the right place to keep React out of it. None of this touches component state. The buffer is a plain object that a requestAnimationFrame loop reads on its own schedule, so a sample arriving at 200Hz is just a slot write, not a re-render. That separation, fast data into a mutable buffer, rendering on its own clock, is the thing that lets the high-frequency path stay cheap, and the buffer is the mutable thing in the middle.

Reading it back in order

The wrinkle in any ring buffer is that the data is stored out of order once it wraps. The newest sample might be in the middle of the array with the oldest just after it, so reading "oldest to newest" means walking from head to the end and then from the start back to head. Here is the read that handles both cases:

private orderedInto(source: Float64Array, out: Float64Array): number {
  if (out.length < this.count) {
    throw new RangeError(
      `readInto target too small: need ${this.count}, got ${out.length}`,
    );
  }
  if (this.count === 0) return 0;
  if (this.count < this.capacity) {
    // Not full yet: oldest is at 0, newest at head-1, no wrap.
    out.set(source.subarray(0, this.count));
    return this.count;
  }
  // Full: oldest sits at head, wrapping forward to head-1.
  const tail = source.subarray(this.head, this.capacity);
  const wrap = source.subarray(0, this.head);
  out.set(tail, 0);
  out.set(wrap, tail.length);
  return this.count;
}

Before it wraps, the data is contiguous and it is one copy. Once full, it is two copies, the run from head to the end followed by the run from the start up to head, stitched into the output in order. subarray is a view, not a copy, so the only actual writes are the two out.set calls into the caller's buffer, and the function returns how many elements it wrote so the caller knows the valid prefix.

Notice that this read fills a buffer you hand it. That is the whole point, and it is the part I got wrong the first time.

The trap

The convenient way to expose that read is to return a fresh array, and that is what the buffer did first:

getValues(): Float64Array {
  const out = new Float64Array(this.count);   // allocates, every call
  this.orderedInto(this.buf, out);
  return out;
}

This is lovely to call and it quietly reintroduces the exact problem the ring buffer was built to remove. Every call allocates a fresh Float64Array. And the draw loop calls it a lot. My chart components read the buffer twice per frame, once to compute the y-axis extent and once to actually draw, across both values and timestamps, which is four allocations per channel per frame. At a default buffer of 10,000 samples, sixty times a second, per channel.

So I had built a zero-allocation buffer and then drained it through an allocating read on the hottest path in the library. The write side was clean and the read side handed all the garbage right back.

The fix is to let the caller own the output buffer and reuse it across frames:

/** Zero-copy ordered read into a caller-owned buffer. Returns the count. */
readInto(out: Float64Array): number {
  return this.orderedInto(this.buf, out);
}
readTimesInto(out: Float64Array): number {
  return this.orderedInto(this.times, out);
}

Same ordered read, no allocation. The component allocates one scratch Float64Array per channel once, at setup, and refills it every frame instead of minting a new one. getValues and getTimes still exist for occasional callers who genuinely want a fresh copy, but the render path uses readInto.

What it actually cost, measured

This is the part I care about getting right, because "allocation is bad" is the kind of claim everyone nods at and nobody checks. So I benchmarked the allocating read against the reused-buffer read, same scene, same math, only the read differs. Every number below is from one machine, and the harness is committed so you can run it on yours.

The first thing the measurement taught me is that on a fast machine, at low channel counts, the allocation costs you nothing visible. Here is a sustained 60-second run at normal CPU speed, looking at per-frame main-thread work in milliseconds:

channels	read	work p50	work p99	work max	frames over 5ms
6	allocate	1.2	1.9	3.8	0
6	reuse	0.6	1.3	1.5	0
24	allocate	3.7	10.1	15.0	263
24	reuse	2.2	4.0	4.6	0

At 6 channels the allocating version never even spikes. The frame rate stayed pinned at 60 the whole time, because each garbage collection pause was short enough to fit inside the frame's idle budget. If you had stopped measuring here you would conclude the allocation does not matter, and you would ship it.

Look at the 24-channel rows. The allocating read has a p99 of 10ms and 263 frames where main-thread work crossed 5ms. Those are GC pauses, and at normal speed they hide under the vsync interval, eating your headroom without dropping a frame. The reused-buffer read has a p99 of 4ms and zero such spikes. The garbage was never free. It was being absorbed by the spare time in each frame, which means it was quietly spending the budget you would want for everything else the app does.

Now take the headroom away. Here is the same thing under 6x CPU throttle, which is a reasonable stand-in for a mid-tier laptop, counting frames that ran long enough to miss a vsync:

channels	read	dropped frames	bad stutters
6	allocate	16	1
6	reuse	0	0
24	allocate	363	46
24	reuse	0	0

This is where the hidden cost becomes visible. The 24-channel allocating view dropped 363 frames in 30 seconds, roughly half of them, on hardware that is not exotic. The reused-buffer version dropped none. The exact same GC pauses that were invisible on the fast machine become dropped frames the moment the budget shrinks, and the user on the slower machine is precisely the user you cannot test on and most need to not fail.

That is the whole argument for the ring buffer, restated honestly. It is not that the buffer makes reads fast. It is that the buffer makes the steady state allocate nothing, and that property is only worth anything if you do not undo it at the read. The speed was always in the allocation, and the trap is that the convenient read silently reintroduces the allocation you removed.

What this does not fix

One thing I want to name so the post does not oversell itself. Killing the per-frame allocation does not reduce how much the chart draws. The draw loop still walks every sample in the buffer, so a 10,000-sample buffer drawing into an 800-pixel chart is still rasterizing far more geometry than the display can resolve. That is a separate problem with a separate fix, decimating to pixel columns, and it is tracked as its own piece of work rather than smuggled into this one. The allocation fix and the overdraw fix are independent, and this post is only the first one.

The buffer ships in @altara/core as RingBuffer, with useRingBuffer(capacity) as the React hook that gives a component a stable instance for its lifetime. The benchmark, including the allocating-versus-reused read comparison, is in the repo and runs from one command, so the numbers above are yours to reproduce or disagree with on your own hardware.

SVG renders telemetry at 60fps. We use Canvas anyway, and here is the measured reason

Jaya Sai Kishan Chapparam — Thu, 18 Jun 2026 22:09:19 +0000

Let me start with the concession, because the version of this post that skips it is the version nobody senior finishes reading. SVG renders real-time telemetry at 60 frames a second perfectly well. On a reasonably fast machine you can put a couple hundred instruments on screen, update every one of them every frame, and the browser will hold 60fps without dropping anything. If you have read that SVG cannot handle high-frequency animation, that is not what the numbers say, and I went and got the numbers.

I still render the high-frequency parts of Altara, a telemetry component library I maintain, on Canvas. This post is about why, and the reason turns out to have almost nothing to do with frame rate. It is about where the work goes.

The comparison is really two questions

Every Canvas-versus-SVG post I have read makes the same mistake, and I nearly made it too. They compare "SVG" against "Canvas" as if those are two things, when the SVG side is almost always SVG driven through a framework's render cycle. In React that means every frame you set state, React reconciles the component tree, diffs the virtual DOM, and commits attribute changes to the real SVG nodes. When that turns out to be slow, the conclusion gets written up as "SVG is slow," which is the wrong conclusion, because you measured two costs and blamed one of them.

So I benchmarked three things, not two:

svg-react: the SVG nodes live in React, and every frame triggers a re-render. This is what most people mean by "SVG" and it is the thing those posts actually measured.
svg-imperative: the SVG node tree is built once at mount, and every frame mutates it directly through refs, setAttribute for the transforms and points, textContent for the readouts, driven by a single requestAnimationFrame loop with no React in the hot path.
canvas: one <canvas>, one rAF loop, clear and repaint each frame, no React state involved in drawing.

All three draw the identical scene from identical per-frame math: N small widgets, each a rotating needle, a numeric readout, and a scrolling sparkline. The only variable is how the picture reaches the screen. Stripped down, the three hot paths look like this:

// svg-react: React owns the DOM, re-render the whole <svg> every frame
function Widget({ angle, value, points }) {
  return (
    <svg viewBox="0 0 100 100">
      <line transform={`rotate(${angle} 50 50)`} x1="50" y1="50" x2="50" y2="10" />
      <text x="50" y="60">{value}</text>
      <polyline points={points} fill="none" />
    </svg>
  );
}
// driver: setState every frame -> React reconciles all N widgets

// svg-imperative: build once, keep refs, mutate in one shared rAF loop
needle.setAttribute('transform', `rotate(${angle} 50 50)`);
readout.textContent = value;
spark.setAttribute('points', points);

// canvas: one surface, one rAF loop, clear and repaint
ctx.clearRect(0, 0, width, height);
for (const w of widgets) drawWidget(ctx, w);

The reason three conditions matter is that the gaps between them are the answer:

svg-react  -  svg-imperative  =  the cost of React's render loop
svg-imperative  -  canvas      =  the cost of the SVG/DOM format itself

A two-way benchmark fuses those into one number and lets you tell whichever story you prefer. The three-way version makes you say both.

One caveat I want stated plainly rather than buried. Every number below is from a single machine, an Intel i9-9880H on Chromium 147 at devicePixelRatio 2, and your hardware will produce different numbers. The benchmark is committed to the repo and runs from one command, so the honest move is for you to run it yourself rather than trust my table. From a clone:

pnpm install && pnpm --filter @altara/demo dev   # then open http://localhost:5173/bench/

Click "Run full matrix," or drive it headless with the Playwright runner in scripts/bench/.

What it measured

Frame rate is the wrong number to lead with, because it is quantized to the display. Everything below 16.7ms of work reads as a flat 60fps, which hides the entire story until the moment it falls off a cliff. The honest metric is per-frame main-thread work, the time your JavaScript actually occupies the main thread each frame. Here it is in milliseconds, with all three holding a clean 60fps through N=200:

N	svg-react	svg-imperative	canvas
1	0.45	0.22	0.07
50	3.84	1.86	0.39
200	10.51	5.18	1.07

Read the two gaps at N=200. React's render loop costs about 5.3ms (10.51 minus 5.18). The SVG/DOM format itself, mutation plus layout plus paint, costs about 4.1ms (5.18 minus 1.07). They are close to equal. That is the finding that kills both clichés at once. You cannot honestly write "SVG is slow," because half the cost was React. And you cannot honestly write "the problem was just React," because stripping React out left a 4ms format cost that is still roughly 5 times what Canvas spends. Both costs are real, and they stack.

Where each one falls over

Stay at 60fps long enough and eventually each strategy drops frames. Where, and why, is the part that decided it for me:

mode	first drops at	at that point	bound by
svg-react	N ≈ 300	54fps, work 15.4ms	JS (reconcile + layout)
svg-imperative	N ≈ 600	46fps, work 14.5ms	JS (mutate + layout)
canvas	N ≈ 600	54fps, work 2.3ms	paint / compositor

Look at the work column at the drop point. Both SVG strategies die with the main thread pinned near 15ms, because they ran out of JavaScript budget: reconciliation, attribute mutation, and the layout the browser recomputes afterward. Canvas drops frames with the main thread spending 2.3ms. It did not run out of JavaScript budget. It ran out of paint, the compositor rasterizing a 2880-by-840 surface at DPR 2. Even at N=1200, Canvas main-thread work is still only about 4ms.

That is the whole argument, and it is not "Canvas is faster." Canvas does not make frames free. It moves the bottleneck off the main thread. When SVG drops a frame, your JavaScript is the thing that overran, and you have zero milliseconds left for anything else your app needs to do that frame. When Canvas drops a frame, your JavaScript spent 2ms and the GPU is the constraint, which means you still have most of a frame's budget for state updates, network handling, and the rest of the application.

The part that actually matters: headroom on the machine you do not own

Your benchmarks run on your machine, and your machine is fast. Your users are on a five-year-old laptop with a browser full of tabs. So the number I care about is not what happens on the i9, it is what happens when the budget shrinks. Here is the same scene under 6x CPU throttle, which is a reasonable stand-in for mid-tier hardware:

N	svg-react	svg-imperative	canvas
50	36.7fps	57.4fps	60fps
200	11.6fps	18.8fps	60fps (work 6.7ms)

Imperative SVG, the genuinely good version with no React in the hot path, collapses to 18.8fps at N=200. Canvas holds a flat 60. This is the 10x main-thread headroom from the first table cashing out exactly where it counts. On a fast machine the headroom is invisible, all three look like 60fps. The headroom is not there to make the fast machine faster. It is there so the slow machine still works.

A confession about allocations

While I was measuring this I found a bug in my own library, and it is worth telling because it is the failure mode this whole post is about. My existing performance docs claimed the Canvas path was clean because it kept state out of the render loop. That is true and it is also not the same thing as being free.

The chart components buffer samples in a fixed-size RingBuffer, and the draw loop pulled the data out with getValues() and getTimes(), each of which allocates a fresh Float64Array. The draw pass called them twice per channel per frame, once to compute the y-extent and once to draw. Four typed-array allocations per channel per frame, at a default buffer of 10,000 samples, 60 times a second.

On the i9 this never dropped a frame. V8 absorbs short-lived typed arrays well enough that even 96 allocations a frame at 24 channels stayed locked at 60fps. It showed up only as GC work-spikes eating into the frame's spare budget, the headroom this entire post is an argument for protecting. Shrink the budget and those spikes become real drops. Under 6x throttle at 24 channels, the allocating version dropped 363 frames over 30 seconds, about 28fps. So I added a zero-copy read path:

// before: allocates two Float64Arrays per channel, per frame
const values = buffer.getValues();
const times = buffer.getTimes();

// after: fill reusable buffers allocated once, no per-frame allocation
const n = buffer.readInto(scratchValues);   // returns the count written
buffer.readTimesInto(scratchTimes);
// draw from scratchValues[0..n]

Reading once per frame into reused scratch took per-frame allocation from four-per-channel to zero, removed every GC spike, and turned that throttled 28fps back into a flat 60. It shipped in @altara/core@0.2.0 as readInto and readTimesInto. I am including this not to pad the post with a victory lap but because it is the exact trap the headline is about. The benchmark proves Canvas keeps the main thread cheap. The library only delivers that headroom if it does not quietly hand it back to the garbage collector. "No state in the hot path" was a true sentence that let me believe a false one.

It is a ladder, not a verdict

The conclusion is not "use Canvas." It is "match the rendering strategy to the update frequency," and the same library makes that obvious if you look at how its components are actually built:

The line charts and the flight display, which redraw everything every frame, are Canvas.
The gauge, a single needle that moves occasionally, is plain SVG driven by React state. It updates rarely enough that reconciliation cost is irrelevant, and SVG gives it crisp scaling and simpler code for free.
The event log and the status panels are ordinary DOM, because text that updates a few times a second has no business on a canvas, where you would lose selection, accessibility, and the browser's text layout for nothing.

Three tiers, chosen by how often the thing changes. Canvas is the right rung for moving line charts in the hundreds. It is the wrong rung for a needle that twitches once a second, and the wrong rung for a scrolling log.

Where Canvas stops

A deep dive that does not name its own ceiling is a sales pitch, so here is where this approach runs out.

The first wall is closer than you would expect, and it is self-inflicted. The chart draw loop currently emits one line segment per buffered sample. With a 10,000-sample buffer drawing into an 800-pixel-wide chart, that is more than ten times the geometry the display can resolve. The fix is decimation: bucket the buffer by pixel column and draw the min and max of each column, which caps drawn geometry at roughly twice the chart width regardless of how fast data arrives, and decouples draw cost from sample rate. One detail specific to telemetry: use min/max per column, not the prettier largest-triangle-three-buckets that general charting libraries reach for, because LTTB can drop a single-sample spike and in telemetry that spike is often the alarm you exist to display. This one is tracked as an open issue and is the subject of a later post, because most "we need WebGL for our charts" conclusions are really "we forgot to decimate."

Past that, the ladder continues. To move the 2D rasterization itself off the main thread you reach for OffscreenCanvas in a worker, which the library does not use yet. When you genuinely need to draw a hundred thousand primitives, dense scatter or a point cloud, 2D Canvas is paint-bound and you move to the GPU, which is exactly why the library's LiDAR point cloud renders through three.js and WebGL rather than a 2D context. And underneath all of it, today each chart runs its own independent rAF loop with no shared scheduler, so many components means many uncoordinated clear-and-repaint passes. Collapsing those into one scheduler is its own piece, on the architecture.

So the tiers go all the way up: DOM, SVG, 2D Canvas, WebGL, each one the right answer for a different load. The point was never that Canvas wins. It is that the format was never really the question. The question is where the work runs, and the reason to keep it off the main thread is the machine you will never get to test on.

The components are MIT licensed on npm as @altara/core and friends, and the benchmark, including the imperative-SVG condition and the allocation A/B, is in the repo and runs from one command, so you can disagree with my i9 on your own hardware.

Building a real-time drone ground control station in React

Jaya Sai Kishan Chapparam — Thu, 18 Jun 2026 18:58:50 +0000

I had a quadcopter publishing telemetry over MAVLink and a stubborn preference for not leaving the browser. QGroundControl and Mission Planner are both excellent, but they are native apps, and the thing I actually wanted was a status page the rest of the team could open in a tab. Attitude, position, battery, and a running log of whatever the flight controller was complaining about.

The catch is that a drone publishes attitude at 30 to 50 Hz, and the first React version of this that anyone writes tends to fall over the moment real data arrives. You wire each reading to a piece of state, the state updates a few dozen times a second across five or six components, and React spends its whole frame budget reconciling instead of drawing. The display either lags behind the aircraft or, worse, different instruments end up showing different instants of the same moment.

So I built it with Altara, a set of telemetry components I maintain that keep the high-frequency path off React's render cycle. This post builds the ground control station in two passes. First the entire dashboard in mock mode, with no drone and no rosbridge involved, so you can get the layout and styling right against animated data. Then we point the exact same components at a real MAVROS stack.

What we're building

Four panels, the same four every ground station has:

A primary flight display (PFD), the artificial horizon with airspeed and altitude tapes, a heading scale, and a vertical speed indicator. A moving map showing the aircraft's position and the track it has flown. A battery gauge. And an event log for the messages coming off the flight controller.

We will lay them out in a grid, get all four animating, and only then think about where the numbers come from.

Setup

The PFD lives in the aerospace package and the map, gauge, and log live in core, so:

npm install @altara/core @altara/aerospace

The map renders with Leaflet, which Altara treats as an optional peer dependency and loads on mount. If you skip it the map will throw a setup hint at you, so install it now even though we are still in mock mode:

npm install leaflet@^1.9.4 react-leaflet@^4.2.1

The smallest thing that moves

Before the full grid, here is the PFD and the map side by side, animating themselves with no data plumbing at all:

import { PrimaryFlightDisplay } from '@altara/aerospace';
import { LiveMap } from '@altara/core';

export function FlightDeck() {
  return (
    <div style={{ display: 'flex', gap: 16 }}>
      <PrimaryFlightDisplay mockMode size="md" showFlightDirector />
      <LiveMap mockMode />
    </div>
  );
}

That is the whole thing. The mockMode flag on each component switches on a built-in generator, so there is no provider to set up and nothing to feed them.

What you see is worth describing, because it is more deliberate than random jitter. The PFD runs a gentle cruise profile. The horizon banks left and right through about 18 degrees on a slow cycle, the nose pitches up and down a few degrees out of phase with the bank so it reads as a coordinated turn rather than a metronome, the heading scale sweeps slowly around east, and the airspeed and altitude tapes drift around 120 knots and 4500 feet. The vertical speed needle leads the altitude changes correctly, because it is driven by the rate of the same wave. With showFlightDirector on, the magenta guidance bars lag the aircraft slightly, so they look like something the pilot is chasing instead of sitting dead center. It reads as an aircraft loafing along in cruise, which is exactly the point. You want to develop against motion that looks plausible.

The map, meanwhile, flies a slow circle around a fixed point and turns its nose to follow the track, leaving a trail behind it.

The full dashboard, still faked

Now the real layout. Four panels in a grid, every one of them in mock mode except the log, which works a little differently:

import { LiveMap, Gauge, EventLog, type EventLogEntry } from '@altara/core';
import { PrimaryFlightDisplay } from '@altara/aerospace';

const demoEvents: EventLogEntry[] = [
  { timestamp: Date.now() - 9000, severity: 'info', message: 'EKF using GPS' },
  { timestamp: Date.now() - 6000, severity: 'info', message: 'Armed' },
  { timestamp: Date.now() - 3000, severity: 'warn', message: 'Wind 11 m/s, approaching limit' },
  { timestamp: Date.now() - 1000, severity: 'info', message: 'Waypoint 3 reached' },
];

export function GroundControlStation() {
  return (
    <div
      style={{
        display: 'grid',
        gridTemplateColumns: '1fr 1fr',
        gap: 16,
        padding: 16,
        alignItems: 'start',
      }}
    >
      <PrimaryFlightDisplay mockMode size="md" showFlightDirector />
      <LiveMap mockMode />
      <Gauge
        mockMode
        mockProfile="ramp"
        min={0}
        max={100}
        label="Battery"
        unit="%"
        thresholds={[
          { value: 0, color: 'var(--vt-color-danger)' },
          { value: 20, color: 'var(--vt-color-warn)' },
          { value: 40, color: 'var(--vt-color-active)' },
        ]}
      />
      <EventLog entries={demoEvents} />
    </div>
  );
}

Two things in there are worth pulling out.

The gauge has a mockProfile. The default mock animation sweeps the needle up and down with a sine wave, which is fine for a generic gauge but looks absurd on a battery, because the charge appears to refill itself every few seconds. The ramp profile drains it from full to empty and resets, so a screenshot of your dashboard does not show a battery doing something physically impossible. Small detail, but it is the difference between a demo that looks considered and one that looks like a component sampler.

The event log is the odd one out. It has no mock mode, and that is on purpose. Every other component here carries a single number per channel, and the log carries text and a severity, which is a different kind of thing entirely. So instead of a mockMode flag, you hand it an array of entries and own that array yourself. Here it is a static list. Later, when we have real data, we will append to it from the flight controller's log stream. The shape is just a timestamp, a message, and one of info, warn, or error.

One layout thing that will save you a confused minute. The PFD has a fixed pixel footprint rather than a fluid one, around 680px wide at size="lg" and narrower at md. In a two-up grid that means the grid has to be wide enough to hold it, or the instrument overflows its column. I dropped to size="md" above so the dashboard sits comfortably at normal widths. If you want the larger PFD, give the grid the room for it rather than expecting the instrument to shrink.

Everything above runs without a drone, without rosbridge, and without a simulator. You can build the entire dashboard, get the grid proportions right, tune the thresholds, and hand it to a designer, all before any real telemetry exists. That is the reason to start in mock mode rather than treating it as an afterthought. The hard part of a ground station is rarely the data. It is the layout and the rendering, and you can finish both of those against fake motion.

Next we throw the mock flag away and point these same four components at a live MAVROS stack over rosbridge, which is where the interesting wiring lives: turning an IMU quaternion into something the horizon can draw, getting five channels onto one display, and feeding text logs into a component that only speaks numbers.

Wiring it to a real drone

The plan from here is the same four components, none of them changed, fed by a live MAVROS stack instead of the mock generator. The bridge between the two worlds is a small idea. Every Altara component that takes live data takes a dataSource, an object you subscribe to for a stream of timestamped numbers. rosbridge, meanwhile, hands you ROS topics over a WebSocket. So the wiring is mostly about turning topics into data sources, with a couple of places where the translation is more than a rename.

You will need a rosbridge server in front of your ROS graph (the standard rosbridge_suite), and for a MAVLink vehicle, MAVROS bridging the flight controller into ROS. Once that is up, everything below talks to it at ws://localhost:9090.

These four are the imports for the whole section:

import { useEffect, useMemo, useState } from 'react';
import { EventLog, Gauge, LiveMap, type EventLogEntry } from '@altara/core';
import { PrimaryFlightDisplay } from '@altara/aerospace';
import {
  createBatteryStateAdapter,
  createImuAdapter,
  createRosbridgeAdapter,
  mergeChannels,
} from '@altara/ros';

The PFD: five numbers, two topics, one instrument

This is the one with the actual problem in it. A primary flight display shows five live values: roll, pitch, heading, airspeed, and altitude. They do not come from one place. Roll and pitch come from the IMU, and heading, airspeed, and altitude come from the flight controller's HUD topic. The display, though, wants a single data source.

export function LivePrimaryFlightDisplay({ url }: { url: string }) {
  const source = useMemo(() => {
    const imu = createImuAdapter({ url, topic: '/mavros/imu/data' });
    const hud = createRosbridgeAdapter({
      url,
      topic: '/mavros/vfr_hud',
      messageType: 'mavros_msgs/VFR_HUD',
      channels: {
        heading: (m) => m.heading,
        airspeed: (m) => m.airspeed * 1.94384, // m/s -> kt
        altitude: (m) => m.altitude * 3.28084, // m -> ft
      },
    });
    return mergeChannels({
      roll: imu.roll,
      pitch: imu.pitch,
      heading: hud.heading,
      airspeed: hud.airspeed,
      altitude: hud.altitude,
    });
  }, [url]);

  useEffect(() => () => source.destroy(), [source]);

  return <PrimaryFlightDisplay dataSource={source} showFlightDirector />;
}

Three things are happening there.

createImuAdapter opens one socket to the IMU topic and gives you back roll, pitch, and yaw as separate channels. That matters more than it looks, because sensor_msgs/Imu reports orientation as a quaternion and the horizon needs degrees. The adapter does that conversion for you, and if you ever want it on its own, quaternionToEuler is exported too. There is one detail in that conversion worth knowing about, which I will come back to.

The HUD adapter uses the generic createRosbridgeAdapter with a channels map, which pulls several numbers off a single message. VFR_HUD publishes heading already in degrees, but airspeed in meters per second and altitude in meters, so the conversions to knots and feet are mine to do, right there in the extractor. The tapes display whatever number you give them. Hand them meters and they will read 4500 meters without complaint.

Then mergeChannels unions those named sources into one channel-tagged stream, keyed by the names I passed. That key is what the PFD routes on internally, so the labels are load bearing. roll has to be roll. The whole display ends up running on two sockets, one to the IMU and one to the HUD, which is about as lean as five live values across two topics gets. One more thing the merge does quietly: calling destroy() on the merged source tears down both child adapters, which is why the cleanup above only has to destroy the one thing it kept a handle to.

A note on the IMU topic, since it is an easy half hour to lose. Use /mavros/imu/data, not /mavros/imu/data_raw. The raw topic ships without orientation populated, so the quaternion is all zeros and your horizon sits there perfectly level while the aircraft rolls.

The conversion, and the value that goes NaN

The quaternion to roll/pitch/yaw conversion is standard, but the pitch term is an asin, and asin is only defined on the range minus one to one. Near vertical, where pitch approaches plus or minus 90 degrees, floating point error can push the argument a hair past one, and asin of 1.0000001 is NaN. One NaN in the pitch channel and the horizon blanks. So the conversion clamps the argument before the asin. You inherit that clamp for free through createImuAdapter, but if you pull quaternionToEuler out to use directly, that is the line that keeps a drone pointed straight up from blanking your display.

The map: GPS is two numbers that arrive separately

LiveMap is a controlled component. It does not take a dataSource, it takes a position. And GPS arrives as a sensor_msgs/NavSatFix message where latitude and longitude are two fields, which the adapter surfaces as two channels. So you merge them like the PFD, then accumulate the stream into a position object yourself.

export function LiveDroneMap({ url }: { url: string }) {
  const source = useMemo(() => {
    const gps = createRosbridgeAdapter({
      url,
      topic: '/mavros/global_position/global',
      messageType: 'sensor_msgs/NavSatFix',
      channels: {
        lat: (m) => m.latitude,
        lng: (m) => m.longitude,
      },
    });
    return mergeChannels({ lat: gps.lat, lng: gps.lng });
  }, [url]);

  const [position, setPosition] = useState<{ lat: number; lng: number }>();
  useEffect(() => {
    const latest: { lat?: number; lng?: number } = {};
    const off = source.subscribe((v) => {
      if (v.channel === 'lat') latest.lat = v.value;
      if (v.channel === 'lng') latest.lng = v.value;
      if (latest.lat !== undefined && latest.lng !== undefined) {
        setPosition({ lat: latest.lat, lng: latest.lng });
      }
    });
    return () => {
      off();
      source.destroy();
    };
  }, [source]);

  return position ? <LiveMap position={position} trackLength={800} /> : <LiveMap />;
}

The thing to notice is the accumulation. Latitude and longitude come in as separate samples, so position stays undefined until both have landed at least once. That is the position ? ... : <LiveMap /> at the end. For the first fraction of a second after connecting, before both axes have arrived, you render an empty map rather than a marker at the equator. trackLength is how many points of history the trail keeps.

The battery: when the firmware will not tell you the charge

The battery looks like the easy one, and on good hardware it is. createBatteryStateAdapter reads the state of charge straight off sensor_msgs/BatteryState and you are done.

export function LiveBatteryGauge({ url }: { url: string }) {
  const source = useMemo(
    () =>
      createBatteryStateAdapter({
        url,
        topic: '/mavros/battery',
        voltageRange: { min: 14.0, max: 16.8 }, // 4S LiPo (3.5–4.2 V/cell)
      }),
    [url],
  );
  useEffect(() => () => source.destroy(), [source]);

  return (
    <Gauge
      dataSource={source}
      min={0}
      max={100}
      label="Battery"
      unit="%"
      thresholds={[
        { value: 0, color: 'var(--vt-color-danger)' },
        { value: 20, color: 'var(--vt-color-warn)' },
        { value: 40, color: 'var(--vt-color-active)' },
      ]}
    />
  );
}

The voltageRange is there for the common case where the firmware cannot give you a charge percentage at all. Plenty of PX4 and ArduPilot setups publish percentage as minus one when there is no battery estimator configured, and a gauge reading a steady minus one is useless. When that happens, the adapter falls back to estimating charge from pack voltage, with voltageRange telling it the empty and full voltages of your pack. The 14.0 to 16.8 above is a 4S LiPo, 3.5 to 4.2 volts a cell. Be honest with yourself about what that estimate is, though. A LiPo's voltage sags under load and the discharge curve is famously flat through the middle, so a voltage based percentage is a presence of charge indicator, not a fuel gauge. It will tell you the battery is there and roughly how worried to be. It will not tell you how many minutes you have left.

The event log: text in a numeric world

The other three components all carry numbers. The log carries text and a severity, which the rest of the library has no concept of. Altara's data model is numeric all the way down, deliberately, because that is what keeps the high-frequency path fast. So there is no adapter for log messages, and rather than bolt strings onto a numeric pipeline, the log just talks to rosbridge directly. You open the socket, subscribe to /rosout, and map each message into the entry shape the log wants.

const ROSOUT_LEVEL: Record<number, EventLogEntry['severity']> = {
  20: 'info',
  30: 'warn',
  40: 'error',
  50: 'error', // rcl_interfaces/Log fatal -> error
};

export function RosoutEventLog({ url }: { url: string }) {
  const [entries, setEntries] = useState<EventLogEntry[]>([]);

  useEffect(() => {
    const ws = new WebSocket(url);
    ws.onopen = () =>
      ws.send(JSON.stringify({ op: 'subscribe', topic: '/rosout', type: 'rcl_interfaces/Log' }));
    ws.onmessage = (e) => {
      const data = typeof e.data === 'string' ? e.data : '';
      if (!data) return;
      const env = JSON.parse(data) as {
        op: string;
        topic?: string;
        msg?: { level: number; name: string; msg: string; stamp?: { sec: number; nanosec: number } };
      };
      if (env.op !== 'publish' || env.topic !== '/rosout' || !env.msg) return;
      const m = env.msg;
      if (m.level < 20) return; // skip debug
      setEntries((prev) =>
        [
          ...prev,
          {
            timestamp: m.stamp ? m.stamp.sec * 1000 + m.stamp.nanosec / 1e6 : Date.now(),
            severity: ROSOUT_LEVEL[m.level] ?? 'info',
            message: `[${m.name}] ${m.msg}`,
          },
        ].slice(-500),
      );
    };
    return () => ws.close();
  }, [url]);

  return <EventLog entries={entries} maxEntries={500} />;
}

Two things in there earn their keep. The slice(-500) caps the array you hold in state, and it is yours to remember. maxEntries on the component limits what gets rendered, not what you retain, so a chatty /rosout will grow your state without bound if you forget the slice. And map the fatal level (50) explicitly. If you leave it out it falls through to the ?? 'info' default, and a crash shows up colored like a routine status line, which is the one time you really do not want that.

What it took to make the horizon not lie

The wiring above is the part you write. The part you do not see is why the PFD holds together at all, and it comes down to two decisions that were not obvious to me until the naive version failed.

The first is that the entire instrument is one canvas driven by one requestAnimationFrame loop, and incoming data never touches React state. A PFD is really six instruments sharing a frame: the attitude sphere, the airspeed tape, the altitude tape, the vertical speed needle, the heading scale, and the flight director. The obvious React build gives each of them its own state and lets props flow down. The problem shows up in a banking turn. The airspeed tape repaints on one frame, the attitude on the next, and for a moment they are showing different instants of the same maneuver. The instrument visibly disagrees with itself. The fix was to stop using React for the moving parts entirely. Data, whether from mock, props, or rosbridge, mutates a single ref, and one animation loop reads that ref every frame and paints the whole instrument at once. React mounts the canvas and then gets out of the way. There are zero re-renders during flight, and because everything is painted from one ref in one pass, the six instruments can never disagree.

The second decision is a single minus sign, and it is the kind of bug that passes every screenshot and fails in the air. The horizon moves and the aircraft symbol stays fixed, which is how real attitude indicators work. You do that with a canvas transform, not by repositioning shapes:

ctx.translate(cx, cy);
ctx.rotate((-s.roll * Math.PI) / 180); // note the minus
ctx.translate(0, s.pitch * pitchPxPerDeg);

You rotate the coordinate system and draw the sky, ground, and pitch ladder into it, which is far simpler than computing rotated coordinates for every line and clips cleanly at the edges. The minus on the roll is the part that matters. The sphere has to rotate opposite to the aircraft, so that when the drone banks right, the horizon tilts left behind a fixed wing symbol. Drop the minus and a static screenshot looks completely correct, every line where you expect it. Then the aircraft banks and the horizon banks with it, in the same direction, and the instrument is now confidently telling the pilot the opposite of the truth. The flight director bars layer on top of all this from the error between commanded and actual attitude, which is why they drift toward center as the aircraft captures the command rather than sitting pinned.

Where that leaves you

The same four panels you built against fake motion are now running on a real aircraft, and almost nothing about the components changed between the two. That is the whole argument for starting in mock mode. The dashboard, the layout, the thresholds, the thing you actually design and iterate on, none of it cares whether the numbers are real. The real work was never the rendering, which the library handles, but the translation at the edges: a quaternion into degrees, five channels onto one instrument, two GPS axes into a position, a flat discharge curve into a believable percentage, and text logs into a pipeline that otherwise only counts.

The components are MIT licensed and on npm as @altara/core, @altara/aerospace, and @altara/ros. The full source for every snippet here lives in the repo, and there is a live demo of the dashboard if you want to see it move before installing anything. The live demo goes a step past the snippet in this post, with a streaming event log and the real wiring block included, both of which are exactly what we built above.