Cisco Connector

The Cisco Connector for the DeepHub subscribes to Cisco Spaces location events via gRPC and forwards them as omlox-compliant location updates to the DeepHub.

Setup and Configuration

The Cisco Connector is available through Docker Hub as a standalone Docker image: flowcate/deephub-connector:cisco-0.1.0. Configuration is controlled via environment variables (see Environment Variables below).

Example Docker Compose Configuration

To start this connector alongside a DeepHub instance, add a service like the following to your docker-compose.yml file:

services:
  deephub:
    image: flowcate/deephub:latest
    container_name: deephub
    restart: unless-stopped
    environment:
      - DEEPHUB_PORT=7081
      - ...
    ports:
      - '7081:7081'
    networks:
      - deephub-net

  cisco-connector:
    image: flowcate/deephub-connector:cisco-0.1.0
    container_name: cisco-connector
    restart: unless-stopped
    environment:
      - CISCO_API_KEY=<enter your api key>
      - CISCO_GRPC_URL=<your-cisco-spaces-grpc-endpoint>:443
      - DEEPHUB_URL=deephub:7081
    depends_on:
      - deephub
    networks:
      - deephub-net

networks:
  deephub-net:

Using a Device Whitelist File

To restrict forwarding to a specific set of devices, mount a plain-text file into the container and point CISCO_DEVICE_WHITELIST_FILE to it. Each line in the file is treated as one device ID. The file is merged with any IDs set via CISCO_DEVICE_WHITELIST.

whitelist.txt (one device ID per line):

device-001
device-002
aa:bb:cc:dd:ee:ff

Note:

Device IDs may be logical names (e.g. device-001) or MAC addresses (e.g. aa:bb:cc:dd:ee:ff), depending on how devices are identified in your Cisco Spaces deployment.

docker-compose.yml:

services:
  cisco-connector:
    image: flowcate/deephub-connector:cisco-0.1.0
    container_name: cisco-connector
    restart: unless-stopped
    environment:
      - CISCO_API_KEY=<enter your api key>
      - CISCO_GRPC_URL=<your-cisco-spaces-grpc-endpoint>:443
      - DEEPHUB_URL=deephub:7081
      - CISCO_DEVICE_WHITELIST_FILE=/config/whitelist.txt
    volumes:
      - ./whitelist.txt:/config/whitelist.txt:ro
    depends_on:
      - deephub
    networks:
      - deephub-net

networks:
  deephub-net:

The same pattern applies to CISCO_DEVICE_BLACKLIST_FILE.

Environment Variables

Variable	Default	Description
CISCO_API_KEY		Cisco Spaces API key.
CISCO_GRPC_URL		Cisco Spaces gRPC endpoint.
DEEPHUB_URL	localhost:7081	DeepHub host and port.
DEEPHUB_TARGET	v2/ws/socket	WebSocket path on the DeepHub.
DEEPHUB_USE_WSS	false	Set to true to connect to DeepHub over WSS (TLS).
DEEPHUB_WSS_SKIP_VERIFY	false	Set to true to skip TLS certificate verification when connecting over WSS. Useful for self-signed certificates.
RECONNECT_DELAY_SECONDS	5	Delay in seconds before reconnecting after a gRPC error.
MAX_RECONNECT_ATTEMPTS	0	Max reconnection attempts.
CISCO_LOCATION_UNIT	m	Unit of local coordinates received from Cisco Spaces. Set to feet to convert x/y values to meters before forwarding to DeepHub.
LOG_LEVEL	INFO	Log verbosity level at runtime (e.g. DEBUG, INFO, WARNING, ERROR).
CISCO_DEVICE_WHITELIST		Comma-separated list of device IDs to allow. Only devices on this list are forwarded to DeepHub.
CISCO_DEVICE_WHITELIST_FILE		Path to a file containing allowed device IDs, one per line. Merged with CISCO_DEVICE_WHITELIST.
CISCO_DEVICE_BLACKLIST		Comma-separated list of device IDs to block. Matching devices are not forwarded to DeepHub.
CISCO_DEVICE_BLACKLIST_FILE		Path to a file containing blocked device IDs, one per line. Merged with CISCO_DEVICE_BLACKLIST.

Property Mapping

The connector transforms Cisco Spaces EventRecord messages into omlox location updates. The mapping is derived from the gRPC message structure used in the connector:

Event types

The connector currently forwards Cisco Spaces location updates from the following EventRecord.event_type values:

• DEVICE_LOCATION_UPDATE
• IOT_TELEMETRY

Field mapping

Cisco Spaces (gRPC EventRecord)	omlox / DeepHub payload field
device_location_update.device.device_id	provider_id (for DEVICE_LOCATION_UPDATE)
iot_telemetry.device_info.device_id	provider_id (for IOT_TELEMETRY)
device_location_update.map_id	source (for DEVICE_LOCATION_UPDATE)
iot_telemetry.detected_position.map_id	source (for IOT_TELEMETRY)
longitude / latitude	position.coordinates when crs="EPSG:4326"
x_pos / y_pos	position.coordinates when crs="local"
record_timestamp	timestamp_generated
full original gRPC message	properties.original_cisco_message

The connector chooses the coordinate reference system as follows:

• If longitude/latitude are within a valid range, they are sent as a geographic position with crs = "EPSG:4326".
• If longitude/latitude are missing (which appears as 0.0 in proto3) or a placeholder 0,0 and map-id is present, the connector uses x_pos / y_pos and sets crs = "local".

The resulting omlox location is wrapped into a WebSocket message on the location_updates topic and sent to the DeepHub.

Provider type mapping

DeepHub expects a provider_type string describing the positioning technology. The connector maps:

• DEVICE_LOCATION_UPDATE → provider_type = "wifi"
• IOT_TELEMETRY → provider_type = "ble-aoa"

Notes and common inconsistencies

• Different provider_id formats: DEVICE_LOCATION_UPDATE uses a Cisco device ID (often device-...) while IOT_TELEMETRY commonly uses a MAC-like identifier. DeepHub will treat these as different providers.
• Missing GPS: Lat/lon are explicitly available as 0,0 in the DEVICE_LOCATION_UPDATE event_type. However, these parameters are missing in the IOT_TELEMETRY event_type.

Authentication

If DeepHub requires OAuth-based authentication, configure the following variables in addition to the ones above:

Variable	Description
DEEPHUB_OAUTH_TOKEN_URL	OAuth token endpoint for DeepHub.
DEEPHUB_OAUTH_CLIENT_ID	OAuth client ID used by the connector.
DEEPHUB_OAUTH_CLIENT_SECRET	OAuth client secret used by the connector.
DEEPHUB_OAUTH_SCOPE	OAuth scope string requested for the token.