Use Cases

Common integration patterns for the Cisco Spaces Firehose API.

Real-Time Location Tracking

Consume DEVICE_LOCATION_UPDATE events to track device positions on floor maps in real time.

Typical flow:

  1. Connect to the streaming endpoint
  2. Filter for DEVICE_LOCATION_UPDATE events
  3. Extract xPos, yPos, latitude, longitude, and mapId from the payload
  4. Plot positions on a floor map retrieved via GET /api/partners/v1/maps/{mapId}/image

Relevant events: DEVICE_LOCATION_UPDATE, DEVICE_RSSI_UPDATE

Tips:

  • Use the map metadata endpoint to get image dimensions and coordinate scaling
  • Location updates arrive frequently for active devices — batch UI updates if rendering to a dashboard

Occupancy and People Counting

Track how many people are in a space using device counts, camera counts, or space occupancy events.

Typical flow:

  1. Subscribe to DEVICE_COUNT, CAMERA_COUNT, and/or SPACE_OCCUPANCY events
  2. Aggregate counts by locationId
  3. Store time-series data for trend analysis

Relevant events: DEVICE_COUNT, CAMERA_COUNT, RAW_CAMERA_COUNT, SPACE_OCCUPANCY, SPACE_OCCUPANCY_CHANGE

Tips:

  • DEVICE_COUNT includes both associated (connected to Wi-Fi) and probing (not connected) counts
  • CAMERA_COUNT provides aggregated people counts; RAW_CAMERA_COUNT gives per-camera data
  • Use SPACE_OCCUPANCY_CHANGE for threshold-based alerting (e.g., room is now occupied)

Visitor Analytics and Presence

Analyse visitor behaviour — dwell times, visit frequency, entry/exit patterns — using presence events.

Typical flow:

  1. Subscribe to DEVICE_PRESENCE and/or USER_PRESENCE events
  2. Track lifecycle: entry → active → inactive → exit
  3. Compute dwell time from entry_timestamp and exit_timestamp
  4. Use days_since_last_visit for repeat visitor analysis

Relevant events: DEVICE_PRESENCE, USER_PRESENCE

Tips:

  • USER_PRESENCE groups multiple devices by the same user (via authentication identity)
  • Use visit_id to correlate all lifecycle events within a single visit
  • Inactive events fire after 10 minutes of no activity; exit fires after ~3 hours

IoT Sensor Monitoring

Monitor environmental sensors (temperature, humidity, air quality, accelerometer, battery) from BLE and RFID devices.

Typical flow:

  1. Subscribe to IOT_TELEMETRY events
  2. Extract sensor data from temperature, battery, accelerometer, and other telemetry fields
  3. Alert on thresholds (e.g., temperature > 30°C, battery < 20%)

Relevant events: IOT_TELEMETRY, IOT_USER_ACTION, BLE_RSSI_UPDATE

Tips:

  • Use Firehose filters to narrow events to specific BLE devices by MAC, OUI, iBeacon UUID, or Eddystone namespace
  • IOT_USER_ACTION captures button presses and other physical interactions

Network Health Monitoring

Track network infrastructure health and performance metrics.

Typical flow:

  1. Subscribe to NETWORK_TELEMETRY and NETWORK_STATUS_UPDATE events
  2. Monitor AP telemetry (clients per AP, SNR, channel utilisation, RSSI)
  3. Alert on connector/controller disconnections via NETWORK_STATUS_UPDATE

Relevant events: NETWORK_TELEMETRY, NETWORK_STATUS_UPDATE, AP_TOPOLOGY_CHANGE

Tips:

Location Hierarchy Sync

Keep your application's location model in sync with Cisco Spaces.

Typical flow:

  1. Subscribe to LOCATION_CHANGE events
  2. Handle ADD, REMOVE, MOVE, and UPDATE change types
  3. Sync LocationDetails (timezone, city, coordinates, map info) into your local store

Relevant events: LOCATION_CHANGE, LOCATION_ANCHOR_UPDATE

Multi-Tenant Data Routing

Route events to the correct downstream tenant system using the partnerTenantId field.

Typical flow:

  1. Open a single streaming connection (all tenants on one channel)
  2. Read partnerTenantId from each event
  3. Route to the appropriate tenant pipeline or storage

Tips:

  • No need for separate connections per tenant — the API is multi-tenant by design
  • Use spacesTenantId for Cisco Spaces internal correlation

See Also