Docs

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.

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. Removing a rule removes its interpretation, not the retained sentence. Rules can come from your review of the installation documents or from a supported recorder profile. Built-in published layouts also name selected fields. Check the source and limits of each interpretation.

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.

Catalog versions
The built-in catalog comes with the current app and is not pinned to a saved project. Reopening in another app version can change the available interpretation. Keep the audit and source evidence when documenting a conclusion; a saved project alone does not pin the complete analysis runtime.

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. Enter 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).
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 = A1·10A2 · x + B1·10B2
scale = A1·10A2, offset = B1·10B2
For example, a real rudder sheet: A1 = 4163, A2 = −4, B1 = 3413, B2 = −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 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.

columnRudder ruleAlarm rule
formatterXDRALA
channel000a—
field26
labelRudder angleSteering gear alarm
unit°—
scale0.4163—
offset0.3413—
whenField4—
whenEquals00—
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 present a suggested meaning as an established fact. The editor labels assumptions, but it cannot establish physical meaning from a plausible name or a frequent value. Check the installation documents and applicable published layout. If neither supports the meaning, keep the value coded and describe the uncertainty.

4. Write rules in the editor

Open Decode tables from the Systems tab of the own ship, or from the ingest report. The editor replaces the map. Use “Back to map” or press Escape to go back.

The left column lists the systems of the ship, for example the diesel generators or the steering gear. A system has a list of points, and each point is one signal. When a system has identical units, for example five generators or two pods, each unit is a column. A chip shows the status of each system. Ready means that the editor has no remaining checks for that system. It can still contain assumed answers; it does not establish a correct physical interpretation. Check gives the number of points that need review. “Standard” marks the fields of a published layout, and “Recorder” the rules of a recorder profile.

Editor summaries describe the whole imported recording, not just the playhead. This can be a selected window from a larger archive. An on/off point shows its transitions under the selected interpretation. A number shows its range and a small graph. Click a point to open its form on the right. The form shows each value's share of the readings. Frequency alone does not identify which value physically means “on”.

The editor can suggest an Assumed on value when the source does not state one. Its evidence can include a nearby alarm text, a recorder profile convention, value frequency or your earlier answers. These are interpretation aids, not proof of wiring or polarity. Always 0 describes an unchanged observed value; it does not prove that an alarm was inactive. Check the source text and evidence before saving or confirming an answer. Confirm for all adopts the suggested answers into your analyst rules. Inspect each affected point before a bulk confirmation; an unflagged point can still carry an assumption.

Points without a side or unit of their own get one value column. The editor uses the name, recorded values and rule to suggest a point's kind. Without that evidence, the point stays as text. Source text shows the original name and where it came from: the configuration file, alarm text, published layout or your entry. Use Sentence and field to inspect what the point reads. Its menu offers Show in raw sentences and, for an analyst point, Edit as a rule….

The recorder's own sentences, such as the system information of a SAM VDR, are in “Recorder housekeeping” at the bottom of the list. They are decoded, but they are not counted as points to check or as sentence types to make readable.

“Not readable yet” lists the sentence types that no rule reads. “Make readable” on a row, or the + next to “Systems”, opens a page for a new system. Choose the sentence that it reads. Then say for each field what it is: skip it, or read it as on/off, codes, a number or text. Give each point a name. If one field selects the kind of record, the editor suggests that you split the sentence by it. Choose one point for each alarm text if the sentence carries one. “Raw sentences” lists all sentence types with their fields as numbered chips. Click a field to write a rule with all options. A rule can have a condition on another field, a range of bits, the parts of a field, or calibration points. A proprietary $P… sentence has no published layout, so its chips show no hint. Its field numbers must come from the Record of Configuration of your installation.

If the recording has no configuration file, the editor reads what it can from the sentences. It suggests names from alarm text and channel traffic. A suggested instrument name is an inference about that channel, not an independent installation record. Review each suggestion before applying it.

Stingray keeps analyst and recorder rules with the project. Open the More menu for Export rules as CSV or Import rules from CSV…. The export includes template rows for observed sentences. Preserve its current columns, source text and checks when editing it. An import replaces your analyst rules, and Stingray asks you to confirm this first. The export includes recorder-origin rows for inspection. Import skips these rows: they come from the recorder configuration, which this CSV does not replace. Stingray derives built-in standard fields; rule CSV does not author them. The confirmation reports how many incoming rules resolve against this recording. A rule can be valid CSV and still match no sentence.

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.