Installing a controller

What you need

• A Raspberry Pi 4 or 5 with a 64-bit OS, or a small x64 Linux box.
• A relay board for each barrier, and a weatherproof enclosure with a tamper switch.
• A network connection (wired is best) and, for keypads and readers, the parts in Readers, tags and cameras.

Install

1. Register the controller. In the admin web app, open Gates → Gate controllers → Register controller and choose its gate. Copy the controller id and secret; the secret is shown only once. (Petra Platform staff can also enrol it for you, which produces the whole settings file.)
2. Install the software. Each release has ready-to-run builds for linux-arm64 (Raspberry Pi) and linux-x64. Unpack it on the box and put the appsettings.json beside the program. Run it as a system service so it starts with the box. A Docker image is available too.
3. Set the lanes. In appsettings.json, give each lane its id (from the admin web app), the GPIO pin of its barrier relay, how long to pulse it, and its direction.
4. Check it. On the box, http://127.0.0.1:5090/status shows the controller’s identity, its copy of the estate’s data, its lanes and what is waiting to upload. In the admin web app, the controller shows as online on Gates.

appsettings.json (the parts you set)

{
  "Controller": {
    "ApiUrl": "https://app.virelass.com",
    "ControllerId": "…",
    "Secret": "…",
    "Hardware": {
      "Mode": "Gpio",
      "Lanes": [{ "LaneId": "…", "RelayPin": 17, "Pulse": "00:00:00.800", "Direction": "In" }],
      "TamperPin": 27
    }
  }
}

Settings

Setting	Default
Controller:ApiUrl		The Petra Platform service, e.g. https://app.virelass.com
Controller:ControllerId, Secret		From Register controller
Controller:DataDirectory	data	Where the controller keeps its copy of the estate’s data and its upload queue
Controller:Mqtt:…	none	The message broker for instant updates and remote commands. Without one the controller still syncs every five minutes
Controller:Hardware:Mode	Simulator	Gpio on a real box
Controller:Hardware:Lanes		Each lane’s id, relay pin, pulse and direction
Controller:Hardware:ConsoleLaneId		The lane that USB keypads and QR scanners belong to
Controller:Hardware:TamperPin		GPIO input wired to the enclosure switch (high = open)

If a box is lost or stolen

Revoke it in the admin web app (Gates → Gate controllers → Revoke), then Rotate offline secrets. What the lost box holds stops working once the other controllers resync.