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.
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 |
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 |
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#
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:
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#
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, core 1, 5 |
1,000 ms |
30,000 ms |
none |
not run, no car |
|
OBD, core 1, 5 |
90 s, 10 s |
90 s, 10 s |
one run per search or connect |
not run |
|
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) |
|
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) |
|
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 throughsys_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.