Output format

picket-forest-v2

CAN frames with the expected score and alarms of the calibrated detector. Produced by picket-forest 0.2.0.

Input

Classic CAN frames of one vehicle, one at a time and in bus order: timestamp in microseconds, 11-bit identifier, DLC and up to eight data bytes. CAN FD and extended identifiers are not supported.
The calibration table of the same vehicle (picket_forest_table.h), made on the host from benign traffic of that vehicle before use (at least 60 minutes covering driving, idle and parked phases).
On the device, picket_forest_v2_process() takes one frame and returns 1 if that frame raises an alarm; it can also hand out the forest score and the rules decision of the frame.

Guarantees

expected_scores has one entry per frame, in the order of frames.
expected_alarms lists the indices of the frames that raise an alarm, ascending; every index is a position in frames.
The rules on the calibrated features decide; the forest score is information and does not raise an alarm by itself.
The C code of the release and the Python reference give identical scores and alarms for every frame (checked bit-exactly by the release gate).

Fields

Fields of picket-forest-v2
Field	Type	Allowed values	Meaning	Empty case
`source` required	string	–	Where the frames come from: `synthetic` (generated by the zoo's own CAN generator) or the id of a declared dataset that may be redistributed.	–
`generator`	object	–	For synthetic frames, the generator that made them: its `name`, `version`, random `seed` and the `attack` it injected (for example `fabrication`, `dos` or `fuzzing`), so the frames can be generated again.	–
`frames` required	array of array of any	–	The input, one entry per classic CAN frame in bus order: `[timestamp in microseconds from the first frame, identifier, DLC, [eight data bytes]]`.	–
`expected_scores` required	array of string	–	The forest score of every frame: the share of trees that vote attack, from 0 to 1, as the eight hex digits of its IEEE-754 float32 bit pattern (for example `3f800000` is 1.0), so that results compare exactly. The score is information only; it is not a calibrated probability and does not decide.	–
`expected_alarms` required	array of integer (≥ 0)	–	The indices of the frames at which the detector raises an alarm: frames flagged by the rules pass the alarm stage, which raises an alarm when enough flagged frames fall into a short window and then holds off for a while.	An empty list means no alarm for this frame sequence. For benign traffic of the calibrated vehicle that is the expected result.

Edge cases

Input	What you get
Benign traffic of the calibrated vehicle	`expected_alarms` is empty. This is the correct result, not a failure.
Traffic of a vehicle the table was not made for	Unknown identifiers and other frame rates raise false alarms; calibrate on the vehicle first.
CAN FD frames or 29-bit identifiers	Not supported; the format has no field for them.

Versioning

The format name ends in the version of the detector chain. picket-forest 0.1.0 used picket-forest-v1 (forest decides); 0.2.0 introduced picket-forest-v2 (calibrated rules decide, forest score as information). A change of features, decision or record layout gets a new format version; the old version stays documented.