Skip to content

Alarms: raise, acknowledge, shelve

An alarm is not just a bit that went true. A person has to be told, say they have seen it, silence it for a while if it is a nuisance, and later there has to be a record of all of that. In this lesson you declare one alarm for a tank and use all of those, on a screen and from the command line. About fifteen minutes. You need naut (install), and it helps to have done A screen in five minutes first. Make a project and stay in its folder:

Terminal window
naut new tankalarm --template minimal
cd tankalarm

An alarm watches a BOOL tag: true means “in alarm”. The BOOL comes from your logic, so the limit is ordinary code you can read and test. In nautilus.yaml, replace the scaffold’s tags: entries (the sample Sensor, Setpoint and Actuator) with these two. Level is a setpoint so that you can type a level in by hand, standing in for a sensor:

tags:
- { name: Level, role: setpoint, type: REAL, init: 50.0, desc: Tank level (percent) }
- { name: HighLevel, role: state, type: BOOL, init: false, desc: Level above the high limit }

Replace program.st, and delete the scaffold’s test file tankalarm_test.yaml (it tests the old program):

PROGRAM Tank
HighLevel := Level > 80.0;
END_PROGRAM

Add an alarms: section to nautilus.yaml, anywhere at the top level:

alarms:
defs:
- id: TANK_HIGH
tag: HighLevel
name: Tank high level
priority: high
on-delay: 3s

That is one definition: an id, the tag that means “in alarm”, a name an operator reads, a priority, and an on-delay: the condition must stay true for three seconds before it counts, so a spike does not raise an alarm. Check it and list what you declared:

Terminal window
naut check .
naut alarms list .
nautilus.yaml: 1 alarm definitions
naut check: 1 file(s), 0 with errors
ID PRIORITY SITE CONDITION NAME
TANK_HIGH high HighLevel Tank high level
1 definitions
high 1

(naut alarms list prints every alarm the project will have. With a few hundred alarms generated by rules, that list is how you see what you got.)

The alarm list is part of the screen naut run serves, but only once the project has a screen. Make the smallest one: save this as tank.mimic.json (the screen lesson explains the format):

{
"name": "Tank",
"canvas": {"width": 400, "height": 300},
"equipment": [
{"id": "T1", "component": "Tank", "x": 80, "y": 40, "width": 200, "label": "TK-1", "bind": {"levelPct": "Level"}}
]
}

Run naut check . again: it also checks the screen, so it takes a few seconds longer and may print warnings. A warning that the AGENTS.md guidance is older or that text on the Diagnostics page is small is about naut itself, not your project; ignore them. The line to look for is 0 with errors.

Terminal window
naut run

Open http://localhost:8080 (if that port is already in use, naut run prints the address it moved to; use that one everywhere below). You see the tank at 50 percent, and a bar at the top with alarm buttons that show nothing wrong. Push the level over the limit, the way a sensor would:

Terminal window
curl -s -X POST localhost:8080/api/tags -d '{"name":"Level","value":90}'

Nothing happens for three seconds: the bit is true, the alarm is not yet. Then the banner at the top turns red and says 1 unacked. Click it: that is the Alarms page, with one row, Tank high level, in the state Unack: it is active and nobody has acknowledged it. (Ack all in the top bar acknowledges everything at once.)

Ask the controller from the command line too. This is the same list the page shows, and what any other program would read:

Terminal window
curl -s localhost:8080/api/alarms | jq -c '.alarms[] | {id, state}'
{"id":"TANK_HIGH","state":"unack-active"}

(jq only tidies the output.)

On the Alarms page, tick the row and press Ack (1). Acknowledging says “I have seen this”; it does not fix anything, and the alarm stays on the list while the level is still high. The row now says Acked, with the time, and the banner says 0 unacked. (Without a browser, the same thing is curl -s -X POST localhost:8080/api/alarms/ack -d '{"ids":["TANK_HIGH"],"by":"operator1"}'.) The same call as before says:

{"id":"TANK_HIGH","state":"ack-active"}

Now fix the cause:

Terminal window
curl -s -X POST localhost:8080/api/tags -d '{"name":"Level","value":50}'

The alarm leaves the list. Because you had acknowledged it, there is nothing left for an operator to do. Had the level dropped before anyone acknowledged, the alarm would have stayed on the list as returned to normal, unacknowledged (unack-rtn in the API) until someone did: the alarm happened, and clearing the bit does not discharge the need to have seen it.

Push the level up again and wait the three seconds. A sensor that is flapping, or a tank being filled on purpose, would raise this over and over. Tick the row and press Shelve: a box asks for a duration (5 minutes to start) and who is doing it. Shelve it for 5 minutes. The row moves out of the active list (tick show shelved to see it) and the banner goes quiet. (Without a browser: curl -s -X POST localhost:8080/api/alarms/shelve -d '{"id":"TANK_HIGH","seconds":300,"by":"operator1"}'.) The command line says:

{"id":"TANK_HIGH","state":"shelved"}

A shelf always ends: there is no way to shelve forever, because a silenced alarm that never comes back looks exactly like a broken alarm. When the time is up the alarm returns in the state it was in. Press Unshelve now to bring it back yourself (/api/alarms/unshelve with {"id":"TANK_HIGH"}): it is unacknowledged again, because shelving is never a way of acknowledging.

Every change is written to a journal, kept in memory with no database needed:

Terminal window
curl -s localhost:8080/api/alarms/journal | jq -c '.events[] | {kind, state}'
{"kind":"unshelve","state":"unack-active"}
{"kind":"shelve","state":"shelved"}
{"kind":"active","state":"unack-active"}
{"kind":"rtn","state":"normal"}
{"kind":"ack","state":"ack-active"}
{"kind":"active","state":"unack-active"}

Newest first: raised, acknowledged, returned to normal, raised again, shelved, unshelved. Each event also has a by and a time (jq .events shows all of it). by is the name an operator typed into the Shelve box; the Ack button on the page leaves it empty. It is a name written down, not a login: the controller records what it is told, and signing operators in is a separate matter (see Who may operate it). Stop naut run with Ctrl-C.

Your logic is tested without a clock, and so are alarms. Put this in tankalarm_test.yaml:

tests:
- name: high level alarms after three seconds, acknowledges, clears
steps:
- given: { Level: 90.0 }
advance: 2s
alarms: { active: [] }
- advance: 1500ms
alarms: { active: [TANK_HIGH], unacked: 1, state: { TANK_HIGH: unack-active } }
- ack: { ids: [TANK_HIGH], by: test }
scans: 1
alarms: { unacked: 0, state: { TANK_HIGH: ack-active } }
- given: { Level: 50.0 }
scans: 1
alarms: { active: [], journal: [active, ack, rtn] }
- name: a brief spike never alarms
steps:
- given: { Level: 90.0 }
advance: 2s
- given: { Level: 50.0 }
advance: 5s
alarms: { active: [], journal: [] }
Terminal window
naut test .
tankalarm_test.yaml
ok high level alarms after three seconds, acknowledges, clears
ok a brief spike never alarms
2 tests, 2 passed, 0 failed

alarms: asserts what the alarm engine says; ack: is the operator pressing the button. The three seconds are exact, and the test takes milliseconds. It also earns its place: change on-delay: 3s to 1s and both tests fail, naming the alarm that appeared too early.

A real plant has hundreds of alarms, and you do not write them one by one. A rule makes one alarm for every tag of a type (every analog input’s high-high member, say) and a rule’s enable: can silence a whole site whose link is down instead of leaving its alarms lit on their last reading. Alarm state is kept across a restart, and the journal can go to a file or a database so it outlives the controller. The Alarms guide covers rules, priorities and classes, the journal sinks and the webhook for sending events elsewhere.

A button and a setpoint that write puts controls on the screen, so an operator can start and stop things as well as see them.

nautilus is free and open source (Apache 2.0), built by Joy Automation. For implementation or support on your site, see Joy Automation services. Privacy.