Decode rules · Last updated 2026-08-07

Decode the coded sentences of your installation

A VDR records many sentences that Stingray can recognize but cannot interpret. Examples are XDR transducer words, ALA and ALR alarms, and engine telegraph sentences. The meaning of their fields is specific to your installation. Which transducer is the rudder, and which alarm code is the watertight door, is in no public standard. That knowledge is in the Record of Configuration of your ship. A decode rule carries it into Stingray.

Rules are data, not code

A rule is data that you can review. Rules apply at display time, never at ingest. Stingray does not change the recorded track, and the raw coded sentences stay visible beside every derived value. If you delete a rule, you lose nothing. Stingray has no vendor meanings in its code. Meaning enters Stingray only as text that an analyst can read and review.

1. The parts of a rule

One rule reads one value from one sentence type. Three parts are always necessary: formatter, field and label. The other parts control if the rule applies, and how the value reads.

formattere.g. XDR · ALA · PAVBIOP

The formatter selects which sentence the rule reads. Take it from the tag of the sentence, without the $ at the start. For a standard sentence, use the three-letter type without the talker: write XDR, not IIXDR. For a proprietary sentence, keep the whole address: PAVBIOP, not PAVB. One maker code covers several different sentences. To read more than one value from one sentence, make one rule for each value.

channele.g. 000a (the sheet's CH-10)

The channel limits the rule to one source channel. Two instruments can send the same sentence type with different meanings, for example an engine-room alarm and a bridge-console alarm. If you leave the channel blank, the rule reads the sentence from all channels. Be careful with the numbering: configuration sheets count channels in decimal, but the recording labels them in hex. The sheet's CH-10 appears as 000a, and CH-19 appears as 0013. Enter the channel as the recording writes it (the editor shows both forms side by side).

fielde.g. 2 (the second value after the tag)

The field selects which value in the sentence the rule reads. Commas separate the values, and the count starts at 1 after the tag. In $IIXDR,A,-20,D,00, field 1 is A and field 2 is -20. You do not have to count the commas. The editor shows the latest recorded sentence with each value as a numbered chip. Click the value that you recognize, and the editor fills in this part.

label · unite.g. Rudder angle · °

The label is the name of the value in the drawer, in the floating dialog, and in the alarm lane of the timeline. Use the name that your configuration sheet gives to the signal. The screen and the case documents then use the same words. Stingray prints the unit after the number and does nothing more with it. The unit converts nothing.

scale · offsete.g. 0.4163 · 0.3413

The scale and the offset turn the raw transmitted number into the real reading: shown = raw × scale + offset. Leave both parts blank to show the number exactly as transmitted. You do not have to calculate these two values yourself. The analog coefficients on your configuration sheet give them directly (see the formula below).

whenField · whenEqualse.g. 4 · 00

This condition makes the rule apply only if another field of the same sentence holds an exact value. Some instruments send two variants of the same sentence one after the other, and only an id field separates them. Without this condition, a rudder rule sometimes reads the other variant, and the value flickers. Fill in both parts, or leave both parts empty. Be careful with the padding: the sheet writes 0, but the recording usually writes 00. Enter the value as the recording writes it (the field chips in the editor show the real form).

valueMape.g. 30=Full Ahead; 20=Half Ahead; 0=Stop

A value map is a translation table for fields that carry codes, not measurements. Write the transmitted code on the left and its meaning on the right, and separate the entries with ;. A telegraph position or a pump state reads through a value map, and a rudder angle reads through the scale and the offset. Stingray reads the table first, and compares the code exactly as transmitted. If no entry matches, Stingray then tries to read the field as a number.

alarmValuese.g. A (or vendor codes such as H;L)

This part makes the rule an alarm and lists the transmitted values that mean the alarm is active. For example, use A if the field reads A for active and V for normal. While the field holds one of these values, the timeline shows a named span for the alarm (Section 6). List only the values that your documents confirm, or that the recording itself shows. A guessed alarm meaning is worse than no alarm rule.

alarmWhenPresente.g. true

Some alarms have no usable on/off field, because the field is broken or always the same. For these alarms, set this part to true. The sentence itself then counts as the alarm, and Stingray reads no value. If several alarms share one stream, add a when condition to select the one alarm that you mean.

The IEC analog formula on your configuration sheet gives the scale and the offset directly:

IEC analog conversion → scale / offset

Real = A₁·10^A₂ · x + B₁·10^B₂

scale = A₁·10^A₂, offset = B₁·10^B₂

For example, a real rudder sheet: A₁ = 4163, A₂ = −4, B₁ = 3413, B₂ = −4 → scale 0.4163, offset 0.3413.

2. A worked example

This rudder-angle rule comes from a real configuration sheet. The analog table gives the coefficients (scale 0.4163, offset 0.3413). The channel map says that the sentence arrives on wire channel 000a. The XDR sends two variants in each cycle, and only the id in field 4 separates them. The rule therefore carries a when condition:

● Rudder angleXDRch 000afield 2 · when #4 = 00

$IIXDR,A,-20,D,00*4F
└ field 2 × 0.4163 + 0.3413 = −7.98° → shown as “Rudder angle −8.0°”

XDR · ch 000a (= 10) · decode table

The table below shows the same rule as a CSV row. The twelve columns are rows here, so they stay legible. The rudder rule is beside an alarm rule: an ALA sentence whose condition field reads A while the alarm is active.

column	Rudder rule	Alarm rule
formatter	XDR	ALA
channel	000a	—
field	2	6
label	Rudder angle	Steering gear alarm
unit	°	—
scale	0.4163	—
offset	0.3413	—
whenField	4	—
whenEquals	00	—
valueMap	—	A=Active; V=Normal
alarmValues	—	A
alarmWhenPresent	—	—

A dash is a blank column. The alarm rule gives a readable state in the drawer. It also gives named spans on the timeline while the alarm is active (Section 6).

3. Sources of meaning

Only two sources of meaning are legitimate:

The documents of the installation. These give the channel assignments, the analog coefficients, the alarm contact names, and the telegraph tables. Only the document can give facts that are specific to the installation.
The published IEC 61162 layout of a standard sentence. The layout makes some fields clear, for example an ALA condition field or a telegraph position. You can use these fields also if the document does not restate them.

Never invent

Never invent a meaning. A wrong scale or a guessed alarm meaning makes an evidence artifact that is wrong, and nothing on the screen shows the error. Fewer correct rules are better than rules that you guess. If neither the document nor the published layout states a meaning, leave the value coded.

4. Write rules in the editor

The Decode Tables editor opens from the “Needs code tables” section of the own-ship drawer. It starts with the traffic that Stingray observed in the recording but did not interpret. The editor groups this traffic by formatter and channel, and shows the latest sample as numbered field chips. Click the field that you recognize, and the editor fills in the rule form. Before you save a rule, the editor previews it against the latest sentence that matches.

This traffic includes the proprietary $P… sentences of the recording, with a proprietary badge. They work in the same way, with one difference. The field chips of a standard sentence show the published meaning of each position as a hint. The chips of a proprietary sentence cannot show a hint, because no published layout exists. For a proprietary sentence, the field numbers must come from the Record of Configuration of your installation.

Stingray keeps the rules with the project, and the rules round-trip as a CSV file with the same twelve columns as the table above. Download the current rules, or download a template that Stingray builds from the observed sentences. Fill it in a spreadsheet, and import it again. An import replaces all rules, and Stingray asks you to confirm this first. The confirmation also reports how many of the incoming rules resolve against this recording. A rule that uses the numbering of a sheet can be valid CSV and still match no sentence in the recording.

5. Draft rules with Claude

You do not have to copy the Record of Configuration by hand. Claude can draft the CSV from it. The flow is narrow by design:

You upload the configuration document only. You never upload the recording. Stingray asks for your consent first, because a configuration sheet names the vessel and is case material.
You can also opt in to send a few observed sensor samples. These samples are sensor sentences only, with no positions and no identities. The alarm values and the variant conditions then come back with the real codes of your installation.
The model computes no field positions for proprietary sentences. For these sentences the model returns only what the document states: the signal names in order, the variant groups, and which signals are alarms. Stingray then derives the field numbers, the channels and the variant conditions from your recording, in your browser. This derivation is deterministic: the same document and the same recording always give the same rules. If the recording cannot confirm a signal, Stingray writes an abstention instead of a rule.
The result is a normal CSV file, and the server validates it. The CSV also carries the channel-profile entries and the vessel identity that the document states. It goes through the same review-then-replace confirmation as a CSV that you write by hand. No rule applies until you adopt it.

The reviewed CSV is the artifact. A model reads the names, Stingray solves the positions from the recording, and the analyst adopts the result.

6. Alarms on the timeline

An alarm rule does more than give a name to a value. Stingray draws the active intervals of the alarm as named spans on the timeline. The own-ship drawer also groups the alarm rules into status cards. A card shows the live Active/Normal state and the rule values at the playhead. It also shows the delay between the playhead and the last sentence of the alarm stream, because a large delay is itself forensic evidence. You can hide one alarm rule from the timeline, and the rule stays in the table.

7. Value resolution

A derived value resolves in the same way as every other own-ship reading. The value at the playhead comes from the latest sentence that matches, at or before the playhead. For a rule with a condition, a sentence matches only if the condition also matches. Stingray uses the latest sentence of the correct variant, not the latest sentence of the correct type. A value map compares the raw field, without the spaces at the two ends, before any numeric conversion.

Each derived row carries a provenance line with the name of the decode table. The original coded rows stay in the list beside the derived rows. A derived value is more evidence, never a replacement.

Rules apply retroactively. Open an old project, add a rule, and Stingray reads the whole recording again through that rule. This works because Stingray fixes nothing at ingest. See the methodology for the principle that governs this, and the reference for the tier of each sentence formatter.