LineKeeper — User Manual

A few words you'll meet throughout:

• PLC — the industrial computer inside the machine's control cabinet that actually runs the machine. LineKeeper talks to it over the network.
• Tag — a single named value inside the PLC: a temperature, a motor speed, a counter, an on/off state. Machines typically have hundreds or thousands of tags.
• Writing a tag — sending a new value to the machine (like pressing a button or changing a setpoint on a normal operator panel).
• Collecting / recording — storing a tag's values over time so they can be charted and analyzed later. Nothing is recorded until you choose which tags to record.

The interface works two ways: on the device's own touchscreen, or from any browser on the same network — open http://<device-address>:5000. For longer setup sessions the browser is more comfortable; the on-device screen is small and best for day-to-day use.

1. A quick tour — where everything is

Left sidebar — the main menu:

Below the menu: a live counter of Tags and I/O modules on the connected machine, and a Collecting indicator — green when the recorder is running. The Logout button is at the very bottom.

Top bar, left to right:

• ☰ — hide/show the sidebar.
• Clock, and next to it the time of the last data update received from the machine.
• Theme toggle (light/dark).
• Status pill — the connection indicator: green with the machine's address when connected (e.g. EMULATOR:0 or 192.168.1.10:0), Reconnecting… or Offline otherwise. Click it to open System Logs. See section 18.
• When two or more machine profiles exist, a machine selector also appears here (section 11).

Signed in as Operator, the menu shows only PLC, Control Panel and Dashboards, and all setup controls are hidden — operators can watch values and use the panel, nothing else.

2. First-time setup, step by step

What you need: the device powered on, a network connection between the device and the PLC (cable to the machine's switch, or the same plant network), and the administrator password.

Step 1 — open the interface

• On the device screen: it boots straight into the interface.
• From a computer: open http://<device-address>:5000 in a browser. The device's current address is shown on its own screen under Settings → Wired network / Wi-Fi, or ask whoever manages your network (the device appears as plc-gateway in the router's client list).

Step 2 — sign in

Choose the Administrator role, enter the administrator password, press Sign in (section 3).

Step 3 — connect to the machine

On the PLC tab:

1. The machine profile is already selected (rename it later in Settings → Machines).
2. Protocol: EtherNet/IP (Allen-Bradley ControlLogix / CompactLogix).
3. Enter the controller's IP address and Slot (usually 0 — your electrician or the machine documentation will know).
4. Press Connect.

Within seconds the full tag list appears with live values — nothing is typed in manually. Tick Auto-connect so the device reconnects by itself after a restart. The last 10 connections are kept in a history list under the form.

No machine at hand? Press Emulator — the device connects to a built-in demo generator with synthetic tags so you can try every feature safely. All screenshots in this manual were taken this way.

Step 4 — choose what to record

Recording powers dashboards, the Database view and all analytics — pick the values that matter (temperatures, speeds, counters, run signals, fault codes):

1. On the PLC tab, press + Collect on each tag you care about (or tick several and press + Collect selected).
2. Go to Storage, and for each tag set the mode and write a short description ("Main pump motor current") — the AI quotes these descriptions and refuses to guess about undescribed tags. Details in section 6.
3. In Collector Status, press ▶ Start and enable auto-start so recording resumes by itself after a power cycle.

Step 5 — verify data is flowing

Open the Database tab, pick one of your tags, press Refresh — you should see fresh timestamped rows appearing. If yes, recording works.

Step 6 — build your first screens

• Assemble an operator panel: section 5.
• Build a dashboard — start from a ready-made recipe in section 8.

Setup checklist: connected (green pill in the top bar) → tags collecting (green "Collecting" in the sidebar) → rows visible in Database → auto-connect and collector auto-start enabled → passwords changed from the defaults (section 14).

3. Signing in and roles

1. Choose your role: Operator or Administrator.
2. Enter the password for that role and press Sign in.

• Operator — can view everything visible to them and use the Control Panel buttons. Stays signed in for 7 days.
• Administrator — full access: connections, recording, dashboards, settings, users. Stays signed in for 24 hours.

The Gateway online dot under the button confirms the device itself is up.

Forgot the administrator password? It can be reset from the device's service console with the included reset_password.sh utility — the new password is printed on screen. (There is no "email me a reset link": the device is fully offline by design.)

4. PLC tab — connect, watch, write

(Screenshot in section 1.)

Connection

The PLC Connection card at the top: machine profile, protocol, IP, slot, Connect / Disconnect, Emulator, Auto-connect — as in Step 3 above.

Watching live values

The tag table updates twice a second:

• Search by name or filter by data type.
• ★ Star the tags you care about; "★ Favorites only" filters the table down to them. Favorites are reused across the app (Control Panel pickers, AI, filters).
• ▼ Bits — expand an integer tag to see each of its bits individually (useful when one number packs many on/off flags). Bits can be written by clicking them.
• Structured tags (UDTs) and arrays unfold into their fields and elements.
• I/O modules — the machine's physical input/output cards with their states.

Sending values to the machine

Each row's actions (some behind the ⋮ menu):

• ⇄ Toggle — flip an on/off tag.
• ⏺ Momentary (Hold) — the tag is ON while you hold, OFF when you release.
• ✎ Write — type a new value for a number or text tag.

Every write is recorded in the audit log: who, when, which tag, what value, and whether it succeeded. What a write does is entirely up to the machine's own program — LineKeeper behaves exactly like a normal operator panel.

5. Control Panel — your operator screen

This is the screen an operator uses day to day — you assemble it yourself, no programming.

Widgets

• Button (momentary) — active only while pressed, like a jog button. Releases automatically, even if the page is closed mid-press.
• Button (maintained) — press to turn on, press again to turn off.
• Indicator — a lamp that lights when a tag is on.
• Numeric display — a live number, read-only.
• Numeric input — shows the current value plus a field to send a new one (type a number, press ▶).
• Text (string) — a live text value, read-only.
• Section — a header to group widgets visually.

Building the panel

1. Press Edit mode.
2. In the form: choose Type, write a Label ("Conveyor ON/OFF" reads better than a raw tag name), pick the Tag, press + Add. Tick ★ Favorites to shorten the tag list to your starred tags.
3. Optionally give a button a separate Indicator tag — the command goes to one tag, the button's lamp reflects another (e.g. confirmation from the machine).
4. Drag widgets to reorder, × to remove. Press View mode when done.

Create multiple panels (+ Panel / Rename / Delete panel) — for example one per line section; switch them with the dropdown next to Edit mode. Values refresh several times per second.

6. Storage — recording history

Nothing is stored until you choose tags here. Recording is what powers Dashboards, Database and all analytics.

Collector Status — the recorder itself: state, polls, writes, errors, database health. ▶ Start / ■ Stop, and in Settings below: the PLC address it records from, poll interval, and auto-start on boot (recommended: on).

Tags for collection — per tag:

• Mode — on_change: store a point only when the value changes (a deadband ignores tiny noise: with deadband 0.5, a change from 66.2 to 66.5 is not stored); on_interval: store every N seconds regardless of change.
• Description — a plain sentence about what the tag is ("Filler tank temperature, normal 66–72"). Strongly recommended: the AI quotes these descriptions and refuses to guess about undescribed tags.
• Active — pause/resume recording of that tag without deleting its settings.

The recorder runs in the background with its own connection — it keeps logging when nobody is looking at the screen, and reconnects automatically after network problems.

How long data is kept: every raw point for 30 days; hourly averages for 1 year; daily averages for 5 years. This happens automatically — dashboards pick the right tier for the period you ask for.

7. Dashboards

Create any number of named dashboards (+ New / Rename / Delete) and fill them with widgets. Ready-made examples with exact settings are in section 8.

Adding a widget

Pick a Tag, a Type (the list adapts to the tag's data type), a Period, and optionally an Aggregation; for charts and gauges you can add up to four limit lines (HH / H / L / LL), set Points (detail level, 20–200) and a color. Press + Add.

Widget types

Periods and refresh

Pick a period per widget (real time, 15 minutes … 30 days), or override all widgets at once with Period (all widgets) — including a custom date range (two date-time pickers). Set Auto refresh (30 s / 1 min / 5 min) for a wall display; otherwise refresh manually.

Every widget can explain itself

Not sure what a widget is actually showing? Press its ? button:

It explains — for that specific tag and period — how many time windows the period is split into, which aggregations run, where the data comes from and how often it refreshes. Use it to check the widget is set up the way you intended.

Full data and CSV export

Every widget has a 📋 button — the complete list of stored points behind it, with Download CSV for reports and spreadsheets:

8. Dashboard examples (recipes)

Three dashboards that cover the most common needs. Tag names are from the demo bottling line — substitute your own.

Recipe 1 — Production for the shift

Answers: how much did we make, at what rate, how many rejects, per hour?

Needs a cumulative production counter recorded (e.g. Good_Parts), ideally a reject counter and a speed value.

How to read it: the big number is production for the period (counter resets are handled automatically), with the hourly rate underneath; the bars show which hours were strong or weak — gaps and short bars point at stops.

Recipe 2 — Downtime and faults

Answers: how much did the machine actually run, when did it stop, why?

Needs an on/off "running" signal recorded (e.g. Conveyor_Run); a numeric fault-code tag and a step-number tag make it much more useful.

How to read it: the ribbon shows when the machine ran (green) and stood (gray); the stats show uptime %, number of starts and cycle times; the error-code widget names the codes that cost the most time; the sequencer shows which step of the machine cycle eats the time.

Recipe 3 — Process monitoring (temperature, pressure, speed)

Answers: is the process value where it should be, and was it ever outside limits?

(Screenshot at the top of section 7.)

Needs an analog value recorded (e.g. Tank_Temp_C), with sensible limits.

How to read it: the shaded band is min–max per window — a short spike shows as a band spike even on a 24-hour chart (in the screenshot, the temperature spike crossed the orange H line during a jam); the dashed lines are your limits. Add an Out-of-spec % widget on the same tag to get "the value was outside limits X% of the time" as a number.

9. Database — inspecting raw records

Choose a tag, how many rows (20–500), and see exactly what was stored: timestamp (to the millisecond) and value, newest first, with optional 2-second auto-refresh. Handy to verify recording is working before you rely on it — and the fastest answer to "is data flowing right now?"

10. AI Analytics

The device continuously computes statistics over recorded data and scans for problem patterns — out-of-limit values, drift toward an alarm level, abnormal on/off cycling, stalled production counters, growing error codes, stuck sensors, gaps in data, and more. Findings are plain sentences with a likely physical cause.

What you can do here:

• Daily Health Report — a scheduled once-a-day report (time configurable in Settings): overall status, issues ranked by severity with likely cause and recommended action, whether yesterday's issues are Resolved / Persist / Worsening, a monthly overview, and things to watch tomorrow. A colored strip shows the last ~30 days at a glance. Press Run now any time (takes 1–3 minutes).
• Tag Overview — a live statistics table for every recorded tag: trend arrow, min/mean/max, current value and status (normal / watch / alert).
• ⚡ Anomalies — an on-demand scan of the chosen period (1 hour to 7 days).
• ⇆ Shift Compare — compares the previous shift with the current one and says whether the equipment is trending better or worse.
• Custom Analysis — type your own question about chosen tags: "Is Motor_Speed trending down over the last 8 hours?"
• AI Context Health — shows how many of your tags have descriptions and lets you fill the gaps, plus a description of the equipment itself ("Rotary filler, 12 valves, PET bottles 0.5–1.5 L"). The more context you give, the more concrete the reports.

If risks are found by the periodic background check, a red ! badge appears on the AI Analytics tab.

Privacy note: the AI model runs on the device itself; no data is sent anywhere. If the AI component is disabled or unavailable, the same findings are still shown as a plain automated report (the screenshot above shows exactly that mode).

11. Several machines on one device

Settings → Machines. Add a profile per machine ("Filling Line 1", …). Each profile keeps its own controller address, recorded tags, favorites, panels, dashboards, history and AI reports — completely separate. Give each machine a one-line description — the AI uses it.

Switch the active machine from the dropdown in the top bar (visible once there are two or more profiles). Switching stops the recorder and disconnects from the current controller before changing over. Operators can see the active machine but not switch it.

12. Network and remote access

All under Settings:

• Wired network — the port that talks to the PLC. Shows cable state, current address and mode. Choose DHCP or Static and set the address right from the screen — e.g. if your PLC lives at 10.0.0.50, give the device 10.0.0.20 with prefix 24. Gateway and DNS are optional; leave them empty on an isolated PLC network (internet keeps flowing over Wi-Fi).
• Wi-Fi — see the current network, signal strength and address; Scan networks, tap one, enter its password, Connect.
• Remote access — built-in VPN-based access (Tailscale) lets a trusted specialist (your OEM, integrator, or your own engineer at home) open the interface securely from anywhere — no router changes. Enable, disable or re-authorize with one tap; access is per person and revocable. Off by default, and nothing else on the device needs the internet.

13. Sending data to other systems (MQTT)

Settings → MQTT Sparkplug B. If you have (or later buy) a SCADA or IIoT platform, enter its broker address and LineKeeper publishes every recorded tag to it in the industry-standard Sparkplug B format, transmitting only when values change. Off by default; one form to fill; nothing else changes on the device.

14. Users, passwords and the audit log

Settings → Users & Security.

• Change passwords per role (administrator only; confirmed with the current administrator password). Changing a password signs out all other devices using that role. Do this on day one.
• Active sessions — every signed-in device is listed; Revoke signs one out instantly.
• Audit log — every login (including failed attempts) and every value written to a machine, with role, time, tag, value and result.

Lost administrator password: ./reset_password.sh engineer on the device's service console prints a new one (see section 3).

15. Backup, export and profiles

Settings → Backup & Profiles.

• Export config — downloads the entire configuration (machines, recorded-tag lists, panels, dashboards, settings) as one file. Do it after finishing setup and keep the file somewhere safe.
• Import config… — restores from such a file (asks for confirmation before overwriting).
• Profiles — save the current configuration under a name on the device and switch between saved setups.

16. Software updates

Settings → Software Update shows the current version. When an update is available, a button also appears in the sidebar. Press Apply & Restart — the device updates and restarts itself. If a new version fails to start, the device automatically rolls back to the previous working version and reports that it did. Recorded data is not touched by updates.

17. Using the built-in screen (full-screen mode)

Out of the box the device boots straight into the interface, full screen, with no desktop and no login prompt for the screen itself.

• An on-screen keyboard pops up automatically when you tap a text field (⌨ button in the bottom-right corner opens/closes it manually).
• To leave full-screen mode for maintenance: Settings → Kiosk → Close window, or tap the bottom-left corner of the screen three times quickly and enter the PIN (default 1234).
• The built-in screen is compact — best for the Control Panel and day-to-day viewing. For building dashboards or long configuration sessions, open the same interface from a browser on your computer.

18. Reading the status indicators

Top-right corner of the interface:

Key safety fact: if the connection is lost, LineKeeper never switches anything on or off by itself. Momentary buttons release; the machine continues running its own program exactly as before.

19. Troubleshooting

Work top to bottom: power → network → connection → recording → display.

Operators: please don't change values on the PLC tab without instruction — use the Control Panel that was built for you.