Servers
Route: Admin → Data → Servers (/admin/data/servers)
A server is one connection OpSee makes to get data out of the plant: an OPC-UA endpoint, an MQTT broker, a Sparkplug B broker, or a Modbus TCP slave. This is the first screen an integrator touches on a new install — nothing else in the data chain works until a server here reaches Connected. Once it does, the Browse and Sniff tools turn what the server exposes into Data Tags.
Permissions
OpSee has no admin bypass — every action below is gated on an explicit permission.
| Permission | What it allows |
|---|---|
perm:servers:read | Open the Servers, Browse and Sniff screens; list servers, read certificates, run Test connection, and browse an OPC-UA address space |
perm:servers:write | Create, edit and delete servers; set passwords; upload, trust and delete certificates |
perm:servers:probe | Run an MQTT sniff, match topics against a parser rule, and discover tags from sampled payloads |
perm:tags:write | Bulk-create tags from a Browse selection, a Sniff result, or the Modbus register mapper |
perm:collectors:admin | Change the Collector field of a server (without it the field is read-only) |
A user with only perm:servers:read sees the grid and can test connections, but every save is refused by the API.
The server list
The grid refreshes live: the initial list is loaded over REST, and a server-sent event stream then pushes status changes without a reload. The Live indicator in the header shows whether that stream is connected.
| Column | Meaning |
|---|---|
| Name | Technical identifier, with the optional display name beneath it |
| Kind | MQTT, OPC-UA, Sparkplug B or Modbus TCP |
| Endpoint | The URL OpSee dials. Modbus servers show a synthesised modbus://host:port. |
| Auth | Anonymous, User & password, Client cert, or User+pass + cert |
| TLS | A hint, not a guarantee — see Reading the TLS chip |
| Status | The live connection state |
| Collector | Central when the central OpSee collects this server itself, otherwise a link to the remote collector that owns it |
| Active | Inline switch. An inactive server is not collected and is hidden from Browse and Sniff. |
| Last seen | Turns red once the last successful contact is more than 5 minutes old |
Search matches name, display name and endpoint. The search box, the Kind filter and Show inactive are all mirrored into the URL, so a filtered view can be bookmarked or pasted to a colleague.
Status values
| Status | What it means |
|---|---|
| Connected | Handshake succeeded and the session is live |
| Connecting… | Handshake in progress (pulsing) |
| Auth failed | Credentials were rejected — wrong user, wrong password, or a client certificate the peer does not accept |
| TLS failed | The transport could not be secured — untrusted or expired certificate, wrong hostname, plain endpoint against a TLS listener |
| Timeout | No response in time — usually a firewall, a wrong port, or an unreachable host (pulsing) |
| Disconnected | The session ended |
| Idle | Never observed — a freshly created server that has not been contacted yet |
Hover the badge for the last-seen time and the last error message the collector reported.
Banners
Three warnings can appear above the grid:
- Expired certificates — connections using them will fail until you upload replacements.
- Certificates expiring within 30 days — edit the affected server and upload a replacement before it bites.
- Untrusted peer certificate — an OPC-UA server presented a certificate OpSee has not trusted. Review and trust it on the server's TLS / Trust tab (see Trusting an OPC-UA server certificate).
Adding a server
Click Add server. The dialog has four tabs — General, Authentication, TLS / Trust and Advanced — and the fields on each depend on the Kind you pick.
TLS / Trust is only available once the server exists. On a new server the tab is disabled: save first with Save & configure, then reopen the server to upload certificates and to run Test connection.
Three fields are common to every kind:
| Field | Description |
|---|---|
| Name | Unique technical identifier. Used internally and not meant to change once data is bound to it. |
| Display name | Optional human-friendly label shown in lists |
| Collector | Central (default) or the remote collector that collects this server. Choosing a collector moves the server even if another collector had it. Requires perm:collectors:admin. Sparkplug B servers cannot be collected by a remote collector — keep them on Central. |
OPC-UA
| Field | Notes |
|---|---|
| Endpoint URL | opc.tcp://host:4840 or opc.https://host:4843 |
| Authentication | Anonymous, user & password, client certificate, or both |
| Security policy | None, Basic128Rsa15, Basic256, Basic256Sha256, Aes128_Sha256_RsaOaep, Aes256_Sha256_RsaPss |
| Security mode | None, Sign, SignAndEncrypt |
| Application URI | Must match the Subject Alternative Name on the server certificate |
| Verify ApplicationUri | On by default; turning it off skips that match |
| Record rejected peer certs | Saves unknown server certificates so you can review and trust them instead of guessing |
| Auto-trust on first use | Development only. Promotes any unknown server certificate to trusted automatically. |
| Session timeout (ms), Publishing interval (ms) | Session and subscription tuning |
| Allow writes | Per-server kill-switch for OPC-UA writes. While it is off, no tag value can be written to this server whatever the per-tag setting says. |
The policy and mode you choose must be an endpoint the server actually offers. A mismatch shows up as TLS failed, not as an authentication error.
MQTT
| Field | Notes |
|---|---|
| Endpoint URL | mqtt://host:1883 (plain), mqtts://host:8883 (TLS), ws:// / wss://host:9001 (WebSocket) |
| Topic filters | Comma-separated MQTT patterns; default #. # matches multiple levels, + exactly one. |
| Default QoS, Keepalive (s), Client ID, Clean session | Standard MQTT client settings |
| Verify server certificate | Leave on outside development |
| Trust system CAs | Trust the OS root store in addition to any CA you upload for this server |
| Auto-discover unknown tags | On by default. When off, topics from this broker that no tag resolves are dropped instead of being auto-created — see Data Tags. |
If the endpoint still starts with mqtt:// while the configuration clearly wants TLS — certificate-based auth, port 8883, or a trusted MQTT CA uploaded for the server — the dialog offers a one-click rewrite to mqtts:// rather than changing the URL silently.
Sparkplug B
A Sparkplug B server is an MQTT broker plus the Sparkplug specifics:
| Field | Notes |
|---|---|
| Group ID filter | Empty subscribes to all groups (spBv1.0/#); set it to subscribe to spBv1.0/<group>/# |
| Primary Host ID | When set, OpSee acts as Sparkplug Primary Host and publishes STATE/<host_id> |
| Rebirth on unknown alias | Issues NCMD/Node Control/Rebirth when data arrives whose alias was not in the latest NBIRTH/DBIRTH |
| Keepalive (s), Publishing interval (ms), Client ID | Client tuning |
Modbus TCP
Modbus TCP is addressed by Host and Port (default 502) rather than a URL, and it has neither authentication nor transport security — the Authentication and TLS / Trust tabs are disabled for it. The dialog says so explicitly: put the slave on a segmented network, or reach it through a VPN or gateway.
| Field | Notes |
|---|---|
| Default unit id | Slave id (0–255) used when a mapped register does not specify one |
| Timeout (ms), Poll interval (ms) | Poll interval has a 50 ms floor |
| Byte order / Word order | The slave firmware's decoding convention. Big-endian is the Modbus default; flip the word order for "swapped" 32-bit values. |
| Max registers per read, Max bits per read | Request size caps |
| Max gap (registers) | Unused registers tolerated when coalescing neighbouring reads into one request |
| Delay between requests (ms) | Raise it for slow serial gateways |
Modbus has no browsable address space and no topics to sniff, so its tags are entered by hand — see Mapping Modbus registers.
Credentials and certificates
Passwords are encrypted at rest with MASTER_ENCRYPTION_KEY and are never returned by the API. In the edit dialog the Password field is blank with a "has password" marker: leave it empty to keep the stored one, type a new value to replace it. If the key is missing from the environment, a banner tells you so — password and certificate storage will not work until it is set and the API is restarted.
The TLS / Trust tab holds this server's certificate material, grouped into tabs: All, Trusted peers, Issuers, Client cert & key, Rejected and CAs. You upload PEM files, and each entry shows subject, issuer, fingerprint and expiry.
Trusting an OPC-UA server certificate
With Record rejected peer certs on, an unknown server certificate is stored instead of discarded. When that happens the grid shows a warning banner and the server's TLS chip reads review cert.
- Edit the server and open TLS / Trust → Rejected.
- Check the subject, issuer and fingerprint against what the OPC-UA server should be presenting.
- Click Move to trusted.
The next connection attempt uses the now-trusted certificate. Untrust reverses it.
Reading the TLS chip
The chip is a hint derived from the endpoint scheme and the certificates on file, not a report of the negotiated session:
| Chip | Shown when |
|---|---|
| review cert | The server has at least one rejected peer certificate waiting — this takes priority over everything else |
| mTLS | MQTT/Sparkplug B with a mqtts:// or wss:// endpoint and a client certificate uploaded |
| TLS | MQTT/Sparkplug B with a mqtts:// or wss:// endpoint |
| plain | MQTT/Sparkplug B on a plain endpoint |
| Sign+Enc | OPC-UA with a client certificate uploaded |
| None | OPC-UA with no client certificate |
Testing a connection
Test connection sits at the bottom left of the edit dialog and only appears when you are editing an existing server. It opens a short-lived client, runs the handshake and reports back:
- OK (n ms) — the handshake succeeded, with the measured latency.
- Failed — retry — the button changes and a snackbar carries the error text.
The test reuses the same connection code as the real collectors, so "works in test, fails in production" drift is not possible.
:::caution Where the test actually runs For a server assigned to a remote collector, an OPC-UA, Modbus or MQTT test is dispatched to that collector and executed on the plant LAN — the collector must be online (it must have heartbeated recently) or the test returns "assigned collector is offline". A Sparkplug B test is refused behind a collector: collectors have no Sparkplug B data plane, so such a server can only be collected (and tested) from Central. :::
Browse (OPC-UA address space)
Route: /admin/data/servers/browse, or the tree icon on any OPC-UA row.
Use Browse when the server exposes a structured address space and you want to pick specific variables to record. It answers "what is on this server, and what is it worth reading?"
- Pick an OPC-UA server from the selector. Only active OPC-UA servers appear; the endpoint and live status badge are shown next to it.
- Expand the tree. Children are fetched one level at a time on click, so a large address space stays responsive. Each row shows the browse name, node class, data type for variables, and a best-effort preview of the current value.
- Tick the variables you want. They collect in a Selected (n) strip above the tree, with a Clear all and an Add n as tag(s) button.
- Click Add n as tag(s). The modal lists one row per node with its Tag name, Composite, Transformation and Deadband — adjust and create. Tags that already exist are reported as skipped rather than duplicated.
Show node IDs turns on the full wire-level node_id under each row — useful when you are chasing one specific identifier and do not want to hover.
The value preview is best-effort: a node OpSee cannot read still browses, it just shows no value.
Browse is routed through the assigned remote collector when the server has one, so an address space that only the plant LAN can reach still browses from a central OpSee. As with the connection test, that requires the collector to be online.
Sniff (MQTT topics)
Route: /admin/data/servers/sniff, or the RSS icon on any MQTT row.
Reach for Sniff when there is no address space to browse — an MQTT broker only tells you what it is publishing if you listen. It is a three-step wizard: Sniff → Define parser → Create tags.
Step 1 — Sniff
| Setting | Notes |
|---|---|
| Topic filter | MQTT wildcards: # multi-level, + single-level. Start broad. |
| Duration | 5–120 seconds. The 120 s ceiling is enforced by the API, not just the slider. |
| Max topics | Stop early once this many distinct topics have been seen (1–1000) |
Click Start sniff and wait out the window. If nothing appears, the wizard says so and suggests a broader filter or a longer duration — a slow-publishing broker genuinely may say nothing in 30 seconds.
Step 2 — Define parser
Sniffing gives you topics and sample payloads; a parser rule turns a payload into a value. The wizard proposes one from the samples and lets you correct it:
- Name and Topic pattern for the rule.
- Value path, Tag name path, Device name path, Timestamp path and, for array payloads, Metrics array path — JSON paths into the payload. When the sample is JSON you can click a leaf in the rendered payload to fill a path instead of typing it.
- Timestamp format.
If the payload is not JSON the wizard says so and you type the paths yourself.
Step 3 — Create tags
The wizard runs the rule over the sampled payloads and lists the tags it would create, marking each row new or exists. Hide existing tags trims the list to what is actually new. Remove any row you do not want, then create the batch.
:::caution Sniff runs where the server is collected Like OPC-UA browse and the connection tests, an MQTT sniff of a server assigned to a remote collector is routed through that collector, so a broker only the collector's LAN can reach can still be sniffed. The collector must be online for the sniff to run. :::
Mapping Modbus registers
Modbus TCP has no discovery of any kind, so the register map is entered directly. Click the table icon on a Modbus row (visible only with perm:tags:write) and add one row per register:
| Column | Notes |
|---|---|
| Tag name | Required, unique within the batch |
| Unit id | 0–255; defaults to the server's default unit id |
| Register type | Coil (RW bit), Discrete input (RO bit), Holding register (RW), Input register (RO) |
| Address | 0–65535 |
| Data type | Must be valid for the register type. 32-bit types span two registers and are rejected if they would overrun the address space. |
| Bit | 0–15, and only for int16 / uint16 |
| Transformation | Pass-through, counter delta, or change detection |
| Deadband, Composite | Optional |
Submitting reports how many rows were created, skipped (already mapped) and rejected. New tags are picked up within about 5 seconds — no restart.
Where a server's data goes next
- The tag icon on any row opens Data Tags filtered to that server, with the status filter set to all so freshly discovered tags are not hidden by the default "configured only" view.
- Values then land in Data Trends and feed equipment OEE.
Deleting a server
Deleting a server permanently removes it, all of its uploaded certificates, and unbinds tag sources from it. Tag sources whose foreign key is ON DELETE RESTRICT block the delete instead — clean those up first. If you only want to stop collecting, switch the row's Active toggle off.
Related
- Remote Collectors — collect servers that live on a plant LAN the central OpSee cannot reach
- Data Tags — what Browse, Sniff and the Modbus mapper create
- Data Trends — the history those tags produce
- Tag Quality — spotting stale or suspicious tag data