Controller revisions

How the Spectoda codebase distinguishes product code, PCB code, firmware version and controller system revision.

What controller revision means in Spectoda

When the team or service documentation mentions a “Controller revision”, it can refer to several different layers:

Identifier	What it describes	Typical example	Practical impact
`productCode`	Controller product code	`SC Industry A2`, `SC Pixel B2`	tells which product the unit belongs to
`pcbCode`	Controller PCB code	`PCB_CODE_PIXEL_B1_REV1`	tells which concrete PCB hardware version was used
`fwVersion`	application firmware version	`0.12.11`	defines available features and bug fixes
`systemRevision`	low-level runtime system revision	`rev0`, `rev1`	defines OTA behaviour, memory layout and migration rules

The most important distinction is between PCB code and system revision:

PCB code describes the physical board or concrete PCB hardware version inside the Controller.
System revision describes the low-level runtime profile on which the Controller runs.

These values may be related, but they are not the same thing.

Product code

Product code defines which product the Controller belongs to. It is the commercial and catalogue identity of the unit.

It answers the practical question:

What product is this?

Typical examples include:

SC Industry A2
SC Pixel B2
another sellable product variant in the product layer

For manufacturing and service, product code matters because it:

connects the unit to the correct product in the internal catalogue
tells what type of Controller or device should be expected
provides the parent identity to which the concrete PCB code is connected

PCB code

PCB code defines which concrete PCB hardware version was used for this exact unit.

It answers the practical question:

Which exact board is inside this unit?

This is important when one product code can use multiple PCB hardware versions over time, or when you need to know exactly:

which PCB was actually assembled
which hardware baseline was used in manufacturing
which service or production workflow belongs to that unit

In other words:

product code tells what product it is
PCB code tells which concrete PCB hardware version was used for that unit

PCB code is connected to product code, but it is not the same thing. Product code defines product identity, while PCB code defines the concrete hardware implementation of the unit.

What the codebase distinguishes today

In firmware and higher-level tooling, a Controller is identified through a combination of several values:

Firmware returns productCode and pcbCode as the manufacturing identity of the Controller.
Firmware returns systemRevisionCode, which is converted at runtime into a readable value such as rev0 or rev1.
WASM and JavaScript layers pass this information into Studio tooling, so Controller Info can show not only the FW version, but also the system revision.

In practice, two Controllers can have:

the same productCode
the same pcbCode
the same FW version

and still differ in systemRevision if they are not yet running on the same system baseline.

System revision in the current codebase

The current firmware architecture works with two known system revisions:

rev0 = the original 4 MB layout
rev1 = the newer layout with larger OTA slots

System revision does not describe application logic. It describes things such as:

partition table layout
OTA slot size
expected boot and post-OTA behaviour
future differences such as different flash geometry, bootloader or PSRAM baseline

That is why firmware version alone is not enough during service or manufacturing. The same firmware line can temporarily run on multiple system revisions at the same time.

What changes between `rev0` and `rev1`

In the current codebase, the transition between rev0 and rev1 is mainly connected to memory layout:

OTA slots in rev1 are larger than in rev0
LittleFS space is smaller compared to rev0
migration requires rewriting the partition table

This is why rev0 and rev1 are not just different numbers. They are different operating baselines for the Controller.

Practical impact:

some larger firmware images no longer fit into the older rev0 OTA slot
a Controller on rev0 may need a one-time migration to rev1
after migration to rev1, standard OTA updates continue normally

How revision affects OTA

The codebase actively uses controller revision during OTA:

the Controller advertises the maximum firmware image size it can still receive
peer OTA checks whether the target Controller can accept the image size
if it cannot, the update should be skipped or rejected instead of leaving the Controller in a broken OTA state

This matters especially in networks where older and newer Controllers temporarily coexist.

Another important rule is that low-level migrations should be step-by-step:

rev0 -> rev1
rev1 -> future rev2

Direct jumps between distant revisions should not be used, because each revision needs its own migration contract, recovery logic and post-OTA steps.

What this means for manufacturers

For manufacturing and provisioning, treat these values as separate layers:

productCode = product code, or what product the unit is
pcbCode = PCB code, or which concrete PCB hardware version was used
systemRevision = which low-level runtime profile is actually running on the Controller

Recommended operational approach:

record productCode, pcbCode and systemRevision during manufacturing and flashing
treat pcbCode as unit-level information about the PCB version actually used
do not confuse product code with PCB code, because each describes a different identity layer
do not infer compatibility from FW version alone
expect older units to still be on rev0
use the newer system revision for new production baselines so that an extra migration layer is not needed later

What this means for creators and service

For creators, integrators and service technicians, this information is mainly diagnostic:

two Controllers with the same FW version can behave differently during OTA
the issue may not be in the project or configuration, but in a different system revision
if the Controller hardware is correct but the update image does not fit, revision migration is often the thing to check

In short: FW version tells what the Controller can do; system revision tells what baseline it can run that firmware on.

Practical recommendation

For clean project or manufacturing records, store at least these four values for every Controller:

productCode
pcbCode
fwVersion
systemRevision

Only the combination of these four fields gives the full picture:

what Controller it is
what hardware baseline it has
what software runs on it
what its real OTA and service options are