with n tag(s) bound* confirms it.

The generator binds, for a motor: Mode to the MODE tag (read and write), Running to RUN_FB, Failed to Start to FTS, Fault to FLT and Speed Setpoint to SP (read and write). For a valve: Mode to MODE (read and write), Open Limit to OPEN_FB, Closed Limit to CLOSE_FB, Failed to Open to FTO and Failed to Close to FTC. Pins holding a number rather than a tag are skipped. Clicking the button again adds a second faceplate; it never replaces the first.

9.4.2 Placing faceplates from the HMI palette

Both faceplates are also ordinary HMI elements in the Devices category of the HMI Designer palette — Motor Faceplate (190 × 150) and Valve Faceplate (190 × 120). Place one and bind it in the Properties panel like any widget when you want a faceplate for a device that is not a MOTOR or VALVE block, or a second layout of your own. The valve bindings are Mode (MODE), Open Limit (OPEN_FB), Closed Limit (CLOSE_FB), Failed to Open (FTO) and Failed to Close (FTC).

9.4.3 What the operator sees

• Motor: the device name; a RUNNING / STOPPED lamp; CALL, RUN, FTS and FAULT annunciators; a SPEED entry box when a speed setpoint is bound; and AUTO / HAND / OFF mode buttons that write 2, 1 or 0 to the MODE tag.
• Valve: the device name; a position lamp (green open, red closed, amber in between or with no limit switches); FTO and FTC annunciators; and OPEN / CLOSE / AUTO / OFF buttons that write 1, 2, 3 or 0 to MODE.

Properties on both: Device Name, Show Meters and Body Color. The mode values are the same numbers the ladder blocks use, so a faceplate and a selector switch bound to the same MODE tag always agree.

9.5 Python as a callable block

Ladder can call a function written in the project’s app.py through the PYFB block: each rising edge of the network sends the block’s arguments to Python and, when the function returns, the result lands on the block’s OUT pin with DONE set. The Python side is one decorated function:

from whisker import pyfb

@pyfb("calc_dose")
def calc_dose(ctx, flow_gpm, target_ppm):
    return flow_gpm * target_ppm * 0.012

PYFB is the right tool for a curve fit, a lookup table or a calculation that is ten lines of Python and forty networks of ladder. It is not for per-scan math — a round trip is about 20 ms — and the function must return quickly. The block’s pins are in Ladder Instruction Reference; the Python side, including how app.py is deployed, is in Python on the Controller.

10 HMI Designer

The HMI Designer is where you build operator screens: the touch screens shown on the display of a Nexus.io Automation Controller, and the windows of a WhiskerHMI PC application. The same designer, elements and properties serve both; the differences are the screen size and where the screens run. This chapter is the reference for the designer. For running screens on a PC see The WhiskerHMI PC Application; for trend data see Historian and Trends; for alarms see Alerts Editor.

10.1 Concepts

A screen is one page of HMI content. A project usually has several (Overview, Setpoints, Alarms). On the controller’s display one screen is visible at a time and Nav Buttons move between them; on a WhiskerHMI PC each screen can be its own window.

An element is one visual component on a screen: a gauge, a push button, a tank, a label. You add elements from the ELEMENTS palette on the left of the designer and edit them in the Properties panel on the right.

A tag binding ties an element to a tag. Display elements read the tag; controls write it. The binding rows in the Properties panel are typed, so a State (bool) binding only accepts a BOOL tag and a Value (real) binding accepts a numeric one.

10.2 Screens

In the Project Tree, HMI Screens lists the project’s screens. Click Add Screen under it; the Add HMI Screen dialog asks for a Screen Name (the suggestion is Screen1) and opens the new screen in the designer. The screen is created at the target’s native size: 1280 × 800 for the Nexus.io controller’s 10-inch display, 1920 × 1080 for a WhiskerHMI project.

Right-click a screen for Copy or Delete; right-click another project’s HMI Screens folder for Paste. Pasting into a WhiskerHMI project that imported the source project’s tags remaps every binding to the imported names (including any prefix) and reports how many were remapped; if the tags are not there yet the paste is refused with a list of what to import first. Screen names cannot be renamed after creation, so choose them carefully.

Click an empty part of the canvas to select the screen itself. Its Properties panel shows:

There is no theme system. The look of a screen is its background plus the colour properties of each element.

10.3 The ELEMENTS palette

The palette is grouped into five collapsible sections. Elements marked writes send operator input to their bound tag.

Notes on the less obvious ones:

• Motor Faceplate and Valve Faceplate are the operator face of the MOTOR and VALVE ladder blocks: mode selection plus running, failed-to-start and fault feedback for a motor; open and closed limits plus failed-to-open and failed-to-close for a valve. Bind each row to the matching block pin tag. See Function Blocks, Faceplates and Tasks.
• Trend Chart plots historian data for the tags you list; see Historian and Trends.
• Alert Table shows the controller’s alert history with ACK, CLR and RESET buttons; it needs no bindings. See Alerts Editor.
• Lock Button ends the operator’s login session when tapped. The runtime status bar offers the same lock action, so placing one is optional.
• Nav Button switches to another screen; Page Selector shows the screen list.
• Status Text shows a word per integer value (default {"0":"OFF","1":"RUN","2":"FAULT"}).

10.4 Placing and arranging elements

Click an element in the palette. It appears near the top left of the canvas at the next free spot and is selected; drag it where you want it. Dragging and resizing snap to the grid when Snap to Grid is on. Four corner handles resize a selected element; Polyline and Pipe Route show a handle per vertex instead. Draw Polyline and Draw Pipe Route put the canvas in drawing mode: click to add points, double-click or press Enter to finish, Esc to cancel.

Selection: click selects; Shift+click adds to the selection; drag on empty canvas draws a selection rectangle; Ctrl+click picks one element out of a group. Ctrl + mouse wheel zooms (25 % to 400 %); the current zoom is shown on the toolbar.

Designer toolbar, left to right: Toggle Grid, Snap to Grid, Undo, Redo, Copy, Paste, Duplicate, Draw Polyline, Draw Pipe Route, Delete Selected, Rotate 90°, Lock/Unlock, Alignment Tools (with two or more selected: Align Left / Center H / Right, Align Top / Center V / Bottom, and with three or more Distribute Horizontal / Vertical), Group, Ungroup, Bring to Front, Send to Back.

10.5 Element properties

Select an element and the Properties panel shows, in order: Position & Size (X, Y, Width, Height, Rotation (degrees)), Appearance (the element’s own properties), Tag Bindings, and for gated controls a Security section (see Operator login below).

Each binding row is labelled with its purpose and type, for example Level (real) or Output (bool); type a tag name or pick one from the list. For a numeric binding the panel adds Raw Range, Scaled Range and Units so a 0–10000 register can display as 0–100 %.

Appearance properties of the most used elements:

A push button in momentary mode writes TRUE while pressed and FALSE on release; toggle flips the tag on each tap. Confirm asks the operator to confirm before writing. Changing an element’s Orientation between horizontal and vertical swaps its width and height.

10.6 Navigation between screens

Place a Nav Button and set Target Screen. The dropdown lists the other screens and offers + New Screen..., which creates a screen without leaving the designer. A Page Selector gives the operator a list of every screen. On a WhiskerHMI PC, screens assigned a window role open as windows instead; see The WhiskerHMI PC Application.

10.7 Previewing screens

The HMI Preview tab in the bottom panel group shows any screen of the project at a chosen zoom. Until monitoring is on it draws design-time defaults and ignores presses (the chip reads not live). Connect to the controller or run Build & Emulate, turn on monitoring, and the chip changes to LIVE — touch enabled: the preview shows live tag values and presses write to the tags, so you can exercise a screen from the IDE before an operator ever sees it. See Monitoring and Debugging for the monitoring gate.

On the controller, screens run after a deploy: connect and press Build (F5); the IDE compiles and downloads the program, screens included, to the connected controller.

10.8 Operator login at the panel

The Nexus.io controller can require operators to log in before they touch a screen. Operators are the users of your Whisker.io account, each with a personal PIN, so this needs the Cloud edition and an account whose administrator has enabled PIN codes for HMI access.

Open Project Properties and find the HMI Settings group:

• PIN — the project’s 4–6 digit PIN that opens the controller’s settings screen (network settings and the like). This is a device PIN, not a user login.
• Cloud PIN Login — turn on to require a user login at the panel. The row explains what is missing if it cannot be enabled (not logged in to Whisker.io, or PIN codes not enabled for the organization).
• Session Timeout (s) — idle time after which the panel re-locks (300 by default); screen-off always re-locks.
• Offline Fallback — when on, the project PIN above opens a Local maintenance session if Whisker.io cannot be reached. Off is the secure default.

With Cloud PIN Login on, a Roles at the panel table appears with one row per action — View screens, Buttons and switches, Setpoints and sliders, Acknowledge alarms, Clear alarms, Save trend presets, Export history, Open windows, Audit log and settings — and a Required role for each: No login needed (viewing and acknowledging only), Any logged-in user, or one of the account’s roles. Roles load from Whisker.io; use the refresh button after the account administrator changes them. To make one element stricter than its action, select it and set Required role in its Security section (push buttons, selector switches, numeric inputs, sliders, faceplates and the Alert Table).

At the panel the operator taps their name in the user picker, then enters their PIN. A wrong PIN is answered with Not recognised; after repeated failures that user is locked for a few minutes while other users can still log in. A tap on a control the operator’s role does not allow shows a brief Requires message. The session ends after the timeout, when the screen turns off, or when the operator taps a Lock Button or the lock icon in the status bar. Every login attempt and every gated action is recorded in the audit trail; see Security, Provisioning and Enrolment.

11 Alerts Editor

Alerts are alarm rules evaluated on the controller: each one watches tags, drives an output tag while its rule is true, and writes FIRED and CLEARED events to the alert history that the Alert Table widget shows on the panel and in a WhiskerHMI PC application. This chapter is the reference for defining them. Placing the Alert Table is covered in HMI Designer.

11.1 What an alert is

An alert has:

• a name — what operators see in the Alert Table (High Pressure, Pump 2 Overload);
• a rule — one condition, or a group of conditions joined by AND or OR. A condition compares a tag with a constant or with another tag;
• an output tag — a BOOL tag, or one bit of an INT tag, that is TRUE while the alert is active. Ladder logic and HMI elements can use it like any other tag;
• a latch flag — off: the output follows the rule and the alert clears itself; on: the alert stays active after the rule goes false until a Clear tag goes true.

There is no severity, no message text and no free-text expression language. Alerts exist in Nexus.io Automation Controller projects and in WhiskerHMI projects; a WhiskerHMI project’s alerts are evaluated on the PC from the tags it reads.

11.2 Opening the editor

In the Project Tree, click Alerts under the project. The editor is a table with one row per alert:

The last column holds a Delete Alert button, which asks for confirmation. Everything else is edited in the Properties panel: click a row to select the alert.

11.3 Creating an alert

1. Click Add Alert above the table. The Add Alert dialog asks for an Alert Name; the name must be unique in the project. Click Add.
2. The new alert is selected. In the Properties panel, fill in the sections below.

11.4 Alert properties

11.4.1 Alert

Name — edit and press Enter to rename. A duplicate name is not accepted.

11.4.2 Output

Tag — the tag the alert drives. Pick a BOOL tag, or pick an INT tag and enter a Bit Index (0–15, empty for direct BOOL) to pack several alerts into one word (the Alert Table and any WhiskerHMI panel read the same bit). Leave the tag at - if nothing needs to react to the alert: the compiler then gives it a private bit in an internal alerts word so it still reaches the alert history. Up to 32 alerts can share that internal word; give the rest an output tag of their own.

11.4.3 Behavior

Latch — a switch. Off: Clears when condition clears. On: Stays active until alarm reset, and a Clear tag dropdown appears: the alert clears when that tag goes true. If you leave Clear tag empty, the alert clears when a tag named alarm_reset_request goes true — the shared reset convention that the Alert Table’s RESET button uses (see Alert history at runtime). A ladder network can drive the same tag with a Reset coil from a push button.

Tip. When the condition tag is itself a latched ladder bit (a coil set with a Set coil and cleared by a reset network), make the alert latched too and give it the same clear tag. The alert and the ladder then agree about when the fault is over. {.tip}

11.4.4 Rule

The rule starts as a single condition card:

1. Left tag — the tag to test.
2. The operator — >, >=, <, <=, == or !=. For a BOOL left tag only == and != are offered.
3. The right-hand side. By default it is a constant whose editor follows the left tag’s type: a True / False dropdown for BOOL, a whole number for INT and DINT, a decimal value for REAL. Click the toggle button (Switch to tag comparison) to compare with another tag instead (Switch to constant changes it back).

Below the card, + Condition adds a second condition and + Group adds a nested group; either turns the rule into a group. Conditions in a group are separated by an AND or OR chip; click the chip to switch the whole group between AND and OR. Each condition and each nested group has a remove button; a group that drops to one member unwraps itself. This lets you express, for example, (Level > 95 OR High_Float == True) AND Pump_Running == False without writing any text.

Tags are chosen from dropdowns of the Tag Database, so an alert cannot reference an undefined tag. If you delete a tag an alert uses, the field shows blank; the Tag Cross Reference lists alerts by name under the tags they use, and a tag used only by an alert is never offered by Remove Unused Tags.

11.5 How alerts run

Alerts are compiled with the rest of the project: connect and press Build (F5); the IDE compiles and downloads the program to the connected controller. On the controller a separate alert task evaluates every rule continuously, independent of the ladder scan:

• A non-latched alert’s output equals its rule.
• A latched alert’s output is set when the rule becomes true and cleared when its Clear tag (or alarm_reset_request) is true. If the rule is still true when the reset arrives, the alert re-fires on the next evaluation.

Alerts have no compile-time checks of their own. An alert with an empty rule is always true, and an empty group counts as true, so finish every rule before you build.

In a WhiskerHMI project the same rules are written to the PC application’s configuration and evaluated there.

11.6 Alert history at runtime

The controller watches every alert’s output and appends an event to its alert history each time the output changes: FIRED when it goes true, CLEARED when it goes false. An alert already active when the controller starts is recorded as FIRED. Latched and non-latched alerts are logged the same way; the difference is only that a latched alert stays FIRED until it is reset. The history keeps the most recent 1000 events on the controller.

The Alert Table widget shows that history with columns ID, Timestamp, Alert Name, State and Ack, newest first, with All / Active / Cleared filter chips and a name search. Active rows are red until acknowledged and amber afterwards; cleared rows are grey. Its buttons:

On the controller’s own display all three buttons act on the controller. In a WhiskerHMI PC application the Alert Table is a viewer of the controller’s history: acknowledge and clear marks made on the PC are not sent to the controller and disappear at the next refresh, and RESET has no effect; reset latched alerts from the panel or from a ladder-driven push button.

With operator login enabled, Acknowledge alarms and Clear alarms are separate actions in the project’s role table, and the Alert Table can carry its own Required role; see HMI Designer.

11.7 Removing an alert

Click Delete Alert on the row and confirm. There is no disable switch; an alert you do not want evaluated must be deleted (keep a copy of its rule in the project’s Design Spec if you expect to restore it).

12 Modbus Server and Map Viewer

A Nexus.io Automation Controller runs a Modbus TCP server on port 502. It publishes the tags you choose as coils and holding registers so that SCADA software, a building management system or another PLC can read and write them. This chapter covers marking tags for exposure, controlling their addresses, the read-only Modbus Map view, and the CSV exports that hand the map to whoever configures the SCADA side.

Note. This is the controller as a Modbus server. Polling Modbus I/O modules, where the controller is the client, is described in I/O Configuration and Devices. Both run at the same time. A WhiskerHMI PC application reads the controller over ArenaTCP and does not need Modbus.

12.1 How the server works

There is no enable switch and no port or unit-ID setting in the project: the server listens on port 502 and answers any unit ID. It is part of the controller’s standard software; every unit built from the current image runs it from first boot (a unit commissioned by hand from the production guide gets it in that guide’s Modbus server step). The server is TCP only. The controller’s RS-485 port is a Modbus RTU master for I/O modules (see I/O Configuration and Devices); the controller cannot be polled as a Modbus RTU slave. It supports Read Coils (FC 01), Read Holding Registers (FC 03), Write Single Coil (FC 05), Write Single Register (FC 06), Write Multiple Coils (FC 15) and Write Multiple Registers (FC 16). Discrete inputs and input registers (FC 02 and FC 04) are not used; everything is a coil or a holding register.

Reading an address that is not mapped returns 0, so SCADA range scans do not fail. Writing an unmapped address is rejected. A write to a mapped register changes the tag on the controller immediately — including a field input, which the I/O scanner overwrites again on its next poll. Nothing in the server refuses writes, so give the SCADA side the map’s Access column and keep write permissions on that side.

The map is compiled with the program: connect and press Build (F5); the IDE compiles and downloads the program, and the server picks up the new map without dropping its clients.

12.2 Exposing a tag

Tags are exposed one at a time. Open the Tag Database and look at its two Modbus columns:

Click a tag to select it, then in the Properties panel find the Modbus Server section:

• Expose via Modbus — tick to publish the tag. The IDE assigns the next free address at once. Untick and the panel reads Hidden — not visible to the Modbus server; the tag remembers its last address and gets it back if it is still free when you re-expose it.
• HR — the holding-register address. Type either the raw 0-based address (100) or the Modicon form (40101).
• Coil — BOOL tags only: the coil address, raw (50) or Modicon (00051).

Under each field the panel shows both forms of the address and the word manual once you have typed one yourself. Manual addresses are never moved by renumbering unless you ask.

If you type an address another tag already owns, the Modbus HR address in use (or Modbus Coil address in use) dialog names the owner and offers Swap: the two tags exchange addresses and both become manual. Two-word tags can only swap with two-word tags.

12.3 Address layout and data types

A BOOL is published in both spaces, so a SCADA that only reads registers can still see it. Two-word values are stored low word first (word order CDAB, each word big-endian); select “word swap” or “CDAB” in the SCADA driver. A two-word value must be written with FC 16 in one request starting at its first register; FC 06 on either half is refused so a DINT or REAL can never be half-updated.

Addresses in the IDE are 0-based and are shown alongside the Modicon convention (holding register 0 is 40001, coil 0 is 00001). Field inputs (%I, %IW) are listed as read-only in the map and exports; everything else is read/write.

12.4 Auto-numbering

Select the project node in the Project Tree and open the Modbus Server section of its properties. Auto-numbering mode decides how Renumber lays out addresses:

With Group by data type an Address ranges per data type table appears with a start and size for Coil bool, HR bool, HR int and HR real (defaults: coils and BOOL registers from 0, INT from 1000, REAL from 2000, 1000 addresses each). Ranges are useful when the SCADA engineer wants all the analog values in one block.

Click Renumber all auto-assigned tags to apply the mode. The Renumber Modbus addresses? dialog warns that this changes the address of every value the SCADA reads and offers Keep manually-assigned addresses (ticked by default). Changing the mode in the dropdown triggers the same confirmation (Change auto-numbering mode?); cancelling it leaves the mode unchanged. Tags you deleted leave gaps; the Remove Unused Tags dialog reminds you that a renumber closes them.

Warning. Renumbering after the SCADA has been configured breaks every address it reads. Do it before hand-off, or export a new map and re-import it on the SCADA side. {.warning}

12.5 The Modbus Map view

As soon as one tag is exposed, a Modbus Map node appears in the Project Tree under the project, next to Design Spec. Click it to open a read-only view built from the Tag Database as it stands — no build is needed and there is nothing to edit here.

The view has two sections, Holding Registers (FC 03 / 06 / 16 · base 40001) and Coils (FC 01 / 05 / 15 · base 1), each a table with the columns Tag, Description, Type, IEC Address, Modbus (0-based), Modicon, Width, Word Order (CDAB for two-word values), Access (R or RW), Units, Gain, Offset, Min and Max. The last five come from the tag’s process-variable settings and travel into the exports as scaling.

Toolbar, left to right: a Show / hide columns button (the choice is remembered per project), Export…, and a search box (Search tag, description, address…) with a row counter on the right. Hover a row for Copy row to clipboard, which copies every column tab-separated for pasting into a spreadsheet.

The project’s Design Spec document also carries a generated Modbus Registers section with the same holding-register and coil tables, so the map is part of the printed design record.

12.6 Exporting the map for the SCADA engineer

Click Export… in the Modbus Map view. The Export Modbus Map dialog asks for:

• Format — one of the four below.
• Output file — with Browse…; the suggested name is <project>_<format>.csv.
• Device name — the OPC path prefix (Ignition) or the access name (AVEVA) the SCADA will use for this controller.
• Ignition tag-path prefix (Ignition only, default Tags).
• Default scan rate (ms) (KEPServerEX only, default 100).

All four are UTF-8 with a byte-order mark, sorted holding registers first then coils by address. The last-used values of the dialog are remembered per project. The Output panel reports Exported N Modbus map rows to ….

Tip. Keep the exported CSV with the project’s documentation and re-export it after every renumber. When the SCADA side reports a wrong value, the CSV is the record of what it should be reading. {.tip}

12.7 When the SCADA cannot connect

• The SCADA must reach the controller’s address on TCP port 502; check firewalls between them.
• The map on the controller is the one from the last Build (F5). Exposing a tag in the IDE does nothing until the program is downloaded.
• Check the addressing convention in the SCADA driver: the IDE shows both 0-based and Modicon addresses, and KEPServerEX expects the six-digit form.
• For DINT and REAL values, set the driver’s 32-bit word order to low-word-first (CDAB).

See Troubleshooting in the appendices for more.

13 Python on the Controller

Both controller families run Python, in different ways. A Nexus.io Automation Controller project carries an app.py that runs beside the ladder program, reads and writes the same tags, and can serve function calls from ladder. A SmartController (Classic) project is MicroPython: its files are edited in the IDE and synchronised to the device over USB serial. This chapter covers both, starting with the editor they share.

13.1 The Python editor

Click a Python file in the Project Tree and it opens in the Python editor: syntax highlighting, line numbers, and the editing behaviour you expect from a code editor.

• Ctrl+F opens the find bar (Find…, Replace…, Enter for next, Shift+Enter for previous, Esc to close). Search is case-insensitive plain text.
• Tab and Shift+Tab indent or outdent the selected lines by four spaces; with no selection, Tab inserts four spaces and Shift+Tab outdents the current line.
• Enter keeps the previous line’s indent and adds a level after a line ending in :, (, [ or {.
• Ctrl+/ toggles a # comment on the line or selection.
• Pasted text has tab characters converted to four spaces, so mixed-indent errors cannot creep in from another editor.
• Edits are saved into the project automatically as you type; Ctrl+S saves the project.

13.2 Part 1 — Python on the Nexus.io controller

13.2.1 app.py and run(ctx)

Every Nexus.io controller project has a Python node in the Project Tree containing app.py. It cannot be deleted; Add Python File adds further modules (helpers.py, utils/math.py) that app.py can import. A new project’s app.py is a template:

def run(ctx):
    ctx.log.info("App started")
    while not ctx.shutdown_requested:
        # Your application logic here
        ctx.wait(1.0)
    ctx.log.info("App stopped")

The controller’s Python runtime calls run(ctx) once, on its own thread, alongside the ladder program. There is no fixed scan: your loop decides its own rate with ctx.wait(). When run returns, the application has finished; it is started again only when a new bundle arrives. An exception inside run is reported to the Python Log with its traceback and the application stops.

A ladder program and app.py run at the same time and share every tag. A Python-only project — no ladder logic at all — is equally valid; the ladder VM simply has nothing to do.

13.2.2 The ctx API

ctx is the controller’s API. Tag access by name is the normal way to work; the arena calls are there for offset-addressed access when you need it.

ctx.wait(seconds) sleeps for the time you give it from the moment you call it; it does not subtract the time your loop body took. A loop that works for 40 ms and then waits 50 ms repeats every 90 ms. The runtime measures the time between successive wait() calls and streams it to the IDE’s Statistics panel, so you can see your loop’s real period.

A typical loop:

SCAN_S = 0.05   # 50 ms

def run(ctx):
    ctx.log.info("Lift station app started")
    while not ctx.shutdown_requested:
        level = ctx.read_tag("wet_well_level")
        if ctx.read_tag("mode_auto"):
            ctx.write_tag("call_lead", level > ctx.read_tag("sp_lead_start"))
        if ctx.wait(SCAN_S):
            break
    ctx.log.info("Lift station app stopped")

The standard library is available — datetime, json, statistics, re, collections — and extra modules you add to the project’s Python node are importable by file name. There is no package installer: what you can import is the standard library plus your own files.

13.2.3 Deploying Python

Python is part of the normal build. With a controller connected, press Build (F5); the IDE compiles and downloads the program to the connected controller. Before bundling, every Python file in the project is syntax-checked; an error stops the build with the file, line and message in the Output panel. The Python files, the tag map and any Python function blocks are packaged as one bundle inside the deploy. On the controller, the runtime notices the new bundle within a couple of seconds, stops the running run(ctx) (your loop sees shutdown_requested), replaces the files and starts the new application. Nothing needs restarting by hand.

13.2.4 Testing without a controller

Build & Emulate runs the same bundle on your PC. The controller’s Python runtime starts beside the ladder emulator and runs your application unmodified — run(ctx), the alert rules and any Python function blocks — against the emulated memory, so a value you set in the IO Stimulus tab is what ctx.read_tag returns and what ctx.write_tag writes shows in the Tag Monitor and on the HMI Preview. The Python Log panel connects to the emulated runtime automatically. See Connecting, Deploying and Emulating.

13.2.5 The Python Log

The Python Log tab at the bottom of the workspace streams the controller’s application log live: every ctx.log line with its time and level, plus the runtime’s own messages about starting and stopping the application. It connects automatically when the IDE connects to a Nexus.io controller, and to the emulated runtime during Build & Emulate.

• An exception in run(ctx) or in a Python function block appears as a red row with the exception and a source · phase line; click the row to expand the traceback. Unread errors are counted in a red badge in the panel header; click the badge to clear it.
• Header buttons: Connect / Disconnect, Copy all log entries to clipboard, Clear Log, and Auto-scroll ON / OFF. Any text in the list can be selected and copied.

Use ctx.log rather than print(): the log is what the panel shows.

13.2.6 Python function blocks (PYFB)

A ladder network can call a Python function and use its result. On the Python side, decorate a function in app.py:

from whisker import pyfb

@pyfb("calc_dose")
def calc_dose(ctx, flow_gpm, target_ppm):
    return flow_gpm * target_ppm * 0.012

def run(ctx):          # optional when the file only serves function blocks
    while not ctx.shutdown_requested:
        if ctx.wait(1.0):
            break

The whisker module is provided by the runtime; you do not add a file for it. The function receives ctx — the same object as run(ctx), so it can read other tags and log — followed by the block’s wired arguments in pin order, already converted to int, float or bool. Return an int, float or bool; it is written to the block’s OUT pin, typed by the tag bound there. Returning None leaves OUT unchanged.

On the ladder side, the PYFB block’s Properties panel takes the Instance Name, the Python function (@pyfb name in app.py), arguments A1 to A4 (tags or numbers; only wired arguments are passed), a Timeout TO in milliseconds (blank = 1000) and the output tags Result (OUT), Done (DONE), Error (ERR) and Error code (ECODE). Each rising edge of the network sends one request; DONE goes true when the reply arrives and stays true until the next request. ECODE reports 1 for a timeout, 2 when the function raised, 3 when no function of that name is decorated, 5 for a program/runtime mismatch. On any error OUT keeps its last good value, so a dosing loop never slams to zero because Python hiccupped. An exception’s traceback appears in the Python Log.

Rules that keep this reliable:

• Keep the function quick. Functions run one at a time on a dispatcher thread, so a slow one delays the others; a round trip measures about 20 ms at a 10 ms scan. Long work belongs in run(ctx) with a tag handshake.
• Do not call ctx.wait() inside a decorated function.
• Arguments and results are numbers only — no strings or lists.
• A project with PYFB blocks but no decorated function of that name still builds; the block reports ECODE 3 on its first call and the runtime logs the missing name once.

The block’s pin table is in Ladder Instruction Reference.

13.3 Part 2 — SmartController (Classic)

The SmartController (Classic) runs MicroPython. Its logic is Python, edited in the IDE and copied to the device over USB serial. A Classic project shows only what applies to it: the File System tree, Design Spec, Tags (Tag Database and Tag Cross Reference) and, when tags are exposed, Modbus Map. There is no ladder editor, HMI Designer, Alerts editor or Setup node.

13.3.1 Project files

A new Classic project has three files, none of which can be deleted or renamed:

Add further modules with New File in the File System tree.

A Classic project must have at least one process variable (a tag with a PV slot in the Tag Database). Without one the controller’s display task stops and the controller restarts every 30 seconds with a blank screen, so Sync and Build refuse such a project and say why.

13.3.2 Connecting over serial

Plug the controller into a USB port and click Connect in the toolbar. The Connect to SmartController Classic dialog lists the serial devices it finds under Available Devices:; a Classic shows as MicroPython (RP2) with its serial number and is selected for you (or the port you used last time). Set the Baud Rate if needed — 115200 is the default — and click Connect. The toolbar then reads Connected (COMn).

Connecting stops the program on the controller so the IDE can read and write its files, and keeps the controller at the >>> prompt. The controller has a hardware watchdog that would otherwise restart it a few seconds after its program stops; while the IDE holds it, the IDE keeps the watchdog satisfied. Disconnect restarts the controller so its program runs again. If the controller restarts or is unplugged while connected, the toolbar reports the connection lost — click Connect again.

Warning. Disconnect before closing the IDE. If the IDE exits while a serial connection is open, Windows keeps the port locked until the USB driver releases it, which can take a minute or more, and the controller stays stopped until it is restarted or power-cycled. {.warning}

13.3.3 The File System tree

At the top of the Project Tree, File System has two sections:

• Local — the files in your project. Buttons: Sync all local files to target, New File, New Folder, Delete selected. Double-click a file to edit it.
• Target — the application files on the controller, shown while connected: the files its manifest lists for the installed application and configuration, and any other Python file in the root of its file system. The controller’s own firmware is not shown. Refresh re-reads it. Double-click a target file to view it read-only in a tab titled with its name in square brackets. A folder shown as app (legacy) is left over from an older installation; it hides the installed application and the next Sync removes it.

13.3.4 Sync

There is no per-file upload. Sync installs the project the same way the factory load tool does:

• every project file goes to the root of the controller’s file system;
• files the previous application installed that are not in your project are removed — the controller’s firmware, ident.json and main.py are never touched;
• a legacy /app folder is removed;
• when config.json changes, the saved process variable values (pv.dat) are cleared, because they are restored by position and would otherwise land on the wrong variables;
• each uploaded file is checked on the controller, and the controller’s manifest (/manifest.json, its record of what is installed) gets an app package (your code) and a config package (config.json), both named and versioned from appName and appVersion, next to the firmware’s own package.

The Sync to Target dialog lists the new and modified files, everything it will delete and the package name and version, and Sync carries it out. Files are compared by their SHA-256 hash, so an unchanged project reports Target is up to date — no changes. After a Sync, restart the controller (below) to run the new program.

13.3.5 The console

The SmartController Classic Console tab at the bottom of the workspace is an interactive MicroPython REPL over the same serial port. Type at the >>> prompt; Up and Down recall previous commands. Its buttons are Interrupt (Ctrl+C) — Ctrl+C in the input does the same — Restart controller and Clear.

Restart controller restarts the controller and follows it: the connection is picked up again as soon as the controller is back, without stopping it, so its start-up messages and anything the program prints appear in the console while it runs. Interrupt stops the running program and returns to the >>> prompt.

For a more detailed log in the console, set the project’s Logger Profile to debug (see Project Properties Reference), Sync and restart.

13.3.6 What is different from the Nexus.io controller

• No compile step: MicroPython runs the .py files directly. Build for a Classic project needs no device connection: it asks for a folder and writes the two packages Sync installs — dist_app/ (the code) and dist_config/ (config.json), each with its manifest.json — the form the factory load tool installs from.
• The ctx API, run(ctx) and Python function blocks belong to the Nexus.io controller. A Classic app.py uses app_vars.py and the asyncio loop shown above.
• The Python Log panel is for the Nexus.io controller’s application log; on a Classic, use the console.
• Cloud publishing of a Classic’s process variables is configured in the Tag Database (Cloud Type, Units, R/W and the display settings) and pushed with the project’s cloud configuration; see Project Properties Reference.

14 Connecting, Deploying and Emulating

This chapter takes you from a saved project to a Nexus.io Automation Controller running it: finding the controller on the network, connecting to it in whatever security posture it is in, letting the IDE reconcile your open project with what the controller already holds, deploying with Build, and running the program on your PC with Build & Emulate when there is no controller at hand.

Nothing here needs a Whisker.io account except connecting to a cloud-enrolled controller, which needs the account that enrolled it (see Security, Provisioning and Enrolment).

14.1 Before you connect

• The project builds cleanly or you are prepared to fix what the Output panel reports.
• The controller is powered and on the same network as your PC, or reachable from it.
• You know how the controller was commissioned: standalone (as shipped: plain connections, unsigned deploys, or a unit a site chose to leave that way), managed (enrolled into a cloud account or provisioned into a site CA) or awaiting enrolment (a locked-down configuration some sites order: nothing but enrolment until it is managed). The Connect dialog shows which.

14.2 Discovering controllers

Click Connect on the toolbar. The Connect to Target dialog opens and scans for about five seconds. Every Nexus.io controller announces itself on the local network as an mDNS service of type _ladder-vm._tcp; the IDE lists what it hears. If mDNS finds nothing, the IDE probes the addresses of your PC’s own subnet directly, so a controller on the same network segment still appears even when multicast is filtered.

Each row shows the controller’s model and serial, its address and port, and its posture:

Click a row, then Connect. The refresh icon in the title bar (tooltip Scan for devices) runs the scan again. When a project is open, the dialog says Looking for: followed by the project’s target type and lists only matching controllers.

Note. A PC on a VPN, or on a different subnet from the controller, cannot see mDNS announcements and the subnet probe scans the wrong subnet. Use Enter address manually.

14.2.1 Connecting by address

Expand Enter address manually and fill in Target Address (the controller’s address or host name) and Port (9000 unless you have changed it). Because no discovery record tells the IDE the controller’s posture, it tries a TLS connection with your identity first and falls back to a plain connection if that is refused. Connecting by address is the normal path over a VPN or a routed network. For a standalone controller — which is how a new one arrives — that is the whole procedure: connect, then deploy. A managed controller reached by address still needs the identity that enrolled or provisioned it (see Security, Provisioning and Enrolment).

14.3 Which identity the IDE presents

A managed controller only accepts a certificate issued by the authority it trusts. The IDE picks its identity in this order:

1. Your account identity when you are logged in to Whisker.io. The IDE requested this certificate from the account’s certificate authority at login; a controller enrolled into the same account accepts it.
2. A site identity imported from a site administrator’s package. The project’s Site identity setting (Project Properties, Security) selects which one; with a single site imported the choice is automatic.
3. The local keystore, used only for bench units provisioned from this PC.

If the handshake is refused, the Output panel and the connection message name the reason; the usual causes are listed in Troubleshooting.

14.4 What happens after connect

The toolbar shows a green Connected badge and the status bar reads Connected, with (Running) or (Debug) appended once the controller reports its mode. The IDE also opens the controller’s Python log stream (the Python Log panel) if the program has one.

Straight after connecting, the IDE asks the controller which project it holds and compares it with the project you have open. This is the connect-time reconcile:

The dialog is titled Project on target differs and has two buttons: Keep my project and Download from target. Downloading closes the open project (you are asked to save unsaved edits first) and opens the controller’s copy; that copy has no file location yet, so the first Save asks where to put it.

A controller can only offer a download if the project was deployed with Store editable source on target switched on (Project Properties, Deployment section). With it off, the controller keeps nothing an engineer could pull back, which some customers require for intellectual-property reasons; the IDE then cannot confirm what the controller is running either.

14.5 Deploying with Build

For a Nexus.io project the Build (F5) button is enabled only while a controller is connected, because Build compiles the project and, on success, downloads it to the connected controller in one action. The Output panel calls the pair “Build + Download”. There is no separate Upload or Download button.

Press Build (F5). In order, the IDE:

1. Runs the undefined-tag sweep. If the ladder references a name the tag database does not hold, the dialog N tags are used but not defined lists them with a suggested type; Create All creates them and the build continues, Cancel stops it.
2. Compiles the project and prints the compiler’s output. Errors end the build with Build failed.
3. Applies the deploy-overwrite guard. If the controller holds a different project, the dialog Replace project on target? appears; Replace continues, Cancel leaves the controller untouched.
4. If the project requires cloud PIN login at the panel, requests a fresh device credential from the cloud for this controller’s serial (see Security, Provisioning and Enrolment).
5. Stops the controller’s program.
6. Sends the program. To a managed controller it packages the build into a signed bundle and stages it; the controller verifies the signature against the authority it trusts and only then installs the files. To a standalone controller it sends the build artifacts one by one, unsigned.
7. Reloads the program, starts it running and turns monitoring on. The last line is Program downloaded and running.

14.5.1 The signed bundle

A managed controller never accepts a plain program file. The IDE packs the build directory into one archive, signs it with your certificate, and sends the archive, the signature, a manifest naming the signer and the payload hash, your certificate and the authority’s chain. The controller checks that the payload matches the manifest, that the signature is valid, that your certificate chains to its trusted authority and is not on its revocation list. If any check fails the deploy is refused with the reason in the Output panel and the previous program keeps running.

The first signed deploy to a controller that has no trust anchor yet binds it to your authority; the Output panel says so. From then on only bundles signed under that authority are accepted.

14.5.2 Retained values

Variables marked retained keep their values across a deploy: the controller migrates them by name, so a setpoint an operator entered at the panel survives a program update. Renaming a retained variable makes it a new one. See Tag Database.

14.6 Run, Stop and Debug

Three toolbar buttons control the program on a connected controller: Run Mode (F7), Stop Mode (Shift+F7) and Debug Mode (F9). The keys do the same as the buttons and, like them, work only while a Nexus.io controller is connected.

• Run Mode — the runtime scans every task, reads inputs and drives outputs.
• Stop Mode — the runtime halts. Outputs hold their last state.
• Debug Mode — Run Mode with live monitoring switched on (subject to the gate below). The ladder editor shades energised elements and shows live values.

The active mode is highlighted on the toolbar and named in the status bar.

Warning. Stop Mode freezes outputs where they are. Confirm with operations before stopping a controller that drives live equipment. {.warning}

14.7 Why monitoring is off until you deploy

Live monitoring reads the controller’s memory and labels it with the open project’s tag names. If the controller is running anything else, every value shown would be plausible and wrong. So the IDE fails closed: the monitoring button (tooltip Enable Monitoring) is disabled until this session has built and downloaded the open project to this controller, and it disables again the moment you edit the project. The disabled button’s tooltip states the reason, for example Monitoring unavailable — This project has not been downloaded to the target yet. Use Build + Download to enable monitoring.

The connect-time reconcile applies the same rule from the other side: keeping your project when the controller holds a different one leaves monitoring off; keeping it when the controller holds a different version of the same project gives limited monitoring, where names align but values may be unreliable until you deploy.

14.8 Build & Emulate

Build & Emulate (tooltip Build & Emulate (run on this PC, no target needed)) compiles the project and runs it in an emulator on your PC. It needs no controller and no account. It does need a Python 3.9 or newer interpreter on your PC’s PATH; the emulator is a Python program installed with the IDE.

When you press it, the IDE:

1. Runs the undefined-tag sweep and compiles, exactly as Build does.
2. Disconnects from any controller — the IDE keeps one connection, and two would leave you unsure which one the ladder editor is showing.
3. Starts the emulator on the build it just produced and connects to it on this PC.
4. Turns the toolbar amber for as long as emulation is running (the IO Stimulus tab’s header turns amber too), and prints Emulation running — the IDE is connected to the emulator on this PC, not to a controller.

The emulator runs the ladder program and the controller’s memory areas on your PC. The connect-time reconcile and the monitoring gate are satisfied automatically, because the emulator runs exactly the build it was handed and accepts no other. Press Enable Monitoring (or Debug Mode) and the IDE behaves as it does against a controller:

• Ladder editor — energised elements and wires are shaded, live values appear above the elements.

• Tag Monitor — every addressed tag with its live value; the header counts the emulator’s scans.

• IO Stimulus tab — the panel for driving the program by hand. Its header reads IO STIMULUS — EMULATION. Under INPUTS — drive these every tag bound to a physical input is listed: digital inputs as switches, analogue inputs as a number box or, when the channel has an IODF range, a slider labelled in engineering units with the raw count beside it. A value you set is held every scan so the program cannot overwrite it; a lock icon marks the tag as forced. Under OUTPUTS — what the ladder produced the physical outputs are shown read-only. A project whose tags are all memory (no physical I/O) shows nothing here; drive those from the Properties panel’s write and force controls instead.

• HMI Preview tab — renders the project’s panel screens (screen drop-down, zoom) with live values and marks itself LIVE — touch enabled while monitoring is on, so push buttons, selector switches and numeric inputs on the preview write into the emulated program exactly as the panel would. Without monitoring it shows design-time defaults and ignores presses.

• Properties panel — the ONLINE — WRITE / FORCE section for the selected network works as on a controller (see Monitoring and Debugging).

• Python application — when the project has Python (an app.py, alerts, or Python function blocks), the controller’s own Python runtime starts on your PC beside the emulator and runs it unmodified: run(ctx) is called, ctx.read_tag and ctx.write_tag go to the emulated memory, alerts are evaluated, and a PYFB block in the ladder gets its answer from your @pyfb function. The Output panel confirms it with Python application running under emulation, and the Python Log panel connects to it exactly as it does to a controller, so ctx.log lines, tracebacks and the loop statistics appear there. Its own start-up messages are prefixed [py]. If the runtime cannot start, the Output panel says Python application not running: with the reason and the ladder emulates without it.

Physical devices, the historian and the cloud service are not run by the emulator; the program — ladder, Python and alerts — is what you are testing.

The same button becomes Stop Emulation while the emulator runs. Stopping it ends the Python runtime (your run(ctx) loop sees shutdown_requested) and the emulator, drops the connection to them and restores the toolbar and your previous target address. If a start fails, the last lines of the emulator’s own output appear in the Output panel prefixed [emu]; a port already in use usually means an emulator from an earlier session is still running.

14.9 Disconnecting

Click the toolbar Disconnect button (the same button as Connect, highlighted while connected). Monitoring stops, the Python log stream closes and the status bar returns to Not Connected. Any forces you left on the controller stay active until the controller’s runtime restarts — check the ladder editor’s amber FORCES chip before you leave (see Monitoring and Debugging).

Opening or creating another project also drops the connection, so the toolbar never reports a connection that belongs to a different project.

14.10 A typical session

1. Open the application and select the project.
2. Click Connect, pick the controller, connect. A standalone controller connects plainly; a managed one uses your account or site identity. If the reconcile dialog appears, decide whether the controller’s copy or yours is the one to keep.
3. Edit tags, ladder, HMI and alerts.
4. Press Build (F5). Create any undefined tags the sweep reports. Confirm Replace if the controller held a different project.
5. Watch the Output panel through Program downloaded and running. Monitoring is now on.
6. Use Debug Mode, the ladder editor’s live shading, the Tag Monitor and the Properties panel’s write and force controls to check the logic.
7. Edit again; monitoring switches off. Press Build (F5) again to deploy and re-enable it.
8. Clear any forces, then Disconnect.

If no controller is available, replace steps 2 and 4 with Build & Emulate and work against the emulator; the rest of the loop is the same.

15 Monitoring and Debugging

Once a program is running on a Nexus.io Automation Controller (or in the emulator), the IDE becomes a live window onto it: the ladder editor shades what is energised, the Tag Monitor lists every addressed tag’s value, the Properties panel lets you write and force values, and the Output and Statistics panels tell you what the runtime is doing. This chapter covers each tool and ends with diagnostic recipes for the problems that come up most.

Nothing in this chapter needs a Whisker.io account.

15.1 The monitoring gate

Live values are only ever shown for a program this IDE session has deployed. The rule:

Monitoring is available only after Build (F5) has compiled and downloaded the open project to the connected controller in this session, and it switches off again on any edit.

The reason is safety, not tidiness: monitoring reads the controller’s raw memory and labels it with the open project’s tag names. Against a different program every value would look plausible and be wrong. The toolbar’s monitoring button (tooltip Enable Monitoring / Disable Monitoring) is disabled while the gate is closed, and its tooltip names the reason:

Build (F5) turns monitoring on automatically when it finishes. Debug Mode turns it on as well, when the gate allows. Under Build & Emulate the gate is satisfied by construction, because the emulator runs exactly the build it was given.

15.2 Where live values appear

• Ladder editor. Contacts and coils that are energised change colour; wires carry the power flow across each network; the label above every element shows the tag’s current value. Compare segments (CMP) are evaluated against live values.
• Tag Monitor panel. A table of every addressed tag and its value.
• Properties panel. With a network selected, an amber ONLINE — WRITE / FORCE section lists the tags on that network with their live values and write/force controls.
• IO Stimulus panel. Every tag bound to a physical input as a switch, number box or slider you can drive (values are held every scan), and every physical output read-only. Its header reads IO STIMULUS — TARGET on a controller and IO STIMULUS — EMULATION under Build & Emulate; see Connecting, Deploying and Emulating for the controls.
• HMI Preview panel. The project’s panel screens rendered with live values; LIVE — touch enabled while monitoring is on, so presses on the preview write to the controller as the panel would.
• Statistics panel. Scan timing, program size and connection state.

15.3 The Tag Monitor panel

The Tag Monitor tab sits in the bottom panel group next to Output. It lists every tag that has an address; local temporaries without an address have no memory slot to read and are not shown.

The header shows the connection dot, the scan counter and scan time (for example 1240 scans · 812µs), and three controls:

• Filter — type part of a name, address or description to narrow the list.
• Eye toggle — system-generated tags are hidden by default (tooltip System-generated tags hidden — click to show). Click to include them; this is where the per-device Comm OK, Comm Age and Error Type tags live.
• Copy — tooltip Copy visible tags to clipboard (TSV). Copies the visible rows as tab-separated text (Name, Type, Address, Value, Description) ready to paste into a spreadsheet or a support e-mail.

The right-hand count shows visible / total when a filter or the eye toggle is hiding rows.

Columns are Name, Type, Address, Value and Description. Values are 1/0 for BOOL, integers for INT and DINT, three decimals for REAL. Before monitoring starts the Value column shows a dash and the panel says Not connected — no live values; once monitoring runs, a ? means the tag’s address could not be read from the data the controller sends.

15.4 Debug Mode shading in the ladder editor

Debug Mode (toolbar; tooltip Debug Mode (F9)) puts the controller in Run and switches monitoring on. In the ladder editor:

• an energised contact, coil or output pin is drawn in the active colour;
• a normally closed contact is drawn active when its tag is false, since that is when it conducts;
• wires are coloured from the left rail as far as power flows, so the first de-energised segment on a network is visible at a glance;
• the label above each contact and coil shows the tag’s live value.

Monitoring refreshes about five times a second. The picture is a sampled view, not a scan-by-scan trace; a pulse shorter than the refresh interval may never be seen shaded.

15.5 Writing and forcing values

Select a network in the ladder editor while connected with monitoring on. The Properties panel shows the ONLINE — WRITE / FORCE section with one row per addressed tag on that network.

Each row shows = value (what the controller holds now) and a control for the value you are about to write: a switch for BOOL, plus and minus for integers, a text box for anything typed.

• Write (the pencil, or Enter in the text box) writes the value once. The program can overwrite it on the next scan, which is what you want for a setpoint or a one-shot test.
• Force (the pin; tooltip Force the typed value (held every scan)) writes the value every scan so the program cannot overwrite it. Use it to hold an input high or pin an analogue value while you watch the logic.
• Release (the open lock; tooltip Release force) removes the force on that tag.
• other tag… with Add brings any other addressed tag in the project into the section.
• Clear All Forces (N) releases every force on the controller.

Function-block instances (a timer or counter name) are not tags and cannot be written; force their pins instead.

While any force is active the ladder editor’s header shows an amber chip, FORCES (N) — click to clear, and the Statistics and Properties panels count them. Forces live on the controller: they survive the IDE disconnecting and reconnecting, and are cleared when the controller’s runtime restarts.

Warning. A forced output on a controller driving live equipment stays forced after you disconnect. Clear every force before you leave, and never force outputs on a running plant without operations’ agreement. {.warning}

15.6 The Output panel

The Output tab collects everything the IDE does on your behalf. Each line has an icon for its kind — information, warning, error or success — and a timestamp. Copy All copies the log with [INFO], [WARN], [ERROR] and [OK] prefixes; Clear empties it; right-click a line to copy just that one.

What you will see there:

• Build lines from the compiler, then the deploy sequence (Stopping VM…, Signing bundle for managed controller… or Uploading program to target…, Reloading program…, Starting VM…, Program downloaded and running).
• Connect lines: the connect-time reconcile’s outcome, and on a site-managed controller whether the revocation list was pushed.
• Enrolment and security lines from Provision New Device, Approve Re-Enrollment and the Security dialog.
• Emulator output prefixed [emu] when a Build & Emulate start fails.
• Warnings the deploy carried, such as an optional artifact an older controller did not accept.

15.7 The Statistics panel

The Statistics tab is a dashboard of cards that rearrange to the width of the panel:

• Controller — connected or not, the mode (RUN, STOP or DEBUG), the controller’s name and address, uptime and whether monitoring is on.
• Scan time — a gauge of the current scan time, scaled to the slowest scan seen and coloured green, amber or red as it nears it, with the scan Rate, Min and Max below.
• Scan trend — the last two minutes or so of scan-time samples, with the average.
• Program on controller — Code size, Tasks, FB instances and Scans.
• Python app — when the controller runs a Python application, a gauge of its loop time with rate, average, maximum and loop count.
• Project — the open project’s tags (total and by type), programs, networks and HMI screens.

A rising Max with a steady scan time points at an occasional slow path — a device that times out, or a Python function block doing too much. The trend shows when it happens.

15.8 The Python Log panel

When the connected controller runs a Python application, the Python Log tab streams its ctx.log() output live. The stream opens automatically on connect. For the SmartController (Classic) the SmartController Classic Console tab is the interactive REPL; see Python on the Controller.

15.9 Historian and trends

Values you need over hours or days belong in the on-controller historian, not in a Tag Monitor you have to keep open. Tick Hist for the tag in the Tag Database, deploy, and read it back with a trend chart on the panel or in WhiskerHMI. See Historian and Trends.

15.10 Diagnostic recipes

15.10.1 Start with the system tags

Every device in I/O Configuration gets three tags the IDE maintains for you: <device> Comm OK, <device> Comm Age and <device> Error Type. They are the first thing to check when a value looks wrong. Show them in the Tag Monitor with the eye toggle, or filter on Comm.

• Comm OK false with a rising Comm Age — the controller is not hearing from that device. Check the address, unit ID, cabling and that the device is powered.
• Comm OK true but the value is stale — the device answers, but the register or channel you bound is not the one changing. Check the point binding in I/O Configuration.
• Error Type non-zero — the device answered with an exception. Compare the register map with the device’s documentation.

15.10.2 “The program is deployed but nothing happens”

1. Check the status bar reads Connected (Running). If it says only Connected, press Run Mode.
2. Turn on monitoring (or press Debug Mode). If the button is disabled, read its tooltip — you probably edited since the last deploy. Press Build (F5).
3. Look at the first network that should fire. Follow the wire colour from the left rail; the first grey segment is the contact that is false. Check that tag’s value and where it comes from.
4. If the input never changes, check the device’s system tags as above.

15.10.3 “A value is wrong by a scale factor”

The device’s raw counts are not the engineering value. Check the IODF range chosen for the channel in I/O Configuration and the SCALE block’s parameters in the ladder.

15.10.4 “An alert will not clear”

Latched alerts stay active until acknowledged at the panel even after the condition clears; see Alerts Editor. For a non-latched alert, watch its condition tags in the Tag Monitor: the alert follows them exactly.

15.10.5 “Monitoring stops by itself”

You edited the project. The gate closes on any edit and reopens after the next Build (F5).

15.10.6 “The connection drops”

Read the Output panel’s last lines. A controller that restarts into managed mode after enrolment or site provisioning drops the connection on purpose — reconnect from Connect. A drop during a deploy’s reload step is followed by an automatic reconnect. Repeated drops with nothing in the log point at the network: a second IDE connected to the same controller, a PC that keeps switching between Wi-Fi and cable, or a VPN that resets idle sessions.

15.10.7 “The panel HMI shows old values”

The panel reads the controller’s memory directly and does not depend on the IDE’s monitoring. If the panel is stale while the Tag Monitor is live, the HMI screen is bound to a different tag than the ladder writes. Check the widget’s tag in the HMI designer.

See Troubleshooting for connection, enrolment and deploy failures.

16 Security, Provisioning and Enrolment

A Nexus.io Automation Controller leaves the factory standalone: it has no identity and accepts plain connections and unsigned deploys from any IDE that can reach it. A controller connected to the cloud must be managed, and enrolment makes it so. A controller that is not connected to the cloud is managed only if you choose to make it so, and the IDE, the controller and a WhiskerHMI panel all respect that choice. This chapter explains the three security postures a controller can be in, the two paths — a Whisker.io account (Path A), or standalone with the optional site certificate authority you run yourself (Path B) — the Security dialog that manages both, the local keystore for bench units, PIN login at the panel, and what a managed controller refuses.

What needs what:

The Security dialog opens from the toolbar shield button (tooltip Security) in both editions. The Cloud edition shows it whether or not you are logged in; the Offline edition shows the same dialog without the Account section, since there is no account to show.

16.1 The three postures

Every controller shipped to a customer arrives standalone and stays there until you decide otherwise. Enrolling it into a cloud account (Path A) or provisioning it into a site (the optional step of Path B) makes it managed; it then trusts exactly one authority: the account’s, or the site’s. Awaiting enrolment is not how a delivered controller starts. It is a locked-down configuration a site can order for units that must be managed before they do anything, and the posture a decommissioned controller returns to; in it the controller accepts nothing until it has been enrolled or provisioned.

16.2 Path A — cloud provisioning and enrolment

Path A binds the controller to your Whisker.io account’s certificate authority. You need the Cloud edition, logged in, and a location in the Cloud Explorer to put the device under. At login the IDE requested its own user certificate from the account’s authority, so nothing has to be set up in a keystore first.

16.2.1 Provision New Device

1. Click Connect and connect to the controller while it shows Standalone (or Awaiting enrolment, on a unit configured that way).
2. In the Cloud panel (the tab beside Project), right-click the location and choose Provision New Device.

3. Fill in Device Name (pre-filled from the project name) and, if you like, Description. Serial Number is filled in from the connected controller and locked; the lock icon (tooltip Edit the serial by hand (not recommended)) is only for provisioning a unit that is not connected. Part Number is NIO-AC-11-D-120-0000-112N-N-6 for a Nexus.io controller. Tick Save tag configuration to create the device’s cloud tag template from the project’s process variables at the same time.
4. Click Provision. The status line walks through Checking for duplicates, Creating tag template, Provisioning device, Generating bootstrap nonce, Sending bootstrap.json to the controller… and Bootstrap delivered — waiting for the controller to enrol….

What happens on the controller: the IDE writes a small bootstrap file over the connection it already has. The controller’s enrolment service reads it, contacts the cloud with the one-time nonce, receives a certificate issued by the account’s authority, installs it with the authority’s chain and revocation list, and restarts its services in managed mode. Enrolment usually completes within a few seconds; the IDE polls for up to two minutes.

16.2.2 The reconnect moment

Restarting into managed mode closes the plain connection the IDE was using. The dialog reports Controller enrolled … It restarted into managed mode — reconnect from the Connect dialog. Click Connect again; the row now says Managed and the connection is mutual TLS with your account identity. From here on every deploy to this controller is signed.

16.2.3 The one-time nonce dialog

If the IDE was not connected to the controller when you clicked Provision, or the controller refused the bootstrap, it cannot deliver the nonce itself. The Device Bootstrap Nonce dialog then shows the nonce once, with Copy nonce and I’ve recorded it. You do not need the nonce in normal use: connect to the controller (its row still shows the posture it had before) and choose Approve Re-Enrollment on the device in the Cloud panel. The IDE mints a fresh nonce, delivers it over the connection and waits for the controller to enrol, exactly as Provision New Device does.

16.2.4 Device actions in the Cloud panel

Right-click an enrolled device:

• Rotate Device Cert — revokes the current certificate and opens a five-minute window in which the controller may re-enrol with its old identity. An online controller does so on its next revocation-list check, within fifteen minutes, and comes back with a new certificate without a visit. If it is offline past the window, use Approve Re-Enrollment.
• Decommission Device — revokes the certificate and disables the device in the cloud. The controller drops its identity, closes its data port and waits in the awaiting-enrolment posture until an operator approves re-enrolment. Use it for a unit leaving service, changing hands or suspected compromised.
• Approve Re-Enrollment — mints a new nonce for a decommissioned device, or for one whose enrolment never completed, and delivers it if the IDE is connected to that controller.

Each action first shows the device’s current enrolment state and fingerprint and asks you to confirm. The same three actions, under the same names, are in the row menu of the Security dialog’s controllers table.

16.2.5 Revocation and renewal

The account’s certificate revocation list (CRL) is the list of certificates the authority no longer accepts — rotated or decommissioned controllers, re-issued or withdrawn IDE certificates. Every enrolled controller fetches it from the cloud every fifteen minutes and consults it at every connection and every signed deploy. The IDE refreshes its own copy daily at login.

Certificate renewal is automatic. A cloud-issued device certificate is valid for 30 days; the controller’s renewal service asks the cloud for a new one once fewer than 7 days remain and restarts its services with it. Nothing has to be scheduled, and a controller that is offline for the whole week simply renews when it is next connected, provided its certificate has not yet expired; past expiry, use Approve Re-Enrollment. The IDE’s own certificate is re-issued at login when fewer than 30 days remain.

16.3 The Security dialog — Account section

Logged in, the first section is headed Account N — cloud certificate authority and holds:

• Your IDE certificate (mTLS + deploy signing) — the certificate the cloud issued you, with subject, issuer, fingerprint, status and expiry. Re-issue requests a new one; controllers accept it at once because they trust the authority, not the individual certificate.
• Account certificate authority chain — the Issuing CA and Root CA cards.
• Revocation list (CRL) — when it was fetched and when the next update is due; Refresh fetches it now.
• Controllers enrolled in this account — a table with Serial, Device / location, State, Fingerprint and Enrolled date. State is one of Enrolled, Awaiting, Rotating, Decommissioned, Not enrolled or Error; hover for an explanation. The row menu offers Rotate Device Cert and Decommission Device for an enrolled controller, Approve Re-Enrollment otherwise.
• Panels (WhiskerHMI PC identities issued by this account) — the panel identities this IDE has issued from the account’s authority, with Station, fingerprint, expiry, status and a Revoke icon per row, and the Issue panel identity… button (below).

Not logged in, the section says so and the rest of the dialog still works.

16.3.1 Panels — identities for WhiskerHMI PCs

A WhiskerHMI panel that connects securely to an enrolled controller must present a certificate issued by the account’s authority; the build of the panel ships only the account’s CA chain and revocation list. Each panel PC therefore needs its own panel identity, issued here and imported on that PC. Click Issue panel identity…, enter the Panel PC name (the station name becomes HMI-<NAME>), the Validity (days) and a Panel passphrase (confirmed), click Issue… and save the .whisker-panel package. The cloud issues the certificate; the IDE packages it with the account chain and revocation list. Copy the file to the panel PC and have the operator import it from the panel’s Panel ▸ Import panel identity… menu with the passphrase, sent separately. Revoke on a panel’s row puts its certificate on the account revocation list; enrolled controllers pull the list every fifteen minutes and refuse the panel from then on. The full procedure, including the messages the panel shows, is in The WhiskerHMI PC Application.

16.4 Path B — standalone, and the optional site CA

Path B is for plants without a cloud account. By default it needs nothing from this chapter: the controller stays standalone, you connect by discovery or by address and deploy, and that is the whole procedure. Management is your choice. A plant with several engineers that wants per-engineer identities, signed deploys and revocation sets up a site CA and gets the same managed posture as Path A: one certificate authority for the site, every engineer’s IDE holding a certificate it issued, every controller trusting its chain, one revocation list. The difference from Path A is where the authority lives: on a PC the customer controls, not in the cloud. The rest of this section describes the site CA.

Warning. The customer owns the site CA. D6 keeps no copy and no escrow. Back the admin PC’s keystore folder up to an encrypted USB drive and keep it in a safe: losing it loses the site, and every controller would have to be decommissioned and provisioned again. The Security dialog shows the folder’s location in its title bar. {.warning}

16.4.1 Who is the administrator

What makes a PC the site’s administrator is possession of the authority’s private keys in its keystore, protected by a CA passphrase that the IDE asks for on every issue, revoke and unit provisioning and never stores. There is no login or licence involved. Copying the keystore folder to another PC makes that PC an administrator too, so treat the folder as you would the keys to the plant. The administrator’s PC is also an ordinary engineer PC: its own signing certificate comes from the same authority.

16.4.2 Make this keystore a site

On the PC that will hold the authority, open Security and find the Site section. If the keystore has no certificate authority yet, run the local keystore wizard first (below). Then click Make this keystore a site…, enter a Site name and a CA passphrase (at least eight characters, confirmed) and click Create site. The authority’s keys are encrypted with the passphrase and a ledger of issued identities starts. The section heading becomes Site name — this PC is the certificate authority.

16.4.3 Issue engineer identity

Click Issue engineer identity…. Enter the engineer’s e-mail, the Validity (days) (365 by default), an Identity passphrase for the engineer (confirmed) and your CA passphrase, then click Issue… and choose where to save the package. The result is a .whisker-identity file named after the e-mail and the site, holding the site’s chain and current revocation list plus the engineer’s certificate and private key, the key encrypted with the identity passphrase.

The file and the passphrase must travel separately: e-mail or a share for the file, a phone call or in person for the passphrase. The file alone is useless without it. The Engineers table records every identity issued, with fingerprint, expiry and status.

16.4.4 Import site identity on the engineer’s PC

On each engineer’s PC, open Security, and in the Site section click Import site identity…, pick the .whisker-identity file and enter the passphrase. The dialog reports the site, the identity and the revocation list date. A card for the site now shows Your identity, its expiry and CRL from the list’s date. Managed connections and signed deploys use this identity from now on. With more than one site imported, set Site identity in each project’s properties (Security section) to the site the project belongs to; Automatic works when a single site is imported.

16.4.5 Provision unit (site)

The administrator binds a controller to the site:

1. Click Connect and connect to the controller while it shows Standalone (or Awaiting enrolment, on a unit configured that way). A managed controller cannot be re-provisioned; revoke and decommission it first.
2. In the Site section click Provision unit (site)…. The confirmation names the controller’s serial and the site; click Provision and enter the CA passphrase.
3. The IDE issues a device certificate for that serial, sends it with the site’s chain and revocation list, and the controller verifies the serial, the key and the chain before installing. A controller already bound to another authority refuses.
4. The controller restarts into managed mode and the connection drops. Reconnect; the row now says Managed and the connection uses your site identity.

The Units table lists every controller the site has provisioned. A site-issued unit certificate is valid for 365 days and is not renewed automatically — there is no cloud for the unit to ask — so the administrator re-provisions the unit before it expires (the table shows each certificate’s expiry). Engineer and panel identities issued by the site are also 365 days by default; the Issue dialogs accept 1 to 3650.

16.4.6 Panels — identities for WhiskerHMI PCs

A WhiskerHMI panel that connects securely to a site-managed controller must present a certificate issued by the site’s authority; the build of the panel ships only the site’s CA chain and revocation list. The Panels (WhiskerHMI PC identities issued by this site) sub-section, below the Units table, issues one identity per panel PC. Click Issue panel identity…, enter the Panel PC name (the station name becomes HMI-<NAME>), the Validity (days), a Panel passphrase (confirmed) and your CA passphrase, click Issue… and save the .whisker-panel package. The identity is recorded in the ledger and listed in the table with Station, fingerprint, expiry and status. Copy the file to the panel PC and have the operator import it from the panel’s Panel ▸ Import panel identity… menu with the passphrase, sent separately. Revoking a panel works like revoking an engineer (next section): the list is regenerated at once and reaches the controllers with the next engineer’s connect or Push CRL to unit. The full procedure, including the messages the panel shows, is in The WhiskerHMI PC Application.

16.4.7 Revoke, the CRL and the seven-day warning

Click the Revoke icon on an engineer’s row (or a unit’s, or a panel’s) and confirm with the CA passphrase. The certificate goes on the site’s revocation list, which is regenerated at once. A site has no cloud to distribute the list, so it travels with the engineers: every IDE that connects to a managed controller with a site identity compares its list with the controller’s and pushes the newer one before doing anything else. The Output panel logs the result. A revoked engineer can no longer connect, so cannot push; any other engineer’s next visit closes the gap. A controller nobody connects to keeps accepting the revoked certificate until someone does — walk the plant with a laptop after a revocation that matters. Push CRL to unit in the Site section sends the list to the connected controller on demand.

To get the new list to the engineers, the administrator clicks Export site trust package… (CA passphrase required) and distributes the resulting .whisker-site file, which holds only public material. Each engineer imports it with Update trust package…. When an engineer’s copy of the list is more than seven days old the site card and the Output panel warn: your revocation list is N days old — update the site trust package.

Revoking a unit’s identity is followed by provisioning it again with a new one; revoking a panel’s, by issuing a new identity and importing it on the PC if it stays in service.

16.5 Local keystore — Offline edition and bench units

The last section of the Security dialog, Local keystore — Offline edition / bench units, is the IDE’s own certificate authority on this PC. It exists for two reasons: it is what a site CA is built on, and it lets you provision a bench unit by hand for development. Set up local certificates… runs a wizard in five steps — Welcome, Root certificate authority, Intermediate certificate authority, Your signing certificate, Confirm and create. Once it has run, the section shows your local signing certificate, the chain, and a Bench device certificates (issued here) table with Issue bench device cert… (enter the serial) and a Revoke icon per row.

A controller enrolled into a cloud account or provisioned into a site does not trust anything issued here. The local keystore is never the way to reach a customer’s controller, and a WhiskerHMI build for such a controller takes nothing from it: the panel PC imports an identity issued by the account or the site instead (the Panels sub-sections above).

16.6 PIN login at the panel

Operators can be required to log in at the panel with their Whisker.io user and PIN before they can act on the HMI. It is a project setting, not a controller setting:

1. Your organisation enables PIN codes for HMI access in the Whisker.io Control Panel (Account Info). Until then the project’s Cloud PIN Login row explains why it is unavailable.
2. In Project Properties, switch Cloud PIN Login on (the row reads Required at the panel). Set the Session Timeout (s) after which an idle session re-locks and the Offline Fallback behaviour. The Roles at the panel table maps each action (commands, setpoints, acknowledging and deleting alarms) to a role from your account.
3. Deploy. Every deploy mints a fresh device credential for the connected controller’s serial and sends it with the program, which is why the controller must be registered to your account. Without a Whisker.io login the deploy stops with This project requires a PIN at the panel, which needs a Whisker.io login to mint the device credential. Operator login at the panel is a cloud feature: for a controller on Path B, switch Cloud PIN Login off. The project’s Settings PIN still guards the panel’s settings screen.
4. For a WhiskerHMI PC, the credential travels in the PC’s panel identity package instead: with the setting on, Issue panel identity… in the Account section’s Panels sub-section mints a station credential for HMI-<NAME> and puts it in the package the operator imports on that PC (see The WhiskerHMI PC Application). The installer never carries it, because one installer serves every PC and a credential belongs to one. The Panels table marks such rows [PIN], and revoking the panel revokes its credential too. A site-managed PC has no cloud account and therefore no PIN login.

At the panel the operator picks their name from the list of users who hold the login role and have a PIN, then enters the PIN. Five wrong PINs lock that user for five minutes, doubling on each further cycle up to thirty; the panel says This PIN is locked for N minutes. Other users can still log in. Every attempt is audited. A controller that loses its cloud connection accepts, for 24 hours, the users who logged in while it was online. The Lock Button widget and the status-bar lock icon end a session; see HMI Designer for the widgets.

16.7 Signed deploys and what a controller refuses

A managed controller installs a program only from a signed bundle whose signature verifies against its trusted authority. It refuses, leaving the running program untouched, and the Output panel says why:

A standalone controller accepts an unsigned program from any IDE that can reach it. That is the shipping posture, and the right one for a bench and for a site that has chosen not to manage its controllers. It also means anyone who can reach the controller on the network can program it; if that is not acceptable at your site, enrol it (Path A) or provision it into a site CA (Path B).

Note. The first signed deploy to a controller that has an identity but no trust anchor yet binds it to the signer’s authority; the Output panel reports trust anchor installed. A controller enrolled into an account or provisioned into a site already has its anchor, and a standalone controller receives its deploys unsigned, so this only concerns bench units given a certificate from the local keystore.

17 Generating HMI Installers

This chapter applies to projects whose target is WhiskerHMI. The IDE turns such a project into a Windows installer that you hand to the customer; running it puts a complete HMI application on a PC, connected to the Nexus.io Automation Controller the project points at. Deploying to a controller is covered in Connecting, Deploying and Emulating; what the installed application does is covered in The WhiskerHMI PC Application.

17.1 What the installer contains

The generated installer bundles two kinds of content:

• The WhiskerHMI runtime — the same application for every project: the HMI window program, its I/O scanner service (which talks to the controller), the local history database used by Trends and CSV export, and the Microsoft Visual C++ runtime the program needs on a fresh PC.
• Your project’s compiled configuration — produced by Build (F5) for a WhiskerHMI project:

The runtime is identical from one project to the next; the configuration is what makes the installer yours.

The installer does not contain a panel identity. A panel that connects securely to a managed controller needs one identity per PC, issued from the Security dialog’s Panels sub-section and imported on that PC after installation from the panel’s Panel ▸ Import panel identity… menu; the same installer serves every panel PC. An identity already imported survives an update, because the installer adds and replaces files without removing it. The procedure is in The WhiskerHMI PC Application, under Panel identity — connecting to a managed controller.

17.2 Before you generate

• Inno Setup 6 must be installed on the PC running the IDE. It is a free installer builder the IDE drives in the background; the dialog tells you if it cannot find it.
• The WhiskerHMI project must build without errors. For a WhiskerHMI project Build (F5) compiles the configuration files on the PC; it needs no controller connection, and the Run button starts the runtime locally so you can check the screens before packaging.
• The ArenaTCP device in the project’s IO Config must carry the controller address the customer’s PC will use. If the device has Secure connection ticked and the project resolves to a cloud account or a site, the build stages the authority’s chain and revocation list and the Output panel reports Panel identity: this build trusts …; import a panel identity package on each panel PC (Security dialog → Panels). Only a project that resolves to the local keystore (a bench controller) gets a station certificate minted at build time. See The WhiskerHMI PC Application.

17.3 The Generate Installer dialog

With the WhiskerHMI project selected, click Generate Installer on the toolbar (it is only shown for WhiskerHMI projects). The dialog reads Bundle this WhiskerHMI project as a Windows installer and asks for:

All four are required. Click Generate. The dialog switches to Building installer… and streams its log (also echoed to the Output panel): compiling the project, checking requirements, generating the installer script, running the Inno Setup compiler. When it finishes the title reads Installer ready with the path of the file, or Installer failed with the errors. Open folder shows the result in Explorer.

The output file is named WhiskerHMI_Setup_<version>.exe — from the Version field, not the app name — so give each project its own output folder.

Two warnings may appear in the Output panel without stopping the build: that the history database was not found (the installer then ships without Trends support) and that the Visual C++ redistributable was not found (the customer may need to install “Microsoft Visual C++ Redistributable (x64)” by hand on a fresh PC). Both components ship with the IDE; a warning means the IDE installation is incomplete.

17.3.1 If generation fails

The Installer failed page lists the reason. The ones you are likely to meet:

The generator writes a temporary script into the output folder while it runs and removes it when the build succeeds; if it fails, the script is left there and can be sent to support.

17.3.2 Test the installer before hand-off

Run the new installer on your own PC first. The IDE’s Run button shows the screens but not the installed form of the application, so this is the only way to see what the customer will see: the wizard pages, the SmartScreen prompt, the shortcuts, and the application starting with its status bar reading IO Scanner connected and the controller listed under Devices. Uninstall it from Apps & features afterwards if this PC is not meant to keep it.

17.4 What the customer sees

The installer is a standard Windows setup wizard. It needs administrator rights and installs:

• the application under C:\Program Files\WhiskerHMI\<ProjectName>\;
• the configuration files under C:\ProgramData\WhiskerHMI\<ProjectName>\config\;
• a Start Menu shortcut and, if the customer ticks Create a desktop icon, a desktop shortcut;
• a Launch option on the last page.

Nothing is registered as a Windows service. The application starts its I/O scanner and the history database itself each time it is launched and stops them when it closes, so the controller is polled and history is collected only while the application is running on a logged-in desktop. An operator who wants the panel up after a reboot puts the shortcut in the Windows Startup folder, or sets the PC to log in automatically.

The installer is not code-signed. Windows SmartScreen therefore shows an “unknown publisher” warning the first time it runs; the customer chooses More info and Run anyway. If you distribute installers regularly, sign them with your own code-signing certificate after generation.

Deliver the .exe however suits the site — email, download link, USB stick, or the customer’s software distribution system. It has no dependencies beyond a 64-bit Windows PC.

17.5 Changing the configuration on site

The installed application has no settings screen. Everything it knows comes from the configuration folder, and the controller address lives in the ArenaTCP device entry of io_scanner_config.json. There are two ways to change it:

1. Regenerate. Edit the device in the IDE (IO Config → select the device → Properties panel), Build, Generate Installer with a new Version, and run the new installer on the PC. This is the supported path and keeps the project as the record of what is installed.
2. Edit the file. For a quick fix on site, an administrator can edit the ip (and port) of the device in C:\ProgramData\WhiskerHMI\<ProjectName>\config\io_scanner_config.json and restart the application. The next installer run overwrites the file.

Per-user data the application creates on the PC — saved trend presets, the offline login cache and the audit log — lives under the Windows user’s application-data folder and is not touched by either path.

17.6 Updating an installed application

1. Make the changes in the IDE and raise the Version in the Generate Installer dialog.
2. Generate and send the new installer.
3. The customer runs it over the existing installation; the wizard replaces the application and the configuration in place. Shortcuts stay, and per-user data (presets, audit log) is kept.

There is no in-place update mechanism and no need for one: every version is a complete installer.

18 Project Properties Reference

Every project-wide setting lives in the Properties panel: click the project’s header node in the Project Tree and the panel shows Project Settings, split into sections. Which sections appear depends on the project’s target. This chapter lists every section and every field, in the order the panel shows them, for the three targets:

Changes take effect as you type or when you leave the field; there is no Apply button. They are written to disk with the next Save.

18.1 Identity

18.2 HMI Settings

Shown for Nexus.io and WhiskerHMI projects. These settings travel with the project to the panel or the PC application.

Note. When you deploy a project with Cloud PIN Login on, the IDE first obtains a device credential for the connected controller’s serial number from Whisker.io. If that fails the deploy stops and the Output panel says why. This happens on every deploy, so a project for a controller that runs without Whisker.io (an offline site, or the Offline edition) must have Cloud PIN Login switched off. The switch can always be turned off, even when you are not logged in.

18.3 Deployment

18.4 Cloud

Shown in the Cloud edition only.

The account and location a project is published under are chosen in the Cloud Explorer when you use Publish to Cloud, not here. The Application’s link to a cloud application record is on the Application node (see the end of this chapter).

18.5 Device Settings (Classic only)

These fields become the SmartController’s config.json at Build.

18.6 Modbus Server (Nexus.io only)

The Nexus.io controller always runs a Modbus TCP server; these settings control how tags marked Expose in the Tag Database are numbered. See Modbus Server and Map Viewer for the whole picture.

Warning. Renumbering changes the addresses every SCADA system reads from this controller. Export a fresh Modbus map afterwards and update the other side. {.warning}

18.7 CIP tag server (Nexus.io only)

Serves the tags you publish by name over EtherNet/IP, for a Logix-style SCADA driver. See CIP Tag Server.

Warning. CIP has no authentication. Leave the server off on a controller reachable from an untrusted network. {.warning}

18.8 Display (WhiskerHMI only)

18.9 Authentication (WhiskerHMI only)

18.10 Security (WhiskerHMI only)

Individual widgets can be stricter than the table: select a button, switch, input, slider, faceplate or alarm table in the HMI designer and set its Required role.

18.11 Window Layout (WhiskerHMI only)

One row per HMI screen:

See The WhiskerHMI PC Application for how the layout behaves at run time.

18.12 The Application node

Click the Application header at the top of the tree to see Application Properties:

19 Ladder Instruction Reference

One entry per instruction available in the Ladder Logic Editor for a Nexus.io Automation Controller, grouped by purpose. How to place and wire them is in Ladder Logic Editor.

19.1 How to read the tables

• Direction. Rung is the network’s own power flow — every block is driven by it and executes only while the network is true, so it is listed only where it carries a meaning beyond “enable”. In and Out are pins bound to tags in the Properties panel. In/Out is one tag that the block reads and writes back each scan. Setting is chosen in the Properties panel (a dropdown or checkbox), not bound to a tag.
• Type. BOOL, INT, DINT or REAL as in the Tag Database. Number means a DINT or REAL tag, or a numeric literal typed into the field; a literal compiles to a constant and creates no tag. Word means INT or DINT.
• Unwired pins read 0. A blank input is zero, a blank output is simply not written. Where zero has a special meaning — a timeout that disables supervision, a day mask that means every day — the entry says so.
• Instance names. Every block has an instance name that identifies its private state. It is not a tag; to observe a value, bind an output pin to a tag.
• Integer or float. Compute blocks work in integer or floating point according to the tags you bind; SCALE, FILTER and PID always compute in floating point and their outputs must be REAL tags.

19.2 Basic: contacts and coils

19.2.1 NO Contact, NC Contact

A contact reads a BOOL and passes or blocks power. NO passes power while the tag is TRUE; NC while it is FALSE. A contact on a word tag can test a single bit by entering a Bit Index, shown as status_word.3.

NC inverts the test, not the field device: a normally-closed stop button wired to an input reads TRUE while it is not pressed, so test it with an NO contact.

Example: ─┤ pb_start ├──┤/ pb_stop ├──( motor_run )

19.2.2 P Contact, N Contact (edge)

P passes power for exactly one scan when the tag goes FALSE to TRUE; N for one scan when it goes TRUE to FALSE.

A one-scan pulse is shorter than the monitor refresh, so it is invisible in live view; feed it into a counter or a Set coil to see its effect.

Example: ─┤P pb_count ├──[ CTU batch_ctr ] counts button presses.

19.2.3 Coil, Neg Coil

A coil writes the network’s power to a BOOL every scan: TRUE when the network is true, FALSE otherwise. Neg Coil writes the inverse.

Example: ─┤ level_high ├──( fill_valve_cmd )

19.2.4 Set Coil, Reset Coil

Set writes TRUE when the network is true and leaves the tag TRUE when the network goes false. Reset writes FALSE when the network is true and otherwise leaves the tag alone. Pair every Set with a Reset somewhere in the program.

An alarm driven by a Set coil must use a latched alert rule; a non-latched rule clears the alarm the ladder just latched (see Alerts Editor).

Example: ─┤ float_alarm ├──(S alarm_latched ) and, elsewhere, ─┤ pb_reset ├──(R alarm_latched ).

19.2.5 Flash

While the network is true, the output goes TRUE at once and then toggles every RATE milliseconds (50 % duty). When the network goes false the output is FALSE and the phase resets.

Example: ─┤ alarm_active ├──(FL beacon ) with RATE 500 flashes a beacon at 1 Hz.

19.3 Timers

All three timers share the same pins. PT is interpreted in the chosen UNIT; ET is always reported in milliseconds and freezes at PT rather than climbing without limit.

19.3.1 TON — On-Delay Timer

When the network goes true, ET accumulates; Q turns on once ET reaches PT. When the network goes false, ET resets to 0 and Q turns off.

ET is not retained across a false network; for accumulated run time use TONR.

Example: ─┤ call_lead ├──[ TON t_lead_delay PT=5 ] with Q bound to lead_start delays a pump start by five seconds.

19.3.2 TOF — Off-Delay Timer

Q turns on as soon as the network goes true. When the network goes false, Q stays on for PT and then drops.

Example: a cooling fan that runs for 60 s after the motor stops.

19.3.3 TP — Pulse Timer

A rising network starts a pulse: Q is on for exactly PT whatever the network does afterwards. It retriggers only after the pulse completes.

Example: a 2 s blowdown valve pulse on each rising edge of blowdown_req.

19.3.4 TONR — Retentive Timer

Like TON, but the accumulated time is kept when the network goes false, so it totals across many runs. R resets it. The accumulator lives in a tag you nominate, so it can be retained and written from the panel.

Choose Seconds for run-time meters: milliseconds overflow a 32-bit tag in about 25 days, seconds last 68 years. Make the accumulator tag VAR_RETAIN and it survives a power cycle; one tag per block.

Example: ─┤ pump1_running ├──[ TONR pump1_hours ACC=pump1_run_s UNIT=Seconds ].

19.4 Counters

PV is not a ceiling: counting continues past it; PV only decides Q.

19.4.1 CTU — Count Up

CV increments on each rising edge of the network. Q is on while CV ≥ PV. R resets CV to 0.

Example: ─┤P bottle_sensor ├──[ CTU batch PV=24 ] with Q bound to batch_done.

19.4.2 CTD — Count Down

CV decrements on each rising edge. Q is on while CV ≤ 0. LD loads CV with PV. Counting below zero is normal behaviour, not a fault.

Example: doses remaining in a batch, loaded from a recipe tag.

19.4.3 CTUD — Count Up/Down

Both directions on one instance. R (reset to 0) dominates LD (load PV).

Example: vehicles in a bay — entry sensor on CU, exit sensor on CD.

19.5 Edge detection and latches

19.5.1 R_TRIG, F_TRIG

Q is TRUE for one scan when the network rises (R_TRIG) or falls (F_TRIG). The block form of a P or N contact, for when the pulse is needed as a named tag.

Example: ─┤ comm_ok ├──[ F_TRIG comm_lost_trig ] pulses comm_lost when a device drops.

19.5.2 SR — Set-Dominant Latch, RS — Reset-Dominant Latch

Q1 sets on the set input and resets on the reset input. They differ only when both are true at once: SR sets, RS resets.

Use SR where an alarm must be seen even if the reset is stuck on; RS where stop must always beat start.

Example: ─┤ pb_start ├──[ RS motor_latch R1=pb_stop ] with Q1 bound to motor_cmd.

19.6 Compare

19.6.1 EQ, NE, GT, GE, LT, LE — inline comparisons

An inline comparison sits in a segment like a contact and passes power when the test is true. The operator is chosen in the Properties panel.

Example: ─┤ level > 80 ├──( high_alarm ). For start/stop levels prefer HYST, which adds the deadband.

19.6.2 CMP — Compare Block

Compares two values and reports all three relations at once.

Example: IN1 = aho_mode, IN2 = 1 decodes an Off/Hand/Auto word into LT = off, EQ = hand, GT = auto in one network.

19.6.3 MEQ — Masked Equal

Q is TRUE when IN1 and IN2 match in every bit where MASK has a 1; bits where MASK is 0 are ignored. Integer only.

Example: test a drive status word for “ready and not faulted” while ignoring its speed bits.

19.7 Math

19.7.1 MATH operations

MOVE, ADD, SUB, MUL, DIV, MOD, MIN, MAX, ABS, SHL, SHR, ITOF, FTOI, the Bitwise group and the Advanced Math group are all one block with a different operation. Integer or float is chosen from the tags you bind. Unary operations use IN1 only.

SWPB and SWPW repair Modbus values from devices that deliver bytes or words reversed; apply them to the raw tag before scaling. They work on the raw 32 bits, so they also fix a reversed REAL.

Example: [ MATH SQRT IN1=dp_pa OUT=flow_root ] for flow from a differential-pressure transmitter.

19.7.2 LIMIT — Clamp to Range

OUT = IN clamped between MN and MX.

Example: keep a computed drive speed between 0 and 100.

19.7.3 SEL — Select by Boolean

OUT = IN1 when G is TRUE, otherwise IN0. A bit copy, so it works for any type.

Example: day/night setpoint selection.

19.7.4 MUX — Select 1 of 8

OUT = the input selected by K (0–7, clamped). Unwired inputs read 0.

Example: pick one of several recipe setpoints by a mode number.

19.7.5 PACK, UNPACK

PACK assembles up to 16 BOOL inputs into a word (B0 is bit 0). UNPACK splits a word into 16 BOOLs. Only wired bits need binding.

Example: build a Modbus status word from alarm bits; decode a drive’s status word; drive coils from a DRUM’s pattern.

19.8 Process

19.8.1 SCALE — Linear Scaling

Maps an input span onto an output span: OUT = OUT_LO + (IN − IN_LO) × (OUT_HI − OUT_LO) / (IN_HI − IN_LO). Always floating point; OUT must be a REAL tag.

Tick Clamp output to range for any transmitter scaling; without it a failed sensor extrapolates to absurd values that propagate into alarms and control.

Example: 4–20 mA counts 800–4000 to 0–100 % level.

19.8.2 HYST — Deadband Comparator

Q turns on at ON_LEVEL, off at OFF_LEVEL, and holds between them. Direction is inferred: ON above OFF is a rising trip (start on high level), ON below OFF a falling trip (start on low level). Equal levels behave as a plain comparison.

The start/stop block for tanks and wet wells; the deadband is what stops a pump short-cycling.

Example: IN_VAL wet_well_level, ON_LEVEL sp_lead_start, OFF_LEVEL sp_lead_stop, Q call_lead.

19.8.3 TOTAL — Totalizer

Integrates a rate into a running total. A fractional carry is kept internally so a small rate still accumulates rather than rounding to nothing each scan.

Same retained-tag rule as TONR. Pair with SQRT for differential-pressure flow.

Example: RATE flow_gpm, TIMEBASE per minute, accumulator flow_total_gal (VAR_RETAIN).

19.8.4 FILTER — First-Order Lag

Smooths a noisy signal. TC is the time constant in seconds: the output reaches about 63 % of a step in one TC. TC ≤ 0 passes the input through. OUT must be a REAL tag.

Example: filter a 4–20 mA level before it feeds HYST so jitter cannot chatter a pump.

19.8.5 ROC — Rate of Change

Samples the input every PERIOD milliseconds and reports the change per TIMEBASE unit, holding the output between samples. The first sample is suppressed so a startup transient is not reported as a huge rate. OUT must be REAL.

Example: leak and burst detection, rapid-drawdown alarms.

19.8.6 PID — Closed-Loop Controller

A full PID controller with anti-windup and derivative on the process value. Always floating point: every setpoint, value, gain and output must be a REAL tag. The block computes on its own SAMPLE_MS period, so tuning means the same thing whatever the scan rate.

The same number means Ki in one form and Ti in the other; getting the form wrong tunes the loop backwards. Manual-to-auto is bumpless. For on/off equipment use HYST; PID is for modulating control.

Example: SP sp_level, PV level_filtered, CV vfd_speed_cmd with CV_MIN 0 and CV_MAX 100.

19.8.7 ALT — Lead/Lag Pump Alternator

Decides which pumps run; CALL says how many the process wants (0 = none, 1 = lead, 2 = lead and lag, 3 = all). Up to three pumps; leave the third unwired for a duplex station. An unavailable pump is skipped, not counted, so a call for two still starts two.

Use it instead of hand-rolled alternation from counters and latches, which double-starts on a failure or strands a failed pump as lead.

Example: CALL from two staged HYST blocks (call_lead + call_lag via ADD), AVAIL from each pump’s fault and HOA logic, RUN outputs to the MOTOR blocks’ CALL contacts.

19.9 Industrial

19.9.1 DEBOUNCE — Input Filter

Q follows the network only after it has held its new value continuously for PT. Symmetric: it filters both on and off transitions, replacing the two-timer idiom.

Example: a float switch with PT 100 ms.

19.9.2 MOTOR — Motor Device Block

The networks every motor needs in one block: Off/Hand/Auto selection, an overload input, “did the starter pull in”, a start counter and a runtime meter — and a single instance for a faceplate to bind to.

Hand means running, like the middle position of a three-way switch wired to the starter; Auto follows CALL; anything else is Off, so a corrupt mode word can never start a motor. The block controls and annunciates; it does not latch. Faults clear when their cause goes away, and RUN is not withdrawn by a fault — the overload contact breaks the starter circuit, and the motor resumes when someone resets it. Latch a fault with a latched alert on FLT, or with one network on CALL if the output must drop. Starts count rising edges of RUN; runtime accumulates only while RUN_FB is true. Hours = RT ÷ 3600.

Example: CALL from run_p1 (an ALT RUN output), RUN_FB p1_aux, MODE p1_hoa, OL p1_ol, FTS_T 5 seconds, RUN p1_start, FLT p1_fault.

19.9.3 VALVE — Valve Device Block

The sibling of MOTOR: “did the actuator actually travel”. Which valve style you have is declared by which pins you bind.

Spring return: bind only OPEN; dropping the request closes the valve. Dual-acting: bind CLOSE too; if CALL_CLOSE is also bound, Auto closes only on that request and an actuator with neither request holds position, so partial travel is a normal state. Each direction is supervised only if its own limit switch is bound, so a valve with one switch or none never faults on what it cannot observe. FTO and FTC self-clear like MOTOR’s faults.

Example: CALL_OPEN from drum_step_bws (an UNPACK bit), OPEN_FB bws_ols, PT 30 s, OPEN bws_valve_cmd, FTO bws_fto.

19.9.4 FIRSTOUT — First-Out Interlock Annunciator

When an interlock string drops everything stops at once; which permissive went first is the fault. FIRST captures the 1-based index of the first permissive to drop and holds it while any stays down.

Fill the slots contiguously from IN1: the block counts permissives up to the highest bound slot, so a gap reads as a dropped permissive and trips at the gap. Ties within one scan go to the lowest index. It self-clears; keep a record with an alert on FIRST.

Example: IN1 e_stop_ok, IN2 guard_closed, IN3 air_ok, OK line_permissive, FIRST first_out_idx bound to a numeric display.

19.10 Sequencing and time

19.10.1 DRUM — Step Sequencer

A table of up to 64 steps, each with a 16-bit output pattern and a time. STEP is the current row (1-based, 0 = idle); PAT is that row’s pattern — wire it into an UNPACK to drive coils. The step table is edited in the block’s Properties panel.

Each scan while running, in priority order: RST goes idle; a rising JOG advances; in event or both mode a rising EV advances; in time or both mode ET ≥ PT advances. A step time of 0 means no time limit — the step waits for EV or JOG even in time mode. After the last step, Loop wraps to step 1 with DONE pulsed for one scan; otherwise STEP holds with DONE true until RST or IN drops. Make the step tag VAR_RETAIN and the sequence resumes after a power cycle.

Example: a filter backwash — drain (event: low float), air scour 180 s, backwash 600 s, settle 60 s, filter-to-waste 300 s, return — with PAT feeding an UNPACK whose bits drive five VALVE blocks.

19.10.2 RTC — Wall Clock

Reads the controller’s local time once per scan, so every block in a scan sees the same instant. Outputs hold while the network is false.

VALID is true only when the year is plausible and the clock is synchronised — from the network or a battery-backed clock the controller has been told to trust. Alarm on VALID: a schedule must never run on an unset clock.

Example: TOD bound to clock_tod for HMI display and day-of-week gating in plain ladder.

19.10.3 SCHED — Time-of-Day Window

Q is true while the local time is inside the ON_TOD to OFF_TOD window on an enabled day. It is derived, not edge-triggered: a power-up at 03:00 inside a 22:00–06:00 window gives Q at once.

ON later than OFF is an overnight window (22:00 to 06:00 is 1320 to 360) and the day test applies to the start day. SCHED needs a trusted clock: while RTC’s VALID is false, Q is 0 and NEXT_MIN is −1. Bind ON_TOD, OFF_TOD and DOW_MASK to VAR_RETAIN tags and operators edit the schedule with numeric inputs on the panel; several windows a day are several SCHED blocks in parallel.

Example: Q backwash_window as a permissive into a DRUM’s IN; an off-peak fill window; a chemical-delivery lockout.

19.11 Program flow

19.11.1 PYFB — Python Function

Calls a @pyfb function in the project’s app.py on each rising edge of the network and delivers the return value to OUT. The Python runtime does the work outside the scan, so a slow or missing function can never stall the program.

On any error OUT keeps its last good value. A round trip is about 20 ms, so use ladder math for per-scan calculations. The Python side is in Python on the Controller.

Example: function calc_dose, A1 flow_gpm, A2 sp_target_ppm, OUT dose_rate (REAL), DONE dose_valid.

19.11.2 CALL, RET

CALL runs the named function when its network is true and the caller continues with its next network afterwards. RET, when its network is true, returns from a function to its caller, or ends the current scan of a task. Neither has pins or outputs; the function shares the project’s tags with its caller. A function cannot call itself; see Function Blocks, Faceplates and Tasks.

19.12 Common traps

• An instance name is not a tag. Bind an output pin to a tag to observe a value; an output with no tag shows -- and looks like a dead block.
• Unwired inputs read 0. For MOTOR’s FTS_T, VALVE’s PT and DEBOUNCE’s PT that means “supervision disabled”, never “trip immediately”.
• Accumulators live in tags. TONR, TOTAL, MOTOR’s counters and DRUM’s step keep their value in the tag you nominate; make it VAR_RETAIN, and use one tag per block.
• Float outputs need REAL tags. SCALE, FILTER, ROC and PID write floating-point bits; an INT or DINT tag there holds garbage.
• One-scan pulses are invisible in monitoring. Feed P/N contacts and R_TRIG/F_TRIG into a counter or latch to see them.
• Set-coil alarms need a latched alert rule.
• Divide by zero returns 0 rather than faulting.
• Tick Clamp on SCALE for every transmitter.

20 Historian and Trends

A Nexus.io Automation Controller keeps its own history of the tags you choose, on its internal storage, for a configurable number of days. The Trend Chart widget on the panel draws that history. A WhiskerHMI PC application keeps a second history on the PC for the tags it reads, and offers a Trends dialog and CSV export. This chapter explains what is recorded, where, how to turn it on, and how to look at it.

20.1 Two historians

The two are independent: the PC does not read the controller’s history, and the panel cannot export CSV. If you need a file, the PC application is where to export it.

20.2 Recording history on the controller

20.2.1 Choosing the tags

Open the Tag Database. The Hist column shows a timeline icon per tag; click it to toggle. The tooltip reads Kept in the controller history (tap to stop) or Not historized (tap to keep 60-day history). Tags used by a Trend Chart element on any screen are recorded whether or not Hist is ticked, so a trend never comes up empty.

In the Cloud edition a selected tag’s Properties panel also shows a History (on-controller, 60-day) switch and, when it is on, History Deadband (0 = every change). Leave the deadband at 0 for setpoints and BOOL tags; set it to the noise band of an analog value (for example 0.5 for a level in percent) to keep the stored history small.

20.2.2 Retention

In Project Properties, under HMI Settings, set History Retention (days). The default is 60. Press Enter to commit the value. The field explains itself: tags with History checked in the tag table, plus any tag on a Trend Chart, are kept on the controller this long.

20.2.3 What is stored

The historian reads the selected tags once a second and keeps a sample when the value has moved by more than the deadband since the last stored sample, or when 60 seconds have passed without one (a heartbeat, so a flat line still has points). BOOL tags are stored as 0 and 1. Alongside the raw samples it keeps a per-minute minimum, maximum and average for every tag.

Raw samples are kept for 7 days; the per-minute summaries are kept for the full retention period. Old data is purged every hour, and a size guard trims the oldest raw days early if the database grows past its limit. Because summaries are only one row per tag per minute, a plant with a few dozen historized tags uses well under a gigabyte for 60 days. Retained history survives a program update and a power cycle; at most the last second of samples is lost on power failure.

History is configured on the controller by the same deploy as the program: connect and press Build (F5); the IDE compiles and downloads the program together with the historian configuration. Changing the tag set or retention takes effect on the next deploy; tags that stay selected keep their existing history.

20.3 The Trend Chart widget

Place a Trend Chart (Indicators group) on a screen and set its properties:

On the panel the chart shows a legend with each tag’s latest value and a set of range chips — 1h, 8h, 24h, 7d, 60d — that the operator taps to change the window; the widget’s Time Range is only the starting point. Long windows are drawn from the per-minute summaries, short ones from raw samples. If the chart reads No history yet, the tag has just been added and the first samples have not arrived; No tags configured means the Tags list is empty.

In the designer and in HMI Preview the chart draws sample curves rather than data.

20.4 History on the WhiskerHMI PC

The PC application’s I/O scanner writes every tag it reads, once a second, into a local time-series database that the installer ships with the application. Retention comes from the WhiskerHMI project’s History Retention (days) (Project Properties, under the Authentication group; default 60) and is applied each time the scanner starts. There is no per-tag selection or deadband on the PC side. See The WhiskerHMI PC Application for installation and login; the rest of this section describes the dialogs.

20.4.1 The Trends dialog

Click Trends in the status bar. The dialog has a searchable tag list on the left (Search tags…) and the plot on the right:

• Tick up to six tags; the counter reads N / 6 selected. Every tag the project reads is offered.
• Range chips 1 h, 8 h, 24 h, 7 d, 30 d, 60 d set the window; the plot refreshes every 2 s (every 10 s for windows over a day). Long windows are averaged into about 300 points.
• Saved trends… lists presets; Save as preset stores the current tags and range under a name you enter (Preset name), and Delete preset removes one. Presets are kept per Windows user and per project on that PC.
• Export CSV opens the export dialog pre-filled with the plotted tags and range.

The chart has no zoom or cursor; choose a shorter range to see detail.

20.4.2 Exporting history to CSV

Click Export in the status bar, or Export CSV in the Trends dialog. The Export History to CSV dialog asks for:

1. The tags — any number, with Select all and None.
2. Time range — chips Last 1 h to Last 60 d, or explicit Start and End date and time pickers.
3. Resolution — Raw samples, 1 second, 10 seconds, 1 minute (default), 15 minutes or 1 hour. Coarser resolutions average the samples in each interval.

The dialog estimates the row count (About N rows × M tags). Click Export… and choose a file; the suggested name is whiskerhmi_export_<date>_<time>.csv. The file has a timestamp column in local time (YYYY-MM-DD HH:MM:SS) followed by one column per tag, headed with the tag name and its units when known. An empty range still writes the header row and tells you so.

With operator login enabled, opening Trends needs the View screens permission, saving presets needs Save trend presets, and exporting needs Export history; every export is written to the audit log.

20.5 Alert history

Alarm events are not part of the tag historian. The controller keeps its own list of the last 1000 FIRED and CLEARED events, shown by the Alert Table widget on the panel and in the PC application; it has no time-based retention and no CSV export. See Alerts Editor.

21 The WhiskerHMI PC Application

WhiskerHMI is the Windows application the IDE generates from a WhiskerHMI project: the same screens you design for a Nexus.io Automation Controller, running in one or more windows on a PC and reading the controller live. This chapter describes it as an installer and an operator meet it — starting it, connecting, windows, the status bar, login, trends and the audit log. Building the project and producing the installer is covered in Generating HMI Installers; designing the screens in HMI Designer.

21.1 Starting the application

Launch it from the Start Menu or desktop shortcut created by the installer. The application starts its two helpers if they are not already running — the I/O scanner, which holds the connection to the controller, and the local history database — then opens the main window, plus any windows whose role is Auto Open. Closing the main window closes every other window and stops the helpers.

The application has no settings screen; its configuration is the compiled project (see Generating HMI Installers for where the files live and how to change the controller address).

21.2 Connecting to the controller

The I/O scanner connects to the controller named by the project’s ArenaTCP device and keeps its tags in step. The status bar shows the state at its left end:

When the scanner is up but a controller is not, a dark red banner appears above the status bar: <device> (<address>:<port>) — not connected, or a count when several devices are down. It disappears when the connection returns; the check runs every 3 seconds. While a controller is unreachable, its tags read as zero and writes are dropped.

21.3 Panel identity — connecting to a managed controller

If the project’s ArenaTCP device has Secure connection (NexusSec — mutual TLS) ticked, the scanner opens a mutually authenticated TLS connection: it presents this PC’s own certificate — its panel identity, issued to the station name HMI-<PC name> — and checks the controller’s certificate against the CA chain shipped in the configuration. What the panel PC needs depends on the controller’s posture (see Security, Provisioning and Enrolment):

21.3.1 What the build carries

When a WhiskerHMI project is built for a managed controller, the IDE decides the authority the same way it does for a deploy: the Whisker.io account you are logged in to, otherwise the project’s Site identity (Project Properties). For either, the security folder of the compiled configuration holds only that authority’s CA chain and revocation list, plus a marker file PANEL_IDENTITY_REQUIRED.txt naming the authority. Nothing is issued from the local keystore. The Output panel says so:

Panel identity: this build trusts cloud account N; import a panel identity package on each panel PC (Security dialog → Panels)

(or site for a site-managed project). A build without a revocation list on this PC adds a warning to refresh it in the Security dialog. Only a project that resolves to the local keystore still gets a station certificate minted at build time.

21.3.2 Issuing a panel identity

The engineer issues one identity per panel PC, in the IDE:

1. Open Security (the toolbar shield). For a cloud project, scroll to the Account section’s Panels (WhiskerHMI PC identities issued by this account); for a site-managed project, to the Site section’s Panels (WhiskerHMI PC identities issued by this site).
2. Click Issue panel identity…. The dialog is titled Issue panel identity — account N or — and asks for:
   • Panel PC name — the Windows computer name of the panel PC (the hint reads e.g. CONTROL-ROOM-PC-1). Below it the dialog shows the resulting Station name: HMI- followed by the name in upper case, with anything other than letters, digits and hyphens replaced by a hyphen. The name is a label for your records; the importer does not check it against the PC.
   • Validity (days) — 365 by default, 1 to 3650. A cloud account issues in whole years and rounds the days up.
   • Panel passphrase (for the package) and Confirm panel passphrase — at least eight characters. It protects the private key inside the package; the operator types it once, at import.
   • CA passphrase (this PC) — site path only; the site’s CA keys are encrypted with it.
3. Click Issue… and choose where to save the package. The suggested name is HMI-<NAME>.<account or site id>.whisker-panel.

The Output panel confirms Issued panel identity HMI- (), valid to , the package path, and the instruction to copy the file to the panel PC and tell the operator the passphrase separately. The package holds the panel’s certificate and private key (encrypted with the panel passphrase), the authority’s CA chain and its current revocation list. Send the file and the passphrase by different routes, as you would an engineer identity.

PIN login credential. When the project has Cloud PIN Login switched on (Project Properties) and the identity is issued from a cloud account, the same action also mints the PC’s PIN-login credential for HMI-<NAME> and adds it to the package; the confirmation then ends with a PIN-login credential for this PC. This is the PC’s counterpart of the device credential a controller receives on every deploy, and it is what lets the panel register PIN logins and upload its audit log. It is never part of the installer, which is one file for every PC. The project must have been set up on the account you are logged in to; otherwise the IDE stops with Wrong account for PIN login. A site-managed project has no account, so a site-issued package carries no credential and its panel offers email-and-password login only.

The Panels table records every identity issued: Station, fingerprint, expiry and status, with a Revoke icon per row; a station whose package carried a PIN-login credential is marked [PIN]. On the cloud path the table lists identities this IDE issued; on the site path it is the site ledger’s panel rows.

21.3.3 Importing the identity on the panel PC

1. Install the WhiskerHMI application (see Generating HMI Installers) and start it. Until the identity is imported the dark red banner reports the controller as not connected.
2. Copy the .whisker-panel file to the PC (any folder; it is read once).
3. In the main window’s status bar click Panel and choose Import panel identity…. The Panel menu is on the main window only, because that window owns the I/O scanner.
4. Pick the file. The Import panel identity dialog names the file and asks: Enter the passphrase the engineer set when this package was issued. Type it and click Import.
5. The I/O scanner checks the package before installing anything: the passphrase decrypts the key; the key matches the certificate; the certificate is within its validity dates and chains to the package’s CA chain; and, when the configuration already carries a CA chain, that chain and the package’s have the same root — the panel must be built for the authority that issued the identity. It then writes the certificate, the key (readable by the current Windows user only), the chain and the revocation list into the configuration’s security folder and removes the PANEL_IDENTITY_REQUIRED.txt marker. A package that carries a PIN-login credential has it checked too — it must name this station — and installed as hmi_auth.json in the configuration folder, readable by the current Windows user only.
6. The result dialog reads Panel identity installed, with Station, Fingerprint, Valid until and PIN login (credential installed or not in this package), and the note The IO scanner was restarted and will use this identity. (or, if the restart failed, Restart the IO scanner (or this panel) to use this identity.). When a credential was installed the note adds Restart this panel to enable PIN login with the new credential. — the application reads the credential when it starts. On failure the dialog reads Import failed with the scanner’s reason (below). Within a few seconds the banner clears and the controller is listed under Devices.

The import is written to the audit log as Imported panel identity with the station name and fingerprint as the target; the passphrase is never recorded. The identity stays on the PC across application updates and restarts; a newer installer adds and replaces configuration files but does not remove it.

21.3.4 Revoking a panel

A panel PC that is retired, re-imaged or no longer trusted has its identity revoked in the IDE: in the same Panels sub-section click the Revoke icon on its row and confirm (site path: enter the CA passphrase). The certificate goes on the authority’s revocation list and the row’s status shows Revoked. Controllers refuse the panel once they hold that list:

• Cloud account — enrolled controllers fetch the account’s list every fifteen minutes, so the panel is refused within fifteen minutes.
• Site CA — the list is regenerated at once and travels with the engineers: the next time any engineer’s IDE connects to a managed controller it pushes the newer list (or use Push CRL to unit). A controller nobody connects to keeps accepting the panel until then.

On the cloud path, revoking a panel marked [PIN] also revokes its PIN-login credential, so the PC can no longer register PIN logins or upload audit events; the confirmation says so. If that second step fails the message tells you to revoke the credential in the Whisker.io Control Panel.

A revoked panel cannot be reinstated. If the PC stays in service, issue a new identity and import it; the new one replaces the old on the PC.

21.3.5 Messages and what they mean

The scanner reports its connection error in its own output and the device is shown as not connected in the banner; the panel does not display the error text itself.

21.4 Windows and the layout editor

Each screen of a WhiskerHMI project can be a window. In the IDE, select the project node and open the Window Layout section of its properties (it appears only for WhiskerHMI projects). The table has one row per screen:

Windows without Fill open centred on their monitor at the project’s display size and can be moved and resized like any Windows window; positions are not remembered between launches. The window title is the project name, or <project> — <screen> for secondary windows.

At runtime the Windows item in the status bar lists every Popup and Auto Open screen, with its monitor number when one is assigned; click one to open it. A window that is already open is not opened twice. Close a secondary window with its title-bar close button.

Each window runs as its own process, and an operator login belongs to the window it was made in: a popup opened from a logged-in main window asks for its own login when a gated control is used.

21.5 The status bar

Left to right:

• the connection status and device list (above);
• when logged in, the operator’s name and Log out; otherwise Log in (when login is enabled);
• Audit — opens the audit log (requires the Audit log and settings permission);
• Panel — this PC’s own settings; today its one item is Import panel identity… (main window only; see Panel identity — connecting to a managed controller above);
• Windows — the menu of openable windows;
• Trends and Export — the trend and CSV-export dialogs, present when the project ships history support;
• the version label.

There is no alarm banner: alerts are shown where the designer placed an Alert Table element (see Alerts Editor). On the PC the table is a live viewer of the controller’s alert history; acknowledge, clear and reset made here do not reach the controller and are undone at the next refresh, so reset latched alerts at the panel or through a ladder-driven push button.

21.6 Trends and CSV export

Trends plots up to six tags over 1 hour to 60 days from the PC’s local history and can save presets; Export writes any tags and time range to a CSV file at a chosen resolution. Both are described in Historian and Trends. History on the PC is recorded for every tag the project reads and kept for the project’s History Retention (days).

21.7 Operator login and roles

Login is optional and needs the Cloud edition of the IDE and a Whisker.io account: operators are the account’s users, and roles are the account’s roles. Configure it in the WhiskerHMI project’s properties:

• Security — the switch that turns gating on, followed by a table of actions and the role each requires: View screens, Buttons and switches, Setpoints and sliders, Acknowledge alarms, Clear alarms, Save trend presets, Export history, Open windows, Audit log and settings. Each can be No login needed (viewing and acknowledging only), Any logged-in user or a named role. Refresh roles from Whisker.io reloads the role list.
• Individual buttons, switches, inputs, sliders, faceplates and Alert Tables can override their action’s role with their own Required role (Properties panel, Security section).
• PIN login at the console — lets operators log in by picking their name and entering their Whisker.io PIN instead of typing an email and password.
• Session Timeout (min) — idle minutes before the operator is logged out (default 480). Any touch or click restarts the timer.
• Offline grace (hours) — how long a user who has logged in on this PC can keep logging in while Whisker.io is unreachable (default 24).

With the switch off, every control works for everyone; changes are still written to the audit log with no operator name.

21.7.1 What the operator sees

When View screens requires a login, the Operator login panel covers the window at start-up; otherwise the operator works unauthenticated and is asked to log in when they touch a gated control. The panel offers Email & password (with a verification Code step when the account uses two-factor authentication) and, when enabled, PIN: a Who are you? picker of the account’s users and a keypad; the PIN is submitted automatically at its full length. A Continue as viewer button appears when viewing needs no login.

A wrong entry is answered with Not recognised and the number of tries left. After five wrong PINs that user is locked for five minutes, doubling on each further round up to 30 minutes; the message says so and other users can still log in. PIN login also requires the PC’s own PIN-login credential, which arrives inside its panel identity package when the project has Cloud PIN Login on (see Panel identity — connecting to a managed controller); without it the panel says PIN login not provisioned on this PC and email-and-password login remains available.

Using a control the operator’s role does not allow shows a short dark-red message — Log in to setpoints and sliders or Requires Supervisor — and nothing is written. Log out in the status bar, a Lock Button on a screen, or the session timeout ends the session.

When Whisker.io cannot be reached, users who have logged in on this PC within the grace period can still log in from a local cache (the PIN picker is captioned Offline — recent users only). After the grace period expires the operator is told so and must wait for the connection to return.

21.8 The audit log

Every change of state on the PC is recorded locally: logins, failed logins, logouts, locks and timeouts; each button, switch, setpoint and slider write with the tag, the old and new value, the element and the screen; alarm acknowledgements and clears; preset saves; exports; and every denied action with its reason. Viewing screens and opening windows are not logged. Records are chained with a hash so that a removed or altered line is detectable, and are kept for 400 days in monthly files.

Click Audit in the status bar (requires Audit log and settings). The Audit Log dialog shows When, Who (with the login method), Action, Target, Change (old → new) and Result (OK, Denied or Failed), newest first. Filter by range (24 h, 7 d, 30 d, All), User, action group (Sessions, HMI changes, Alarms or a single action), Target and result. Export CSV writes the filtered rows to whiskerhmi_audit_<date>_<time>.csv with the full record including the chain hash.