Skip to main content

Cisco Spaces Integration

Import 2D floor plans from Cisco Spaces into Aida Controller Facility so operators do not re-upload the same maps. Lighting, shade, and HVAC control stay on the controller. Spaces is an optional spatial source — not a replacement for Aida control.

:::info Status Ready to deploy on Aida Controller 2.0 (v0.79.0+). Enable the Cisco Spaces module, paste a Detect & Locate token, and import a plan onto a floor. Occupancy Firehose overlays, AI Maps 3D, and write-back into Space Manager are not in this release. :::

Purpose​

AudienceWhat this integration provides
Facilities / OTUse the maps IT already maintains in Spaces as the Facility floor plan; place Aida devices on that image
IT / networkingKeep Cisco Spaces as the map authority; Aida pulls a raster on demand and caches it locally
OperatorsOffline viewing after import; refresh when the Spaces map changes

Aida Controller owns device pins, live lighting/shade state, zones, and control.
Cisco Spaces owns the 2D map image (and later occupancy / AP overlays).
Aida Platform lists this integration and documents setup; the token and import run on the controller, not in the cloud UI.

What ships in v1​

  • Optional controller module cisco-spaces (enable/disable in Modules)
  • Detect & Locate Location Cloud API v2 token (region + JWT)
  • Hierarchy picker → floor → image picker when a floor has more than one raster (for example Meraki vs Spaces 2D)
  • Cached plan on the controller; viewer badge Plan from Cisco Spaces · {building} - {source}
  • Refresh from Spaces, or switch the floor back to a local PNG/JPEG upload
  • Place, move, and operate Aida device pins as with any other floor plan

Out of this release

  • Wi‑Fi / BLE occupancy heatmaps (Firehose)
  • Writing fixtures or geometry back into Space Manager
  • AI Maps 3D viewer (waiting on Cisco SDK access)
  • Cisco Wayfinding SDK

Architecture​

The controller calls Cisco Spaces on demand over HTTPS, then stores the image locally. After import, the floor viewer works offline. Browse, test, and refresh need outbound HTTPS to the Spaces region host.

RegionLocation API host
UShttps://dnaspaces.io
EUhttps://dnaspaces.eu
Singaporehttps://ciscospaces.sg

Auth: Authorization: Bearer <Detect & Locate JWT>.

Prerequisites​

  1. Aida Controller 2.0 v0.79.0 or later, with a site admin who can enable modules (modules.config) and edit floors (facility.write).
  2. A Cisco Spaces tenant with Detect and Locate enabled and at least one campus → building → floor that has a 2D map.
  3. A Location Cloud API v2 key (JWT). Create it in Detect & Locate: Notifications → API Keys → Add.
  4. Outbound HTTPS from the controller to the region host (timeouts are about 60 seconds). The token is shown once, expires in 7–365 days, and is stored encrypted on the controller — never in git.

Setup​

1. Enable the module​

  1. On the controller, open Modules → Cisco Spaces.
  2. Enable the module.
  3. Choose region (us, eu, or sg).
  4. Paste the Detect & Locate JWT into the token field (write-only; the UI shows configured, not the secret).
  5. Optionally set a default map source (ask, MERAKI, or SPACES_2D_MAP).
  6. Click Test. A successful test reports how many floors are in the hierarchy and shows token expiry.

If the module is disabled, import UI is hidden. Floors that already imported a Spaces plan keep the cached image; the controller does not call Spaces.

2. Import a floor plan​

New floor

  1. Facility → Floors → Add from Cisco Spaces.
  2. Browse the Spaces hierarchy and select a floor.
  3. If the floor has more than one image, pick which raster to use (source, size, thumbnail).
  4. Confirm. The controller creates the floor (name/number from Spaces when available), downloads the image, and opens the viewer.

Existing floor

  1. Open the floor → Import from Cisco Spaces (instead of uploading a file).
  2. Same hierarchy + image picker.
  3. Confirm. The active plan becomes plan_source: spaces. Switching from a local upload is explicit.

3. Place devices and operate​

  • Drag Aida devices onto the plan as usual. Pins stay on the controller.
  • Lock floor to prevent accidental moves; click a pin or zone for live data and controls.
  • The viewer badge shows Plan from Cisco Spaces · {building} - {source} (the Spaces network node is the building).

You cannot crop, draw on, or replace the raster in-app while the source is Spaces. To use a local file instead, upload a plan (the floor switches to a local source).

4. Refresh​

On a Spaces-backed floor, Refresh plan re-pulls the current map (or lets you pick a different maps[] image). If the image hash is unchanged, placements are kept. Normalized pin coordinates stay if dimensions change; a large aspect-ratio shift may need a visual check.

Offline behavior​

ActionNetwork required?
View cached plan, pan/zoom, pins, live device stateNo (LAN / controller only)
Test connection, hierarchy picker, first import, refreshYes — HTTPS to the Spaces region

Troubleshooting​

SymptomWhat to check
Test returns 401 / expiredCreate a new Detect & Locate API key; paste it and Test again. JWTs expire (7–365 days).
Import returns 409Module is disabled, or the request is not allowed for the current role. Enable Cisco Spaces and use an operator/admin with facility.write.
Viewer still shows the old image after importRefresh the page. The controller busts cache with the plan content hash; a hard refresh clears a stuck browser blob.
No floors in the pickerConfirm Detect & Locate maps exist for that tenant/region, and the token is for the same region you selected.
Image download fails / too largeFacility max plan size still applies (same as file upload). Try a smaller raster from maps[] if the tenant exposes more than one.
Viewer cannot import but GET plan still worksExpected when the module is off: cached rasters remain readable; outbound Spaces calls are blocked.

What not to do​

  • Do not treat Spaces "x,y,z" zone coordinates as a 3D mesh — they are 2D plan vertices (z is usually 0).
  • Do not merge this module with Webex Control Hub. Webex remains a separate integration for room panels and webhooks.
  • Do not upload or edit maps in Spaces from Aida. Raster authority stays in Cisco Spaces.