Lidar Hub

The Ouster Lidar Hub is the customer’s interface to the Ouster Perception software stack. It is deployed as a separate Docker container in conjunction with the Ouster Perception solution and provides various configuration and integration features, including:

• On-device Aggregation of occupations and object lists

• The gathering and reporting of Diagnostics and Alerts to the Ouster Gemini Portal

• Down-sampling, Batching and Filtering of Perception JSON Streams used by:

  • TCP Relay Server(s)

  • MQTT Publishers

• On-device Data Recording of JSON Streams and Point Cloud data

• Zone Occupancy Event Recorder

Architecture

Lidar Hub Architecture

Application Configuration

The Ouster Lidar Hub is configured via the Gemini Detect Viewer Settings. When started for the first time, the Lidar Hub will load its default settings.

The “application” section of the Lidar Hub settings is used for defining top-level application-specific settings.

Example

"application": {
    "id": "*ABCD1234EFGH5678",
    "label": "Site A",
    "logging": {
    },
    "gemini_portal": {
    },
    "world": {
    }
}

Primary application Fields

Primary Application Fields

Field	Format	Description
ID	string	Unique ID of this installation (typically the unique hardware identifier generated by the Ouster Agent or the hardware MAC Address)
logging	object	System Logging configuration
gemini_portal	object	Ouster Gemini Portal configuration
world	object	World configuration

Optional Application Fields

Optional Application Fields

Field	Format	Description
label	string	User-defined label displayed in the Gemini Portal and used as an MQTT Publisher configuration variable
concurrency_port	int	System port number to use for ensuring a single instance of the application (default = 4999)
internal_port_range	list	Internal queues bind port range…10 ports in total must be defined (default = [4001, 4002, 4003, 4004, 4005, 4006, 4007, 4008, 4009, 4010])
zmq_send_hwm	int	Internal queue send high-water-mark (default = 100)
zmq_receive_hwm	int	Internal queue receive high-water-mark (default = 100)
web_server_port	int	Web server listening port number (default = 8003)
debug	bool	Used for application diagnostics (default = false)

System Logging

The Lidar Hub supports System logging to both the console and to file. When running in a Docker container, console logging is captured by Docker. When installed on an Ouster Catalyst device, console logging is forwarded to the common Ouster logs accessible at https://<<host>>/logs.

Configuration

The application and application.logging sections of the Lidar Hub settings are used for configuring application logging. By default, file logging is disabled, and the console logging level is set to INFO.

Example

"application": {
    ...
    "logging": {
        "console_log_level": 20
    }
}

Primary logging Fields

Primary logging Fields

Field	Format	Description
logging	object	Logging configuration``
logging.console_log_level	int	Application logging level (CRITICAL = 50, ERROR = 40, WARNING = 30, INFO = 20, DEBUG = 10, VERBOSE = 1, DISABLED = 0)

Optional logging Fields

Optional logging Fields

Field	Format	Description
log_health_level	int	Application health logging level (default 10 - DEBUG)
log_health_interval_secs	int	Application health logging interval (default 3600)
logging.file_log_level	int	Optional application file logging level (CRITICAL = 50, ERROR = 40, WARNING = 30, INFO = 20, DEBUG = 10)
logging.file_log_path	string	Optional application file logging path (default = /opt/ouster/logs/)

Ouster Gemini Portal

Ouster’s cloud-based device management, monitoring and analytics platform is where the end user can gain visibility into the health and performance of their Lidar deployment(s). The Gemini Portal is offered as a Ouster Mananged / Ouster Hosted cloud service and as a Ouster Managed / Customer Hosted product.

Configuration

The application.gemini_portal section of the Lidar Hub settings is used for configuring the integration with the Ouster Gemini Portal. By default, System Diagnostics are configured to be published to the Gemini Portal every 60 seconds. When the Aggregation Module is enabled, real-time and timeseries data will also be published to the Gemini Portal as configured.

Example

"application": {
    ...
    "gemini_portal": {
        "host": "gemini.ouster.dev",
        "customer_id": "73bbb8a6-ffd7-4898-a8dd-8003441ec724",
        "state": "provisioned",
        "diagnostics_publishing_enabled": true,
        "aggregation_publishing_enabled": false,
        "rpc": {
        }
    }
}

Primary gemini_portal Fields

Primary gemini_portal Fields

Field	Format	Description
gemini_portal	object	Gemini Portal configuration
gemini_portal.host	string	Host name/IP of the Gemini Portal
gemini_portal.customer_id	string	Your Gemini Portal Customer ID (provided by Ouster)
gemini_portal.state	string	Provisioning state with the Gemini Portal (un-provisioned or provisioned)
gemini_portal.diagnostics_publishing_enabled	bool	Indicator if the publishing of diagnostics to the Gemini Portal is enabled (default = true)
gemini_portal.aggregation_publishing_enabled	bool	Indicator if the publishing of aggregation to the Gemini Portal is enabled (default = false)
gemini_portal.rpc	object	Gemini Portal RPC configuration

Optional gemini_portal Fields

Optional gemini_portal Fields

Field	Format	Description
gemini_portal.port	int	Gemini Portal MQTT port number (default = 1883)
gemini_portal.tls	bool	Flag indicating if the Gemini Portal requires TLS for MQTT connectivity (default = false)
gemini_portal.qos	int	Gemini Portal MQTT QOS (0 = At most once, 1 = At least once, 2 = Exactly once) (default = 1)
gemini_portal.connecting_timeout_secs	float	Seconds to wait for a connection to be established to the Gemini Portal (default = 5.0)
gemini_portal.connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the Gemini Portal (default = 60.0)
gemini_portal.rpc.read	bool	Flag indicating if Gemini Portal Requests are enabled (e.g. “GET”) (default = true)
gemini_portal.rpc.write	bool	Flag indicating if Gemini Portal Commands are enabled (e.g. “PUT”, “POST”, “DELETE”) (default = true)
gemini_portal.rpc.output	bool	Flag indicating if Gemini Portal Generation of Output is enabled (default = true)
gemini_portal.rpc.ota	bool	Flag indicating if Gemini Portal OTA is enabled (default = true).
gemini_portal.software_ota_frequency_secs	float	Interval as which to check for Gemini Portal Software OTA requests (default = 3600.0 seconds).
gemini_portal.firmware_ota_frequency_secs	float	Interval as which to check for Gemini Portal Firmware OTA requests (default = 3600.0 seconds).

World

The Lidar Hub has the ability to optionally convert JSON Data Stream x/y cartesian coordinates to WGS84 longitude/latitude coordinates given a scene’s world reference geo-coordinate and azimuth. By default, this option is disabled.

Configuration

The world section of the Lidar Hub settings is used for configuring the scene’s world reference geo-coordinate and azimuth.

Example

"application": {
    ...
    "world": {
      "latitude": 37.76466741329934,
      "longitude": -122.4136976526134,
      "azimuth": 57.6
    }
}

Primary World Fields

Primary World Fields

Field	Format	Description
world	object	Lidar Hub world configuration
world.latitude	float	Scene’s world reference latitude
world.longitude	float	Scene’s world reference longitude
world.azimuth	float	Scene’s world reference azimuth

Optional World Fields

None

Map

The Lidar Hub’s world can also be configured using an interactive map accessible at https://<<host>>/lidar-hub/map/. The configuration pane can be collapsed using the ‘>’ button at the top-left edge of the pane. Note: Any changes not applied will be reverted when the configuration pane is collapsed.

1. Choose desired map layer (Street, Satellite, Hybrid or Terrain). The desired layer can be changed at any time.

2. Drag the Ouster map pin to the desired location and/or use the ‘World Latitude’/’World Longitude’ form fields to set the world. Zoom in and out with your mouse wheel, track pad or zoom controls at the top-left of the map.

3. For precise alignment, check the ‘Zones’ checkox and click Start to view the site’s configured Event Zones and a Live perception stream. Use the ‘Azimuth’ form field to rotate the alignment (fractional degrees are acceptable).

4. Click ‘Apply Changes’ to save the world’s new position.

Lidar Hub Interactive Map

Perception Software Stack

By default, the Lidar Hub will connect to the Perception software stack running in the same Docker Network on the local host, and once initialized, will begin generating system diagnostics at a cadence of once every 60 seconds.

Configuration

The Perception section of the Lidar Hub settings is used for configuring Perception Software Stack connectivity, Lidar Hub system diagnostics and the Lidar Hub aggregation module.

Example

"perception": {
    "perception_websocket": {
      "host": "perception",
      "port": 3001
    },
    "event_zone_websocket": {
      "host": "event-zones",
      "port": 3004
    },
    "align_websocket": {
      "host": "perception",
      "port": 3005
    },
    "object_list": {
      "host": "perception",
      "port": 3002,
      "suppress_unoccupied_frames": false
    },
    "occupations": {
      "host": "event-zones",
      "port": 3003,
      "suppress_unoccupied_frames": false
    },
    "diagnostics": {
      "interval_secs": 60.0
    },
    "aggregation": {
      "realtime_hertz": 1.0,
      "timeseries_secs": 60.0
    }
}

Primary perception Fields

Primary perception Fields

Field	Format	Description
perception_websocket	object	Perception Server web socket configuration
perception_websocket.host	string	Host name of the Perception Server (typically the Docker service name)
perception_websocket.port	int	Port number of the Perception Server web socket server
event_zone_websocket	object	Event Zone Server web socket configuration
event_zone_websocket.host	string	Host name of the Event Zone Server (typically the Docker service name)
event_zone_websocket.port	int	Port number of the Event Zone Server web socket server
align_websocket.host	string	Host name of the Perception Server (typically the Docker service name)
align_websocket.port	int	Port number of the Alignment web socket server
object_list	object	Perception Server object_list configuration
object_list.host	string	Host name of the JSON object_list TCP server (typically the Docker service name)
object_list.port	int	Port number of the JSON object_list TCP server
occupations	object	Event Zone Server occupations configuration
occupations.host	string	Host name of the JSON occupations TCP server (typically the Docker service name)
occupations.port	int	Port number of the JSON occupations TCP server
diagnostics	object	System Diagnostics configuration
aggregation	object	Aggregation Module configuration

Optional perception Fields

Optional perception Fields

Field	Format	Description
perception_server_api	string	URL of the Perception Server RESTful API endpoint (default = https://perception:8000/perception/api/v1/)
event_zone_server_api	string	URL of the Event Zone Server RESTful API endpoint (default = https://event-zones:8001/event/api/v1/)
agent_api	string	URL of the Ouster Agent RESTful API endpoint (default = http://host.docker.internal:4443/agent/api/v1/)
inference_server_api	string	URL of the Ouster ML Server RESTful API endpoint (default = http://ml-detection:5000/ml-detectio/api/v1/)
analytic_server_api	string	URL of the Ouster Event Server RESTful API endpoint (default = http://ouster-analytic-server:8004/analytic/api/v1/)
agent_timeout_secs	float	Maximum time to wait for Agent connectivity (default = 30 seconds)
perception_websocket.tls	bool	Flag indicating if the Perception Server web socket server requires TLS (default = true)
perception_websocket.connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the Perception Server web socket server (default = 60.0)
perception_websocket.receive_timeout_secs	float	Seconds to wait before resetting a connection due to no data being received from the Perception Server web socket server (default = 60.0)
event_zone_websocket.tls	bool	Flag indicating if the Event Zone Server web socket server requires TLS (default = true)
event_zone_websocket.connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the Event Zone Server web socket server (default = 60.0)
event_zone_websocket.receive_timeout_secs	float	Seconds to wait before resetting a connection due to no data being received from the Event Zone Server web socket server (default = 60.0)
object_list.tls	bool	Flag indicating if the JSON object_list TCP server requires TLS (default = true)
object_list.connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the JSON object_list TCP server (default = 60.0)
object_list.receive_timeout_secs	float	Seconds to wait before resetting a connection due to no data being received from the JSON object_list TCP server (default = 60.0)
object_list.suppress_unoccupied_frames	bool	Flag indicating if unoccupied frames shoud be supressed from processing and all published streams (default = false)
occupations.tls	bool	Flag indicating if the JSON occupations TCP server server requires TLS (default = true)
occupations.connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the JSON occupations TCP server (default = 60.0)
occupations.receive_timeout_secs	float	Seconds to wait before resetting a connection due to no data being received from the JSON occupations TCP server (default = 60.0)
occupations.suppress_unoccupied_frames	bool	Flag indicating if unoccupied frames should be suppressed from processing and all published streams (default = false)

System Diagnostics

The Lidar Hub includes a Systems Diagnostics module that collects and aggregates statistics, health, alerts, and telemetry from the compute device, all active Lidar sensors and all software related to the Perception Solution, including the Lidar Hub itself. The Diagnostics data is broken into three buckets:

• Attributes: Static data that is only reported when changed.

• Telemetry: Dynamic data that is reported every diagnostics_interval_secs

• Alerts: Lidar and software alerts reported with every detection and update

Configuration

The perception.diagnostics section of the Lidar Hub settings is used for configuring the generation of diagnostics. By default, diagnostics are enabled at an interval of once every 60-seconds.

Example

"perception": {
    ...
    "diagnostics": {
        "interval_secs": 60.0
    }
}

Primary diagnostics Fields

Primary diagnostics Fields

Field	Format	Description
diagnostics	object	Diagnostics configuration
diagnostics.interval_secs	float	Diagnostics interval in seconds. A diagnostics record is emitted every interval (DISABLED = 0)

Optional diagnostics Fields

None

Diagnostics Attributes

Compute device, lidar sensor and software Attributes will be published to the Gemini Portal when any value changes. The current attribute and telemetry diagnostics values can also be requested at any time via the Lidar Hub’s /diagnostics REST API resource.

Example Batching of one or more Frame(s) in a single Message

{
  "diagnostics": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "hardware_id": "*1234567890",
  "customer_id": "73bbb8a6-ffd7-4898-a8dd-8003441ec724",
  "label": "Site A",
  "latitude": 37.76466741329934,
  "longitude": -122.4136976526134,
  "azimuth": 57.6,
  "compute": {
    "host_name": "CATALYST-PRO-01",
    "mac_address": "FF:FF:FF:FF:FF:FF",
    "architecture": "x86_64",
    "is_arm": false,
    "has_gpu": false,
    "os_version": "",
    "last_upgrade": "",
    "last_upgrade_timestamp": 0,
    "total_cpu_cores": 16,
    "total_memory": 33354051584,
    "total_disk_space": 982141468672,
    "boot_timestamp": 1702226939,
    "health": "ONLINE"
  },
  "lidars": [
    {
      "model": "OS1",
      "serial_number": "992144000616",
      "hostname": "os-992144000616.local.",
      "ip_address": 255.255.255.255,
      "node_id": "",
      "beam_configuration": "128",
      "firmware": {
        "version": "v2.3.1",
        "image": "ousteros-image-prod-aries-v2.5.3+20240111055903"
      },
      "position": {
        "x": -122.4136976526134,
        "y": 37.76466741329934,
        "z": 3.42
      },
      "connection_status": "connected",
      "status": "RUNNING",
      "is_ml": false,
      "host_health": "ONLINE",
      "health": "ONLINE"
    }
  ],
  "nodes": [
    {
      "hostname": "NODE-A,
      "id": "ABCD1234EFGH5678",
      "license": "none",
      "position": {
        "x": 12.37,
        "y": -8.97,
        "z": 0.01
      },
      "perception_client": "connected",
      "port": 1234,
      "raw_frame_client": "connected",
      "rest_client": "connected",
      "host_health": "ONLINE",
      "health": "ONLINE"
    }
  ],
  "solutions_agent": {
    "software_version": "2.2.0",
    "package_version": "2.2.0-1,
    "is_running": true,
    "is_software_repository_available": true,
    "software_repository_version": ""
  },
  "perception_server": {
    "software_version": "2.2.0",
    "settings_version": 5,
    "is_ml": false,
    "is_aggreagtor": false,
    "is_running": true,
    "is_paused": false,
    "license": "none",
    "num_inclusion_zones": 0,
    "num_exclusion_zones": 0,
    "configuration": {
    },
    "extrinsics": {
    }
  },
  "event_zone_server": {
    "software_version": "2.2.0",
    "settings_version": "1.0.0",
    "is_running": true,
    "license": "none",
    "num_event_zones": 0,
    "configuration": {
    },
    "event_zones": {
    }
  },
  "lidar_hub": {
    "software_version": "2.2.0",
    "settings_version": "2.2.0.1",
    "license": "none",
    "is_running": true,
    "diagnostics_enabled": true,
    "aggregation_enabled": false,
    "mqtt_publishers": 0,
    "tcp_relay_servers": 2,
    "datarecorders": [
    ],
    "configuration": {
    },
    "is_scout": false
  },
  "health": "ONLINE",
  "is_scout": false,
  "diagnostics_version": 2.2.0
}

JSON Field Definitions

JSON Field Definitions

Field	Format	Description
hardware_id	string	identifying ID of Edge Device (MAC Address or Agent Locking Code)
customer_id	string	Your Gemini Portal Customer ID (provided by Ouster)
label	string	User-defined label displayed in the Gemini Portal and used as an MQTT Publisher configuration variable
latitude	float	Lidar Hub world latitude
longitude	float	Lidar Hub world longitude
azimuth	float	Lidar Hub world azimuth
compute	object	Compute Device details
compute.host_name	string	Host name of the compute device
compute.mac_address	string	MAC Address of the compute device
compute.architecture	string	Compute device CPU architecture (x86_64, aarch64)
compute.is_arm	bool	Indicator if the compute device CPU architecture is identified as ARM
compute.has_gpu	bool	Indicator if at least one compute device GPU has been detected
`compute.os_version	string	Operating system of the compute device
compute.last_upgrade	string	Description of last OS upgrade performed on the compute device
compute.last_upgrade_timestamp	int	Timestamp of last OS upgrade performed on the compute device (microseconds since Jan. 1, 1970)
compute.total_cpu_cores	int	Number of CPU cores on the compute device
compute.total_memory	int	Total memory installed in compute device (bytes)
compute.total_disk_space	int	Total storage installed in compute device (bytes)
compute.boot_timestamp	int	System boot time (seconds since Jan. 1, 1970)
compute.health	int	Determined health of the compute device (ONLINE / WARNING / OFFLINE)
lidars	array	Array of active Lidar sensors
lidars[].model	string	Lidar sensor model
lidars[].serial_number	string	Lidar sensor serial number
lidars[].hostname	string	Lidar sensor host name
lidars[].ip_address	string	Lidar sensor IP Address
lidars[].beam_configuration	string	Lidar sensor beam configuration as reported by the firmware
lidars[].firmware	object	Lidar Firmware details
lidars[].firmware.version	string	Lidar sensor firmware version as reported by the firmware
lidars[].firmware.image	string	Lidar sensor firmware image as reported by the firmware
lidars[].position	object	Lidar sensor position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
lidars[].position.x	float	x cartesian coordinates or longitude
lidars[].position.y	float	x cartesian coordinates or latitude
lidars[].position.z	float	height in meters
lidars[].connection_status	string	Lidar sensor connection status
lidars[].status	string	Lidar sensor status as reported by the firmware
lidars[].is_ml	string	Indicator if sensor is being used for ML Perception
lidars[].host_health	string	Health of the lidar sensor’s host
lidars[].health	string	Determined health of the lidar sensor (ONLINE / WARNING / OFFLINE)
nodes	array	Array of active Leaf Nodes for Aggregator when Distributed Perception in use
nodes[].host_name	string	Host name of the Leaf Node compute device
nodes[].id	string	Leaf Node ID when sensor is running as part a Distributed Perception Aggregator
nodes[].license	string	Leaf Node license details
nodes[].position	object	Leaf Node position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
nodes[].position.x	float	x cartesian coordinates or longitude
nodes[].position.y	float	x cartesian coordinates or latitude
nodes[].position.z	float	height in meters
nodes[].perception_client	string	Indicator of connectivity w/Perception Aggregator
nodes[].port	string	Perception Aggregator listening port
nodes[].raw_frame_client	string	Perception Aggregator’s web socket connection status to the Leaf Node
nodes[].rest_client	string	Perception Aggregator’s REST API connection status to the Leaf Node
nodes[].host_health	string	Health of the Perception Aggregator
nodes[].health	string	Determined health of the Leaf Node (ONLINE / WARNING / OFFLINE)
`solutions_agent	object	Ouster Solutions Agent details
solutions_agent.software_version	string	Ouster Solutions Agent software version
solutions_agent.package_version	string	Ouster Solutions Agent package version (DEB/RPM/etc.)
solutions_agent.is_running	bool	Indication if the Ouster Solutions Agent is running
solutions_agent.is_software_repository_available	bool	Indicator if registry.ouster.com is available
solutions_agent.software_repository_version	string	Latest package version available in registry.ouster.com
perception_server	object	Perception Server details
perception_server.software_version	string	Perception Server software version
perception_server.settings_version	string	Perception Server settings version
perception_server.is_ml	bool	Indication if the Perception Server is running ML Perception
perception_server.is_aggregator	bool	Indication if the Perception Server is running as a Distributed Perception Aggregator
perception_server.is_running	bool	Indication if the Perception Server is running
perception_server.is_paused	bool	Indication if the Perception Server is paused on a replay
perception_server.license	string	Perception Server license details
perception_server.num_inclusion_zones	int	Number of Perception Server inclusion zones
perception_server.num_exclusion_zones	int	Number of Perception Server exclusion zones
perception_server.configuration	object	Perception Server configuration
perception_server.extrinsics	object	Perception Server extrinsics
event_zone_server	object	Event Zone Server details
event_zone_server.software_version	string	Event Zone Server software version
event_zone_server.settings_version	string	Event Zone Server settings version
event_zone_server.is_running	bool	Indication if the Event Zone Server is running
event_zone_server.license	string	Event Zone Server license details
`event_zone_server.num_event_zones	int	Number of Event Zone Server event zones
event_zone_server.configuration	object	Event Zone Server configuration
event_zone_server.event_zones	object	Event Zone Server Event Zones
lidar_hub	object	Lidar Hub details
lidar_hub.software_version	string	Lidar Hub software version
lidar_hub.settings_version	string	Lidar Hub settings version
lidar_hub.license	string	Lidar Hub license details
lidar_hub.is_running	bool	Indication if the Lidar Hub is running
lidar_hub.diagnostics_enabled	bool	Indication if Diagnostics are enabled
lidar_hub.aggregation_enabled	bool	Indication if Aggregation is enabled
lidar_hub.mqtt_publishers	int	Number of configured MQTT publishers
lidar_hub`.tcp_relay_servers	int	Number of configured TCP Relay Servers
lidar_hub.datarecorders	list	List of configured Data Recorders
lidar_hub.configuration	object	Lidar Hub configuration
lidar_hub.is_scout	bool	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
health	string	Determined health of the Perception System (ONLINE / WARNING / OFFLINE)
is_scout	bool	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
diagnostics_version	string	Version of this message

Diagnostics Telemetry

Compute device, lidar sensor and software Telemetry will be generated at the diagnostics_interval_secs and published to the Gemini Portal and an internal memory-based broker for consumption by MQTT Publishers, TCP Relay Servers and Data Recorders. The current attribute and telemetry diagnostics values can also be requested at any time via the Lidar Hub’s /diagnostics REST API resource.

Example Batching of one or more Frame(s) in a single Message

{
  "diagnostics": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "hardware_id": "*1234567890",
  "latitude": 37.76466741329934,
  "longitude": -122.4136976526134,
  "azimuth": 57.6,
  "compute": {
    "cpu_utilization": 19.6,
    "cpu_core_utilization": [
        18.9,
        18.7,
        21.9,
        16.8,
        19.3,
        16.9,
        27.6,
        16.9
    ],
    "cpu_temperature_deg_c": 73,
    "cpu_core_temperature_deg_c": [
        73,
        72,
        69,
        70
    ],
    "gpu_utilization": 0,
    "gpu_temperature_deg_c": 0,
    "available_memory": 18890395648,
    "available_disk_space": 762672287744
  },
  "lidars": [
    {
      "model": "OS1",
      "serial_number": "992144000616",
      "firmware": {
        "input_current_ma": 704,
        "input_voltage_mv": 24044,
        "internal_temperature_deg_c": 0,
        "phase_lock_status": "DISABLED",
        "timestamp_ns": 1727503038782740
      },
      "position": {
        "x": -122.4136976526134,
        "y": 37.76466741329934,
        "z": 3.42
      },
      "num_background_points": 83010,
      "num_foreground_points": 416,
      "num_failed_points": 865,
      "num_no_return_points": 46781,
      "num_zone_filtered_points": 4,
      "num_ground_points": 0,
      "num_clusters": 6,
      "num_filtered_clusters": 0,
      "percentage_incomplete_frames": 0,
      "tilt_since_reset": 0.08322851640914329
    }
  ],
  "nodes": [
  ],
  "solutions_agent": { },
  "perception_server": {
    "up_time": 0,
    "num_objects": 0,
    "num_websocket_clients": 3,
    "num_tcp_clients": 3,
    "largest_arrival_delta": 134,
    "lowest_frame_rate": 5.979538020892506,
    "mean_frame_rate": 10.872046880266147,
    "benchmarks": [
    ],
    "timestamp": 1660673730063520
  },
  "event_zone_server": {
    "up_time": 0,
    "num_occupations": 0,
    "num_websocket_clients": 2,
    "num_tcp_clients": 2,
    "timestamp": 1660673730110978
  },
  "lidar_hub": {
    "up_time": 338111.726481,
    "cloud_ingress_mbps": 0.0000176,
    "cloud_ingress_bytes": 132,
    "cloud_ingress_entries": 1,
    "cloud_egress_mbps": 0.0030373333333333333,
    "cloud_egress_bytes": 22780,
    "cloud_egress_entries": 6,
    "mqtt_publishers_connected": 4,
    "mqtt_publishers_mbps": 0.0028957333333333333,
    "mqtt_publishers_bytes": 21718,
    "mqtt_publishers_entries": 4,
    "tcp_relay_server_connections": 0,
    "tcp_relay_server_mbps": 0,
    "tcp_relay_server_bytes": 0,
    "tcp_relay_server_entries": 0,
    "datarecorders_disk_bytes": 10573,
    "datarecorders_disk_entries": 3,
    "timestamp": 1710781920008258
  },
  "timestamp": 1660698930000000,
  "is_scout": false,
  "diagnostics_version": "2.0.0"
}

JSON Field Definitions

JSON Field Definitions

Field	Format	Description
hardware_id	string	MAC Address of the compute device (MAC Address or Agent Locking Code)
latitude	float	Lidar Hub world latitude
longitude	float	Lidar Hub world longitude
azimuth	float	Lidar Hub world azimuth
compute	object	Compute Device details
compute.cpu_utilization	float	Total CPU utilization across all cores
compute.cpu_core_utilization	list	CPU utilization by core
compute.cpu_temperature_deg_c	float	Average CPU temperature across all cores
compute.cpu_core_temperature_deg_c	list	CPU temperature by core
compute.gpu_utilization	float	Total GPU utilization across all cores
compute.gpu_temperature_deg_c	float	Average GPU temperature across all cores
compute.available_memory	int	Available memory on the compute device (bytes)
compute.available_disk_space	int	Available storage on the compute device (bytes)
lidars	array	Array of active Lidar sensors
lidars[].model	string	Lidar sensor model
lidars[].serial_number	string	Lidar senor serial number
lidars[].firmware	object	Lidar Firmware details
lidars[].firmware.input_current_ma	int	Lidar sensor input current as reported by the firmware (milliamps)
lidars[].firmware.input_voltage_mv	int	Lidar sensor input voltage as reported by the firmware (millivolts)
lidars[].firmware`.internal_temperature_deg_c	int	Lidar sensor internal temperature as reported by the firmware (degrees celsius)
lidars[].firmware.phase_lock_status	string	Lidar sensor phase lock status as reported by the firmware
lidars[].firmware.timestamp_ns	int	Timestamp of these values as reported by the firmware (nanoseconds since Jan. 1, 1970)
lidars[].position	object	Lidar sensor position (geo-coordinates if Lidar Hub world is set, otherwise cartesian coordinates in the world reference frame)
lidars[].position.x	float	x cartesian coordinates or longitude
lidars[].position.y	float	x cartesian coordinates or latitude
lidars[].position.z	float	height in meters
lidars[].num_background_points	int	Number of background points for the last frame
lidars[].num_foreground_points	int	Number of foreground points for the last frame
lidars[].num_failed_points	int	Number of failed points for the last frame
lidars[].num_no_return_points	int	Number of points not returned for the last frame
lidars[].num_zone_filtered_points	int	Number of points filted by inclusion and exclusion zones for the last frame
lidars[].num_ground_points	int	Number of points filtered as ground points for the last frame
lidars[].num_clusters	int	Number of clusters detected for the last frame
lidars[].num_filtered_clusters	int	Number of clusters remaining after filtering and merging for the last frame
lidars[].percentage_incomplete_frames	float	Percentage of incomplete frames
lidars[].tilt_since_reset	float	Change in sensor tilt since last reset
nodes	array	Array of active Leaf Nodes for Aggregator when Distributed Perception in use
solutions_agent	object	Ouster Solutions Agent details
perception_server	object	Perception Server details
perception_server.up_time	int	Perception Server run time since last started
perception_server.num_objects	int	Number of objects currently being tracked by the Perception Server
perception_server.num_websocket_clients	int	Number of web socket clients connected to the Perception Server
perception_server.num_tcp_clients	int	Number of TCP clients connected to the Perception Server
perception_server.largest_arrival_delta	float	Difference between all the arrival times of all the sensors
perception_server.lowest_frame_rate	float	The longest time to process a frame in the last 10 seconds
perception_server.mean_frame_rate	float	The average time to process a frame
perception_server.benchmarks	array	Perception Server benchmark statistics
perception_server.timestamp	int	Timestamp of these values (microseconds since Jan. 1, 1970)
event_zone_server	object	Event Zone Server details
event_zone_server.up_time	int	Event Zone Server run time since last started
event_zone_server.num_occupations	int	Number of objects currently being positioned inside event zone(s)
event_zone_server.num_websocket_clients	int	Number of web socket clients connected to the Event Zone Server
event_zone_server.num_tcp_clients	int	Number of TCP clients connected to the Event Zone Server
event_zone_server.timestamp	int	Timestamp of these values (microseconds since Jan. 1, 1970)
lidar_hub	object	Lidar Hub details
lidar_hub.up_time	int	Lidar Hub run time since last started
lidar_hub.cloud_ingress_mbps	float	Cloud inbound Megabits/Second of last timeseries
lidar_hub.cloud_ingress_bytes	int	Cloud inbound total Bytes of last timeseries
lidar_hub.cloud_ingress_entries	int	Cloud inbound total Entries of last timeseries
lidar_hub.cloud_egress_mbps	float	Cloud outbound Megabits/Second of last timeseries
lidar_hub.cloud_egress_bytes	int	Cloud outbound total Bytes of last timeseries
lidar_hub.cloud_egress_entries	int	Cloud outbound total Entries of last timeseries
lidar_hub.mqtt_publishers_connected	int	Number of configured MQTT publishers connected to their endpoint
lidar_hub.mqtt_publishers_mbps	float	MQTT Megabits/Second of last timeseries
lidar_hub.mqtt_publishers_bytes	int	MQTT total Bytes of last timeseries
lidar_hub.mqtt_publishers_entries	int	MQTT total Entries of last timeseries
lidar_hub.tcp_relay_server_connections	int	Number of TCP clients connected to Lidar Hub TCP Relay Servers
lidar_hub.tcp_relay_server_mbps	float	TCP Megabits/Second of last timeseries
lidar_hub.tcp_relay_server_bytes	int	TCP total Bytes of last timeseries
lidar_hub.tcp_relay_server_entries	int	TCP total Entries of last timeseries
lidar_hub.datarecorders_disk_bytes	int	Data Recorder total Bytes of last timeseries
lidar_hub.datarecorders_disk_entries	int	Data Recorder total Entries of last timeseries
lidar_hub.timestamp	int	Timestamp of these values (microseconds since Jan. 1, 1970)
timestamp	int	Timestamp of this message (microseconds since Jan. 1, 1970)
is_scout	bool	Indication if Lidar Hub is running as a Scout (standalone w/out a Perception Server)
diagnostics_version	string	Version of this message

Dignostics Alerts

Lidar sensor and software Alerts will be published when first detected and when any update is reported to the internal memory-based broker for consumption by MQTT Publishers, TCP Relay Servers and Data Recorders.

Example

{
  "alerts": [
    {
      "active": true,
      "category": "SHOT_LIMITING",
      "cursor": 2833,
      "alert_code": "0x0100000f",
      "level": "WARNING",
      "source_info": "OS1-992144000616",
      "id": 13962805723535194000,
      "msg": "Shot limiting mode is active. Laser power is partially attenuated;
             please see user guide for heat sinking requirements.",
      "msg_verbose": "Shot limiting has started.",
      "first_occurred": 0,
      "last_occurred": 0,
      "active_count": 0
    },
    {
      "active": true,
      "category": "UDP_TRANSMISSION",
      "cursor": 2822,
      "alert_code": "0x01000016",
      "level": "WARNING",
      "source_info": "OS1-992144000616",
      "id": 11061546793406626000,
      "msg": "Could not send lidar data UDP packet to host; check that network is up.",
      "msg_verbose": "Failed to send lidar UDP data to destination host 10.0.0.39:34642",
      "first_occurred": 0,
      "last_occurred": 0,
      "active_count": 0
    }
  ]
}

JSON Field Definitions

JSON Field Definitions

Field	Format	Description
alerts	array	Array of active alerts
alerts[].active	bool	Indication if the alert is still active
alerts[].category	string	Alert category (application specific)
alerts[].cursor	int	Alert cursor (lidar only)
alerts[].alert_code	string	Alert code (application specific - hex)
alerts[].level	string	Alert level (application specific)
alerts[].source_info	string	Alert source information (application specific)
alerts[].id	int	Unique alert ID (application specific)
alerts[].msg	int	Alert message
alerts[].msg_verbose	int	Additional alert details (if any)
alerts[].first_occurred	int	First occurrence of the alert code (micro/nano seconds since Jan. 1, 1970)
alerts[].last_occurred	int	Last occurrence of the alert code (micro/nano seconds since Jan. 1, 1970)
alerts[].active_count	int	Total occurrences of the alert code

Aggregation Module

The Lidar Hub includes an on-device Aggregation module that aggregates zone occupations by timeseries by object classification. A system-defined classification of “ALL” will also be aggregated for each zone representing an aggregate of all objects. The Aggregation module also aggregates all tracked objects by timeseries by object classification into a system-defined site-wide zone with an id of 0.

The Aggregation module generates three outputs:

• TimeSeries: Detailed occupancy metrics by zone by classification reported every timeseries_secs.

• RealTime: Summary occupancy metrics by zone by classification reported on change, but not more frequently than realtime_hertz.

• Alerts: Zone occupancy alerts generated on rule violation, but not more frequently than realtime_hertz.

Configuration

The perception.aggregation section of the Lidar Hub settings is used for configuring the Aggregation module. By default, the Aggregation module is enabled with a timeseries interval of 60 seconds and a real-time interval of 1Hz.

Example

"perception": {
    ...
    "aggregation": {
        "timeseries_secs": 60.0,
        "realtime_hertz": 1.0
    }
}

Primary aggregation Fields

Primary aggregation Fields

Field	Format	Description
aggregation	object	Aggregation module configuration
aggregation.timeseries_secs	float	Aggregation interval in seconds…a timeseries record is emitted every interval (DISABLED = 0)
aggregation.realtime_hertz	float	Frequency at which Aggregation will emit real-time updates (DISABLED = 0)

Optional aggregation Fields

Optional aggregation Fields

Field	Format	Description
aggregation.source_hertz	float	Frequency at which Aggregation will process Perception data (default = 2.0)
aggregation.realtime_transmit_hertz	float	Frequency at which real-time data will be published (default = 1.0)
aggregation.timeseries_transmit_hertz	float	Frequency at which timeseries data will be published (default = 0.0)
aggregation.departure_debounce_ms	int	Timeout before exiting an object from a given zone in milliseconds (default = 2500)
aggregation.excluded_classifications	list	List of classifications to be excluded from Aggregation (default = [“PROSPECT”, “UNKNOWN”])
aggregation.storage_path	string	Path for the non-volatile storage of aggregation metrics…clear to disable (default = /opt/ouster/conf/data/storage)

Aggregation RealTime Events

Event Zone real-time occupancy events will be generated in real-time and published at transmit_realtime_hertz to the internal memory-based broker for consumption by the Gemini Portal, MQTT Publishers, TCP Relay Servers and Data Recorders.

Example Batching of one or more Frame(s) in a single Message

{
  "aggregation_realtime": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
  "timestamp": 1711227039549025,
  "aggregation_realtime": [
    {
      "id": 1659467677889,
      "name": "Office",
      "timestamp": 1660664443771926,
      "current_point_count": 350,
      "classification_metrics": [
        {
          "description": "ALL",
          "active_occupants": 115,
          "total_visitors": 1200,
          "total_visits": 1275,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        },
        {
          "description": "PERSON",
          "active_occupants": 105,
          "total_visitors": 1160,
          "total_visits": 1235,
          "last_update": 1660664443771926,
          "sub_classification_metrics": [
            {
              "description": "pedestrian",
              "active_occupants": 105,
              "total_visitors": 1160,
              "total_visits": 1235,
              "last_update": 1660664443771926
            }
          ]
        }
      ]
    },
    {
      "id": 1658947733821,
      "name": "Desk",
      "timestamp": 1660664443771926,
      "current_point_count": -1,
      "classification_metrics": [
        {
          "description": "ALL",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 2,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        },
        {
          "description": "PERSON",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 2,
          "last_update": 1660664443771926,
          "sub_classification_metrics": [
            {
              "description": "pedestrian",
              "active_occupants": 1,
              "total_visitors": 1,
              "total_visits": 2,
              "last_update": 1660664443771926
            }
          ]
        },
        {
          "description": "UNKNOWN",
          "active_occupants": 1,
          "total_visitors": 1,
          "total_visits": 1,
          "last_update": 1660664443771926,
          "sub_classification_metrics": []
        }
      ]
    }
  ]
}

JSON Field Definitions

Aggregation Real-Time Description

Field	Format	Definition
timestamp	int	Timestamp of when the update was generated. Units in microseconds since Jan. 1, 1970.
aggregation_realtime	array	Array of Event Zone real-time occupancy updates

realtime update

Real-time occupancy for a given Event Zone.

JSON Field Definitions

Field	Format	Description
id	int	Event Zone ID
name	string	Event Zone name
timestamp	int	Timestamp of the real-time event (microseconds since Jan. 1, 1970)
current_point_count	int	Number of points currently occupying the zone (-1 indicates this feature is disabled)
classification_metrics	array	Array of object classifications occupying the zone
classification_metrics.description	string	Object classification name (“ALL” indicates an aggregate of all classifications)
classification_metrics.active_occupants	int	Number of objects currently occupying the zone
classification_metrics.total_visitors	int	Total unique visitors that visited the zone at least once. Uniqueness is defined by each object’s uuid.
classification_metrics.total_visits	int	Total visits to the zone.
classification_metrics.last_update	int	Last zone update (microseconds since Jan. 1, 1970)
classification_metrics.sub_classification_metrics	array	Optional array of object sub-classifications occupying the zone. ML Perception required.
classification_metrics.sub_classification_metrics.description	string	Object sub-classification name
classification_metrics.sub_classification_metrics.active_occupants	int	Number of objects currently occupying the zone
classification_metrics.sub_classification_metrics.total_visitors	int	Total unique visitors that visited the zone at least once. Uniqueness is defined by each object’s uuid.
classification_metrics.sub_classification_metrics.total_visits	int	Total visits to the zone.
classification_metrics.sub_classification_metrics.last_update	int	Last zone update (microseconds since Jan. 1, 1970)

Aggregation TimeSeries Aggregates

Zone timeseries aggregates will be generated every timeseries_secs and published at transmit_timeseries_hertz to the internal memory-based broker for consumption by the Gemini Portal, MQTT Publishers, TCP Relay Servers and Data Recorders.

Example Batching of one or more Frame(s) in a single Message

{
  "aggregation_timeseries": [
    {...},
    {...},
    {...}
  ]
}

Example Frame

{
   "timestamp": 1711227039549025,
   "aggregation_timeseries": [
       {
       "id": 1659467677889,
       "name": "Office",
       "timestamp": 1660664440000000,
       "current_point_count": 350,
       "current_max_point_count": 870,
       "current_avg_point_count": 125,
       "overall_max_point_count": 1190,
       "overall_avg_point_count": 85,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 5,
               "total_visits": 5,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.122,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.122,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829
             }
           ]
         }
       ]
     },
     {
       "id": 1658947733821,
       "name": "Desk",
       "timestamp": 1660664440000000,
       "current_point_count": -1,
       "current_max_point_count": -1,
       "current_avg_point_count": 0,
       "overall_max_point_count": -1,
       "overall_avg_point_count": 0,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.122,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.122,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 5,
               "total_visits": 5,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.122,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.122,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829,
             }
           ]
         }
       ]
     },
     {
       "id": 0,
       "name": "Edge-FF:FF:FF:FF:FF:FF",
       "timestamp": 1660664440000000,
       "classification_metrics": [
         {
           "description": "ALL",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 5,
           "total_visits": 5,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.124,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.124,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": []
         },
         {
           "description": "PERSON",
           "active_occupants": 1,
           "max_active_occupants": 1,
           "avg_active_occupants": 1,
           "total_visitors": 1,
           "total_visits": 1,
           "new_visitors": 1,
           "new_visits": 1,
           "departed_visitors": 0,
           "current_max_speed": 0.227,
           "current_avg_speed": 0.124,
           "overall_max_speed": 0.22669327197460112,
           "overall_avg_speed": 0.124,
           "current_avg_dwell": 0,
           "overall_avg_dwell": 0,
           "last_update": 1660664449970829,
           "sub_classification_metrics": [
             {
               "description": "pedestrian",
               "active_occupants": 1,
               "max_active_occupants": 1,
               "avg_active_occupants": 1,
               "total_visitors": 1,
               "total_visits": 1,
               "new_visitors": 1,
               "new_visits": 1,
               "departed_visitors": 0,
               "current_max_speed": 0.227,
               "current_avg_speed": 0.124,
               "overall_max_speed": 0.22669327197460112,
               "overall_avg_speed": 0.124,
               "current_avg_dwell": 0,
               "overall_avg_dwell": 0,
               "last_update": 1660664449970829
             }
           ]
         }
       ]
     }
   ]
 }

JSON Field Definitions

Aggregation Timeseries Description

Field	Format	Definition
timestamp	int	Timestamp of when the update was generated. Units in microseconds since Jan. 1, 1970.
aggregation_timeseries	array	Array of Event Zone timeseries aggregates

timeseries aggregates

Timeseries aggregates for a given Event Zone.

JSON Field Definitions

Field	Format	Description
id	int	Event Zone ID
name	string	Event Zone name
current_point_count	int	Number of points currently occupying the zone (-1 indicates this feature is disabled)
current_max_point_count	int	Maximum number of points occupying the zone in this timeseries (-1 indicates this feature is disabled)
current_avg_point_count	float	Average number of points occupying the zone in this timeseries
overall_max_point_count	int	Maximum number of points occupying the zone (-1 indicates this feature is disabled)
overall_avg_point_count	float	Average number of points occupying the zone
timestamp	int	Timestamp of the timeseries aggregate (microseconds since Jan. 1, 1970)
classification_metrics	array	Array of object classifications occupying the zone
classification_metrics.description	string	Object classification name (“ALL” is an aggregate of all classifications)
classification_metrics.active_occupants	int	Number of objects currently occupying the zone
classification_metrics.max_active_occupants	int	Maximum number of objects occupying the zone in this timeseries
classification_metrics.avg_active_occupants	int	Average number of objects occupying the zone in this timeseries
classification_metrics.total_visitors	int	Total unique visitors to the zone. Uniqueness is defined by each object’s uuid.
classification_metrics.total_visits	int	Total visits to the zone
classification_metrics.new_visitors	int	New unique visitors to the zone in this timeseries. Uniqueness is defined by each object’s uuid.
classification_metrics.new_visits	int	New visits to the zone in this timeseries
classification_metrics.departed_visitors	int	Total unique visitors that left the zone in this timeseries. Uniqueness is defined by each object’s uuid.
classification_metrics.current_max_speed	float	Maximum speed observed in the zone in this timeseries
classification_metrics.current_avg_speed	float	Average speed observed in the zone in this timeseries
classification_metrics.overall_max_speed	float	Maximum speed observed in the zone
classification_metrics.overall_avg_speed	float	Average speed observed in the zone
classification_metrics.current_avg_dwell	float	Average dwell observed in the zone in this timeseries
classification_metrics.overall_avg_dwell	float	Average dwell observed in the zone
classification_metrics.last_update	int	Last zone update (microseconds since Jan. 1, 1970)
classification_metrics.sub_classification_metrics	array	Optional array of object sub-classifications occupying the zone. ML Perception required.
classification_metrics.sub_classification_metrics.description	string	Object sub-classification name
classification_metrics.sub_classification_metrics.active_occupants	int	Number of objects currently occupying the zone
classification_metrics.sub_classification_metrics.max_active_occupants	int	Maximum number of objects occupying the zone in this timeseries
classification_metrics.sub_classification_metrics.avg_active_occupants	int	Average number of objects occupying the zone in this timeseries
classification_metrics.sub_classification_metrics.total_visitors	int	Total unique visitors to the zone. Uniqueness is defined by each object’s uuid.
classification_metrics.sub_classification_metrics.total_visits	int	Total visits to the zone
classification_metrics.sub_classification_metrics.new_visitors	int	New unique visitors to the zone in this timeseries. Uniqueness is defined by each object’s uuid.
classification_metrics.sub_classification_metrics.new_visits	int	New visits to the zone in this timeseries
classification_metrics.sub_classification_metrics.departed_visitors	int	Total unique visitors that left the zone in this timeseries. Uniqueness is defined by each object’s uuid.
classification_metrics.sub_classification_metrics.current_max_speed	float	Maximum speed observed in the zone in this timeseries
classification_metrics.sub_classification_metrics.current_avg_speed	float	Average speed observed in the zone in this timeseries
classification_metrics.sub_classification_metrics.overall_max_speed	float	Maximum speed observed in the zone
classification_metrics.sub_classification_metrics.overall_avg_speed	float	Average speed observed in the zone
classification_metrics.sub_classification_metrics.current_avg_dwell	float	Average dwell observed in the zone in this timeseries
classification_metrics.sub_classification_metrics.overall_avg_dwell	float	Average dwell observed in the zone
classification_metrics.sub_classification_metrics.last_update	int	Last zone update (microseconds since Jan. 1, 1970)

Aggregation Alerts

The Aggregation module will generate real-time alerts whenever the occupancy of a zone exceeds a pre-defined Zone Alert condition set in a zone’s metadata. These alerts can be polled at any time via the Lidar Hub’s /event_zones/alerts REST API resource.

Example

"alert": [
  {
    "id": 1234567890,
    "name": "Warning Zone",
    "severity": "WARNING",
    "occupancy": 3,
    "message": "Zone is not empty"
  },
  {
    "id": 0987654321,
    "name": "Crosswalk Zone",
    "severity": "MAJOR",
    "occupancy": 1,
    "message": "Vehicle detected in crosswalk!"
  }
]

JSON Field Definitions

Alerts Description

Field	Format	Definition
alert	array	Array of real-time occupancy alerts
alert[].id	string	Event Zone ID
alert[].name	string	Event Zone name
alert[].severity	string	Severity of the event
alert[].occupancy	int	Current occupancy of the Event Zone
alert[].message	string	Message associated with the alert

JSON Data Streams w/Down-sampling, Batching & Field Mapping

One or more MQTT Publishers and/or TCP Relay Servers may be configured for supported JSON data streams (object_list | occupations | aggregation_realtime | aggregation_timeseries | diagnostics). MQTT Publishers and TCP Relay Servers enable the down-sampling and batching of JSON output, as well as custom field mapping, filtering and decimal precision of floating-point values. When running in a Docker container, all TCP Relay Server port(s) must be exposed in the compose.yml.

Since batching is inherent to this feature, transmissions are wrapped in a JSON array with the data stream name as the field name. Although this wrapping is enabled by default, it can be overridden by setting “return_as_array”: false in the specific MQTT Publisher/TCP Relay Server configuration. Please note that a malformed JSON message will be received if return_as_array is disabled and batching returns more than one frame.

Example Batching

{
  "object_list": [
    {...},
    {...},
    {...}
  ]
}

object_list, occupations and diagnostics JSON fields can be filtered and (optionally) renamed by setting field_mappings to a dictionary of key/value pairs, where the key is the field name and the value is the new name (leaving blank will result in no renaming). Once field_mappings are applied, all desired fields must be defined in the field_mappings dictionary. If the field is an object, list or dictionary, the entire object, list or dictionary will be returned…unless one of its fields are added to the field_mappings.

Example field_mappings

{
  "timestamp": "ts",
  "objects": "objs",
  "classification": "typ",
  "position": "pos",
  "velocity": "velo",
  "dimensions": "dim",
  "x": "x",
  "y": "y",
  "length": "l",
  "width": "w",
  "height": "h"
}

Once field_mappings are in use, decimal precision for floating-point values can be defined by setting “decimal_precision”. decimal_precision will only apply to fields defined in field_mappings and does NOT automatically propagate to nested fields in objects, lists or dictionaries. A value of -1 disables decimal_precision.

MQTT Publisher Configuration

The mqtt_publishers section of the Lidar Hub settings is used for configuring one or more MQTT Publisher(s). By default, no active MQTT Publishers are pre-configured, but an invalid example is included for reference.

Multiple publishing threads can be configured for a given MQTT Publisher. If a publisher falls behind, additional publishing threads will be launched until max_publishers is reached. A high_water_mark controls how far behind publishing can fall before messages are dropped. Once publishing is caught back up, the additional publishing threads will gradually be terminated in attempts to minimize resources while maintaining pace with the velocity of data.

${device_name} and ${device_label} are special variables that can be used in-line when defining the topic of an MQTT Publisher. The variable is replaced with its equivalent value at runtime.

Example

"mqtt_publishers": [
    {
        "source": "object_list",
        "host": "mqttbroker.mycompany.com",
        "port": 1883,
        "user_name": "",
        "password": "",
        "topic": "/v1/${device_name}/object_list",
        "qos": 1,
        "data_hertz": 1,
        "transmit_hertz": 1
    },
    {
      ...
    }
]

Primary mqtt_publishers Fields

Primary mqtt_publishers Fields

Field	Format	Description
mqtt_publishers	array	Array of MQTT Publishers
mqtt_publishers[].source	string	Comma-delimited list of desired JSON data stream source(s) (object_list, occupations, aggregation_realtime, aggregation_timeseries, diagnostics)
mqtt_publishers[].host	string	MQTT Broker host name/IP address
mqtt_publishers[].port	int	MQTT Broker port number (default = 1883)
mqtt_publishers[].user_name	string	MQTT Broker username to authenticate with [MQTT-3.1.3-11] (default = “”)
mqtt_publishers[].password	string	MQTT Broker password to authenticate with. Optional, set to “” if not required. (default = “”)
mqtt_publishers[].topic	string	MQTT Broker topic to publish to
mqtt_publishers[].qos	int	Quality of Service (0 = At most once, 1 = At least once (default), 2 = Exactly once)
mqtt_publishers[].data_hertz	float	Down-sampling Hz (a value of 0 disables down-sampling)
mqtt_publishers[].transmit_hertz	float	Transmission Hz (a value of 0 sends immediately, while a value greater than data_hertz invokes batching)

Optional mqtt_publishers Fields

Optional mqtt_publishers Fields

Field	Format	Description
mqtt_publishers[].client_id	string	User-defined MQTT Client ID. A uuid will be generated and used as the Client ID if one is not defined. “max_publishers” is limited to one when a user-defined Client ID is provided.
mqtt_publishers[].convert_to_geo_coordinates	bool	Converts cartesian coordinates to WGS84 longitude/latitude coordinates
mqtt_publishers[].connecting_timeout_secs	float	Seconds to wait for a connection to be established to the MQTT Broker (default = 5.0)
mqtt_publishers[].connect_retry_interval_secs	float	Delay in seconds before retrying a failed connection to the MQTT Broker (default = 60.0)
mqtt_publishers[].tls	bool	Indicator if MQTT Broker requires TLS (default = false (CURRENTLY NOT TESTED))
mqtt_publishers[].return_as_array	bool	Controls the wrapping of transmissions into a well-formed JSON array (default = true)
mqtt_publishers[].field_mappings	dict	JSON field filtering and renaming (default = {})
mqtt_publishers[].decimal_precision	int	Decimal precision for floating-point values (default = -1 (disabled))
mqtt_publishers[].min_publishers	int	Minimum number of publishing threads (default = 1)
mqtt_publishers[].max_publishers	int	Maximum number of publishing threads (default = 3)
mqtt_publishers[].max_retries	int	Maximum retry attempts to publish a given message (default = 2)
mqtt_publishers[].high_water_mark	int	Maximum number of messages pending to be published (default = 100)
mqtt_publishers[].reenqueue_failures	bool	Restore messages to send queue if max_retries is exceeded. If the high_water_mark is exceeded, the message will be dropped. (default = true)
mqtt_publishers[].heartbeat_interval_secs	float	Interval to send heartbeat_message when source stream is inactive (default = 0 (disabled))
mqtt_publishers[].heartbeat_message	string	Message to transmit when source stream is inactive (default = “{}”)

TCP Relay Server Configuration

The tcp_servers section of the Lidar Hub settings is used for configuring one or more TCP Relay Server(s). By default, TCP Relay Servers are pre-configured for object_list and occupations JSON data streams at 1Hz on ports 3302 and 3303 respectively.

Example

"tcp_servers": [
    {
      "source": "object_list",
      "port": 3302,
      "data_hertz": 0,
      "transmit_hertz": 0
    },
    {
      "source": "occupations",
      "port": 3303,
      "data_hertz": 0,
      "transmit_hertz": 0
    },
    {
      ...
    }
]

Primary tcp_servers Fields

Primary tcp_servers Fields

Field	Format	Description
tcp_servers	array	Array of TCP Relay Servers
tcp_servers[].source	string	Comma-delimited list of desired JSON data stream source(s) (object_list, occupations, aggregation_realtime, aggregation_timeseries, diagnostics)
tcp_servers[].port	int	TCP Relay Server listening port
tcp_servers[].data_hertz	float	Down-sampling Hz (a value of 0 disables down-sampling)
tcp_servers[].transmit_hertz	float	Transmission Hz (a value of 0 sends immediately while a value greater than data_hertz invokes batching)

Optional tcp_servers Fields

Optional tcp_servers Fields

Field	Format	Description
tcp_servers[].tls	bool	Enable TLS (default = true)
tcp_servers[].convert_to_geo_coordinates	bool	Converts cartesian coordinates to WGS84 longitude/latitude coordinates
tcp_servers[].return_as_array	bool	Controls the wrapping of transmissions into a well-formed JSON array (default = true)
tcp_servers[].field_mappings	dict	JSON field filtering and renaming (default = {})
tcp_servers[].decimal_precision	int	Decimal precision for floating-point values (default = -1 (disabled))
tcp_servers[].heartbeat_interval_secs	float	Interval to send heartbeat_message when source stream is inactive (default = 0 (disabled))
tcp_servers[].heartbeat_message	string	Message to transmit when source stream is inactive (default = “{}”)

Event Recorder

The Lidar Hub Event Recorder can generate recordings in real-time when the occupancy of a zone exceeds a pre-defined Zone Event Recorder condition set in a zone’s metadata.

The Event Data Recorder maintains a rolling buffer of perception output for the recording of activity before an event occurs. Completed recordings are uploaded to the Ouster Gemini Portal (if configured) for playback. The module also supports a retention period, compression and purge strategies for handling recordings when the device is offline/not configured to upload to the Gemini Portal. By default, recordings are saved to disk before they are uploaded to the Gemini Portal. In the event a recording fails to upload to the Gemini Portal, the Event Recorder vacuum (enabled by default) will continiously reattempt to upload recording(s) until successful or disabled.

Configuration

The event_recorder section of the Lidar Hub settings is used for configuring the Event Data Recorder module. By default, Data Recording is disabled for all features.

When both “json_data”.”object_list_enabled” and “binary_data”.”trackedobjects_enabled” are set, “binary_data”.”trackedobjects_enabled” will take precedence.

When both “json_data”.”occupations_enabled” and “binary_data”.”zone_events_enabled” are set, “binary_data”.”zone_events_enabled” will take precedence.

The following options must at least be set for recordings that are intended to be played with the Ouster Gemini Portal Player:

• “binary_data”.”pointclouds_enabled”: true

• “binary_data”.”clusters_enabled”: true

• “binary_data”.”trackedobjects_enabled”: true

• “binary_data”.”zone_events_enabled”: true

Example

"event_recorder": {
  "json_data": {
    "object_list_enabled": false,
    "occupations_enabled": false,
    "aggregation_timeseries_enabled": false,
    "aggregation_realtime_enabled": false,
    "diagnostics_enabled": false
  },
  "binary_data": {
    "pointclouds_enabled": true,
    "pointclouds_downsampling": 1,
    "clusters_enabled": true,
    "trackedobjects_enabled": true,
    "images_enabled": true,
    "zone_events_enabled": true
  },
  "upload_to_cloud": true,
  "max_rolling_buffer_secs": 120.0,
  "reset_on_timeout": false,
  "post_processor_enabled": false,
  "retention_count": 0,
  "min_available_disk": 0.10,
  "purge_strategy": "oldest",
  "use_compression": true
}

Primary data_recorder Fields

Primary data_recorder Fields

Field	Format	Description
json_data	object	JSON data to be included in each Event Recording
json_data.object_list_enabled	bool	Indicator if JSON object lists should be captured in recordings (default = false)
json_data.occupations_enabled	bool	Indicator if JSON occupations should be captured in recordings (default = false)
json_data.aggregation_timeseries_enabled	bool	Indicator if JSON aggregation timeseries output should be captured in recordings (default = false)
json_data.aggregation_realtime_enabled	bool	Indicator if JSON aggregation real-time output should be captured in recordings (default = false)
json_data.diagnostics_enabled	bool	Indicator if JSON diagnostics telemetry and alerts output should be captured in recordings (default = false)
binary_data	object	Flatbuf data to be included in each Event Recording
binary_data.pointclouds_enabled	bool	Indicator if flatBuf background point clouds should be recaptured in recordings (default = true)
binary_data.pointclouds_downsampling	bool	Downsampling factor of background point clouds (default = 1 (none))
binary_data.clusters_enabled	bool	Indicator if flatBuf clusters should be captured in recordings (default = true)
binary_data.trackedobjects_enabled	bool	Indicator if flatBuf tracked objects should be captured in recordings (default = true)
binary_data.images_enabled	bool	Indicator if NearIR/CalRef images should be captured in recordings (default = true)
binary_data.zone_events_enabled	bool	Indicator if JSON zone events should be captured in recordings (default = true)
max_rolling_buffer_secs	float	Maximum length of perception output rolling buffer in seconds (default = 120.0)
retention_count	int	Number of recordings to retain (0 = unlimited)
min_available_disk	float	Minimal percentage of available storage before implementing the purge_strategy (default = 0.10 (10%))
purge_strategy	string	Recording purge strategy to invoke when minimum available storage is reached oldest/newest/disable (default = oldest)
use_compression	bool	Indicator if completed recordings should be compressed w/GZip (default = true)

Optional data_recorder Fields

Optional data_recorder Fields

Field	Format	Description
max_recording_length_secs	float	Maximum length of any event recording in seconds. This value supersedes Zone Event Recorder configuration(s) (default = 900)
reset_on_timeout	bool	Indicator if all events will automatically re-trigger after a timeout. This value can be overridden by Zone Event Recorder configuration(s) (default = false)
post_processor_enabled	bool	Indicator if a custom post-processor will be invoked after an event clears (default = false). There is currently one custom post-processor and it applies to all event types. If enabled, this custom post-processor will generate an additional event recording file consisting of Object List Data filtered for the object that triggered the event (offender) for the duration of the event. This additional event recording file can be found in the “event_recorder”.”log_path”.
upload_to_cloud	bool	Indicator if completed Event Recordings will be uploaded to the Gemini Portal (default = true)
purge_on_upload	bool	Indicator if Event Recordings successfully uploaded to the Gemini Portal will be removed from disk (default = true)
vacuum_age_secs	float	Minimum recording age in seconds to be considered for vacuuming (default = 3600). A value of 0 disables the Event Recorder vacuum.
vacuum_retry_secs	float	Delay in seconds before retrying a failed vacuum (default = 900)
vacuum_build_recording	bool	Indicator if the vacuum will attempt to (re)generate recording metadata if missing or corrupt (default = false)
log_path	string	Recordings path (default = /opt/ouster/conf/data/events/)

User Recordings

Users and applications can manually trigger Event Recordings via the LidarHub REST API:

https://<<host>>/api/v1/user_recording/start

The body of the API POST is used to configure the Event Recording

Example

{
  "allow_concurrent": false,
  "event_buffer_seconds": 5,
  "id": "",
  "zone_id": 0,
  "zone_name": "",
  "offender_id": "",
  "start_timestamp": 0,
  "max_recording_length_secs": 10,
  "meta_data": {},
  "name": "",
  "player_enrichment": {},
  "severity": "INDETERMINATE"
}

User Recording Configuration Fields

User Recording Configuration Fields

Field	Format	Description
ID	string	Optional user defined ID of the recording. If not assigned, the id will be set to a UUID.
name	string	Optional user defined Name of the recording. If a valid zone_id or zone_name is provided, this will be overridden with the Event Zone Name and the recording description will be set to the request name. The name will be set to User Recording at [datetime.utcnow()] if not assigned.
severity	string	Severity of the event (INDETERMINATE, WARNING, MINOR, MAJOR, CRITICAL)
zone_id	int	Optional ID of the Gemini Detect Event Zone associated with the recording. Either zone_id or zone_name should be defined, but not both. If both zone_id and zone_name are defined, zone_id will take precedence.
zone_name	string	Optional Name of the Gemini Detect Event Zone associated with the recording. Either zone_id or zone_name should be defined, but not both. If both zone_id and zone_name are defined, zone_id will take precedence.
offender_id	int	Optional id or uuid of the object associated with the recording.
start_timestamp	int	Optional start timestamp of the event within LidarHub “event_recorder”.”max_rolling_buffer_secs” (Units in microseconds since Jan. 1, 1970).
event_buffer_seconds	float	Optional time in seconds to include in the recording prior to trigger and up to LidarHub “event_recorder”.”max_rolling_buffer_secs”
max_recording_length_secs	float	Maximum length of the recording in seconds (less than or equal). This time is exclusive of “event_buffer_seconds”.
allow_concurrent	boolean	Allows/prevents concurrent User Event Recordings.
meta_data	string	Optional user defined meta data associated with the recording (typically JSON).
player_enrichment	string	Optional reserved for future use.

Accessing Event Recordings

Event recordings can be accessed/downloaded at the following URL:

https://<<host>>/data/events/

JSON Data Recorder

The Lidar Hub has an on-device JSON Data Recorder module with timed-rotation, retention period, compression and purge strategies. Object Lists, Occupations, Aggregation and Diagnostics will be recorded into a combined file. By default, recordings are saved to /opt/ouster/conf/data/recordings/.

Configuration

The json_data_recorder section of the Lidar Hub settings is used for configuring the JSON Data Recorder module. By default, Data Recording is disabled for all features. Data Recording can also be disabled by setting “rotation_minutes” = 0.

Example

"json_data_recorder": {
    "object_list_enabled": false,
    "occupations_enabled": false,
    "aggregation_timeseries_enabled": false,
    "aggregation_realtime_enabled": false,
    "diagnostics_enabled": false,
    "rotation_minutes": 5,
    "retention_count": 288,
    "min_available_disk": 0.10,
    "purge_strategy": "oldest",
    "use_compression": true
}

Primary data_recorder Fields

Primary data_recorder Fields

Field	Format	Description
object_list_enabled	bool	Flag indicating if JSON object lists should be recorded (default = False)
occupations_enabled	bool	Flag indicating if JSON occupations should be recorded (default = False)
aggregation_realtime_enabled	bool	Flag indicating if JSON aggregation realtime output should be recorded (default = False)
aggregation_timeseries_enabled	bool	Flag indicating if JSON aggregation timeseries output should be recorded (default = False)
diagnostics_enabled	bool	Flag indicating if JSON diagnostics telemetry and alerts output should be recorded (default = False)
rotation_minutes	float	Data recording file rotation interval in fractional minutes…set to 0 to disable data recording (default = 5.0)
retention_count	int	Number of recordings to retain (default = 288 (1 day))
min_available_disk	float	Minimal percentage of available storage before implementing the purge_strategy (default = 0.35 (35%))
purge_strategy	string	Recording purge strategy to invoke when minimum available storage is reached oldest/newest/disable (default = oldest)
use_compression	bool	Flag indicating if recordings should be compressed w/GZip after rotation (default = true)

Optional data_recorder Fields

Optional data_recorder Fields

Field	Format	Description
log_path	string	Recordings path (default = /opt/ouster/conf/data/recordings/)

Accessing JSON Data Recordings

JSON data recordings can be accessed/downloaded at the following URL:

https://<<host>>/data/recordings/

Binary Data Recorder

The Lidar Hub has an on-device Binary Data Recorder module with timed-rotation, retention period, compression and purge strategies. Point Clouds, Clusters, Tracked Objects and Images are recorded as flatbuf messages, while Event Zone Server Zone Events are stored as JSON messages. All messages are merged into a combined file in binary format, where each message is prepended with a 4-byte unsigned length (big-endian). By default, recordings are saved to /opt/ouster/conf/data/recordings/.

Configuration

The binary_data_recorder section of the Lidar Hub settings is used for configuring the Binary Data Recorder module. By default, Data Recording is disabled for all features. Data Recording can also be disabled by setting rotation_minutes = 0.

Example

"data_recorder": {
    "pointclouds_enabled": false,
    "clusters_enabled": false,
    "trackedobjects_enabled": false,
    "images_enabled": false,
    "zone_events_enabled": false,
    "rotation_minutes": 5,
    "retention_count": 288,
    "min_available_disk": 0.35,
    "purge_strategy": "oldest",
    "use_compression": true
}

Primary data_recorder Fields

Primary data_recorder Fields

Field	Format	Description
pointclouds_enabled	bool	Flag indicating if FlatBuf point clouds should be recorded (default = False)
clusters_enabled	bool	Flag indicating if FlatBuf clusters should be recorded (default = False)
trackedobjects_enabled	bool	Flag indicating if FlatBuf tracked objects should be recorded (default = False)
images_enabled	bool	Flag indicating if NearIR/CalRef images should be captured in recordings (default = False)
zone_events_enabled	bool	Flag indicating if JSON zone events should be recorded (default = False)
rotation_minutes	float	Data recording file rotation interval in fractional minutes…set to 0 to disable data recording (default = 5.0)
retention_count	int	Number of recordings to retain (default = 288 (1 day))
min_available_disk	float	Minimal percentage of available storage before implementing the purge_strategy (default = 0.35 (35%))
purge_strategy	string	Recording purge strategy to invoke when minimum available storage is reached oldest/newest/disable (default = oldest)
use_compression	bool	Flag indicating if recordings should be compressed w/GZip after rotation (default = true)

Optional data_recorder Fields

Optional data_recorder Fields

Field	Format	Description
log_path	string	Recordings path (default = /opt/ouster/conf/data/recordings/)

Accessing Binary Data Recordings

Binary data recordings can be accessed/downloaded at the following URL:

https://<<host>>/data/recordings/

Utilities

The Lidar Hub includes utilities to assist with verifying that the MQTT Publishers and TCP Relay Servers configured are producing output as expected.

MQTT Echo

A browser-based utility to test configured MQTT Publisher(s) can be found at https://<<host>>/lidar-hub/mqtt_echo

1. Select the desired pre-configured Publisher from the drop down.

2. Edit the auto-filled fields if desired.

3. Click Connect to subscribe to the MQTT Topic…data published to topic will be received and appended to the data pane (max 25 entries).

TCP Echo

A browser-based utility to test configured TCP Relay Servers can be found at https://<<host>>/lidar-hub/tcp_echo

1. Select the desired pre-configured Server from the drop down.

2. Edit the auto-filled fields if desired.

3. Click Connect to connect to the TCP Server…data received from the server will be appended to the data pane (max 25 entries).

RESTful API Specification

Diagnostics

GET /lidar-hub/api/v1/about

Get static information ‘about’ the Lidar Hub

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/diagnostics

Get System Diagnostics

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/system_health

Get System Health

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/telemetry

Get Lidar Hub ‘telemetry’ information

Status Codes:

• 200 OK – OK

Settings

GET /lidar-hub/api/v1/default_settings

Get application default values

Status Codes:

• 200 OK – OK

PUT /lidar-hub/api/v1/default_settings

Restore application settings to default values

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/settings

Get all application settings

Status Codes:

• 200 OK – OK

POST /lidar-hub/api/v1/settings

Set all application settings.

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/world

Get the World Geo-Coordinates

Status Codes:

• 200 OK – OK

PUT /lidar-hub/api/v1/world

Set the World Geo-Coordinates

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

Cloud Storage

GET /lidar-hub/api/v1/cloud_storage

Get Cloud Storage Profiles

Status Codes:

• 200 OK – OK

POST /lidar-hub/api/v1/cloud_storage

Add/Update a Cloud Storage Profile

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

PUT /lidar-hub/api/v1/cloud_storage

Set The Active Cloud Storage Profile

Query Parameters:

• profile (string) – Cloud Storage Profile.

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

Connectivity

POST /lidar-hub/api/v1/certificate

Save a Certificate

Query Parameters:

• name (string) – Certificate Name

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

Sensor Management

GET /lidar-hub/api/v1/background_cloud

Retrieves the background point cloud for all sensors

Query Parameters:

• downsample_factor (number) – How much to downsample the background cloud (1 = no downsampling)

Status Codes:

• 200 OK – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/background_cloud/{sensor_id}

Retrieves the background point cloud for a single sensor

Parameters:

• sensor_id (string) – Lidar Sensor ID (serial number)

Query Parameters:

• downsample_factor (number) – How much to downsample the background cloud (1 = no downsampling)

Status Codes:

• 200 OK – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/firmware/compatibility_matrix

Get firmware compatibility matrix

Status Codes:

• 200 OK – OK

POST /lidar-hub/api/v1/firmware/compatibility_matrix

Set firmware compatibility matrix

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/firmware/default_compatibility_matrix

Get default firmware compatibility matrix

Status Codes:

• 200 OK – OK

PUT /lidar-hub/api/v1/firmware/default_compatibility_matrix

Restore default firmware compatibility matrix

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

DELETE /lidar-hub/api/v1/firmware/image

Delete a firmware image in available repository

Query Parameters:

• file_name (string) – File Name of the Firmware Image

Status Codes:

• 201 Created – OK

GET /lidar-hub/api/v1/firmware/image

Get firmware image(s) in available repository

Query Parameters:

• sensor_id (string) – Optionally filter firmware images compatible with the selected sensor

Status Codes:

• 200 OK – OK

PUT /lidar-hub/api/v1/firmware/image

Save firmware image to available repository

Query Parameters:

• version (string) – Firmware Version (e.g. 1.0.0)

• force (boolean) – Override Firmware Image if Already Exists

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

GET /lidar-hub/api/v1/firmware/upgrade/{sensor_id}

Get the firmware upgrade status for a single sensor

Parameters:

• sensor_id (string) – Lidar Sensor ID (serial number)

Status Codes:

• 200 OK – OK

• 400 Bad Request – Bad Request

PUT /lidar-hub/api/v1/firmware/upgrade/{sensor_id}

Initiate the firmware upgrade for a single sensor

Parameters:

• sensor_id (string) – Lidar Sensor ID (serial number)

Query Parameters:

• file_name (string) – File Name of the Firmware Image

• force (boolean) – Force the Upgrade Using The Specified Firmware Image

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

Event Zones

GET /lidar-hub/api/v1/event_zones

Get Event Zones

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/event_zones/active

Query Active Occupancy by ID, Classification and Dwell

Query Parameters:

• ids (string) – Comma-delimited string of event zone IDs (default = 0: ALL)

• classifications (string) – Comma-delimited string of Classifications (default = ALL)

• min_dwell_secs (number) – Minimum dwell in seconds (default = 0.0)

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/event_zones/alerts

Get Active Alerts for All Event Zones

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/event_zones/realtime

Get Real-Time Occupancy of All Event Zones

Status Codes:

• 200 OK – OK

GET /lidar-hub/api/v1/event_zones/timeseries

Get Current Timeseries for All Event Zones (Note: timeseries is likely in progress)

Status Codes:

• 200 OK – OK

Execution

PUT /lidar-hub/api/v1/ota/force_firmware_check

Force immediate check for pending firmware OTA request(s)

Status Codes:

• 201 Created – OK

PUT /lidar-hub/api/v1/ota/force_software_check

Force immediate check for a pending software OTA request

Status Codes:

• 201 Created – OK

PUT /lidar-hub/api/v1/reset

Restart the Lidar Hub

Status Codes:

• 201 Created – OK

GET /lidar-hub/api/v1/user_recording/active

Get Active User Recording(s)

Status Codes:

• 200 OK – OK

POST /lidar-hub/api/v1/user_recording/start

Starts a User Recording.

Status Codes:

• 201 Created – OK

• 400 Bad Request – Bad Request

• 405 Method Not Allowed – Method not allowed

GET /lidar-hub/api/v1/user_recording/stop

Stops an active User Recording.

Query Parameters:

• id (string) – User Recording ID

• stop_trail_seconds (number) – Additional time in seconds to include in the recording following the stop request.

Status Codes:

• 200 OK – OK

• 400 Bad Request – Bad Request

• 404 Not Found – Not Found