Decode rules · Last updated 2026-11-10
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.
Recorder rules and published layouts
In Decode tables, open Installation details… from the More menu. This dialog holds the recorder rules, published layouts, vessel identity and channel profile. A supported recorder profile can generate rules from its configuration. From the recorder shows these read-only rules, their source references and profile version. Turn off recorder decoding removes them together; your own rules stay. Re-import the folder to restore them. Older rules that lack required checks can be withheld with re-import guidance. See the recorder guide.
From the published layoutsnames selected standard fields using a cited built-in catalog. Its current source describes the inputs of one recorder, the Furuno VR-7000. It is not the IEC standard itself. It does not prove that another installation follows that layout. Source groups keep the sentence, channel, exact talker and any alarm or shaft identity separate. Records must match the documented shape. Codes and text generally stay as recorded; ALR condition and acknowledgement have the catalog's stated meanings.
Invalid or unsupported readings can remain raw or Unknown. Stingray offers a numeric graph only where the group meets the catalog's numeric and qualifier checks. A recorder rule takes precedence for its sentence and channel. An analyst rule that reads a built-in field takes that field over for its whole source group. The section explains these decisions. Its Download audit (JSON) records the catalog, source citations and interpretation scope.
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.
$ 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.defaultto read only the sentences that the recorder stored without a channel tag. Use it when the same sentence type also arrives on a tagged channel, for example the recorder's own alarms beside a watch alarm on channel 0C. 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).$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.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).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).;. 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.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.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:
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:
└ 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 basic CSV fields used by these examples. They are rows here, so they stay legible. The current download also carries fields for bit selection, calibration, structural checks, grouping and origin. 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.
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 and the variant groups. A value meaning, a unit, a scale or the value that means an alarm is active comes back only when the document writes it out. A signal named FLOODING is not an alarm on its name alone, because a contact can be wired either way round. Without a stated meaning the signal shows its raw value, and you add the meaning once you have confirmed it. 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. This includes a sentence that carries more fields than the document describes, when nothing shows where the extra field sits. Stingray also checks every name against the text of your document, and makes no rule for a name it cannot find there. If the document describes a field only by its values on one line (for example “A= activation - V= deactivation”), that line becomes the name. If the document repeats a list of signals once per unit and the draft gives one copy for the whole sentence, Stingray makes no rules for it and says why.
- For a standard sentence, the published layout wins. Stingray checks the drafted rows against your recording. If the recorder does not follow the published layout for a sentence on a channel, Stingray drops those rows and says why. If the document gives a value a meaning that contradicts the published layout, Stingray uses the published meaning and shows a note.
- If the import found the configuration file of the recorder, the dialog attaches that file for you. Stingray reads it again from the recording folder, and uses it only if it is the same file that the import read. After a reload, the browser can ask you to allow the folder again.
- Stingray knows the configuration file of a SAM/Wärtsilä VDR4370 (
R<IMO>.xml) and of a JRC JCY-1900 (vdrinfo.dat). For these files, Stingray makes a short version in your browser and sends only that version. The short version holds the vessel identity, the input channels and the sentences. The rest of the file does not leave your browser, and this includes the system files of the recorder. Stingray also leaves out the signals that it already decodes from that file. - One draft can read 512 KB. If your documents are larger, Stingray cuts each large document into its sections (XML elements, JSON members, INI sections or the tables of a sheet). It sends the sections that name a sentence that is not readable yet, or an instrument of your recording. It also sends the lists of sensors and alarms. The dialog shows which sections go, and you can change them. Claude is told that the document is an excerpt. Stingray sends any other file as it is.
- The dialog tells you when the server would refuse a document, before you send it. The server refuses a file that is not text, and a recording. It also refuses a selection that is too small to look like a configuration document.
- 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.