Controllers, doors and readers

Controllers lists the access controllers of the tenant. Every controller is reached through one connector, has one or two doors, and up to two readers that serve those doors.

Adding, changing and removing controllers, doors and readers needs the Tenant admin role; operators can send a configuration again; everyone can look (Roles and permissions).

Controller types

The Controller type selects the connector's driver:

Type	Driver	Status
Simulator (no hardware)	simulator	Complete. Software controllers inside the connector, for trials, demos and tests (Trying Edge with the simulator).
TRAcK ACCESS TrackBase002	trackbase002	Not yet verified. The connector speaks the controller's protocol over TCP: it configures the controller, reads its events, sets its clock and opens its doors. It needs the controller's PIN, set in Edge (Controller PIN). See TrackBase002 controllers.

TrackBase002 controllers

Verify on one controller first

The protocol was reverse-engineered from the vendor's server software and has not been verified against a live controller yet. Try it on one controller before moving a site over. The connector log at debug level shows every exchange with the controller (the PIN masked).

Before you add one:

• Have the controller's PIN at hand: enter it in Controller PIN when you add the controller (Controller PIN). Without it the controller is Offline with the error the controller's PIN is not set: set it in Edge, and its configuration Failed with config_rejected.
• Clear the controller's card memory with the vendor's tools. Edge cannot list or clear a controller's cards: cards enrolled earlier by the vendor's software and not in Edge's configuration are not removed.
• Reach it over TCP/IP. RS-485 (serial) is not supported: the configuration Failed with unsupported.

What the controller can hold:

• A card is stored with one time zone, so it must have the same schedules at every door it opens. Otherwise the configuration is Failed with config_rejected, naming the card.
• Each distinct set of schedules becomes a time zone of the controller: at most 16 per controller, at most 8 time windows per day each (windows of overlapping or adjacent schedules are merged). More: config_rejected.
• Card numbers are 24-bit. Wiegand 26 cards fit (facility code and number); iButton keys must fit in 6 hex digits. Two credentials with the same 24-bit number: config_rejected. A full memory: capacity_exceeded.
• Holidays are not enforced: weekday times apply on them, and the controller shows the warning holidays are not enforced by TrackBase controllers: weekday times apply on them.
• iButton readers (readers 3 and 4) accept every enrolled card at every door, as the vendor's own software does. The controller shows a warning when that matters.

How it works:

• Changes are sent as the difference to what was last applied. Send configuration again rewrites every time zone and card.
• Events are read from the controller's event log (31,968 records). A new controller is read from its current position: older events are not imported. Card reads arrive as granted, denied or unknown card with the door, reader, direction and credential. The controller does not record whether it opened, so the connector decides from the configuration it applied (without holidays). Other records (temperatures, inputs) are not shown yet.
• After a connector restart, events arrive once the configuration has been applied again: automatically when the controller is online, retried every minute.
• The connector sets the controller's clock, in the configuration's time zone, whenever it is more than 2 seconds off.
• Remote opening operates the door's Lock relay; the controller releases it after its own relay time, so the Unlock time (ms) set in Edge is not sent.
• Online or Offline comes from a status read, at most every 30 seconds. Door states stay Unknown: they are not reported yet. The missing PIN and the warnings above are shown as the controller's error.
• Firmware shows the controller's version and type, e.g. 0123 (type 02).

Add a controller

Choose Add controller (at least one connector must exist) and fill in:

Field	Meaning
Connector	The connector that reaches the controller. Preselected when there is only one; offline connectors are marked (offline).
Name	For example Main entrance; 1–200 characters.
Controller type	See Controller types. Cannot be changed later.
Connection	TCP/IP, or RS-485 (Modbus).
Address	host:port, e.g. 192.168.1.50:5000; for RS-485 the serial port or the Modbus gateway.
Bus address (1-31)	RS-485 only: the controller's unit address on the bus.
Doors	Two doors, one reader each, or One door with entry and exit readers (see Door modes). Can be changed later (Change the doors layout).
Site	Its site (the schedules follow the site's time zone), or No site (the tenant's default time zone).
Controller PIN	TrackBase002 only, optional: the PIN the controller was set up with (the one the Track Access software used), a number from 1 to 4294967294. Without it the controller is added but does not work until a PIN is set (Controller PIN).

Choose Add controller. Edge creates the doors and readers and sends the configuration right away (Controller added: its configuration is on its way.).

One connector cannot have two controllers on the same address (and bus address): controller_address_taken.

Find controllers

Instead of typing the address, choose Find controllers. The connector looks for controllers and the dialog lists what answered (Found 2: pick one to fill in the form.). Picking one fills in the address, the connection, the bus address, the door mode and the model, serial number and firmware.

• Simulator: every simulated controller of the connector is listed.
• TrackBase002: enter the Addresses to probe (one per line) first (up to 256). Discovery has no PINs: each address that answers on TCP is listed, without its firmware. Add it with its Controller PIN; Test connection then shows the firmware.

Discovery needs an online connector (connector_offline otherwise) and gives up after two minutes.

Door modes

Door mode	Doors	Readers
Two doors, one reader each (two_unidirectional)	Door 1 (lock relay 1), door 2 (lock relay 2), named <controller> – door 1 and – door 2	Wiegand 1: entry to door 1; Wiegand 2: entry to door 2
One door with entry and exit readers (one_bidirectional)	Door 1 (lock relay 1), named like the controller	Wiegand 1: entry; Wiegand 2: exit

New doors have an unlock time of 3,000 ms and a held-open alarm after 30 seconds.

Change the doors layout

Doors in Edit controller switches between the two modes. Edge rebuilds the doors and readers as adding the controller with the new mode would, keeping what stays:

• Door 1 always stays, with its name, lock relay, unlock time and place in access groups. Its door id does not change, so its history stays with it.
• One door → two doors: door 2 is added (lock relay 2, or the first relay door 1 does not use; named <controller> – door 2) and the Wiegand 2 reader becomes its entry reader. Door 2 is in no access group yet: add it to the groups that should pass it.
• Two doors → one door: door 2 is removed and the Wiegand 2 reader becomes door 1's exit reader. While access groups use door 2 this is refused with door_in_use (409), naming the groups (door "Main entrance – door 2" is used by the access groups Staff: remove it from them first); the dialog shows it under Doors. Remove door 2 from those groups first. Door 2's events stay in the access log.
• Readers keep their name and whether they are enabled; their door and direction follow the new layout.

The dialog explains what will happen before you save. The new layout is sent to the controller right away, like a new address.

The controller list

Column	Meaning
Name	Opens the controller.
Site	Its site.
Address	Its address; #n is the RS-485 bus address.
Connector	The connector that drives it.
Status	Online, Offline, Error (online but reporting a problem, shown on the controller's page), Unknown (its connector is offline, or it has not reported yet) or Disabled (Disable a controller).
Configuration	The sync status: In sync, Pending, Syncing, Failed (the reason on hover) or Disabled. See Configuration sync.
Cards	Cards on the controller out of its capacity, e.g. 412 / 2000.

The controller page

Overview

Connector, Site, Model, Serial number, Firmware (as reported by the controller), Last seen, the Configuration status with the Applied version and the Wanted version and when it was last applied, and the Cards it holds out of 2,000. A problem the controller reports (status Error) is shown below.

A TrackBase002 also shows Controller PIN: Set or Not set (Controller PIN).

When the connector is offline the page says so: The connector is offline: changes are applied when it reconnects.

Controller PIN

A TrackBase002 only answers commands that carry its PIN. The Controller PIN row of the Overview shows whether one is set; the PIN itself is never shown again once saved.

• Set PIN (or Change PIN when one is set) asks for the PIN: a number from 1 to 4294967294, the one the controller was set up with. Save PIN (PIN saved: the connector uses it from now on.).
• Clear PIN deletes it from Edge after a confirmation; the connector cannot reach the controller until a PIN is set again.
• Without a PIN the page warns: Set the controller's PIN: the connector cannot reach the controller without it.

Setting, changing and clearing the PIN needs the Tenant admin role. Edge stores the PIN encrypted with the server's master key and sends it to the connector only with each job for the controller; the audit log records only whether a PIN is set. A new or cleared PIN sends the configuration to the connector again.

• The server needs EDGE_MASTER_KEY for PINs. Without it saving or clearing one fails with master_key_missing (controller PINs need EDGE_MASTER_KEY on the server).
• If the server can no longer decrypt a stored PIN (its master key was lost or changed), the controller's configuration Failed with controller_pin_unavailable: set the PIN again.

Doors

Each door with its name, Lock relay (1–4), Unlock time (ms) (100–60000: how long the lock is released on access or remote opening), and State (Locked, Unlocked, or Unknown until the controller reports it). Tenant admins change the name, relay and unlock time and choose Save; a change to the relay or the time is sent to the controller. Operators and tenant admins open the door from here too (Doors and remote opening).

The held-open alarm time (0–3600 seconds, 0 = never) is set through the API (Edge API).

Readers

Each reader with its Channel (wiegand1, wiegand2, ibutton1, ibutton2), its Name, the Door it serves, its Direction (Entry or Exit) and whether it is used (Enabled or Disabled). Tenant admins name readers (e.g. Lobby entry; up to 200 characters, Save appears once the name changes), change the door and the direction and switch readers on or off; a change to the door, direction or state is sent to the controller. A disabled reader opens nothing.

Activity

The controller's recent jobs: configuration applies, tests, door openings, with their Status (Created, Sent, Acked, Running, Succeeded, Failed, Timeout, Cancelled) and Error.

Test the connection

Test connection asks the connector to reach the controller and report what it is: The controller answered: TrackBase002, or The controller did not answer: … with the reason.

Send the configuration again

Send configuration again (operators and tenant admins) sends the controller's complete configuration even if Edge believes the controller holds it: after a controller was replaced, reset or changed by hand. Edge also does this by itself when the controller reports a different configuration than the one it last confirmed.

Edit a controller

Edit controller in the header of the controller's page (tenant admins) opens a form with the controller's current settings:

Field	Meaning
Name	1–200 characters.
Site	Another site, or No site.
Connection	TCP/IP or RS-485 (Modbus).
Address	As when adding it.
Bus address (1-31)	RS-485 only.
Doors	The doors layout (Change the doors layout).

Save sends only what changed (Controller saved); errors the server finds are shown on their field. The controller type cannot be changed, and the PIN has its own dialog (Controller PIN).

• A new site sends the configuration again (its time zone).
• A new address, connection or bus address, a new PIN, and a new doors layout send it again too, even when the configuration itself is unchanged: the connector then updates how it reaches the controller.
• Through the API it is PATCH /tenants/{tenantID}/controllers/{controllerID} with any of name, site_id or clear_site, transport, address, unit_id, door_mode, pin, clear_pin or enabled (Disable a controller).
• A disabled controller can be edited too; the changes are sent when it is enabled again.

Disable a controller

Disable controller in the header of the controller's page (tenant admins) makes Edge and its connector leave the controller entirely alone, for example while the vendor's old software manages it or while it is serviced. A confirmation explains what stops; after it:

• The connector stops polling, configuring and setting the clock of the controller: Edge cancels its configuration jobs still on their way and sends the connector edge.controller.remove, as when the controller is removed. The controller keeps what it holds and works on its own.
• Card, cardholder, group, schedule and holiday changes are not sent to it, and Edge does not retry: nothing is queued for it while it is disabled.
• Its events are not collected, and what the connector may still report about it (status, doors) is ignored.
• Its Status and Configuration show Disabled, in the list and as a badge in the page header, and the page says This controller is disabled. It is not counted on the dashboard (neither in the controllers online and total, nor as pending or failed).
• Open door, Test connection and Send configuration again are hidden. Through the API, opening one of its doors, testing it and resyncing it are refused with controller_disabled (409).
• Its settings can still be changed: the name, site, connection, PIN, doors layout, doors and readers. Nothing is sent until it is enabled again.

Enable controller (after a confirmation) reverses it: the configuration is sent again in full (Pending, then Syncing), including every change made while the controller was disabled, and the connector starts driving it again as it applies it.

Disabling and enabling are recorded in the audit log as controller.update (enabled in the before and after). Through the API it is PATCH /tenants/{tenantID}/controllers/{controllerID} with enabled: false or enabled: true; controllers carry enabled, and a disabled one has sync_status disabled.

Remove a controller

Remove controller (confirm) removes the controller with its doors and readers, and access groups lose those doors. The connector stops driving it. The access log keeps its events.