quorum
In one minute
- The compiler checks every situation the rules can meet. That proves the rules. It says nothing about the wiring.
- Commissioning is the day you bring the finished rulebook to the real machine and prove each reading comes from the right instrument.
- quorum prints a commissioning sheet: one line per reading, with the action the rulebook must report when you set that reading.
- You work the sheet by hand on the machine, write down what you saw and who saw it, and sign it.
- A bench test can drive a board through the same sheet over a wire first, so you meet the machine with a board you already trust.
Who this is for
This guide is for the engineer or technician who has a rulebook that passed its check and now has to put it on a plant. You trust the rules. The question this guide answers is the next one: how do you prove the plant is wired to match the rules, before you rely on it.
A rulebook is a set of rules for a small machine, written in plain words. The check is the compiler trying every combination of readings. Commissioning is the work after the check, on the real machine.
What a loop check is, and why the rules are not the whole job
A loop check is an old idea from instrumentation. You follow each measurement from the sensor in the field, through the wiring and the controller, to where it is used. You force a known condition at the sensor and confirm the right value arrives at the other end.
quorum needs the same thing. The every-situation check proves what the rules do with the readings they are given. It cannot prove that the readings are true.
This is stated plainly in the quorum honest limits. The check is exhaustive about the rules and silent about the wiring. The commissioning sheet is the tool that covers the second half.
The commissioning sheet
The sheet comes straight from the compiler. The command is:
cbc pump.cb --commissioning pump.sheetquorum studio prints the same sheet for you after a passing check, or on its own with the Commissioning action. The sheet is tab-separated text, so it opens in any spreadsheet and prints on one or two pages.
The top of the sheet names the rulebook, its version, and its fingerprint. The fingerprint is a short number computed from the whole rulebook, including every threshold. For the shipped pump rulebook it is 0x1a375f9d. The board must report this same number at start-up. If it does not, the board is running a different rulebook, and the sheet does not apply to it.
Then the sheet lists the actions in the order the board numbers them, and the action the rulebook takes at rest, with nothing wrong. For the pump that is continue.
After that comes one line per reading. The real pump sheet has fourteen readings. Here are four of its rows, with the columns named.
| reading | how it is set | alone | with | then | without |
|---|---|---|---|---|---|
| bearing_temp_high | presence bit 3 | continue | vib_high | shutdown | continue |
| crackling | presence bit 6 | continue | vib_high, vib_bpf | continue | maintain |
| near_critical | presence bit 9 | continue | vib_high, vib_1x | shutdown | maintain |
| throttled | presence bit 8 | continue | — | — | — |
Read a row left to right.
- The reading and how it is set tell the technician what to force at the machine.
bearing_temp_highis set by presence bit 3. A reading backed by a sensor channel shows the threshold, stale limit, or flatline that sets it instead. - Alone is the action the rulebook must report when only that reading is set. For every pump reading here it is
continue: on its own, one symptom changes nothing. That is a property of this rulebook, not a rule for all of them. - With is the fewest other readings that make the reading matter, up to three.
bearing_temp_highmatters oncevib_highis also set. - Then is the action with the reading set, alongside the "with" readings:
bearing_temp_highwithvib_highgivesshutdown. - Without is the action when you take the reading away but keep the "with" readings:
bearing_temp_highremoved,vib_highstill set, givescontinue.
So the row proves its reading does real work. The technician forces both conditions, confirms the board says shutdown, then clears the bearing condition and confirms it drops back to continue. The throttled row shows dashes in the last three columns: that reading never changes any decision, alone or with up to three others. The sheet tells you so, which is worth knowing at commissioning.
The printable sheet, with sign-off
The sheet has columns the compiler leaves blank on purpose: what was seen, and who saw it. A technician forces each condition, reads the board, writes the result in those columns, and initials the row. At the bottom the sheet carries the rulebook name, its version, its fingerprint, and a place for the name and date of the person who signed the loop check off.
That turns the loop check into a record. The rulebook already carries the document it came from, its version, and its author. The signed sheet adds the proof that this rulebook was checked against this machine on this day by this person. If a threshold or a wire changes later, the fingerprint changes, and the old sheet no longer matches. You commission again.
Test the board first, over Modbus
Before you take anything to the plant, you can drive a board through the whole sheet on the bench. The command is:
quorum-studio bench pump.cb -port COM4The bench test talks to the board over Modbus, the same way a PLC would. It walks every line of the sheet: the rest state, each reading alone, and each reading with the readings that make it matter. For each it writes the readings into the board, reads back the decision, and checks it against the sheet.
The bench test does two safety checks of its own.
- It refuses a board that reports a different fingerprint. The pump image must report
0x1a375f9d. A board running any other image is running different rules, and the test stops rather than pass it by mistake. - It refuses rulebooks that use raw sensor channels. A channel's reading comes from a stream of samples a controller must keep writing, which a single Modbus write cannot reproduce faithfully. Those readings stay on the sheet for the loop check on the real machine.
Measured on a Raspberry Pi Pico 2 with the pump image, the bench test drove 41 of 41 states exactly as the sheet says. That figure is from the quorum repository.
A rulebook with timed readings, such as "pressure high within 10 s after a start", needs a test through time, not a list of states. The compiler adds a script to the sheet: each timed reading just inside and just outside its window, then every line of the sheet. The bench test plays it on the board's test clock, which moves the board's clock forward, so an hour-long window takes seconds. On a Pico 2, the two timed example rulebooks passed 19 of 19 and 17 of 17 checks.
The test clock can only be turned on right after the board starts, and it stays on until the board is reset. Reset the board before it goes into service. On a board that has already been written to, the bench test can wait in real time instead, which takes over an hour.
The bench test checks the board. It proves the board decides every line of the sheet the way the compiler said it would. It does not check the plant. Only the sheet, worked through on the real machine, checks the wiring.
What quorum does not do here
Be clear about the limits, because commissioning is where overclaiming does the most harm.
- No plant has done this yet. The sheet, the sign-off, and the bench test are built and tested. quorum has not run a working machine. It is not certified for safety-critical use. Use it beside your existing protections, not instead of them.
- The Uno R4 bench test has not been run. The 41-of-41 figure is from a Pico 2. The bench path for the Arduino Uno R4 Minima has not been measured. Do not assume it until it is.
- The sheet does not set your thresholds. It reports the thresholds in the rulebook and the actions they produce. Whether a threshold is right for your machine is a decision in the source document, not something the loop check can settle.
- A passing bench test is not a passing plant. The two are different proofs. The bench test says the board matches the sheet. The signed sheet says the machine matches the board. You need both, and only a person at the machine can produce the second.
To see what the every-situation check does prove, and where it stops, read checking every situation. To understand how a reading is tied to its sensor and its threshold, the rulebook language describes every keyword.