Docs / Start

Installing the Connector

Where the Rotorloop Connector runs, what network access it needs, and how to install it with one command.

Where it runs

Any always-on computer that can reach your controllers: a facilities PC, a server or virtual machine, or a small dedicated box. It is one small background process, needs no inbound ports, and leaves the computer free for its other work.

Windows 10/11 or Windows Server 2019 and later.
Linux on x86-64 or ARM64 (for example Ubuntu 22.04+ or Debian 12+).
It must be on the same network segment as the controllers, or able to route to them. See BACnet across subnets below.

The Connector needs Node.js 22.18 or later on that computer. Install it first from nodejs.org. During early access we also set it up with you on a short call.

Install it

In Rotorloop, go to Admin › Site connectors and add a connector. The panel shows the connector token once, together with the install command for each system. The installer asks you to paste the token, so it never ends up in your shell history.

Windows

Open PowerShell with Run as administrator and run:

irm https://app.rotorloop.com/connector/install.ps1 | iex

Linux (systemd)

curl -fsSL https://app.rotorloop.com/connector/install.sh | sudo bash

What the installer does

Downloads the single-file Connector and checks its SHA-256 checksum before using it.
Stores the token where only the service can read it: SYSTEM and Administrators on Windows, or the rotorloop service user on Linux.
Writes a connector.json with BACnet discovery turned on. You can add Modbus devices to it afterwards.
Starts the Connector at boot:
- Windows: a scheduled task named Rotorloop Connector runs as SYSTEM and restarts on failure. Log: C:\ProgramData\Rotorloop\connector.log.
- Linux: a locked-down systemd service, rotorloop-connector, runs under its own user. Logs: journalctl -u rotorloop-connector -f.
On Windows, adds a firewall rule allowing inbound UDP 47808 for Node.js on Domain and Private networks, so BACnet replies get through.

The installers are new in Rotorloop 0.4. Their download, checksum and configuration steps have been tested. The step that registers the Windows scheduled task or the Linux service has not yet been run on a customer machine, so we're with you for the first install.

Network access

Direction	Port	Why
Out to the internet	`TCP 443`	One encrypted WebSocket to Rotorloop. Works through most proxies. Nothing inbound from the internet.
To the BACnet network	`UDP 47808` (0xBAC0)	Discovery (Who-Is / I-Am), reads and writes. The Connector's computer must also accept UDP 47808 replies, so allow it in the local firewall (Windows Defender Firewall blocks it by default).
To Modbus devices	`TCP 502`	Reads and writes to Modbus TCP devices and to Modbus RTU gateways.

The Connector never accepts connections from the internet and never puts your controllers on it. It is the only thing at the site that talks to Rotorloop.

The config file

The Connector reads one JSON file that names the site connector and lists the systems it should talk to. The token is not in this file: it comes from the ROTORLOOP_TOKEN environment variable.

{
  "connectorId": "conn-main-building",
  "cloudUrl": "wss://YOUR-ROTORLOOP-ADDRESS/v1/connect",
  "pollSec": 5,
  "stateFile": "connector-state.json",
  "systems": [
    { "id": "sim", "driver": "simulator", "name": "Simulated rooftop units" }
  ]
}

cloudUrl: the address you get with the connector token.
pollSec: how often values are read, in seconds (default 5).
stateFile: where active holds and point settings are kept, so holds still end on time after a restart or while offline. Keep it on a local disk.
systems: one entry per connection. Each names a driver. The options for each driver are listed in Connecting systems.

Running it by hand

The installer is the normal route. For testing, you can also run the Connector directly with Node.js. Put the token in the ROTORLOOP_TOKEN environment variable and start the Connector with --config connector.json. It runs in the foreground and logs to the console.

Docker

A container image is planned. BACnet discovery uses UDP broadcast, so the container will need host networking (--network host) on Linux. Sites with only Modbus can use normal bridged networking.

BACnet across subnets

BACnet discovery uses broadcasts, which routers don't pass. If controllers sit on a different subnet from the Connector, you have two options:

Put the Connector on the controllers' subnet, often with a second network card or a VLAN.
List those controllers in connector.json by address. A device behind a BACnet router is listed by the router's address plus its network number and station address. See Connecting systems.

Registering with the site's BBMD as a foreign device is planned.

Updating and removing

Update: run the same install command again. It replaces the Connector and keeps your settings, holds and token.
Remove on Windows: run the same command and type remove when asked.
Remove on Linux: sudo systemctl disable --now rotorloop-connector.
Retire a computer: revoke its connector in Admin › Site connectors. It's disconnected at once and its token stops working.

Applies to Rotorloop 0.4 (development preview). Last reviewed November 2026.