Skip to main content

Reference

Troubleshooting​

I can’t load the adapter UI​

  • Confirm the Pi is powered and Ethernet-connected.
  • From a laptop on the same LAN: ping <pi-ip>.
  • Try http://<pi-ip>:3006/ (HTTP, not HTTPS).
  • SSH in and check the service: sudo systemctl status zenspace-iot.service.

Gateway shows offline immediately after adding​

Almost always one of:

  • Wrong API key location — make sure you used Network → Control Plane → Integration, not Site Manager.
  • Missing prerequisites — Super Admin role, Site Manager 5.5.0+, Early Access enabled on the UniFi account.
  • Wrong Access token scope — the token needs all developer scopes.
  • Firewall — confirm both port 443 and port 12445 from Pi to controller.

Door shows offline but I can use it physically​

  • Check the device detail page for api_source. It should be access for UniFi Access devices.
  • If it’s network, delete and re-onboard the device. The bug that caused this was fixed but legacy devices need re-onboarding.
  • Run diagnostics on the door — it’ll tell you exactly which check is failing.

Snapshot button doesn’t work​

  • Confirm the door has a paired Protect camera (camera info is shown in the Camera panel).
  • The Network API key needs Protect read scope (the same ulk_ key works for both — they share auth on UniFi).
  • Try the snapshot from a normal browser tab (not embedded in cloud) — corporate proxies sometimes strip JPEG content types in iframes.

OTA says “No update available” but I expect one​

  • Check the channel — stable won’t see beta builds.
  • Compare versions as semver. 2.1.0-beta.X < 2.1.5 < 2.1.6 < 2.1.8. The agent does not allow downgrades.
  • Look at the Update history panel for the most recent fetch attempt.

Rotated UniFi credentials and now everything is offline​

  • Gateways → click your gateway → Edit credentials.
  • Update the API key values.
  • Save and click Ping.
  • The next health probe (within 2 minutes) restores device status.

SSH access​

ssh zencam@<pi-ip>

The default user is zencam. SSH host keys are generated on first boot.

If SSH refuses connections after a known-good period, the SSH self-healer auto-recovers within a few minutes — it probes port 22 and re-runs ssh-keygen -A if keys are missing.

Security and Best Practices​

Credentials​

  • Never share UniFi API keys outside the secure setup process. They grant full controller access.
  • Rotate UniFi keys every 90 days.
  • Rotate adapter API keys every 90 days.
  • The Pi’s encryption key is generated at first boot and never leaves the Pi. If you re-flash, all stored credential blobs become unreadable — you’ll need to re-add gateways with fresh credentials.

Network​

  • Put the Pi on a management VLAN alongside the UniFi controller.
  • Block outbound internet on the Pi except to:
  • s3.us-east-2.amazonaws.com (OTA)
  • api-spaceos.zenspace.io (cloud)
  • 100.64.0.0/10 (Tailscale, if enabled)
  • Don’t expose port 3006 to the public internet.

Physical​

  • Mount the Pi inside a locked equipment cabinet.
  • Treat the microSD card as physically sensitive — anyone with physical possession can extract the encryption key.

Operations​

  • Run the beta channel on at least one non-critical site to catch issues before they hit production.
  • Keep production sites on stable, update them within two weeks of each stable release.
  • Review the event log monthly. Look for unexplained admin actions or unlock events.

Glossary​

Reference Tables​

UniFi models you’ll commonly see​

Default ports and paths​

Pi file locations​

Systemd units​

Where to get help​

  • In the UI — most panels have a question-mark icon with context-sensitive help
  • Event log — filter by severity: error to see anything that failed recently
  • Diagnostics — run against a target to get a structured report
  • ZenSpace operations team — contact them with the Pi’s hostname and a copy of relevant event log entries

End of guide.