Endpoints

An endpoint is a named outgoing Modbus TCP connection that Overvis keeps open. The English UI says Endpoints; translated UIs call the same section connections. Modbus parameters refer to an endpoint by endpointId. Each endpoint is enabled or disabled on its own.

Setup pages and their routes are in workspace pages. The API bodies are in endpoint procedures. Steps for each task are in Configure endpoints.

Kinds

Kind	Stored kind	Connects to	Port
PIN	pin	A supported Overvis device on the Overvis VPN, identified by its 8-character PIN	Always 502
WireGuard	wireguard	A device on the Overvis VPN, identified by its WireGuard public key	Editable, default 502
TCP	direct	A hostname or IP address that the Overvis server can reach	Editable, default 502

The protocol is Modbus TCP for every kind. The kind is chosen at creation and does not change.

Creating, editing, enabling, disabling, and deleting endpoints requires the editor, admin, or owner role.

Fields

Field (EN)	Applies to	Rules
Name	All	Required LocalizedString; not unique
Description	All	Optional LocalizedString
Kind	All	PIN (pin), WireGuard (wireguard), or TCP (direct); set at creation, read-only after
Protocol	All	Modbus TCP (fixed)
Hostname	TCP	Host name or IP address. Empty values and values with spaces are refused. IPv6 is accepted with or without brackets and stored normalized
Port	TCP, WireGuard	1–65535. A PIN endpoint always uses 502
PIN	PIN	Eight alphanumeric characters, shown upper case; read-only after creation
Public key	PIN, WireGuard	Read-only after creation
SKU	PIN	Product identity, set at creation; shown with the manufacturer and MAC address; not editable in Setup and not changed by setup push
Device meta	PIN	MAC address and manufacturer recorded at creation, for information; not changed by setup push
TCP settings	All	See TCP settings

Setup shows the device model, manufacturer, and MAC address of a PIN endpoint when they are known.

Validation errors

Saving an endpoint can fail with, among others:

• an invalid hostname, port, or TCP setting;
• a TCP endpoint address in a blocked network;
• a PIN that is not found, or a device that is not registered or not connected to the VPN;
• an MC252 that is already connected in this workspace, is not reachable for confirmation, has firmware older than 49, or whose confirmation expired or was not accepted;
• a WireGuard public key that is invalid or already in use;
• no VPN address available;
• the connection service being unavailable.

TCP endpoints

A TCP endpoint connects from the Overvis server, not from the user’s computer. The installation’s network policy blocks some destination addresses: private, loopback, IPv6 unique local, and similar networks, and Overvis VPN addresses. An IP address in a blocked network is refused when the endpoint is saved. A DNS name is accepted at creation and checked when the server resolves it: the connection is refused if any resolved address is blocked. Devices on the Overvis VPN connect as PIN or WireGuard endpoints.

PIN endpoints

• The same device can be connected by PIN several times, also in different workspaces. An MC252 can be connected only once per workspace.
• Creating a PIN endpoint fails when the PIN does not identify a registered device or the device has no VPN connection.
• Deleting one PIN endpoint does not disconnect the device from other workspaces.
• Connecting an MC252 that other workspaces already hold notifies their owners, admins, and editors.
• Setup push cannot create a PIN endpoint. It cannot change the kind, PIN, public key, SKU, protocol, or device identity of an existing one.
• The active connection address is the device’s current VPN address and can change.

MC252 presence confirmation

Creating an MC252 PIN endpoint needs proof that someone is at the device: a press of the R button on the device, or the 8-digit code when the device screen shows one. The confirmation is valid for two minutes. A wrong code can be entered again; after five wrong codes the confirmation starts over. Closing the Setup dialog cancels it. Confirmation needs MC252 firmware 49 or newer; the firmware is updated in the device web interface (Administration). Other PIN products skip this step.

Removing an MC252 connection from other workspaces needs the same confirmation. Parameters in those workspaces that use the connection stop working.

WireGuard endpoints

• The public key is 44 base64 characters ending in =, exactly as wg pubkey prints it: the canonical base64 of 32 bytes. The character before = is one of AEIMQUYcgkosw048; a key ending in any other character is refused.
• One WireGuard endpoint per public key exists in the whole system. A key that already has a VPN address of another kind, such as the key of a device connected by PIN, is refused.
• A static VPN /32 address is reserved for the key a few seconds after creation.
• Disabling the endpoint keeps the key and the address. Deleting the endpoint, or the workspace, releases both. The key cannot change: a new key needs a new endpoint, and its reserved address may differ.
• The port is the Modbus TCP port on the reserved address, not the WireGuard UDP port.

The Documentation dialog opens after creation and from the Documentation icon on the endpoint’s row. It shows setup steps and a live WireGuard configuration: PrivateKey is a placeholder for the device’s private key, Address is the reserved /32, AllowedIPs is the Overvis VPN range, and the keepalive is 30 seconds. Until the address is reserved, the dialog says so and fills in the configuration when it arrives.

TCP settings

Setting (EN)	API field (settings.tcp)	Default	Meaning
Max TCP packet size (bytes)	maxTcpPacketSize	1460	Most bytes of Modbus requests grouped into one socket write
Max simultaneous requests	maxParallelInflightAdus	8	How many Modbus requests may wait for an answer at once
Max queued requests	maxQueuedAdus	1000	Queue depth before new requests are refused as overload
Disconnect after protocol errors	disconnectAfterProtocolErrorCount	3	Protocol errors that close the connection; empty (null) never disconnects
Connect timeout (ms)	connectTimeoutMs	10000	How long a connection attempt may take
Connect retry delay (ms)	connectRetryDelayMs	5000	Wait before the next connection attempt
Total request timeout (ms)	totalRequestTimeoutMs	30000	Overall time a request may take
Response await timeout (ms)	responseAwaitTimeoutMs	5000	Wait for the device’s response
TCP keepalive interval (ms)	tcpKeepaliveEveryMs	30000	Keepalive interval; 0 turns keepalive off

Every setting takes a positive whole number. The keepalive interval also takes 0, and the disconnect threshold also takes an empty value. Setup shows an invalid value’s error beside the setting and does not save until it is corrected.

Max TCP packet size limits the total bytes of the Modbus requests grouped into each socket write, Modbus TCP framing included. A single request whose framed size exceeds it fails with request_too_large, and live values show “Request size … exceeds the connector limit …”. A Modbus TCP request is at most 260 bytes, so only values below 260 can reject requests; lower values send fewer requests per write. The setting does not control TCP segment sizes on the network and does not limit response sizes.

Enabled and disabled

Disabling an endpoint stops its connection from being used until it is enabled again. Setup shows a Disabled badge in the list and an Endpoint disabled banner with the disabled-since time on the status page.

	Disabled	Disconnected
Cause	Someone turned the endpoint off	Live state of an enabled endpoint that is not up
Shown	Disabled badge	Status Disconnected
Ends	When the endpoint is enabled	When the network or device recovers and the state reaches Connected

Deletion

Deleting an endpoint removes its configuration permanently. Deleting a WireGuard endpoint releases its reserved VPN address, so the public key can be used again. An endpoint that parameters, edge programs, automations, or alarm rules still use cannot be deleted: Setup shows “Parameters, edge programs, automations or alarm rules still use this endpoint. Move or change them, or delete them first.” The API and CLI push apply the same rule (endpoint_in_use).

Endpoint list

Each row of the Setup → Endpoints list shows a connection dot (green when connected, red on error, amber while connecting, muted otherwise), the name, and the address: the host (TCP), the PIN with the manufacturer and SKU (PIN), or WireGuard with the port. A disabled endpoint has a Disabled badge, and a WireGuard row has a Documentation action.

Status page

Selecting an endpoint in Setup → Endpoints opens its status page. Tabs show only when the endpoint has more than the Connection tab:

• Programs: on an MC252 PIN endpoint. Its programs with an editor, where they stand on the device, its program settings, and the tasks it runs. See Deploy programs to an MC252.
• Recorded readings: on an MC252 PIN endpoint. It lists readings that the device’s programs recorded for addresses no parameter reads, with Create parameter on each row. See recorded readings.
• Device UI: on an endpoint with a VPN public key (PIN or WireGuard), for owners, admins, and editors. See Device UI.

A TCP endpoint has only the Connection tab.

Connection tab

The Connection tab shows the connection state and the Modbus traffic.

State	Meaning
Connecting	Overvis is opening the connection: to the configured host and port (TCP), or to the current VPN address and port (PIN, WireGuard)
Connected	The connection is up; Connected since shows when it opened
Disconnected	Not connected: waiting to retry, closed by the device or after protocol errors, or awaiting a VPN address
Error	The connection failed; Last error has the reason
Unknown	No status has been reported yet

Last error shows in every state except Connected and keeps the most recent failure until a connection succeeds; — means no failure has been recorded. A PIN or WireGuard endpoint that is waiting for its VPN address shows Waiting for a VPN address. A Modbus exception on one parameter leaves the endpoint Connected: it is a parameter error, not a connection failure.

• Setup address: the configured host and port (TCP); the PIN with the manufacturer and SKU when known, without a port (PIN); the kind and port (WireGuard).
• Active address: the address of the live connection. For PIN and WireGuard it is the VPN address and changes when the device’s VPN address moves.
• Stream indicator: Live (the status stream is healthy), Reconnecting… (the page is reconnecting its stream), or Stream error (a problem with the status stream, not a device Modbus error).
• Traffic log: recent Modbus traffic, Waiting for traffic… while it is empty, and Jump to latest.

The status page does not show packet-level diagnostics. A connected status describes the TCP connection only: it does not show that the device accepts parameter requests.

When other workspaces also hold an MC252 PIN connection, the status line shows Also connected in with their names. Disconnect… deletes the connection from all of those workspaces after the presence confirmation.

Device UI

The Device UI tab opens the device’s web interface through the gateway connection, so the browser needs no direct network access to the device. Over a slow connection, the first opening can take a minute or more while the device sends its files; later openings reuse them. Meanwhile a progress bar shows how much has arrived. When the web interface cannot be reached, the tab shows an error. Open in new window opens the web interface in a separate browser window.

On a WireGuard endpoint the web interface is HTTP on the reserved VPN address. A device without a web interface still has the tab, which reports that HTTP is not reachable.

Endpoints and parameters

A Modbus TCP parameter source names an endpoint, a unit ID (0–255), a table (coil, discrete input, holding register, or input register), and zero-based PDU addresses. Until the workspace has an endpoint, the Setup parameter form shows Modbus TCP (add an endpoint first) and the Modbus source cannot be chosen.

Parameter reads that fail because of the endpoint return the runtime codes endpoint_not_found, endpoint_disconnected, timeout, modbus_exception, and connector_rejected (the connection refused the request). Setup shows them as Endpoint not found, Endpoint disconnected, Timeout, Modbus exception, and Connector rejected. See live value procedures.

Reads by address

endpoint.modbusRead reads registers, coils, or discrete inputs of an endpoint by unit ID, table, address, and quantity, for registers no parameter maps. One call takes up to 32 reads of up to 125 registers or 2000 bits each. It returns their values in order: registers from 0 to 65535, and bits as 0 or 1. Each read fails on its own with a runtime error code, such as modbus_exception or timeout. The reads queue with the endpoint’s other Modbus traffic and show in its traffic log. They need the editor, admin, or owner role.

RS-485 device find

For an MC252 PIN endpoint, the assistant scans the RS-485 bus behind the device and identifies the devices on it:

• The scan runs by default at 9600 baud in RTU mode and stops by itself when it is done. A progress card shows the tries made, the unit IDs found so far, and Cancel.
• For the unit IDs it finds, the assistant identifies each model. It first copies the Overvis device catalog to the MC252’s microSD card; a second progress card shows the identification.
• For each identified model with a parameter template, the assistant offers to add its parameters from the template. Unknown devices and models without a template get a question or parameters created one by one.
• When the scan finds nothing, the assistant retries a few common baud rates and formats, then asks about the wiring, swapped A and B lines, or a known baud rate.

Device find requires the editor, admin, or owner role, an enabled PIN endpoint, and a reachable MC252. Identification also requires a microSD card.

The scan and the identification run on the MC252, which sends the Modbus requests on its RS-485 bus. Parameter readings use the endpoint’s Modbus TCP connection.

When the microSD card is missing, unformatted, or faulty, or the MC252 unmounted it because its supply voltage dropped too low, identification stops before it reads any device and the assistant reports an SD card sync failure. The unit IDs found by the scan are kept. The card must be FAT or FAT32.