Configuration sync and troubleshooting
How sync works
Every controller holds a complete configuration, a snapshot of everything it needs to decide on its own:
- its door mode, doors (lock relay, unlock time, held-open time) and enabled readers;
- the schedules its doors use, and the holidays of the next 90 days, in its local time zone;
- every card that may pass at least one of its doors, with the doors and schedules it may use there (at most 2,000 cards).
Edge never sends partial changes. Every change that affects a controller (a card, a cardholder's status or groups, a group's doors or members, a schedule, a holiday, a door or reader, a site's time zone) gives the controller a new wanted version. Edge then compiles the controller's configuration and sends it through the connector as one job. When the connector reports that the controller holds it, that version becomes the applied version.
- A burst of changes (importing people, editing a group) is merged: the controller receives the newest configuration once, and an older job still on its way is cancelled.
- A change that does not alter what the controller holds (for example a card of someone without access there) is confirmed without sending anything.
- If the controller reports a configuration different from the one it last confirmed (it was reset, replaced or changed by hand), Edge sends the configuration again by itself. After a restart, the connector also restores the last configuration to controllers that lost it.
- Every 5 minutes Edge re-queues every controller whose wanted version was not applied yet: after a connector was offline, a lost job, or a sync that got stuck.
Sync statuses
The Configuration column of Controllers and the controller's page show:
| Status | Meaning |
|---|---|
| In sync | The controller holds the wanted version. |
| Pending | There is a newer configuration; it has not been sent yet (normal for a second; longer while the connector is offline). |
| Syncing | The configuration was sent; the connector is applying it. |
| Failed | It could not be applied. The reason is shown on hover and the code is listed below. The controller keeps working with the last configuration it applied. |
| Disabled | The controller is disabled: nothing is sent to it until it is enabled again, which sends its complete configuration (Disable a controller). |
The controller's page shows the Applied version and the Wanted version side by side, and when the configuration was last applied. Send configuration again forces a full resend.
Troubleshooting
Capacity exceeded
Failed with controller_capacity_exceeded: 2150 cards have access
through this controller; it holds at most 2000. The configuration was not
sent; the controller keeps its previous one. Its Cards column shows
the count it would need, e.g. 2150 / 2000.
A TrackBase002 holds 2,000 cards. Count only what the controller needs: active cards of active, valid cardholders in groups that have one of its doors. To fix it:
- remove groups from this controller's doors that do not need them, or split a large group so fewer people have these doors;
- mark unused cards Lost or delete them, suspend people who left;
- move doors that many people use to another controller.
Edge tries again with every change and every 5 minutes, and sends the
configuration as soon as it fits. capacity_exceeded (without the
controller_ prefix) is the same limit reported by the connector, or a
TrackBase002 whose card memory is full.
Too many schedules
Failed with too_many_schedules: the doors of this controller use more
than 255 different schedules across their access groups. Reuse schedules
across groups.
Rejected by a TrackBase002
Failed with config_rejected, with the cause in the reason. A
TrackBase002 cannot hold the configuration when:
| Cause | What to do |
|---|---|
| A card has different schedules at different doors of the controller (the reason names the card) | Give the card's cardholder the same schedules at every door of this controller, e.g. through one access group. |
| More than 16 different sets of schedules | Use fewer distinct schedule combinations on this controller's doors. |
| More than 8 time windows a day in one set of schedules | Simplify the schedules (overlapping or adjacent windows are merged already). |
| An iButton key over 24 bits (more than 6 hex digits) | Replace the key, or take away its access to this controller's doors. |
| Two credentials with the same 24-bit card number | Remove or replace one of them. |
| No PIN set for the controller (the controller's PIN is not set) | Set it on the controller's page (Controller PIN). |
A full card memory fails with capacity_exceeded. Limits:
Controllers → TrackBase002 controllers.
A controller is offline
Status Offline: the connector cannot reach the controller. A Controller offline event is in the log.
- Check power and the network or bus: ping the address from the connector computer, check the RS-485 wiring and the bus address.
- Test connection on the controller's page shows the connector's error.
- TrackBase002: check its PIN. With a wrong PIN the controller does not answer (check the controller's PIN); without one the error says the controller's PIN is not set: set it in Edge (Controller PIN).
- A configuration sent while it is offline fails with
controller_unreachable; once it is back, the 5-minute reconcile or Send configuration again delivers it. - Events stay in the controller's memory and are read when it is back.
Status Error means the controller answers but reports a problem; the controller's page shows it.
A connector is offline
The connector's Status is Offline and its controllers show Unknown. The dashboard warns: their controllers keep working on their last configuration, and events arrive when they reconnect.
- On the connector computer, check that the
EdgeConnectorservice runs (sc query EdgeConnector), and read%ProgramData%\Entrosity Edge Connector\logs\connector.log. - Check outbound HTTPS to
hub.entrosity.com. edge-connector statusshows the enrollment and the events waiting to be uploaded.- If the connector was removed in Edge, or the tenant suspended, its key no longer works: enroll it again (Connectors).
While it is offline, changes stay Pending, remote opening and
discovery are refused (connector_offline), and events wait on the
controllers and in the connector's queue. When it reconnects, it receives
the newest configuration of each of its controllers.
Sync failed for another reason
| Code | Meaning | What to do |
|---|---|---|
controller_unreachable | The connector could not reach the controller. | See A controller is offline. |
unsupported | The driver cannot reach the controller over this connection (a TrackBase002 on RS-485/serial). | Reach the controller over TCP/IP (TrackBase002 controllers). |
config_rejected | The controller (or the connector's check) refused the configuration. | For a TrackBase002 see Rejected by a TrackBase002. Otherwise send it again; if it persists, check the controller's page and the connector log. |
unknown_driver | The connector version does not have this controller's driver. | Update the connector (Updates). |
controller_pin_unavailable | Edge cannot decrypt the controller's stored PIN: the server's EDGE_MASTER_KEY was lost or changed. Nothing was sent. | Set the PIN again (Controller PIN). |
timeout | The connector did not apply the configuration in time (10 minutes), or never answered. | Check the connector; the reconcile retries. |
connector_removed | The controller's connector was removed (rare: connectors with controllers cannot be removed). | Remove the controller and add it again under an enrolled connector. |
exec_failed | The connector restarted while applying. | The reconcile retries. |
All codes: Error codes.
A card is refused
Open the event in the Live monitor:
| Event | Check |
|---|---|
| Unknown card | Is the card registered with exactly this facility code and number (the same 10-digit card number, or iButton id)? Assigned to a cardholder? Active? Is the cardholder Active and inside the validity period? Is the controller In sync? |
| Access denied — no access to this door | Add one of the cardholder's groups to this door. |
| Access denied — outside the schedule | Check the schedule's windows and the controller's time zone (its site). |
| Access denied — holiday | Today is a holiday: add holiday windows to the schedule if the door should open. |
Events are missing or late
- The connector is offline or cannot reach Edge: events wait and arrive in
order when it is back (
edge-connector statusshows the backlog). - The controller is offline: its events are read when it is back.
- An event with a note about the controller clock was stored at the time it arrived: set the controller's clock.