OpenCarMind EdgeOS#

OpenCarMind EdgeOS is the firmware for the ESP-Mosaico. It runs on FreeRTOS’s preemptive scheduler and adds a small set of rules that decide what may run, when and how fast. This page covers the five parts a driver meets: the boot health check, the runlevels, model admission by response-time analysis, the degradation ladder and battery protection.

Animated, OpenCarMind EdgeOS 2.0.0 on the ESP-Mosaico in six steps: a layer of rules on top of FreeRTOS, under the models and apps. Boot health check: each part checked once after a start, health good at 68.0 s, safe mode with Wi-Fi held if bad. Wi-Fi held until healthy: no radio at boot, released at 68.0 s with 131,975 B of internal RAM free. Model admission: CarMind R.E.V answers in 4.2 ms against a 1,000 ms deadline and is admitted with a margin of 995.8 ms, and a model that would miss its deadline is refused. Parked or Driving: during a drive a model switch, the clock and a format are refused because a drive is running, while the model keeps running. Degradation ladder, in a forced test with extra load: UI slowed at 110.6 s, learner paused at 122.6 s, model paused at 134.6 s, back to normal at 348.6 s, and the model is never swapped. Battery protection, in a board test at lowered limits: hot at 34.2 C sheds load, cooled at 33.7 C restores it, and over-voltage at 4188 mV saves the logs and stops. Internal RAM stays above 60 KB in every phase, lowest about 81 KB OpenCarMind EdgeOS 2.0.0 on the ESP-Mosaico, rendered from the 2.0.0 screen code with example values: three 480 by 480 screens in the dark, light and dark themes. Drive at 64 km/h and 2350 rpm with the AI seeing Cruising 87 % sure, brake 6.3 bar, torque 85 N m and fuel 4.1 L/h, and the tank at 46 %, about 310 km. AI with the four class bars and its estimates. Learning with 14 updates kept, the air constant, a 50 L tank from 3 fill-ups and the model card

What it is#

OpenCarMind EdgeOS is not a new kernel. FreeRTOS, as ESP-IDF 6.1 ships it, still schedules the tasks on the S31’s two cores. The OS is a set of rules on top of it that decide what may run, when and how fast, and what happens when something goes wrong. It adds no task of its own. Its code runs inside the tasks that already exist: the board task every 2 s, the screen task, the USB door and the scheduler monitor.

The rules live in one plain C file, main/os_core.c, with no ESP-IDF calls in it, so the host tests on a computer check every rule. main/os.c connects the rules to the firmware. Files that the S3 build shares call the OS through macros in main/os_hooks.h, which turn back into the old S3 statement on the same line. That is how the OS layer leaves the S3 image as it was.

The parts and why each exists#

Part

What it does

Why it is there

One service table

Eight services (model switch, clock, format, Wi-Fi edit, Wi-Fi radio, the USB door’s commands, the model, the R.E.V learner) each have a mask of the runlevels they may run in. Each model and learner also declares its period, deadline, stall limit, CPU share, self-test and fallback model in one contract table.

Before 2.0.0 these rules were separate if checks spread over the screen, the USB door and the board task. Now one table holds them, and a source audit in the host tests fails if a file decides a refusal by itself.

Runlevels

Boot, Safe, Parked, Driving, Saving and Update. Several can hold at once, and a service runs only if every active runlevel allows it.

In the middle of a drive, a model switch would mix two models’ answers in one log, a clock change would break its timestamps, and a format would erase the drive being written. The board refuses them in one place and says why.

Boot health check

About 65 s after a start the board rates itself good, degraded or bad from the model self-test, the flash FAT check, the NAND, the first screen update, the touch controller and the scheduler’s misses, stalls and response times.

It gives you one line to read on the Board page. It is also the signal an A/B rollback needs to keep or reject a new image.

Model admission

A model loads only if response-time analysis says every job on its core still meets its deadline (see below).

A model that is too slow would make the OBD poll or the learner miss deadlines. The check refuses it before it loads, and the old model stays.

Degradation ladder

When the model misses deadlines, the board steps down: first the AI services slow to a tenth of their rate with their learned heads off (new, being checked on the board), then the screen refreshes every 33 ms instead of 16 ms and the AI services pause, then the R.E.V learner pauses, then the model’s inference pauses. A minute without misses steps back up, in reverse order. Misses of the screen or the AI services alone reach the first rung only.

Estimates such as the battery SoC, screen frames and learning are worth less than the log and the model during a drive, so they go first. The ladder never swaps models.

AI services

Small periodic AI jobs, the battery SoC and SoH estimator first, in one worker task below the screen and the models, admitted by the same response-time analysis (see below). On build 13757fd the board admitted the worker on core 1 with R 2.00 ms. The estimates are being checked.

More small models are coming, a Bluetooth and Wi-Fi intrusion detector next. Each one gets a deadline, a CPU budget and a place on the ladder, instead of its own task and its own rules.

Battery protection

Every 2 s it reads the gauge’s voltage, current and temperature. At 45 °C on USB it sheds load, at 60 °C it stops safely, and at 4.25 V or more it reports a charger fault and stops.

The TP4057 charger has no enable pin and no thermistor input, and its supply comes from USB through diodes. The firmware cannot stop charging, so it watches and stops cleanly instead. The thresholds are placeholders until the cell’s datasheet is known.

Wi-Fi boot hold

No Wi-Fi starts at boot. The automatic start waits for the health verdict and goes ahead on good or degraded. Your own start in the Wi-Fi app is never held.

On mossREV 1.2.0 rc3 the boot window was the internal-RAM low point, 57.7 KB free while the Wi-Fi driver started (measured on the board).

One reset path

Every reset the firmware asks for goes through sys_reset(reason): mark it as asked for, flush and lock the flash FAT and the NAND, then reset. The screen stall guard and the hung-job restart skip the mark, so three of them in a row still start safe mode.

A reset between a sector’s erase and its write had torn the FAT and lost the whole volume twice on the bench, before the storage fixes. Now no asked-for reset skips the flush.

Feature gate

One OS service runs the A/B test for Smart swipe and the Smart UI prefetch: the 50/50 split, the Mann-Whitney test, the Holm correction and the verdict per firmware version.

Each feature had its own copy of the same statistics. Now the thresholds sit in one place that no feature can change, and Smart swipe gave back 776 bytes of internal RAM.

PPA and 2D-DMA graphics

The launcher slide’s window copies, the page pictures’ byte swap and large opaque LVGL fills and image copies run on the S31’s pixel-processing accelerator and 2D-DMA, with a CPU fallback.

The CPU did these copies row by row. The chip has engines for them. A full frame still needs 23.6 ms on the panel’s QSPI link, so the gain is in composing, not in sending.

Services and runlevels#

How the OS decides what may run, drawn as a hand-drawn flow. Step 1, inputs the OS reads: fresh on every check, from start-up, the count of abnormal resets, the drive log and the car link, the battery gauge and USB power, and the reset path and the format, read in rl_inputs() in main/os.c. Step 2, it sets the active runlevels: Boot when start-up has not finished, Safe after 3 abnormal resets in a row, Driving when a drive is recorded or the car's computer answers, Saving when the battery is hot or over-voltage or USB is lost (UPS option, off), Update when a reset, a door entry or a format is running, and Parked when none of these holds. Several can hold at once, for example Safe while Driving. Step 3, a service asks to run: model switch, clock, format, Wi-Fi edit, Wi-Fi radio, USB door, model or R.E.V learner, one mask each in MASK[] in main/os_core.c. Step 4, os_allows(service): every active runlevel must allow the service, and one that does not is enough to stop it. Step 5, yes: the service runs. No: refused with the phrase of the highest blocking runlevel, highest first: Update, an update or format is running. Saving, the board is saving power. Driving, a drive is running, or the car link is up when only the link is on. Safe, safe mode is on. Boot, the board is starting. Parked never blocks, because every service allows it. Separately, once per boot: step 6, boot health at 65 s rates the board good, degraded or bad. Step 7, good or degraded: the Wi-Fi task starts. Bad: Wi-Fi is held until you start it, and a start you make yourself in the Wi-Fi app is never held.

Which runlevels each service may run in, from the mask table in main/os_core.c:

Service

Boot

Safe

Parked

Driving

Saving

Update

Model switch (screen, desktop app)

no

no

yes

no

no

no

Set the clock by hand

yes

yes

yes

no

no

no

Format storage

no

yes

yes

no

no

no

Add or forget a Wi-Fi network

yes

yes

yes

no

no

no

Wi-Fi radio (search, join, clock sync)

yes

yes

yes

no

no

no

USB door commands after pairing

yes

yes

yes

no

no

no

Load the model at boot

yes

no

yes

yes

yes

no

R.E.V learner

yes

no

yes

yes

no

no

Safe still allows a format, the clock, the door and Wi-Fi, so a board in safe mode can always be repaired.

Model admission by response-time analysis#

A model is a real-time job. It has to answer once per second while the OBD poll and the learner share its core. When a model loads at boot or on a switch, the OS takes its self-test run time, doubles it (one measured run is not a worst case), and uses that as the model’s worst-case CPU time C. Then it runs the response-time analysis of Joseph and Pandya[5] for every job on that core:

\[R_i = C_i + \sum_{j \in hp(i)} \left\lceil \frac{R_i}{T_j} \right\rceil C_j\]

Ri is job i’s worst-case response time, the longest it can take from its release to its finish. Ci is its worst-case CPU time. The sum runs over hp(i), the jobs on the same core with a higher priority. Tj is the period of such a job j, so ⌈Ri / Tj⌉ counts how many times j can start, and take its Cj, while job i waits. Ri appears on both sides, so the OS starts from Ri = Ci and repeats the sum until the value stops changing. Job i meets its deadline when Ri ≤ Di. If any job on the core would miss, a switch is undone like a failed load and the screen says, for example, “Not switched: CarMind E.V refused: ml would miss its deadline.” (ml is the models’ job.) A boot load that fails leaves the model off, with an error event.

On the board, the first boot of a 2.0.0 build before the rename (09ec8f5) logged admission CarMind R.E.V: C 4472 us (self-test 2236 us x 2.0) on core 1, R: ml 4.5/1000 ms, margin 995.5 ms (ml): admitted. The log lists only the ml job: the other jobs on core 1 had no measured run yet at 4.3 s, so this first check held the model alone. Host tests pass for the textbook three-job set (C 3, 3, 5 and T 7, 12, 20 give R 3, 6, 20) and for 90,013 random job sets compared with the scheduler monitor’s own loop.

Scheduler budgets per core#

Scheduler budgets per core, drawn as Gantt lanes. Core 1, one 1,000 ms window on an axis broken at 40 ms: obd_poll, priority 5, period 1,000 ms, deadline 30,000 ms, not run on the bench. The ml job, priority 3, period and deadline 1,000 ms, self-test 2.1 ms doubled to a budget of 4.2 ms, admitted with R 4.2 ms on 4aeff43. The rev job, the R.E.V learner, priority 2, period 1,000 ms, deadline 30,000 ms, a 2 % share of 20 ms per second with bursts of at most 30 ms, no run on the bench. Core 0, one 100 ms window: the ui screen job, priority 2, period and deadline 50 ms, worst response 7.8 ms and worst CPU 4.98 ms over 9,597 runs in the 10-minute soak on 06ddf1d, 0 misses. The LVGL refresh every 16 ms. Slow jobs over the first 120 s: boot on 4aeff43 with Wi-Fi held from 4.3 s, the health verdict due at 65 s and good at 68.0 s, the Wi-Fi driver up from 88.1 to 106.5 s and the clock synced at 98.0 s. The learner's 30 s deadline windows and 60 s stall limit. The model's 10 s stall limit. The link_search, obd_poll and ecu_pick deadlines are of 90, 30 and 10 s. The board task every 2 s and the scheduler summary every 60 s.

Every timed job registers a period T and a deadline D with the scheduler monitor. The task it runs in sets its core and priority. The chart takes those from the code and puts the board’s measurements inside them. The model gets 1,000 ms and its admission budget is 4.2 ms, so the first 40 ms of the core 1 axis are drawn 23 times wider, or the bar would be thinner than a pixel. No car was connected on the bench, so the OBD jobs, the model and the learner never ran as periodic jobs there. Their bars are the code’s budgets. The measured ones are the model’s self-test at admission and the screen job over the soak.

Job

Task, core, priority

T

D

Budget in the code

On the board

obd_poll

OBD, core 1, 5

1,000 ms

30,000 ms

none

not run, no car

link_search, ecu_pick

OBD, core 1, 5

90 s, 10 s

90 s, 10 s

one run per search or connect

not run

ml

model, core 1, 3

1,000 ms

1,000 ms

C = 2 × self-test, stall 10 s

self-test 2.1 ms, C 4.2 ms, R 4.2 ms, admitted (4aeff43)

rev

learner, core 1, 2

1,000 ms

30,000 ms

20 per mille of a core in 30 ms bursts, stall 60 s

contract logged, no runs (4aeff43)

ui

screen, core 0, 2

50 ms

50 ms

none

9,597 runs, worst response 7.8 ms, worst CPU 4.98 ms, 0 misses (06ddf1d)

The screen job’s 7.8 ms is wall time from the start of a run to its end, and 4.98 ms is the CPU the screen task used in it. The difference is time the task waited for other tasks on core 0. The response-time analysis counts only registered jobs, so it reports 4.98 ms for ui. The board task (every 2 s), the Wi-Fi task and the scheduler monitor run on core 0 outside the job table.

What you see on the board#

  • The firmware reads “OpenCarMind EdgeOS 2.0.0” on the boot line, in Settings and on the Board page. The desktop app sees fw=EdgeOS-2.0.0.

  • The Board page’s header shows the runlevel and the health at the top right, for example “Parked, health good” in green. Degraded is amber and bad is red. The events list gets “Boot health: good” or the reasons, such as “Boot health: degraded: NAND not mounted”.

  • Wi-Fi stays off for about the first minute after a start. Then the automatic clock sync runs, and on a board whose clock is not set the first sync follows about 20 s later.

  • A refused change says why. During a drive: “A drive is active. End the drive first, then switch models.” For other actions during a drive: “Not now: a drive is running. Try again later.” When the car’s computer answers but no drive is recorded yet: “Not now: the car link is up. Try again later.” The USB door answers “ERR busy: a drive is running, try again when parked”.

  • The ladder and the battery write events such as “Model deadlines: UI slowed”, with the miss count, or “Battery hot (45.0 C on USB): load shed”.

  • The Board page’s battery card shows the current, “on USB” or “on battery”, the gauge temperature, and “uncalibrated” with the cycle count until the gauge is set up for the 65 mAh cell.

The user manual lists every message with what to do about it.

What it costs#

Measured with idf.py size on the S31 build of the release (920318e, the firmware in main), against mossREV 1.2.0 rc3 (8b0b96f):

OpenCarMind EdgeOS 2.0.0

mossREV 1.2.0 rc3

Change

App image

4,778,560 B, 76.0 % of the 6 MB app slot (24 % free)

4,752,720 B

+25,840 B

Static internal RAM (DIRAM)

194,198 B of 503,744 B (38.6 %)

192,124 B

+2,074 B: PPA and 2D-DMA +2,380 B (mostly IRAM code), the pairing change +184 B, the OS parts and fixes +100 B, the feature gate −590 B

Static PSRAM

291,200 B

289,664 B

+1,536 B, mostly the admission’s buffers (1,352 B)

Tasks

the same tasks as 1.2.0

none added: the OS layer runs inside the existing tasks

At 09ec8f5 the graphics work had added 37,312 B to the app image and the OS parts together about 9 KB. The 16 px text floor later saved 24,304 B by dropping the 12 and 14 px fonts, so the release is 25,840 B larger overall. With the UPS option switched on, the deep-sleep path alone would add about 12 KB of IRAM, which is one reason that option stays off.

The target for internal RAM at run time is more than 60 KB free in every phase. This was measured on the board, OpenCarMind EdgeOS 2.0.0 4aeff43, with a debug build of that code that adds a RAM monitor. Each figure is the lowest free internal RAM in that phase, all internal heaps added up:

Phase

Lowest free internal RAM

The first minute after a start, before Wi-Fi

127,407 B

The first Wi-Fi round, with the automatic adapter search

82,907 B

An adapter search alone

112,935 B

An adapter search and Sync clock now together

82,883 B

Sync clock now alone

82,907 B

Wi-Fi search

88,791 B

A theme switch

112,799 B

A switch to E.V

102,383 B

A launcher slide

112,599 B

The lowest is 82,883 B, about 81 KB, with an adapter search and a clock sync running at once. Every phase stays above 60 KB. Two parts of that total were never used in any phase: the 32 KB internal reserve (32,031 B free) and the LP RAM (31,948 B free). The main heap alone went down to 18,900 B.

Before 4aeff43, the Board page’s “lowest” read 32 KB too low. A photo showed 49 KB. ESP-IDF sets the minimum of a heap added after start-up to 0 (heap_caps_init.c, lines 325 to 332, in ESP-IDF 6.1). The 32 KB internal reserve is added that way, so the summed minimum always counted that pool as empty. 4aeff43 restarts the minimum count early in the boot. RAM use stays the same. Only the figure changes.

Prepared but off: A/B rollback and the battery as a UPS#

Two parts are built into 2.0.0 and switched off by default.

  • A/B rollback (CONFIG_OCM_APP_ROLLBACK). The flash has two 6 MB app slots. With ESP-IDF’s app rollback, a new image gets one boot to confirm itself. A good or degraded health verdict would confirm it, and a bad one would reset into the other slot through sys_reset. It stays off because today’s flashing writes slot 0 with esptool and leaves otadata erased, so no image is ever in the state that arms the rollback. Turning it on needs a change to the flashing flow first, and that is the owner’s decision.

  • The battery as a UPS (CONFIG_OCM_UPS). Two gauge readings in a row at or below −20 mA would mean USB is gone: flush the logs, dim the screen, refuse changes, and wait 15 s, because cranking the engine drops the car’s USB for a few seconds. Then quiesce the storage and pull GPIO57 low, the board’s power-switch request. At 3.4 V on battery it would act at once. It stays off until the board’s real draw and the gauge’s current sign are measured. The power-off through GPIO57 for the battery protection (CONFIG_OCM_BATSAFE_POWER_OFF) waits for the same check.