Skip to main content

Initial Deployment

Before You Begin​

Hardware​

  • Raspberry Pi 4 or 5 (4 GB RAM minimum recommended)
  • 32 GB or larger microSD card, Class 10 or better
  • USB-C power supply rated for your Pi model
  • Ethernet cable connected to the same network as the UniFi controller
  • A separate computer with an SD card reader to flash the image

Network​

  • DHCP must be enabled on the network — the Pi gets its IP automatically
  • Port 3006 must be reachable from operator laptops on the LAN (this is the adapter’s web UI port)
  • The Pi must be able to reach the UniFi controller on :443 and :12445
  • Outbound HTTPS must be allowed to:
  • s3.us-east-2.amazonaws.com (for OTA updates)
  • api-spaceos.zenspace.io (for ZenEdge cloud OTP and webhooks)

Accounts and credentials​

You’ll need these in hand before you start setting up:

  • A ZenEdge cloud admin email — this is where the OTP login codes will be sent
  • A UniFi Network API key (begins with ulk_) — for managing APs, switches, routers
  • A UniFi Access API token — for managing door locks, readers, and hubs
  • The UniFi controller’s local IP (e.g., 192.168.0.116)

The next section walks through getting the two UniFi credentials.

Getting your UniFi Network API key​

  • Log in to your UniFi controller at https://<controller-ip> in a browser.
  • Open Network → Settings → Control Plane → Integration.
  • Click Create API Key.
  • Name it (e.g., “zenspace-adapter”) and copy the key — it starts with ulk_.

The key needs three things to be issuable:

  • Your account must be Super Admin on the controller (Custom roles will not work).
  • The Site Manager component must be on version 5.5.0 or later.
  • Early Access must be enabled on your UniFi account at account.ui.com.

If you see “Access Prohibited” at the API Key screen, one of the three is missing.

Important: Do not use the API key from unifi.ui.com/settings/api-keys. That key only authenticates against the UniFi cloud (api.ui.com) and will return 401 against your local controller.

Getting your UniFi Access API token​

  • Open the UniFi Access application in the controller.
  • Go to Settings → General → Advanced.
  • Find the API Token section and click Create New.
  • Set a name, choose a validity period, and grant all developer permission scopes.
  • Click Create and copy the token. UniFi displays the full token only once.

You’ll provide both keys to the adapter in the gateway-setup step.

Step 1 — Flash the Adapter Image​

The adapter is delivered as a complete Raspberry Pi OS image with the runtime, dependencies, and a first-boot script all pre-baked.

  • Receive the image file from your ZenSpace operations contact. It’s named like zenspace-adapter-2.1.8.img.xz and is around 600 MB compressed.
  • Download and install Raspberry Pi Imager from raspberrypi.com/software.
  • Insert the microSD card into your computer.
  • Open Raspberry Pi Imager.
  • Click Choose OS → Use custom, then pick the .img.xz file.
  • Click Choose Storage and select your microSD card.
  • Click Next. When asked about OS customization, click No, clear settings — the image already contains everything needed.
  • Click Yes to confirm. The card is written and verified, which takes 5–15 minutes.
  • Eject the card.

Do not customize SSH keys, hostname, or WiFi credentials in Pi Imager. The image generates its own SSH host keys on first boot, and the rest of the configuration is handled by an internal first-boot service. Custom Imager settings will conflict with this and may break the deployment.

Step 2 — First Boot on the Pi​

  • Insert the microSD card into the Pi.
  • Connect the Ethernet cable to the Pi and to a port on the same network as the UniFi controller.
  • Plug in the power supply.

First boot takes 5 to 8 minutes. Don’t unplug the Pi during this period. The first-boot service is doing several things:

  • Expanding the filesystem to fill the SD card
  • Generating SSH host keys so you can SSH in later
  • Generating a unique encryption key (used to protect credentials stored on this Pi)
  • Compiling the SQLite native binary against the local kernel
  • Bringing up Tailscale (if your image includes it)
  • Starting the adapter service on port 3006

When first boot completes, the status LED settles into a slow heartbeat pattern. If you have a monitor connected, you’ll see the login prompt.

Step 3 — Find the Pi on Your Network​

The Pi obtained an IP via DHCP. To reach the adapter UI, you need that IP.

The easiest way is your router’s DHCP table — most routers list connected devices with hostnames. Look for a host named zencam (the default hostname).

If you don’t have router access, scan the LAN. From a Mac or Linux laptop:

arp -a | grep -iE "b8:27:eb|dc:a6:32|d8:3a:dd|2c:cf:67"

Those are common Raspberry Pi MAC prefixes. On Windows, use a tool like Advanced IP Scanner.

Once you have the IP, open a browser and go to:

http://<pi-ip>:3006/

You should see the adapter login screen. If the page doesn’t load:

  • Wait another minute — first boot may not be complete.
  • Check the Pi’s status LED is on and steady.
  • Confirm your laptop is on the same subnet as the Pi.
  • Try http://<pi-ip>:3006/admin directly.

Step 4 — First Login (OTP)​

The adapter does not have a local password. It uses one-time passwords that are generated and verified by ZenEdge cloud, then exchanged for a JWT session.

The flow looks like this:

You type your email in the adapter UI ↓ Adapter calls ZenEdge cloud — "send OTP to this email" ↓ ZenEdge cloud emails the 6-digit code ↓ You enter the code in the adapter UI ↓ Adapter calls ZenEdge cloud — "verify this code" ↓ ZenEdge cloud returns success + your role ↓ Adapter mints a local JWT and signs you in

To log in:

  • On the login screen, enter your ZenEdge cloud admin email.
  • Click Send code. Check your inbox (and spam folder) for the 6-digit code.
  • Enter the code in the adapter UI. The code is valid for a few minutes.
  • Click Verify. You’re now signed in.

The JWT is stored in your browser. You can refresh the page, navigate, or close and reopen the tab — you stay signed in until the JWT expires, after which you log in again the same way.

If you don’t receive the code:

  • Confirm your email is registered as a ZenEdge cloud admin for your facility.
  • The Pi must have outbound internet access to api-spaceos.zenspace.io.
  • Click Send code again — codes are short-lived and only the most recent one works.