Connectors

The Sphere connector is a small Windows service (SphereConnector) on a computer on a site's network. It reaches the NVRs there, connects out to Sphere over HTTPS and a WebSocket, and publishes video out to Sphere's media server at media.entrosity.com, so the site needs no inbound ports and no VPN.

The connector:

• keeps each NVR in the state Sphere wants: signed in (connected) or signed out (disconnected). A connected NVR is checked every 30 seconds, its details are read again every 5 minutes, and its event stream is followed;
• fetches each NVR's user name and password from Sphere with its own key when they change; they never travel in jobs;
• when someone watches, pulls a camera's stream from the NVR over RTSP and publishes it unchanged (H.264 or H.265 video, G.711 audio) to the media server; a stream that stalls or drops reconnects by itself;
• plays back recordings the same way, searches recordings, and moves PTZ cameras;
• writes every alarm to a durable queue on its disk and uploads it in order, so alarms survive restarts and Internet outages and arrive exactly once;
• reports every NVR and every stream at least every 30 seconds;
• updates itself when Sphere has a newer version (Updates).

Downloading, 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). It does not have to be joined to a domain. The computer of an Edge connector can run the Sphere connector too.

• Outbound only, nothing inbound:

  To	Port	For
  hub.entrosity.com	TCP 443	Sphere's API and WebSocket (HTTPS)
  media.entrosity.com	TCP 8322	The media server (RTSP over TLS): video, only while someone watches

• To each NVR on the LAN: its HTTP port (80) or HTTPS port, and its RTSP port (554), as set on the NVR in Sphere.

• Upload bandwidth for the streams watched at the same time. Each stream is uploaded once, whatever the number of viewers; the connector publishes at most 64 streams at once (a full 8×8 grid).

• One connector per site network is usual; it drives every NVR it reaches. A computer that enrolls again (same name and domain, same tenant) replaces its earlier registration: the old key stops working.

NVRs serve self-signed HTTPS certificates for their LAN address; the connector does not verify them (digest authentication never sends the password itself). The media server's certificate is verified.

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 belongs 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.

Download the installer

Download connector on the Connectors page shows the newest connector version published to Sphere and downloads its installer, sphere-connector-<version>.msi. Each click fetches a fresh link that works for one hour without signing in, so you can also paste it into a browser on the site's computer. The token dialog's Download the connector installer points to the same installer (also for an hour).

Before any connector build has been published to Sphere, the button is disabled (No connector build has been published yet.) and the dialog links the server's download address, if one is configured; otherwise get sphere-connector.msi (and its sphere-connector.msi.sha256) from your Entrosity release page.

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. The command names the file sphere-connector.msi: rename the download, or put its name (sphere-connector-<version>.msi) in the command.

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

The MSI:

1. installs sphere-connector.exe to %ProgramFiles%\Entrosity Sphere Connector\;
2. enrolls the computer with the token (as SYSTEM). A failed enrollment rolls the installation back;
3. installs and starts the Windows service SphereConnector (display name Entrosity Sphere Connector, LocalSystem, automatic start), set to restart 30 seconds after each of its first three failures.

The connector appears in Connectors as Online within a minute.

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

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 Sphere Connector\sphere-connector.exe" enroll --server https://hub.entrosity.com/sphere --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 SphereConnector and sc start SphereConnector).

sphere-connector status shows the enrollment, the number of NVRs and how many alarms are waiting for the server. All commands: Sphere connector.

The connector list

Connectors lists each connector with its Name, the Computer it runs on, its Status (Online or Offline), the number of NVRs it drives, its Version and when it was Last seen.

When a newer connector version is published, tenant admins see next to an older Version:

• updating to X: the connector updates itself and installs X within a few minutes (Updates);
• update to X, in amber: the connector cannot update itself (a build from before self-updates). Install the new version once from Download connector on its computer (Upgrade by hand); from then on it updates itself.

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.

When a connector goes offline:

• its NVRs show Unknown, and live view, playback, PTZ and recording searches on them are refused until it is back (tiles say The NVR is not connected. or The connector is offline.); Overview says how many connectors are offline;
• the NVRs keep recording on their own disks;
• alarms the connector has already received stay in its queue on disk and are uploaded in order when the connection is back. While the connector itself is stopped (the computer is off, the service is stopped), it does not receive the NVRs' events, and they are not in Sphere;
• changes you make to NVRs (connect, disconnect, new address or password) wait and are sent when it reconnects.

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: Sphere offers a newer version, and the connector installs it without anyone at the computer.

• What: the newest version of the server's update channel (set by the server's operators): stable gets tagged releases only; dev gets development builds as well as tagged releases. While Sphere is in beta, production follows dev.
• When: Sphere offers it when the connector connects and every 5 minutes after that, as long as it is newer than the connector's version. The same version is not offered again within an hour, and never while an earlier update is still under way. Version shows updating to X meanwhile.
• How: the connector checks that the release is signed by Sphere, downloads the installer and installs it a minute later. The service restarts on the new version; the NVRs keep recording, streams reconnect and alarms 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 Sphere Connector\logs\connector.log, connector update finished) when the service starts again; the new Version shows in Connectors.

Connectors installed before self-updates

A connector built without the release key cannot update itself: its Version shows update to X in amber. Install the new version once from Download connector on its computer (below); from then on it updates itself.

Connector releases

Global admins see every stored connector installer (the newest ten) under Administration → Connector releases:

• Version, Channel (stable or dev), size, when it was published and the start of its SHA-256; Current marks the release connectors are updated to.
• Download saves that version's installer (sphere-connector-<version>.msi); each click gets a fresh link valid for one hour.
• Connectors by version counts the enrolled connectors by the version they report, to see which ones still need a manual update.
• Release public key: the key connector builds verify releases with.

Updates need the server set up for them (Running Entrosity Sphere → Connector releases). Details: Sphere connector → Self-update.

Upgrade by hand and uninstall

• Upgrade by hand: run the newer MSI (msiexec /i sphere-connector.msi /qn, no properties needed). Data stays in %ProgramData%\Entrosity Sphere Connector, so the connector stays enrolled. An older MSI installs over a newer one too (the self-update rollback needs it).
• Uninstall: from Apps & features, or msiexec /x sphere-connector.msi /qn. This removes the service, the program, the enrollment, the list of NVRs with their credentials, and the alarm queue: alarms not yet uploaded are lost. The logs are kept. Then remove the connector in Sphere (below).

Remove a connector

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

A connector that still drives NVRs cannot be removed (connector_has_nvrs): delete its NVRs first (NVRs).

Troubleshooting

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 a Sphere 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 Sphere Connector\logs\connector.log.
NVRs are Online, but video never starts (media_publish_failed, or the connector did not answer)	Outbound TCP 8322 to media.entrosity.com is blocked, or a proxy intercepts TLS on it.
A stream fails with codec_unsupported	The channel streams MJPEG, or a codec the relay cannot pass through. Change the stream's encoding on the NVR.
It was removed in Sphere	Its key no longer works (connector_unauthorized) and it stops. 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.
Version shows update to X in amber	The connector cannot update itself. Install the new version once from Download connector on its computer.
Version keeps showing updating to X	The update failed or was rolled back. Read connector update finished in the connector log (status rolled_back or failed, and the reason); Sphere offers the version again after an hour.