Maintenance logbook

Who it’s for

Anyone who arrives at a machine and needs to know what the last person did to it. A technician who found the filter already replaced and wants to know when, a shift lead handing over at the end of a run, a manager asking why a pump was touched three times last month. The telemetry says what the machine did; nobody has been able to write down what was done to it without leaving the dashboard for a ticketing system nobody on the floor opens.

What it does

A technician finishes at a compressor, types “Replaced the inlet filter. Differential pressure back to 0.4 bar.” into the box and presses the arrow. The line is stored as telemetry on that compressor, with their name and the time, and everyone looking at the dashboard sees it in the thread a moment later.

• Keeps the history where the readings are. The note lives on the device itself, so it travels with the device and can be read by anything that reads telemetry.
• Says who wrote each line and when, as a conversation rather than a table. An entry from today reads 35 min ago; one from last month reads 8 Oct 17:40.
• Carries a whole line on one card. Point it at several devices and a tab appears for each, with its own thread behind it.
• Shows entries written by a rule chain in the same thread, so an automatic line such as a firmware update sits in order beside what people wrote.
• Respects who may write. The entry is saved through the platform, so a user without write access to the device is refused by the server, not by the card.
• Is a logbook, not a work order system. There are no fields, no statuses and no assignees: it stores what somebody typed, and nothing it cannot store honestly.

How to set up

Data keys

Add one telemetry key on the entity the log belongs to, and give the widget a time window long enough to be worth reading — a month is the default. The key is where the entries are written and read, so the same key name must be used on every entity the widget covers.

The window must have no aggregation. Entries are text, and an averaged window has nothing to average: the platform answers with an empty series and the card reports an empty period while the telemetry is plainly there. The widget ships with its own window — the last 30 days, aggregation None — rather than the dashboard’s, for that reason. If you switch it to the dashboard window, set that window’s aggregation to None as well; the card says so when it finds one.

The key does not have to exist yet, and usually will not. The data tab offers the keys a device has already reported, so a device nobody has written a note about lists nothing to pick. Type the name you want instead — logbook reads well — and the widget creates it with the first entry; from then on it is an ordinary telemetry key that the picker offers and the platform’s own telemetry page shows.

• One telemetry key — Timeseries. Each entry is one point: the timestamp is when it was written, and the value is the text with the author beside it. A key with no points yet simply shows an empty thread.
• Several entities — add a datasource per device, or an alias that resolves to many. A tab appears for each, and entries are written to the device whose tab is open.
• No key at all — the card says Add the key the entries are stored in, since without one it has nowhere to write.

Entries

• Allow new entries — on by default. Off turns the card into a read-only history, which is what a dashboard shared with a customer usually wants.
• Character limit — 500 by default. Telemetry is not built for essays, and the remaining count appears once 50 characters are left.

How to customize

• To change the prompt in the empty box — edit Message box text, What was done to this device? by default.
• To read the latest entry without scrolling — set Newest entry to At the top, from At the bottom. At the bottom reads like a chat and follows new entries as they arrive.
• To count the entries in the period — turn on Show entry count, off by default. It prints a line above the thread.
• To drop the circles with the initials — turn off Show initials, on by default.
• To match the card to your dashboard — set Your entries color, teal by default, which tints your own entries and colors the send arrow, and Other entries color for everyone else’s.
• To make the entries larger — set Entry font, 14px Roboto by default.

Tips

• Name the key the same on every device — logbook works — and one widget can then cover a whole line through a single alias.
• Ctrl+Enter sends, so a technician on a laptop never has to reach for the arrow.
• A rule chain can write to the same key to record what nobody was there to see: a firmware update, a reset, an automatic calibration. Write a plain string and it appears with no author; write {"text": "...", "user": "..."} and it appears with one.
• Give the card a month-long window rather than an hour. A logbook that forgets last week is not a logbook.
• Entries cannot be edited or deleted from the card by design. If a line has to go, it is telemetry, and the platform’s own telemetry page removes it.