HMI on Loupe Documentation

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

A LuxReact HMI has four layers.

Layer	Component	Job
UI binding	LuxReact	Connects React components to variables with hooks
Client	LuxConnect `OpcuaMachine`	Manages the session, subscriptions, and value cache
Transport	HTTPS REST plus a WebSocket push channel	Carries reads, writes, and updates
Gateway	mapp Connect or OPC UA Proxy	Reads and writes variables on the controller over OPC UA

flowchart TD subgraph App["Browser or Electron"] UI[React components] -->|useVariable / useWrite| LR[LuxReact
MachineProvider] LR -->|ICommLayer| LC[LuxConnect
OpcuaMachine] end LC -->|"REST: sessions, read, write"| GW{Gateway} GW -.->|"WebSocket push channel"| LC GW -->|B&R| MC[mapp Connect
on the controller] --> BR[(B&R PLC)] GW -->|"Other OPC UA"| P[OPC UA Proxy
on a PC or in Electron] --> OS[OPC UA server] --> PLC[(Beckhoff or other PLC)]

LuxReact handles the React side: providers, hooks, subscription bookkeeping, and caching values across remounts. It does not know how values reach the PLC. It talks to an ICommLayer interface.
LuxConnect is the ICommLayer implementation. It opens an OPC UA session through the gateway, subscribes to variables, and receives changes over the push channel.
The gateway is mapp Connect on a B&R controller, or OPC UA Proxy for other OPC UA servers. Both offer the same API, so the HMI code is the same either way.

Because LuxReact only depends on ICommLayer, a different transport means writing a different adapter. The React code stays the same. LuxReact ships a MockCommLayer for tests and component previews.

LuxReact + LuxConnect

Mon, 01 Jan 0001 00:00:00 +0000

LuxReact and LuxConnect are the recommended stack for new HMIs on B&R controllers. Both are written in TypeScript and are in active development, so their APIs may change before 1.0.

Package	Repository	What it does
`@loupeteam/lux-react`	LuxReact	React providers and hooks. Works with any transport that implements `ICommLayer`.
`@loupeteam/lux-connect`	LuxConnect	OPC UA client for B&R mapp Connect. Also usable without React, in Node.js or the browser.

The repository READMEs are the API reference. This page covers how the pieces fit together.

Gateways

Mon, 01 Jan 0001 00:00:00 +0000

LuxConnect talks to a gateway that offers the mapp Connect API. The gateway reads and writes variables on the controller.

Gateway	Runs on	Controller	Protocol to controller
mapp Connect	B&R controller	B&R	Built into Automation Runtime
OPC UA Proxy (experimental)	PC, or inside an Electron HMI	Controllers without mapp Connect, through their OPC UA server	OPC UA

mapp Connect

mapp Connect is part of B&R mapp and runs on the controller. See LuxReact + LuxConnect for the controller setup.

Users and login

Mon, 01 Jan 0001 00:00:00 +0000

Users and roles live on the OPC UA server. On a B&R controller, define them in the Automation Studio project under Access and Security. When the HMI connects, LuxConnect opens an OPC UA session as a user, and the server applies that user’s permissions to every read and write.

Sign in with username and password when you create the OpcuaMachine.
Switch users without reconnecting with machine.changeUser(username, password). Call changeUser() with no arguments to switch to the anonymous user.
Read the current user and roles with machine.getSessionInfo(). Use the roles to show or hide screens.

Because the server checks every request, hiding a button is only a convenience. A user without permission can’t write the variable even if they reach it another way.

Platform support

Mon, 01 Jan 0001 00:00:00 +0000

Controller	Support	Gateway
B&R Automation Runtime	Supported	mapp Connect
Beckhoff TwinCAT 3	Experimental	OPC UA Proxy and the TwinCAT OPC UA server (TF6100)
Other OPC UA controllers	Experimental	OPC UA Proxy

Beckhoff

LuxConnect talks to the B&R mapp Connect API, so it can’t connect to a TwinCAT controller directly. OPC UA Proxy fills that gap: it offers the mapp Connect API and forwards requests to the TwinCAT OPC UA server.

This path has not been validated on TwinCAT yet. Variable naming and namespaces differ from B&R, so test reads, writes, and structures on your controller before committing a project to it.

Migrating to LuxReact

Mon, 01 Jan 0001 00:00:00 +0000

Info

This guide is a starting point. It will grow as HMIs are migrated.

Moving from Loupe UX classic to LuxReact is a rewrite of the UI, plus a change on the controller. Plan it as a project, not an upgrade.

Controller changes

On B&R:

Enable mapp Connect and the OPC UA server. See LuxReact + LuxConnect.
Make every variable the HMI uses visible over OPC UA.
Move user handling to OPC UA users and roles. See Users and login.

On Beckhoff, the target is OPC UA Proxy with the TwinCAT OPC UA server. That path is experimental, so keep Loupe UX Server running until it is validated on your controller.

Loupe UX classic (deprecated)

Mon, 01 Jan 0001 00:00:00 +0000

Loupe UX classic is deprecated. Existing HMIs remain supported, but start new HMIs on LuxReact + LuxConnect, and see Migrating to LuxReact to move an existing one.

Loupe UX is the original Loupe web HMI library. You build pages in HTML and connect elements to PLC variables with attributes. It needs no build step and no JavaScript framework beyond jQuery.

Architecture

Component	Runs on	Documentation
Loupe UX (`lux.js`, `lux-data-bind.js`, `lux.css`)	Browser or Electron	Loupe UX Web Client
Tmplits (optional)	Browser or Electron	Tmplits
OMJSON	B&R controller	OMJSON
Loupe UX Server	Windows PC with an ADS route to a Beckhoff controller	Loupe UX Server below

Loupe UX scans the page for elements with data-var-name and reads those variables over a WebSocket. Call LUX.updateHMI() on a timer to refresh the page. Use read groups to limit how much is read and how often.