Connectors

The Edge connector is a small Windows service (EdgeConnector) on a computer in a site's network. It reaches the access controllers there and connects out to Edge over HTTPS and a WebSocket, so the site needs no inbound ports and no VPN.

The connector:

• applies each controller's configuration that Edge sends, and reports what the controller holds;
• reads every controller's events about once a second into a durable queue on its disk and uploads them in order, so events survive restarts and Internet outages and arrive exactly once;
• opens doors on request, finds controllers and tests connections;
• reports each controller's state (online, door open or closed, locked or unlocked) at least once a minute. TrackBase002 controllers do not report door open or locked states yet;
• updates itself when Edge offers a newer version (Updates).

Installing and removing connectors needs the Tenant admin role.

Requirements

• Windows 10/11 or Windows Server, 64-bit, always on (a small server or a mini PC). The computer does not have to be joined to a domain.
• Outbound HTTPS (TCP 443) to hub.entrosity.com. Nothing inbound.
• To TCP/IP controllers: their TCP port. For an RS-485 bus: the serial port, or a Modbus TCP gateway.
• One connector per site network is usual; it drives every controller it can reach. A computer that enrolls again (same name and domain, same tenant) replaces its earlier registration: the old key stops working.

Install a connector

Create an enrollment token

1. Open Connectors and choose Install a connector.

2. Fill in:

   Field	Meaning
   Label	Your name for the token, e.g. Head office server (at most 200 characters).
   Site	The site the connector's controllers belong to, or No site.
   Maximum uses	How many installations may enroll with it: 1–100000, empty for Unlimited. Default 1.
   Expires after (days)	1–3650, or empty for no expiry. Default 7.

3. Choose Create token. The dialog shows the Token and two ready commands. Copy the token now: it is shown only once.

The dialog also links to the connector installer (Download the connector installer) when the server has a download address configured; otherwise get edge-connector.msi from the releases of the entrosity-edge-connector repository: a tagged release (vX.Y.Z), or the development build dev, rebuilt from every change (versioned 0.0.<build>-dev.<commit>; each installs over the previous one, and the first tagged release installs over them). Once installed, the connector keeps itself up to date (Updates).

Install on Windows

Run the command under Windows: install the MSI (elevated prompt) in an elevated command prompt, in the folder that contains the MSI:

msiexec /i edge-connector.msi /qn ENROLLMENT_TOKEN=<token> SERVER_URL=https://hub.entrosity.com/edge

The MSI:

1. installs edge-connector.exe to %ProgramFiles%\Entrosity Edge Connector\;
2. enrolls the computer with the token (as SYSTEM). A failed enrollment rolls the installation back;
3. installs and starts the Windows service EdgeConnector (display name Entrosity Edge Connector, LocalSystem, automatic start), set to restart 30 seconds after each failure.

The connector appears in Connectors as Online within a minute.

/qn hides installer errors. To troubleshoot, add /l*v C:\edge-connector-install.log and look for Return value 3. The verbose log contains the enrollment token: delete it afterwards.

Enroll from the command line

The second command, under Already installed, or a trial run: enroll from the command line, enrolls an installed connector (for example one installed without the properties) or a development run:

"C:\Program Files\Entrosity Edge Connector\edge-connector.exe" enroll --server https://hub.entrosity.com/edge --token <token>

A service that starts without being enrolled waits and checks every ten seconds, so it picks up the enrollment on its own. To enroll a computer again with a new token, add --force, then restart the service (sc stop EdgeConnector and sc start EdgeConnector).

edge-connector status shows the enrollment and how many events are waiting for the server. All commands: Edge connector.

Controller PINs

TrackBase002 controllers only answer with their PIN. The PIN is set in Edge, per controller: in the Controller PIN field when you add the controller, or later on the controller's page (Controller PIN). Edge sends it to the connector with each job for that controller; the connector keeps it with the controller's configuration and never reports it back.

Without a PIN the controller shows Offline with the error the controller's PIN is not set: set it in Edge (the controller's page, Controller PIN), and its configuration fails with config_rejected. With a wrong PIN the controller does not answer: unreachable (check the controller's PIN).

note

trackbase.json is no longer read

Earlier connector versions read the PINs from trackbase.json in their data directory. The connector ignores that file now: set each controller's PIN in Edge. A file left on disk does no harm, and uninstalling still removes it.

Simulated controllers need no PIN.

The connector list

Connectors lists each connector with its Name, the Computer it runs on, its Status (Online or Offline), the number of Controllers it drives, its Version, its Updates channel and when it was Last seen. While an update is on its way, the version shows Updating to X (offered …).

A connector is Online from the moment it connects until its connection drops (shown at once) or it has been silent for three minutes. It sends a heartbeat every minute.

Enrollment tokens

Enrollment tokens lists the tokens with their Label, Status (Active, Exhausted, Expired or Revoked), Uses, when they Expire and who created them (Created by).

• Revoke stops a token from enrolling more connectors. Connectors already enrolled with it keep working.
• Revoked and expired tokens are deleted automatically 30 days later. Global admins can delete a token at once through the API (it asks for their password again).

Tokens are secrets: anyone with a valid token can add a connector to your tenant. Keep Maximum uses at 1 and the expiry short.

Updates

Connectors update themselves: Edge offers a newer version, and the connector installs it without anyone at the computer.

• Channel: each connector follows an update channel, set by tenant admins in the Updates column of Connectors:

  Channel	Gets
  Stable (the default)	Tagged releases (vX.Y.Z) only.
  Beta (development builds)	The newest of the beta and the stable releases: pre-releases (vX.Y.Z-suffix) and development builds as soon as they are published.

• When: Edge offers the newest version of the channel when the connector connects and every 5 minutes after that, as long as it is newer than the connector's version. An offer is not repeated within an hour, and never while an earlier update is still pending. Version shows Updating to X (offered …) meanwhile.

• How: the connector checks that the release is signed by Edge, downloads the installer and installs it a minute later. The service restarts on the new version; the controllers keep working meanwhile, and events wait in the queue. If the new version does not start, the connector reinstalls the version it ran before.

• The outcome is written to the connector log (%ProgramData%\Entrosity Edge Connector\logs\connector.log) when the service starts again; the new Version shows in Connectors.

Connectors installed before self-update

Connectors from before self-update (they do not update, however long you wait) must be upgraded by hand once: run the MSI of the dev release or of a tagged release of entrosity-edge-connector on the computer, as below. From then on they update themselves.

Updates need the server set up for them (EDGE_MASTER_KEY, EDGE_RELEASE_SIGNING_KEY: Running Entrosity Edge). Details: Edge connector → Self-update.

Upgrade by hand and uninstall

• Upgrade by hand: run the MSI (no properties needed). Data stays in %ProgramData%\Entrosity Edge Connector, so the connector stays enrolled and keeps its controllers. An older MSI installs over a newer one too.
• Uninstall: from Apps & features, or msiexec /x edge-connector.msi /qn. This removes the service, the credentials, the list of controllers (with their PINs), a trackbase.json left by older versions and the event queue; the logs are kept. Then Remove the connector in Edge (below).

Remove a connector

Choose Remove on the connector's row and confirm. Its key stops working at once and it disconnects; its open jobs are cancelled. Uninstall it from the computer afterwards.

A connector that still drives controllers cannot be removed (connector_has_controllers): remove or move its controllers first.

When the connector is offline

• Controllers keep working: they decide every badge read with the configuration they hold.
• Their state shows as Unknown in Edge, and remote door opening and discovery are refused (connector_offline).
• Changes you make wait: each affected controller shows Pending, and the configuration is sent when the connector reconnects.
• Events stay in the controller's memory (32,000 events) and, once read, in the connector's queue on disk; they are uploaded in order when the connection is back.

See Configuration sync and troubleshooting.

Troubleshooting installation

Symptom	Cause and fix
The install rolls back	Enrollment failed. Install again with /l*v <log> and read the enroll step: an invalid token (enrollment_token_invalid: mistyped, or not an Edge connector token), no uses left (enrollment_token_exhausted), expired or revoked (enrollment_token_expired), or no route to SERVER_URL. Create a new token.
Enrolled, but the connector stays Offline	Check outbound HTTPS to hub.entrosity.com (proxy, firewall) and the log %ProgramData%\Entrosity Edge Connector\logs\connector.log.
It was removed in Edge	Its key no longer works (connector_unauthorized). Enroll again with a new token and --force, then restart the service.
enroll says already enrolled	The computer holds credentials. Use --force to enroll again.