Revize Controllerů

Jak ve Spectoda codebase rozlišujeme produktový kód, PCB kód, firmware verzi a systémovou revizi Controlleru.

Co znamená revize Controlleru ve Spectoda

Když v týmu nebo při servisu mluvíme o „revizi Controlleru“, může jít o několik různých vrstev:

Identifikátor	Co popisuje	Typický příklad	Praktický dopad
`productCode`	produktový kód Controlleru	`SC Industry A2`, `SC Pixel B2`	říká, do jakého produktu ten kus patří
`pcbCode`	PCB kód Controlleru	`PCB_CODE_PIXEL_B1_REV1`	říká, jaká konkrétní HW verze PCB byla pro ten kus použita
`fwVersion`	Aplikační verzi firmwaru	`0.12.11`	určuje dostupné funkce a bugfixy
`systemRevision`	Nízkou systémovou revizi běhového prostředí	`rev0`, `rev1`	určuje OTA chování, layout paměti a migrační pravidla

Nejdůležitější záměna je mezi PCB Kódem a systémovou revizí:

PCB kód říká, jaká fyzická deska nebo konkrétní HW verze PCB je uvnitř Controlleru.
Systémová revize říká, na jakém nízkoúrovňovém runtime profilu Controller běží.

Tyto dvě informace spolu mohou souviset, ale nejsou to totéž.

produktový kód

produktový kód určuje, do jakého produktu daný Controller patří. Je to obchodní a katalogová identita kusu.

Prakticky odpovídá na otázku:

Co je to za produkt?

Typicky podle něj poznáte, jestli jde například o:

SC Industry A2
SC Pixel B2
jinou konkrétní sellable variantu v produktové vrstvě

Pro výrobu a servis je produktový kód důležitý hlavně proto, že:

váže kus na správný produkt v interním katalogu
určuje, jaký typ Controlleru nebo zařízení se má očekávat
tvoří nadřazenou identitu, na kterou se pak napojuje konkrétní použitý PCB kód

PCB kód

PCB kód určuje, jaká konkrétní HW verze PCB byla použita pro tento konkrétní kus.

Prakticky odpovídá na otázku:

Jaká přesná deska je uvnitř tohoto kusu?

To je důležité hlavně tam, kde jeden produktový kód může v čase běžet na více HW verzích PCB, nebo kde je potřeba přesně vědět:

jaké PCB bylo skutečně osazeno
jaká HW baseline byla použita při výrobě
jaký servisní nebo výrobní postup k tomu kusu patří

Jinými slovy:

produktový kód říká, jaký je to produkt
PCB kód říká, jaká konkrétní HW verze PCB byla použita pro tento kus

PCB kód je tedy na produktový kód napojený, ale není to totéž. produktový kód určuje produktovou identitu a PCB kód určuje konkrétní hardwarové provedení toho kusu.

Co dnes codebase skutečně rozlišuje

Ve firmware i ve vyšších vrstvách se Controller identifikuje kombinací několika údajů:

Firmware vrací productCode a pcbCode jako výrobní identitu Controlleru.
Firmware vrací systemRevisionCode, ze kterého se v runtime skládá čitelný tvar jako rev0 nebo rev1.
WASM a JavaScript vrstvy posílají tuto informaci dál do Studio tooling, takže Controller Info může ukázat nejen verzi FW, ale i systémovou revizi.

Prakticky to znamená, že dva Controllery mohou mít:

stejný productCode
stejný pcbCode
stejnou verzi FW

a přesto se mohou lišit v systemRevision, pokud ještě neběží na stejném systémovém základu.

Systémová revize: co je dnes v codebase

Aktuální firmware architektura pracuje se dvěma známými systémovými revizemi:

rev0 = původní 4MB layout
rev1 = novější layout se zvětšenými OTA sloty

Systémová revize nepopisuje aplikační logiku, ale například:

rozložení partition table
velikost OTA slotů
očekávané chování bootu a post-OTA kroků
budoucí rozdíly typu jiná flash geometrie, bootloader nebo PSRAM baseline

Proto nestačí při servisu nebo výrobě sledovat jen verzi firmwaru. Stejná firmware řada může dočasně běžet na více systémových revizích současně.

Co se mění mezi `rev0` a `rev1`

V současné codebase je přechod mezi rev0 a rev1 spojený hlavně se změnou layoutu paměti:

OTA sloty v rev1 jsou větší než v rev0
LittleFS prostor se proti rev0 zmenšuje
při migraci se musí přepsat partition table

To je důvod, proč rev0 a rev1 nejsou jen „jiná čísla“, ale dvě odlišné provozní základny Controlleru.

Praktický dopad:

některé větší firmware image už se do starého rev0 OTA slotu nevejdou
Controller na rev0 může potřebovat jednorázovou migraci na rev1
po přechodu na rev1 pokračují běžné OTA aktualizace standardně

Jak se revize propisuje do OTA

Codebase s revizí Controlleru aktivně pracuje při OTA:

Controller inzeruje, jak velký firmware image ještě zvládne přijmout
peer OTA kontroluje, jestli cílový Controller unese velikost image
pokud ne, update se má přeskočit nebo odmítnout místo toho, aby Controller skončil v rozbitém OTA stavu

To je důležité hlavně v síti, kde spolu dočasně existují starší i novější Controllery.

Další důležité pravidlo je, že nízkoúrovňové migrace mají být krokové:

rev0 -> rev1
rev1 -> budoucí rev2

Nemá se přeskakovat přímo mezi vzdálenými revizemi, protože každá revize má mít vlastní migrační smlouvu, recovery logiku a post-OTA kroky.

Co to znamená pro výrobce

Pro výrobu a provisioning je bezpečné brát tyto údaje jako samostatné vrstvy:

productCode = produktový kód, tedy co je to za produkt
pcbCode = PCB kód, tedy jaká konkrétní HW verze PCB byla použita pro tento kus
systemRevision = jaký nízkoúrovňový runtime profil na Controlleru skutečně běží

Doporučený provozní přístup:

při výrobě a flashování nových kusů evidovat productCode, pcbCode i systemRevision
brát pcbCode jako kusovou informaci o reálně použité PCB verzi
neplést produktový kód s PCB Kódem, protože každý řeší jinou vrstvu identity
neodvozovat kompatibilitu pouze z verze FW
u starších kusů počítat s tím, že mohou být ještě na rev0
pro nové výrobní baseline směřovat na novější systémovou revizi, aby nebyla potřeba dodatečná migrační mezivrstva

Co to znamená pro tvůrce a servis

Pro tvůrce, integrátory a servis má tahle informace hlavně diagnostickou hodnotu:

dva Controllery se stejnou verzí FW se mohou při OTA chovat odlišně
problém nemusí být v projektu ani v konfiguraci, ale v rozdílné systémové revizi
pokud je Controller po HW stránce „správný“, ale update se nevejde, často je potřeba řešit právě migraci revize

Jinými slovy: verze FW říká, co Controller umí; systémová revize říká, na jakém základu to umí provozovat.

Doporučení pro praxi

Pokud potřebujete mít v projektu nebo výrobě pořádek, ukládejte u každého Controlleru minimálně tyto čtyři údaje:

productCode
pcbCode
fwVersion
systemRevision

Teprve kombinace těchto čtyř polí dává úplný obraz o tom:

co je to za Controller
jaký má hardware základ
jaký software na něm běží
jaké má reálné OTA a servisní možnosti