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:
naut new tankalarm --template minimalcd tankalarm1. A condition to alarm on
Section titled “1. A condition to alarm on”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 TankHighLevel := Level > 80.0;END_PROGRAM2. Declare the alarm
Section titled “2. Declare the alarm”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: 3sThat 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:
naut check .naut alarms list .nautilus.yaml: 1 alarm definitionsnaut check: 1 file(s), 0 with errorsID PRIORITY SITE CONDITION NAMETANK_HIGH high HighLevel Tank high level
1 definitionshigh 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.)
3. A screen to see it on
Section titled “3. A screen to see it on”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.
4. Raise it
Section titled “4. Raise it”naut runOpen 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:
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:
curl -s localhost:8080/api/alarms | jq -c '.alarms[] | {id, state}'{"id":"TANK_HIGH","state":"unack-active"}(jq only tidies the output.)
5. Acknowledge it
Section titled “5. Acknowledge it”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:
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.
6. Shelve a nuisance
Section titled “6. Shelve a nuisance”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.
7. Who did what, and when
Section titled “7. Who did what, and when”Every change is written to a journal, kept in memory with no database needed:
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.
8. Test the alarm in virtual time
Section titled “8. Test the alarm in virtual time”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: [] }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 failedalarms: 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.
Before a real plant
Section titled “Before a real plant”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.