Skip to main content

Getting Started

About the ZenSpace Adapter​

The ZenSpace Adapter is the on-site IoT software that sits between your physical hardware (UniFi door locks, WiFi access points, and cameras) and the ZenEdge cloud platform.

Two systems, two distinct roles:

  • ZenEdge Cloud — the management software your administrators and managers log into. It stores users, schedules, bookings, and access policies. It sends commands like “unlock door 9728” to the adapter when something happens on the platform.
  • ZenSpace Adapter — the local component running on a Raspberry Pi inside your facility. It receives commands from ZenEdge cloud and translates them into the right calls to your UniFi controller. It also reports device status, streams camera snapshots, and pushes events back to ZenEdge.

Throughout this guide, when we say “the adapter” we mean the ZenSpace Adapter on the Pi. When we say “ZenEdge cloud” we mean the cloud-hosted management platform.

How the Two Systems Work Together​

A typical interaction looks like this:

  • A user on the ZenEdge cloud platform clicks Unlock for a door at your site.
  • ZenEdge cloud calls the adapter’s contract API at https://<your-site>:3006/action with an authenticated request.
  • The adapter looks up which UniFi controller the door belongs to, picks the right API (UniFi Access in this case), and sends the unlock command.
  • The door physically unlocks.
  • The adapter records the event locally and posts a webhook back to ZenEdge cloud confirming the result.

The adapter handles all UniFi-specific knowledge — credentials, ports, API quirks, model differences — so ZenEdge cloud only needs to know about generic concepts like “door” and “unlock action.”

What This Guide Covers​

This guide walks you through every step of using the adapter:

  • Flashing the adapter image and bringing the Pi online
  • Logging in via OTP authentication
  • Adding a UniFi gateway with the right credentials
  • Discovering and onboarding devices
  • Using the device detail page (live status, actions, capabilities, UI preview, integration panel)
  • Understanding capabilities and how they drive actions
  • Configuring UI previews including default previews
  • Using the integration panel to test contract endpoints
  • Running diagnostics and reading health monitoring
  • Using the system page for adapter API keys, version checks, and OTA updates
  • Switching between stable and beta channels
  • Troubleshooting common issues