Chapter 17

Troubleshooting and FAQ

Work down the section that matches the symptom. Most problems show up in the Log (chapter 11) or on the Controllers page (chapter 5), so start there.

A controller shows offline

"Offline" means the panel has not heard from the controller for 10 minutes. The door is still working from its saved keyset; what has stopped is updates and event reporting.

1. Power. Is the board lit? Is the PoE switch port up? A controller that reboots every 30 seconds (watchdog) may have a wiring fault shorting a pin.
2. Network. For Wi-Fi: is the SSID still the same, was the password changed, is the signal adequate at the door, and is it 2.4 GHz? For PoE: link light, and does the site DHCP hand out an address?
3. Reach the panel. From a laptop on the same site network, can you connect to the panel address on port 1883 (for example Test-NetConnection doors.example.com -Port 1883 on Windows)? "False" while 443 is "True" means a firewall is blocking 1883 outbound at the site or inbound at the panel.
4. Firewall rule loaded? If a pass rule exists but its counters stay at zero and traffic still hits the default deny, the firewall may not have loaded its rule set. On pfSense, a failing filter reload (for example caused by an oversized pfBlockerNG list) makes every new rule inert while the interface looks normal. Fix the reload error, then re-test. Useful diagnosis order: packet capture on the panel (no packets arriving = dropped upstream), then the firewall's state table and firewall log (which rule matched).
5. Credentials. If the panel's broker requires a username and password and the controller has the wrong ones, it connects and is refused (serial console shows mqtt connect failed rc=5). See "A re-pointed controller never came back" below.
6. Serial console. Plug the controller into a laptop and open a serial monitor at 115200 baud. It prints ACS-WAIT uid=... mqtt=host:port link=down every 5 seconds while it cannot reach the broker, and net: mqtt connected when it can. ACSCFG? typed into the console dumps its settings.
7. Re-provision. On Flash & adopt, step 3, use Query device then Send settings to device over USB (or Bluetooth in setup mode) to rewrite the Wi-Fi, address and credentials.

A fob is denied

Look at the reason in the Log or use Check access on the dashboard with the fob code.

A fob that is granted at one door and refused at another is nearly always an access-level question: the second door is not in any of the person's levels.

Problems after an import

Imported fobs are denied at the door

The log says Unknown fob for people who were imported from a CSV or an AC8000 backup, yet their fob is on their page.

• Compare the two codes. Open the person's page and note the fob code, then look at the code in the log row. The panel matches a fob whether it was stored with 6 or 8 hexadecimal digits (leading zeros do not matter), so 0136A9 on the person will match a reader sending 000136A9. If the digits themselves differ, the wizard was told the wrong reader format or the CSV's decimal box was set wrongly: re-run the import with the other setting (existing people are skipped, so nothing is duplicated) or correct the code on the person.
• Check the reader type. A Wiegand 26 reader sends 24 bits of card number and cannot read a card whose number is above 16,777,215 (hexadecimal FFFFFF): it sends a truncated code that will never match. If the backup contained numbers that large the wizard will have said so and set 8 digits; the readers at the door then need to be Wiegand 34 (or the same model the old system used). A reader that sends 26 bits shows wiegand: 26 bits -> ... on the serial console when a fob is presented; 34 bits for the wider format.
• Nothing in the log at all: the scan never reached the panel; see "A fob is denied" above.

The wizard says it cannot read the file

"Could not read that file" under the file box means the browser could not find the AC8000 tables in what you chose. The wizard needs the database backup made by the AC8000 / iCCard3000 PC software, which is a Microsoft Access file with an .mdb extension. It cannot read a printed report, a spreadsheet, a CSV or any other export from that software: for those, use the CSV / spreadsheet export source instead. If the file is genuinely the backup and still fails, make it again from the old software (a backup taken while the software was writing can be incomplete), and try in a current browser: the file is parsed by the page itself, so an old browser or a content blocker that stops the page's scripts will also produce this message. "parser not loaded" means exactly that: reload the page and choose the file again.

History imported but people show as unknown

Imported history rows are matched to people by fob code. A row with no name and the reason Unknown fob means the card that made that swipe was not in the backup's people list when the backup was taken: a card that had been deleted from the old system, a visitor's card, or a card the old system itself refused. That is what the old system recorded, so the rows are correct as they stand. If the card does belong to someone, add it to them (chapter 6): future scans will show the name, but history rows already written are not re-linked.

The door does not release

• The log shows granted but the lock does not move: the relay is not wired to the expected pin, the relay active level is wrong (relay energised at rest and de-energised on grant), or the lock supply is off. Press Unlock on the Controllers page and listen for the relay click. Check the pulse length is not zero.
• The lock releases for the exit button but not for a fob: access-level or schedule problem; see above.
• The lock releases but only for a moment: normal; the pulse is 4 seconds by default. Lengthen it in Settings and re-provision, or fit a door closer that does not need longer.
• The maglock never holds: the relay contact is on the wrong side (NO versus NC) for a fail-safe lock, or the active level is inverted. Recheck the wiring against chapter 3.
• The door releases on power-up: the relay module is active low and the panel says active high (or the reverse), so the board's "off" state is the relay's "on" state. Change Relay active level in Settings and re-provision.

Phone unlock says "not recognised"

1. Is the caller's number on the person? Under Details, the Phone must match the caller ID on the last nine digits. Withheld numbers cannot match.
2. Is release by phone allowed? The tick "Allow this person to release doors by phone" and at least one door must be set, and the person must be Active.
3. Is the PBX pointed at the right panel with the right token? [door_release] ... http=401 in the Asterisk console (or /tmp/door_release.log) means the token is wrong; http=0 means the PBX cannot reach $BASE.
4. Does the door have an active controller? A release to a door with no active controller is refused with no_controller and logged.
5. Apartment mode: the apartment number is digits only, the PIN is 4 to 10 digits, and the doors are ticked on the resident's page. After five wrong PINs the apartment is locked for a rising period; wait, or set a new PIN (which resets the lockout).
6. Rate limited: a burst of more than 10 calls from the PBX address in a few seconds is refused; wait a few seconds.

The Log has a line for every call with the outcome in the detail column.

Held-open and forced alerts keep appearing

• Door held open on every opening: the door's held-open time (60 s by default) is shorter than the time the door is genuinely open, for example a loading door. Fit a stronger closer, or open the door's page and raise Alert if held open for N seconds (or set it to 0 to switch the alert off for that door). The new value reaches the controller within seconds if it runs the current firmware; older firmware ignores it and keeps 60 s (or the heldOpenMs in its pin map) until it is updated from the Controllers page.
• Door forced on every opening, even legitimate ones: the door sensor is wired the wrong way (open when the door is closed), or the sensor is on a different pin from the one in Settings. The controller expects the contact closed (to 0 V) when the door is closed.
• Both alerts constantly with the door shut: a loose or broken sensor cable. Set the door pin to -1 in Settings and re-provision to silence the alerts until it is fixed.
• No alerts ever: no sensor fitted, or the pin is -1, or (held open only) the door's held-open time is 0. Check the Log for Door opened / Door closed lines first: if they appear, the sensor works and the alert settings are the problem.
• Alerts are in the Log but no Telegram message arrives: see below.

Telegram test message fails

The red message after Send test message or Find my chat ID says what Telegram objected to; chapter 4 has the full table. The three most common:

• 401 Unauthorized / rejected the bot token: the token has a typo, is incomplete, or was revoked. Send /mybots to @BotFather, choose the bot, API Token, copy it again and paste it with no spaces at either end. A 404 means the same thing with the front of the token missing.
• chat not found: the chat ID is wrong or the bot has never been in that chat. Message the bot (or add it to the group, or make it a channel administrator and post once), then use Find my chat ID and Use this rather than typing the number. Groups and channels are negative numbers; keep the minus sign.
• Find my chat ID finds nothing: the bot has not received anything yet, or it is in a group with privacy mode on and cannot read ordinary messages. Send /start in the group (commands are always visible to the bot), or make the bot a group administrator, or turn privacy mode off in @BotFather (remove and re-add the bot afterwards). If the bot is also used by another integration that set a webhook, getUpdates is refused: open https://api.telegram.org/botTOKEN/deleteWebhook once in a browser.

"could not reach Telegram" is the panel host itself: allow outbound HTTPS to api.telegram.org. If the test works but real alerts never arrive, check Enable Telegram alerts and the two alert tick boxes are on, that the door has a sensor and a non-zero held-open time, and that the alert rows actually appear in the Log; then look at the panel's server log for "telegram send failed". Remember repeats for one door are limited to one message per minute.

Door opened / closed does not appear in the log

The controller reports door open and close transitions only when it has a door contact and the current firmware.

• No door contact wired: fit a reed switch or contact between the door pin and 0 V, closed when the door is closed (chapter 5).
• Door pin is -1: the pin map in Settings (or the pin map an installer sent over USB) says there is no sensor, so the controller never reads it. Set the right GPIO and re-provision or re-point the controller so it picks the pin map up.
• Old firmware: builds before the door-event change do not publish Door opened / Door closed or Exit button lines (older builds logged the exit button as a granted access event called rex). Press Update on the Controllers page, or re-flash from Flash & adopt, and check the firmware version shown on the Controllers page afterwards.
• Only opens appear, never closes (or the reverse): the contact is wired the wrong way round or is intermittent; Door forced on every legitimate opening is the usual companion symptom. Watch the serial console while opening and closing the door.
• Nothing for the second door of a dual-door controller: the current firmware watches the channel 1 door contact only.

If the rows are there but you cannot see them, choose Door open/close, exit button in the Kind filter: they are not access events and are excluded from the granted/denied views.

The reception screen is blank or stuck

• Nothing at all: the link has been regenerated; get the new link from Doors and reopen it.
• "Waiting for the next entry" and nothing appears when people fob in: press the gear and check the door filter includes the doors in use; the browser may have an old filter saved. Check the screen machine can reach the panel address.
• Photos show as initials: no photo on the person, or the screen machine cannot fetch images from the panel (proxy or content blocker).
• Counts are zero at the top: no access events today on the selected doors.
• The screen went to sleep: adjust the machine's power settings; the page itself never times out.

Lost admin password

Any admin of the tenant can reset a user's password on the Users page. If nobody can sign in:

• On a hosted panel, contact 2plus1; the super admin resets it.
• On a self-hosted panel, on the server run accesscontroller create-admin <username> <newpassword> with the same ACS_DB as the service (stop the service first if the database is locked). Running it for an existing username resets that password; running it for a new name creates a new super admin in the provider tenant.

A re-pointed controller never came back

Re-point carries the current panel's MQTT credentials when the user and password fields are left blank. If the new server requires different credentials the controller connects, is refused (rc=5 on the serial console), and cannot be reached remotely because it is no longer connected anywhere. Two ways out:

• Temporarily allow the new server's broker to accept the controller (clear its device credentials, restart), let the controller connect, re-point it with the correct credentials, then re-lock the broker; or
• Visit the controller with a laptop and send the credentials over USB from Flash & adopt (step 3, Send settings to device) or via the setup portal. The USB path merges: it keeps the Wi-Fi settings and only changes what you send.

Avoid the problem by using the same device credentials on old and new panels, or by typing the new ones in the Re-point form.

An OTA update failed or the controller now boot-loops

• ota_failed in the log with a reason: usually the controller could not fetch the image (no public HTTPS URL set and the panel's HTTP port not reachable from the site, or no image staged for that chip). Fix and press Update again.
• The controller restarts endlessly after an update: there is no automatic roll-back. Re-flash it over USB from Flash & adopt with a known-good build. Always test an update on one unit first.

The Flash & adopt page says it needs a secure page

Web Serial and Web Bluetooth require HTTPS or localhost. Use the panel's https:// address (accept a self-signed certificate warning on a self-hosted panel) or open the page on the panel machine as http://localhost:8080/flash. iPhones and iPads cannot use either feature; use a laptop.

The board will not flash

Hold BOOT, tap RST, release BOOT, then start the install again. Try a different USB cable (many are charge-only) and port. Close any other program holding the serial port (a serial monitor, another browser tab). If the port never appears, install the USB-serial driver for the board.

An ESP32-S3 hangs after provisioning

The panel's default pin map uses GPIO 33 for Wiegand D1; on an S3 with OPI PSRAM (N16R8 and similar), GPIO 33 to 37 are reserved and driving them hangs the chip. Set the S3-safe pins in Settings (D0 4, D1 5, relay 6, REX 7, door 15) and re-provision over USB with BOOT held at power-up to reach setup mode.

Times in the log are wrong

• Everything is out by a fixed hour or more: the panel timezone (ACS_TZ) is wrong for the site.
• Only events from one controller are wrong, or dated 1970: that controller has no valid time (no network time yet, no RTC). Events without a valid controller time are stamped on arrival at the panel. Fit a DS3231 RTC for sites with poor connectivity.

Phone enrolment does not arm

A caller who presses # and keys in the site number hears the refusal prompt rather than the "present the fob" prompt. The prompts cannot tell the reasons apart by ear, so read the Log:

1. Is a site number set? Settings, Site number (phone enrolment). Empty means phone enrolment is switched off for that site.
2. Did they key in the right one? The number belongs to the building, not to the person. A caller who keys in another site's number is refused, and the Log records "site code belongs to another site".
3. Are enrolment doors ticked? On the Enrolment page, at least one door must be ticked. With none, there is nowhere to present the fob and the call is refused. Enrolment mode itself does not have to be running: the # path switches it on for ten minutes at the ticked doors.
4. Is the caller recognised? The same caller-ID rules as dial release apply; see "Phone unlock says not recognised" above.
5. Did the offer play at all? If callers never hear it, the PBX script is collecting the keypress with a digit-collection primitive rather than "wait for one digit", so the # is being swallowed as a terminator (chapter 9).

When it works, the Log shows Phone enrolment armed, and Fob enrolled at door with "by phone" in the detail once the fob is presented.

A booking does not open the door

1. Is the booking confirmed? Awaiting payment grants nothing. Mark it paid on the Bookings page, or take the payment.
2. Is it actually the slot? Access runs from the room's lead time before the start until five minutes after the end. Outside that, nothing opens.
3. Fob refused, portal button works? The controller's firmware is too old to understand booking windows. Update it from the Controllers page (chapters 5 and 8). The portal button and the phone path work regardless, because the panel sends the unlock itself.
4. Portal button says the controller is offline? The room's door has no active controller mapped, or the controller has dropped off. Check the Controllers page.
5. Is the door mapped to the right channel? On a dual-door controller, a room on the second door must be mapped to channel 2 on the door's page (chapter 3), or the unlock fires the wrong relay.

A resident cannot sign in to the portal

1. Is the portal published? Settings, Bookings and portal, Publish the resident portal. Unpublished, the address returns "not found".
2. Did the code arrive? With no SMS gateway configured, codes are not sent at all: they appear in the Login codes sent panel on the Bookings page, marked development only. That is for commissioning. Configure the gateway before residents use the portal.
3. Wrong apartment number? Someone whose person record has an apartment number is asked to confirm it. Three wrong answers lock them out for 15 minutes. Check the number on their person page.
4. Are they inactive or in the trash? Neither can sign in. Restore or reactivate them.
5. Have they changed their mobile? They cannot self-register, because their apartment already exists. Update the phone number on their person page.

Frequently asked questions

Does the door work if the internet goes down? Yes. The controller decides from its own copy of the access list. Changes made in the panel during the outage reach it when it reconnects.

How many fobs can a door hold? About 1,500 per door in the current firmware. Larger sites should ask 2plus1 before deployment.

Can a fob open doors at two of our sites? Yes. If both sites are in the same tenant, add both doors to the person's levels. If they are separate tenants, the same fob code can be registered in each one (codes are unique within a tenant, not across the panel), but they are two independent people: revoking one has no effect on the other.

Can two people share a fob? No. A fob code belongs to one person. Issue a second fob.

Can I use my existing readers and fobs? Yes, if the readers are Wiegand 26-bit or 34-bit, which nearly all are. The fobs' codes are read as they are.

Can someone have access at some times to one door and all the time to another? Yes: give them two levels, one per door with its own schedule.

Why did "denied today" go up when I enrolled a fob at a door? It should not: captures at a listening door are logged as system events, not denials. If it did, the scan happened before you pressed "Wait for fob" or at a different door.

How do I temporarily let a contractor in? Add them as a person with a fob and a level, and set them inactive (or revoke the fob) when the job ends. Or, if they will phone, use apartment mode with a PIN you clear afterwards.

Can I see who is in the building right now? The log shows entries, not exits (unless exit readers are fitted as separate doors). Occupancy counting is not a feature of the current release.

Can I be told when a door is left open or forced? Yes. Fit a door contact, set the held-open time on the door, and set up Telegram alerts under Settings (chapter 4). Alerts are also always in the Log.

Why does the log show an exit-button press as a door event rather than granted? Because nobody was checked: the exit button always releases the door, so it is recorded as a neutral Exit button pressed line and left out of the scan and denied counts. Older firmware logged it as a granted access event named rex.

I deleted the wrong person. Can I get them back? Yes, for 30 days. Open the trash from the People page, find them and press Restore; their fobs, access levels and phone-release doors all come back (chapter 6).

Can I add an access level to 200 members at once? Yes. Search for them on the People page, tick the header box, pick the level and press Add level(s) (chapter 6). It adds to what they already hold rather than replacing it.

Do I need a card reader on a room we only let residents book? No. A room needs the lock relay and an exit button; residents come in with the portal's Open the door button or by ringing the access line from the mobile they booked with. Fit a reader only if you also want fob entry during a slot (chapter 8).

Can we take money for the residents' lounge? Yes, by card through Stripe or by bank transfer with a quoted reference. Set both up under Settings, Bookings and portal (chapters 8 and 13). The panel does not issue refunds: cancel the booking here and refund in Stripe.

A member is standing at the door with a new fob and nobody is in the office. What now? If the site has a site number and enrolment doors ticked, tell them to ring the access line, press #, key in the site number and present the fob within ten minutes (chapter 9).

What is the difference between the site number and an apartment PIN? The site number says which building a caller is at, for enrolling a fob, and is not a secret. An apartment PIN says which person is calling, for opening a door, and is stored hashed. They are unrelated.

Does enrolment mode open every door on the site? No, not any more. It runs only at the doors you tick when you start it; every other door keeps refusing unknown fobs (chapter 6).