The alarm catalogue

A device on the bus reports a number. The sentence a crew member reads on the alarm page — "Low oil pressure", "Pression d'huile basse" — and the severity attached to it come from a catalogue that ships as its own Debian package, muxen-alarms-database.

This chapter is what that catalogue contains, and what it means when a code is not in it.

What the crew sees, and where it comes from

Each alarm on the page carries three things from the catalogue: an English description, a French one, and a severity — either warning or error. Nothing about the boat changes between the two; the distinction is editorial, and it is what a screen uses to decide colour, placement and whether to make a noise.

The catalogue is a fixed table shipped with the software. It is not learned, not configurable per boat, and not editable from the HMI. A description that is wrong for a given piece of equipment is a change to the software, not a setting.

Before 10.0.0 the top level was spelled alarm. The daemon and the catalogue ship as one version — muxen-alarms depends on muxen-alarms-database (= ${source:Version}) — so the two can never disagree on a boat, but a client can meet either spelling depending on what the boat is running. Clients should therefore read the field through normalizeSeverity() from @muxen/alarms, which maps alarm and error onto one level and ranks it on the ladder error > warning > notice. Nothing in the catalogue carries notice today; it is where an unrecognised or absent severity lands.

Coverage

265 entries across eleven equipment families, plus a small generic set.

Family	Function code	Entries	Codes	File
Bloc 8 power outputs	1	26	1 – 2051	data/bloc8.json
Generator set	4	46	0 – 45	data/genset.json
Battery	5	21	0 – 20	data/battery.json
Power converter	6	8	0 – 7	data/power-converter.json
Motor	7	45	1 – 133	data/motor.json
Solar / MPPT	10	19	2 – 119	data/mppt.json
Watermaker	20	18	1 – 25	data/watermaker.json
Air conditioning	21	28	0 – 27	data/hvac.json
Alternator	27	12	0 – 11	data/alternator.json
Thermal engine	28	31	0 – 30	data/thermal-engine.json
Bow thruster	32	5	0 – 4	data/bow-thruster.json
Generic	(none)	6	65000 – 65040	data/muxen-generic.json

Overall: 185 entries at severity error, 80 at warning.

Any MUXEN function not in that table has no catalogue coverage at all, and every alarm from it is published as unknown. That is not a fault — it means no codes have been written down for that equipment yet.

The generic codes

Six entries carry no functionCode. An entry without one is a wildcard: it matches the code from any device, whatever it is.

Code	Text	Severity
65000	Device not detected on CAN-Bus	warning
65001	Alarm data source lost	error
65010	High temperature	warning
65020	Low temperature	warning
65030	High temperature	error
65040	Low temperature	error

65000 and 65001 are raised by the daemon itself — Devices that go quiet, and the daemon's own health. The four temperature codes are for devices that report a temperature condition without a family-specific code of their own; they are wildcards, so the same code from a battery and from an alternator reads the same way.

The generic block starts at 65000 and the highest device-specific code in the catalogue is 2051, so a generic entry can never shadow a family-specific one today.

Lookup, exactly

For each alarm the daemon looks for the first catalogue entry that:

1. has an alarmCode equal to the alarm's code, and
2. either has no functionCode, or has one equal to the device's.

A missing functionCode is treated as "matches anything", which is what makes the generic block work. Because the first match wins, a family-specific entry and a generic entry sharing a code would resolve to whichever the merged file lists first.

The found entry is copied wholesale into the published alarm, so any field it carries appears there. Bloc 8 entries carry an extra channel field naming the output the code refers to; 24 of the 26 do.

When an alarm says unknown

{
  "alarmCode": 92,
  "alarmDescription": "unknown",
  "severity": "unknown",
  "deviceId": 448,
  "functionCode": 7,
  "functionName": "Motor",
  ...
}

The alarm is real. A device reported code 92 and the daemon is showing it. What is missing is the catalogue entry, and there are three ways to get here:

Cause	How to tell
The equipment family has no catalogue file	the function code is absent from the coverage table above
The family is covered but this code is not	the code is outside the family's listed range, or a gap inside it
The catalogue did not load	every alarm reads unknown, not just this one

The third is the one to rule out first, and it is easy: if a single alarm is unknown the catalogue is fine, and if all of them are it is not. See Troubleshooting.

An unknown alarm is still counted in active and can still be muted like any other. Nothing about it is second-class except the words.

The French text

Each entry carries alarmDescription.FR alongside the English. Two of the 265 do not, both in the motor family (codes 44 and 48), and their English text is truncated — a client asking for French on those two gets nothing back and has to fall back to English.

A client should treat alarmDescription.FR as optional and always fall back to alarmDescription, which is present on every entry.

Where the file lives

The daemon reads one merged catalogue, /usr/share/muxen-alarms/dtc.json, once at startup, and next to it the equipment names in other languages, /usr/share/muxen-alarms/functions.json (below). The twelve data/*.json files are its sources; they are concatenated into a single JSON array at build time and shipped in muxen-alarms-database.

Two things follow.

Changing the catalogue needs a restart. The file is read once, at startup. Installing a new muxen-alarms-database triggers a restart of muxen.target, so an upgrade takes effect by itself; editing the file by hand does not, and needs systemctl restart muxen-alarms.

A different catalogue can be pointed at for testing, with muxen-alarmsd -d /path/to/dtc.json. If the path is unreadable the daemon prints config: dtc file … not readable !, prints its usage block and exits — see Reference.

The equipment names in other languages

functionName — "Power source battery", "Water maker" — is the English name of the reporting device's function, and comes from the shared MUXEN function table, not from this catalogue. Since 10.3.0 the other languages come from a second file in the same package, /usr/share/muxen-alarms/functions.json, built from data/functions.json: one entry per function code, one functionName.<LANG> key per language.

{
  "functionCode": 5,
  "functionName.FR": "Batterie",
  "functionName.DE": "Batterie",
  "functionName.ES": "Batería",
  "functionName.GR": "Μπαταρία",
  "functionName.IT": "Batteria",
  "functionName.PT": "Bateria",
  "functionName.TR": "Akü"
}

<LANG> is the last two letters of the interface's locale, the same suffix as alarmDescription.FR: fr-FR reads functionName.FR, gr-GR reads functionName.GR. English has no key; functionName is the English.

The daemon copies every functionName.* string of the matching entry into the alarm, whichever languages the file carries, so adding a language is a change to data/functions.json alone. The file covers 30 of the 34 function codes that have a name, thermal engine (28) included. The four private keel devices — keel command panel (13), keel management (14), keel charger (15) and keel hydraulic motor (29) — are deliberately left untranslated and have no entry. A code with no entry gets no translated key, and the client falls back to functionName.

The build refuses a data/functions.json that is not a non-empty array of objects, each with a unique functionCode from 0 to 63 and non-empty functionName.<XX> strings, all entries carrying the same languages.

Unlike the catalogue, the file is optional to the daemon: missing, unreadable, not JSON or not an array, it logs one warning and publishes the alarms without translations — see Reference. It is read once at startup, like dtc.json.

The version of muxen-alarms-database is pinned to the version of muxen-alarms, so the pair is never mismatched by an ordinary apt upgrade.