ProXR Control User Guide

01Overview

ProXR Control turns an NCD ProXR relay controller into an operator screen on the gateway. You register each board once, then assemble a panel out of cards: command buttons, relay indicators, relay grids, analog readouts, trend charts and controller status. The app polls every board it owns, so the panel shows the state the controller reports rather than the state that was last commanded.

What it does not do

• It reads no sensor telemetry. ProXR boards are not sensors, so nothing the app does appears on the gateway’s Sensors, Monitor or Reports pages.
• It cannot authorize its own hardware. Registering a board’s radio is an operator action on the gateway, covered in First-Time Setup.
• It does not watch the inter-app bus. It publishes its own state and offers commands, but you decide on the gateway’s Automations page what connects to what.

02Requirements

Two things have to be true before the app can be useful: the gateway has to be new enough, and each ProXR board needs a DigiMesh radio the gateway is allowed to talk to.

Gateway

Per ProXR board

03Installing

ProXR Control installs like any other Atrium app, from the App Center or from a package file. Nothing about the install needs a ProXR board present.

From the App Center

1. 1
   Open Apps

   Click Apps in the gateway’s top navigation.
2. 2
   Click Browse App Center

   The catalog lists every app available to this gateway. Apps already installed are marked INSTALLED with their version.
3. 3
   Choose ProXR Control

   The tile shows the icon PX and the subtitle Relay Control. Install it, and the gateway restarts its API and ingest services when the install finishes.

From a package file

If NCD sent you a .tar.gz package directly, click Install App on the Apps page and choose the file. Install App opens your browser’s file chooser; there is no upload dialog of its own.

Where the app appears afterwards

The installed app gets a card on the Apps page with Open, Update and Uninstall. Open takes you to /apps/proxr-control, which is where the rest of this guide happens. The app’s own screens have real addresses, so /apps/proxr-control/controllers and /apps/proxr-control/schedules can be bookmarked.

04First-Time Setup

Four steps get you from a freshly installed app to a board that answers. The first two happen outside the app — on the gateway and on the radio — and they are where almost every commissioning problem comes from.

1. Register the radio as a DigiMesh peer

An app can never grant itself permission to talk to radio hardware. Registering a peer is the authorization, and only an operator can do it. Until the board’s radio is registered, ProXR Control shows the controller as not connected and names the address you need to add.

1. 1
   Open Settings > Devices

   Scroll past the sensor whitelist and blacklist to the DigiMesh Peers panel at the bottom of the page.
2. 2
   Click + Add Peer

   Enter the DigiMesh Address — the 64-bit MAC of the radio module inside the controller, not the controller’s own part number. A Name and Notes are optional but worth filling in; the name is what the app offers you in its address dropdown.
3. 3
   Click Register Peer

   The peer appears in the table with App Access: Allowed. Registered peers are not sensors and never show up in telemetry or offline reports.

2. Set the radio mode and destination

The radio in the ProXR board has to pass bytes through untouched, and it has to send the board’s replies back to this gateway. Two settings decide both.

Setting	Value	What goes wrong otherwise
AP (API enable)	0 — transparent mode	In API mode the controller receives framed bytes it cannot parse and never answers. The gateway still reports the transmit as delivered, so the failure looks like a dead board.
DH / DL (destination)	This gateway’s radio address, or the broadcast address	The board answers, but the reply goes somewhere else. The app sees timeouts on every read.

The app repeats this list on its own Settings page, under Wiring a ProXR board to this gateway, so an operator standing at the panel does not need this document.

3. Add the controller in the app

Open Controllers in the app’s sidebar and click Add controller. Only three fields matter to get a board answering: the name, the address and the relay count. Everything else has a sensible default and can be changed later.

The address accepts the 64-bit MAC with or without colons — 0013a200423cfef4 and 00:13:a2:00:42:3c:fe:f4 are the same board. The relay count sets how many banks get polled: relays are grouped in eights, and the dialog tells you how many banks that works out to as you type.

Every field on this dialog is documented in Controller settings.

4. Prove the link before you build anything

Open the controller and press Read now. A board that is wired, powered, authorized and in transparent mode answers within a few hundred milliseconds, and the header chip turns to online.

1. 1
   Press Read now

   This polls the board immediately instead of waiting for the next poll interval. Response time in the Link panel fills in, and Last successful read becomes just now.
2. 2
   Press Identify board

   The controller reports which command sets it implements. The Board features panel then lists them, with the raw identification bytes above. This is the fastest way to confirm you are talking to the board you think you are.
3. 3
   Check Recent traffic

   Outbound frames with no reply mean the board is not answering. Frames in both directions mean the link is good and any remaining problem is a configuration one.

With the board answering, go to Creating a panel. If it is not answering, work through Troubleshooting — the symptom table is ordered by how often each cause actually turns out to be the problem.

05Overview Screen

The app’s landing screen answers one question at a glance: is everything talking, and what is currently on. It is also the setup path when nothing is configured yet.

The header

The count beside the title reads online / total — how many controllers answered their most recent poll out of how many are configured. The same figure appears at the bottom of the sidebar as a bar, along with the installed app version.

One card per controller

Each card names the controller, shows its state chip, draws a lamp for every relay on the board, and reports how many are energized. Clicking the controller’s name opens its controller page.

Below the lamps, the card reports how many relays are on out of the total, how many analog inputs are reading, and the board’s address. If the last exchange failed, the error and its age replace the “Last reply” line, in red.

Control panels

The card at the bottom lists every panel with its card count. With no panels yet it explains how to create one and points out that the app can generate a starter set for you.

06Control Panels

A panel is the screen an operator uses day to day. You build it from cards, arrange them on a grid, and from then on nobody needs to know anything about ProXR command codes.

Creating a panel

1. 1
   Click the plus beside PANELS in the sidebar

   The New control panel dialog opens.
2. 2
   Name the panel

   Name it after the place or the process an operator thinks in — Utility room, Line 3, Pump house. The name is the sidebar entry.
3. 3
   Choose a default controller

   Cards inherit this controller unless you override them one by one. Leave it on None — choose per card only if the panel really does drive more than one board.
4. 4
   Click Create panel

   The app opens the new, empty panel.

Generate from a controller

Generate from a controller is the fastest way to something usable. It adds a fixed starter set for the chosen board:

• A Controller status card titled with the board’s name.
• A Relay grid three columns wide, titled Relays.
• An All relays on button, set to ask for confirmation.
• An All relays off button, styled destructive and set to ask for confirmation.
• One Analog input card per configured A/D channel, if the board has analog inputs enabled.

Generating onto a panel that already has cards fills the gaps rather than pushing anything around, so you can generate a starter set and then keep adding to it.

Adding cards

In editing mode, Add card opens a form that is generated from the installed app’s own catalogs — so it always offers exactly what this version supports, and it can never let you save something the board would reject.

Field	What it does	Default
Card type	Which of the nine card types this is. Changing it resets the parameters and appearance options below to that type’s defaults. A one-line description of the selected type appears underneath.	Command button
Title	The card’s heading, or the button’s label. Left empty, the card falls back to a generated title — the command’s name for a button, Relay N for a relay card, Bank N for a bank card, Input N for an analog card, the controller’s name for a status card.	Empty
Controller	Which board this card drives. Left on the panel default, it follows the panel. Absent for the Section heading card, which drives nothing.	Panel default
Command	Command buttons only. A dropdown of all 42 ProXR commands, grouped as Relays, Banks, Timers, Flashers, Read, Refresh, Configuration and Advanced. Commands with a caveat show it under the dropdown — for example that Toggle relay needs ProXR firmware 3.9 or later.	Turn relay on
Sequence	Sequence buttons only. Which saved sequence to run. Only sequences belonging to the selected controller are offered.	None
Command parameters	Whatever the chosen command or card type needs — relay number, bank, pattern, timer index, hours/minutes/seconds, channel, flasher. Each field shows its permitted range underneath and is validated on save.	Per command
Appearance	The card type’s display options: button style, click or momentary behavior, confirmation, meter visibility, relay numbering, chart time span, on/off labels.	Per card type

Editing and removing a card

In editing mode each card carries two icon buttons: a pencil that reopens the same form, and a red cross that removes the card after a confirmation. Removing a card affects the panel only — the controller and its relays are untouched. The edit form is identical to the add form except that it reminds you size and position are set on the panel itself.

Buttons that switch real loads

Three appearance options exist for exactly this problem:

Option	Behavior	Use it for
Ask for confirmation first	Clicking opens a dialog naming the command and the controller. Nothing is transmitted until Send command is clicked.	Anything that starts or stops equipment, and every all-banks command.
Momentary (on while held)	Sends the command on press and the opposite command on release — including when the pointer leaves the button. The card shows Hold to keep on.	Jog controls, gate and door opens, anything that must stop when the operator lets go.
Destructive (red)	Colour only, but it also makes the confirmation dialog read as a destructive action.	All-off and all-banks buttons.

Card types

Nine card types. The Default size column is the footprint a new card takes on the grid, in columns by rows; you can resize any of them afterwards.

Card type	Shows	Options	Default size
Command button	A button that sends one ProXR command. Under the label it summarises what the command targets — the relay, the bank, the timer and duration — so two buttons on the same command are still tellable apart.	Button style (Neutral, Primary orange, Outline teal, Destructive red); Behavior (Click to send once, Momentary); Ask for confirmation first	1 × 1
Sequence button	A button that runs a saved sequence, with its step count underneath. Reads Sequence was deleted and goes inert if the sequence is gone.	Button style; Ask for confirmation first	1 × 1
Relay state card	One relay as a large lamp plus a word. Shows a dash and an unlit lamp until the relay has actually been read.	Label when on (default On); Label when off (default Off)	1 × 1
Relay grid	Every relay on the board as a lamp. Optionally clickable to toggle. A relay that has never been read is drawn dimmed, not off.	Click a relay to toggle it (default on); Show relay numbers (default on)	2 × 2
Bank indicator	The eight relays of one bank as a row of lamps. Read-only.	Bank (1 – 32); Show relay numbers	2 × 1
Analog input card	One A/D input as a large number, with a level meter and the raw count beneath it.	Analog input (1 – 8); Show a level meter (default on)	1 × 1
Analog input chart	A trend of one A/D input drawn from logged samples. Grows to whatever height you give the card.	Analog input; Time span in hours (1 – 720, default 24)	2 × 2
Controller status	Link chip, radio round-trip time, how many relays are energized out of the total, and how long ago the last successful read was. Shows the last error when the board is not answering.	None	1 × 1
Section heading	Plain text for grouping cards. Drives nothing and has no controller.	Text	4 × 1

Clicking a relay in a clickable grid sends turn relay on or turn relay off by number — never toggle — so the grid works on ProXR firmware older than 3.9, and so a lost reply can never invert the load.

Arranging the grid

A panel is a grid of fixed cells — 1 to 6 columns wide, up to 40 rows deep. Cards occupy whole cells, and the app never rearranges your work: a gap you leave stays a gap.

Action	How	Notes
Move a card	Drag it onto any cell, including an empty cell on a row below the last card. Or use the four arrows on its bar to nudge it one cell at a time.	The arrows are the only way to move a card when the cell you want is behind another card, and the only way that works on a touchscreen or with a keyboard.
Swap two cards	Drop a card squarely onto another card of exactly the same size.	This is the one collision the app assumes you meant. Any other overlap is refused with No room there — move the card in the way first, or make this one smaller.
Resize a card	The second group on the bar: narrower, wider, shorter, taller. The readout between them shows the current size.	Maximum height is 6 rows; maximum width is the panel’s column count. Growing into an occupied cell is refused with Another card is in the way, and growing past the right edge with That would run off the right edge of the panel.
Finish	Click Done.	Every move is saved as you make it — there is no separate save step, and no way to discard a layout change other than moving the card back.

Panel settings

Panel settings appears in the header while editing. It holds the three panel-wide properties, and the only route to deleting the panel.

Field	Effect	Default
Panel name	The sidebar entry and the page title.	As created
Default controller	Which board cards follow when they have no controller of their own. Changing it re-points every card that was inheriting.	As created
Columns	1 to 6. More columns means finer placement. Narrowing a panel repacks any card that no longer fits, which is the one case where the app moves your cards for you.	4
Delete panel	Deletes the panel and all of its cards after a confirmation. Controllers, relays and their state are untouched.	—

On a phone or a narrow tablet, cards stack in one column and ignore their grid cells entirely, so a wide panel is still usable in the field — just in a different order.

07Controllers

One controller is one ProXR board behind one DigiMesh radio. This is where you commission a board, name its relays, scale its analog inputs, and drive it directly without building a panel first.

The controller list

Column	Contents
Name	A link to the controller page, with the controller’s notes underneath if any were entered.
Address	The radio’s 64-bit MAC, normalized to colon-separated lower case however you typed it.
Relays	The configured relay count, and how many banks of eight that comes to.
Inputs	Channels and resolution, for example 4 × 10-bit. A dash means analog inputs are switched off for this board.
Status	One of online, no reply, not connected, not registered, peer disabled or disabled. The last three tell you the problem is on the gateway rather than on the wire.
Last read	How long ago the board last answered. Hover for the exact timestamp, in the gateway’s display timezone.

Relays

The controller page is the direct-control screen. The header carries the board’s state chip and three buttons — Read now polls immediately, Identify board asks the controller which command sets it implements, and Edit reopens the settings dialog.

Bank controls

The toolbar above the lamps selects a bank and applies one of four commands to it. The bank selector lists only the banks the configured relay count actually covers.

Button	Effect on the selected bank
All on	Energizes all eight relays in the bank.
All off	De-energizes all eight.
Invert	Every relay in the bank takes the opposite state.
Reverse	Reverses the pattern end to end — relay 1 takes relay 8’s state, 2 takes 7’s, and so on.

The relay table

Column	Contents
#	The relay number, counted across the whole board. Relay 9 is the first relay of bank 2.
Name	An editable field. Type a name and press Enter, or click away, and it is saved. This name is used on this page and in the values the app publishes to Automations. Left empty it falls back to Relay N.
Bank	The same relay expressed as bank.relay, which is how the ProXR protocol addresses it. Relay 11 reads 2.3.
State	on, off, or unknown if the relay has not been read since the service started.
Buttons	On, Off, Toggle and a timed button labelled with the current duration. All four are disabled while the controller is not connected.

Timed commands

The On for field above the table sets a duration in seconds, from 1 to 59. The button on each row then energizes that relay for that long using one of the controller’s own duration timers, so the relay switches off by itself — even if this gateway loses power, loses the network, or is switched off mid-cycle.

The timer used is derived from the relay number, cycling through the board’s sixteen timers, so pressing the same relay’s timed button twice reuses one timer instead of leaving two racing each other. Hovering the button names the timer it will use. For durations longer than 59 seconds, put a Relay on for a duration command on a panel button or in a sequence, where hours and minutes are available too.

Analog inputs

The Analog inputs panel appears only when the board has analog inputs enabled. Its header states the resolution and the full-scale count, for example 10-bit · 0 – 1023 counts.

Column	Contents
Channel	The input number, 1 to 8.
Name	What you called this input, or Input N.
Counts	The raw A/D reading, exactly as the board reported it.
Value	The same reading scaled into your engineering units and rounded to your chosen number of decimals, with the unit beside it.
Chart	Points the chart below the table at this channel.
Scaling	Opens the scaling dialog for this channel.

The chart under the table plots the selected channel over Last hour, Last 6 hours, Last 24 hours or Last 7 days, in engineering units. It is drawn from logged samples, averaged into buckets, so a long span stays readable rather than dense.

Scaling an input

Scaling is a straight line: value = counts × scale + offset.

Field	What it does	Default
Name	What this input is called on this page, on the chart, and in the values published to Automations.	Input N
Unit	Shown beside the value and on the chart’s axis. Free text — psi, %, V, in, ppm.	Empty
Scale	Multiplier applied to the raw count. For a linear sensor across the full input range this is range divided by full scale: a 0 – 5 V input at 10-bit is 5 / 1023 = 0.00489. The dialog states the right figure for a 0 – 5 V input at the board’s resolution.	1
Offset	Added after scaling. Use it for a sensor whose output does not start at zero — a 4 – 20 mA loop, or a gauge reading against atmosphere.	0
Decimals	How many decimal places the value is rounded to for display. 0 to 4.	0
Meter minimum / Meter maximum	The ends of the level meter on an analog card. Leave both blank and the meter spans the full input range; set them to the part of the range that matters and the meter becomes readable. Display only — they do not clamp the value.	Blank

The banner at the bottom of the dialog states what 0 counts and full scale would read with the numbers you have entered. Check both ends there before saving; it catches a scale that is off by a factor of ten immediately.

Link and board features

Row	Meaning
Address	The radio address this controller uses.
Registered peer	The name the peer was registered under on the gateway, which confirms you matched the right hardware. Reads no if the peer does not exist.
Response time	The radio round-trip for the last exchange, in milliseconds. A single figure in the hundreds is normal for DigiMesh; a figure that climbs steadily over days usually means mesh congestion or a marginal link.
Last successful read	How long ago the board last answered. Hover for the exact time.
Poll interval	The configured interval, for confirmation.
Queue depth	How many commands are waiting to go out to this board. ProXR boards answer one exchange at a time, so commands queue. Anything other than 0 or 1 for more than a moment means commands are arriving faster than the radio can carry them.

Board features is empty until you press Identify board. The controller then returns its identification bytes, which the app decodes into a plain list — whether it is a ProXR class controller, whether the AD8 command set is on board, whether it has scratchpad memory, contact closure scan, a Taralist time-activated relay, and so on. The raw bytes are printed above the list. Use it to confirm a command set exists before relying on it: the Read contact closure inputs command, for example, needs AD8 contact closure hardware, and the identification card is where you check.

Recent traffic holds the last 40 exchanges with this board since the ingest service started, transmitted frames marked with an arrow out and replies with an arrow in, errors in red. Unlike the Activity log, this includes polling traffic, which is what makes it the right place to prove a link is alive.

Removing a controller

Deleting a controller removes its definition, its relay names, its analog input scaling and its logged analog samples. Cards that used it stop working until you point them somewhere else; the panels themselves are not deleted. The board’s DigiMesh peer registration belongs to the gateway and is untouched, so re-adding the controller later needs only the address and relay count again.

If the board is only temporarily out of service, clear Enabled on the controller instead. That stops the polling and the “no reply” noise while keeping every name, scale and card intact.

08Sequences

A sequence sends several commands to one controller in order, with an optional wait before each one. Startup interlocks, shutdown orders, backwash cycles, test runs — anything where the order and the gaps matter.

Sequences run on the gateway’s ingest service, one command at a time, and stop at the first failure. That matters: a sequence is not fire-and-forget on the controller, so a board that stops answering half way through leaves the sequence half applied. Where the whole state must be guaranteed, end the sequence with an absolute command — an all-off or a pattern — rather than relying on every earlier step having landed.

Building a sequence

Running one

• Run on the Sequences page runs it now and reports the result, naming the failed step if one fails.
• A Sequence button card puts it on a panel, where it shows its step count under the label.
• A schedule can run it at a time of day.
• The Automations action Run a sequence lets anything else on the gateway trigger it.

09Schedules

A schedule sends one command, or runs one sequence, at a time of day. Schedules are evaluated once a second on the gateway, in the gateway’s own display timezone.

How the time fields work

Day, hour, minute and second are each optional, and this is the part worth reading twice. An unset field that is coarser than the finest one you set means every. An unset field that is finer is treated as zero.

You never have to work this out in your head. The banner at the bottom of the editor states the rule in plain English and lists the next three firings, and it updates as you click. If the banner does not say what you meant, the schedule is wrong — before you save it.

Testing and pausing

10Automations

ProXR Control publishes what its boards are doing, and offers four commands anything else on the gateway can trigger. You connect the two on the gateway’s own Automations page — not inside the app. That click is the authorization: this app holds permission to transmit on the radio, and no other app gets to borrow it without an operator saying so.

The app’s own Settings page lists what it offers, and how much it has published, but bindings are never created here. The panel is a reference so you know what to look for on the Automations page.

What the app publishes

All three are level-triggered current state, not one-shot notifications: the app republishes each value as it evaluates it, and the gateway dispatches only when the value actually changes. That is what lets an automation switch something on when a condition starts matching and back off when it stops, and what lets a binding heal itself after a dropped message or a restart instead of latching on.

Fields you can build conditions on

status and online carry the same fact in two forms on purpose: status gives the condition builder a dropdown, while online reads better dropped into an email body. Use connected to tell “the board is not answering” apart from “the gateway is not allowed to talk to it”.

Commands an automation can run

All four are absolute: you set a state, never toggle one. A binding is re-asserted after a gateway restart, and a relative command would invert the load instead of restoring it.

Building a binding

1. 1
   Open Automations and click + New Automation

   Name it for what it achieves, not for its mechanism — the name is what appears in the audit trail and in the ProXR activity log.
2. 2
   Pick the WHEN event

   Any event the gateway or an installed app offers, including the three from ProXR Control. The form explains what the chosen event is tracked per, which decides how many independent on/off states the binding has.
3. 3
   Add conditions

   Without conditions the automation runs on every one of those events. With them it runs only while they all match. Fields come from the event’s declared payload.
4. 4
   Pick the THEN action and fill in both edges

   A ProXR action asks for its parameters twice: Settings when the condition starts matching and Settings when the condition stops matching. The second is usually the reverse of the first — the same relay, switched off. Leave it blank to do nothing on the way down. Any parameter can instead be filled from a field of the triggering event, using the insert event field dropdown underneath it.
5. 5
   Choose when it runs, then create it

   When it starts matching, and again when it stops is the usual choice for relay control. Re-apply after a gateway restart re-asserts the current state after a reboot, which is what you want for a load whose state should survive a power cycle of the gateway.

Checking the app is offering everything

The catalog at the bottom of the Automations page lists everything Atrium and the installed apps offer. If ProXR Control’s three events and four actions are not there, no binding can reference them, and the cause is one of two things: the gateway is older than platform 2.4.0, or the ingest service has not loaded the app. The app’s Settings page reports both, and its Automations panel says so in a red banner.

Commands an automation triggers are written to the app’s Activity log with the source Automation, or Automation (test run) when an operator pressed Run now on the binding — so a test never looks like a real firing. Each one is also written to the gateway’s audit trail with the binding’s name.

11Command Console

The console is a ProXR terminal. Pick any command from the set, see the exact frame that will be transmitted, send it, and read the controller’s reply decoded. It exists for commissioning a board and for the things the cards do not cover.

Reading the response

Useful console commands during commissioning

12Activity

Every command the app sent on somebody’s behalf, with the bytes exchanged, who sent it and what came back. Polling traffic is deliberately excluded — a board polled every five seconds would bury everything that matters.

Sources

Filters

Controller narrows to one board, or All controllers. Show sets how many entries to fetch — 50, 100, 250 or 500. The count of rows currently shown sits beside the filters. The page refreshes itself every five seconds while the tab is visible.

13Settings

Four panels: how long data is kept, what the app offers Automations, the wiring checklist, and what the app can see about the gateway it is running on. There are no credentials to enter and no external service to configure.

Data retention

Two of the app’s tables grow continuously. Both are pruned by a background worker every 30 minutes, in chunks, so the database is never locked for long. Changes take effect on the next pass — there is no separate save button; choosing a value saves it.

Sizing at the defaults: one board with eight analog inputs at the fastest allowed 10-second logging interval is roughly 480,000 sample rows over seven days, a few tens of megabytes. At the default 1-minute interval the same board stores about 80,000 rows. Analog logging is throttled independently of polling, so a 2-second poll interval for responsive panels does not multiply stored rows.

Automations

A read-only summary of the three events the app publishes and the four commands it offers, with the topic or id of each. See Automations for what to do with them. Underneath, a line reports how many values have been published, how many things are being tracked, and how many publishes were held back by the platform’s rate limit or refused. If the inter-app bus is unavailable, a red banner replaces the counters and says so.

Wiring a ProXR board to this gateway

The five-step commissioning checklist from First-Time Setup, repeated inside the app so an operator at the panel has it to hand, and closing with the reminder that relay state is the controller’s memory state.

About

14Troubleshooting

Ordered roughly by how often each cause turns out to be the real one. Work down the table rather than starting with the exotic explanations.

The board does not answer

Commands go out but nothing switches

Panels, values and history

Schedules and automations

15Reference

The ProXR concepts the app assumes you know, the complete command catalog, and every limit, default and stored field.

curl -H "Authorization: Bearer $TOKEN" \
  http://<gateway>/api/apps/proxr-control/ingest/state

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "relay_on_number", "params": { "relay_number": 1 } }' \
  http://<gateway>/api/apps/proxr-control/ingest/controllers/1/command