Table 1–continuedfrompreviouspage Command Description ResponseExample get time info Returns JSON-formatted sensor timing configuration andstatusofudptimestamp, sync pulse in, and multipur- pose io.
Velodyne Lidar Viewer - Unity Forum That sounds great! here are some links to their specs:
Ouster Sensor API Guide
Firmware v2.0.0 for all Ouster sensors v2.0.0
Ouster Sensor TCP and HTTP API Guide
Nov 30, 2020
TCP and HTTP APIs
1 TCP API
3
1.1 Querying Sensor Info and Intrinsic Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Querying Active or Staged Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.3 Setting Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2 HTTP API Reference
18
2.1 system/firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.2 diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.3 system/network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.4 time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
3 API Changelog
30
This on-sensor reference document is a quick guide to the TCP and HTTP APIs. For the most up-todate and comprehensive information about your sensor, please see the sensor user manuals found at www.ouster.com
2
1 TCP API
1.1 Querying Sensor Info and Intrinsic Calibration
The sensor can be queried and configured using a simple plaintext protocol over TCP on port 7501. An example session using the unix netcat utility is shown below. Note: "xxx" refers to the sensor serial number. The hostname of the sensor can look like "os-xxx" or "os1-xxx".
$ nc os-991900123456 7501 get_sensor_info
{"prod_line": "OS-1-128", "prod_pn": "840-102145-C", "prod_sn": "991900123456", "base_pn": "830-101845-E", "base_sn": "102005001362", "image_rev": "ousteros-image-prod-aries-v2.0.0-2020129230129", "build_rev": "v2.0.0", "proto_rev": "v1.1.1", "build_date": "2020-10-20T18:58:51Z", "status": "RUNNING"}
A sensor may have one of the following statuses:
Status
INITIALIZING WARMUP UPDATING
RUNNING STANDBY
ERROR UNCONFIGURED
Description When the sensor is booting and not yet outputting data.
Sensor has gone into thermal warmup state.
When the sensor is updating the FPGA firmware on the first reboot after a firmware upgrade. When the sensor has reached the final running state where it can output data.
The sensor has been configured into a low-power state where sensor is on but not spinning Check error codes in the errors field for more information
An error with factory calibration that requires a manual power cycle or reboot.
If sensor is in an ERROR or UNCONFIGURED state, please contact Ouster support with the diagnostic file found at http://os-9919xxxxxxxx/diag for support.
The following commands will return sensor configuration and calibration information:
3
Command
get_config_param <active/staged>
get_sensor_info
Table1: Sensor Configuration and Calibration
Description
Response Example
Returns all active or staged
JSON-formatted
sensor
configuration. Note: The
get_config_param
active
command is functionally the
same as the old command
get_config_txt, which will be deprecated in future
firmware.
{ "udp_ip": "192.0.2.123", "udp_dest": "192.0.2.123", "udp_port_lidar": 7502, "udp_port_imu": 7503, "timestamp_mode": "TIME_FROM_INTERNAL_OSC", "sync_pulse_in_polarity": "ACTIVE_HIGH", "nmea_in_polarity": "ACTIVE_HIGH", "nmea_ignore_valid_char": 0, "nmea_baud_rate": "BAUD_9600", "nmea_leap_seconds": 0, "multipurpose_io_mode": "OFF", "sync_pulse_out_polarity": "ACTIVE_HIGH", "sync_pulse_out_frequency": 1, "sync_pulse_out_angle": 360, "sync_pulse_out_pulse_width": 10, "auto_start_flag": 1, "operating_mode": "NORMAL", "lidar_mode": "1024x10", "azimuth_window": [0, 360000], "phase_lock_enable": false, "phase_lock_offset": 0
}
Returns JSON-formatted sensor metadata: serial number, hardware and software revision, and sensor status.
{ "prod_line": "OS-1-128", "prod_pn": "840-102145-C", "prod_sn": "991900123456", "base_pn": "830-101845-E", "base_sn": "102005001362", "image_rev": "ousteros-image-prod-aries-v2.0.
0-2020129230129", "build_rev": "v2.0.0", "proto_rev": "v1.1.1", "build_date": "2020-10-20T18:58:51Z", "status": "RUNNING"}
continues on next page
4
Command
get_time_info
Table 1 continued from previous page
Description
Response Example
Returns JSON-formatted sensor timing configuration and status of udp timestamp, sync_pulse_in, and multipurpose_io.
{ "timestamp": { "time": 302.96139565999999, "mode": "TIME_FROM_INTERNAL_OSC", "time_options": { "sync_pulse_in": 0, "internal_osc": 302, "ptp_1588": 309 } }, "sync_pulse_in": { "locked": 0, "diagnostics": { "last_period_nsec": 0, "count_unfiltered": 1, "count": 0 }, "polarity": "ACTIVE_HIGH" }, "multipurpose_io": { "mode": "OFF", "sync_pulse_out": { "pulse_width_ms": 10, "angle_deg": 360, "frequency_hz": 1, "polarity": "ACTIVE_HIGH" }, "nmea": { "locked": 0, "baud_rate": "BAUD_9600", "diagnostics": { "io_checks": { "bit_count": 1, "bit_count_unfiltered": 0, "start_char_count": 0, "char_count": 0 }, "decoding": { "last_read_message": "", "date_decoded_count": 0, "not_valid_count": 0, "utc_decoded_count": 0 } }, "leap_seconds": 0, "ignore_valid_char": 0, "polarity": "ACTIVE_HIGH" } }
}
continues on next page 5
Command
get_beam_intrinsics
Table 1 continued from previous page
Description
Response Example
Returns JSON-formatted beam altitude and azimuth offsets, in degrees. Length of arrays is equal to the number of channels in sensor. Also returns distance between lidar origin and beam origin in mm, to be used for point cloud calculations.
{ "lidar_origin_to_beam_origin_mm": 15.806, "beam_altitude_angles": [ 21.4764, 21.1679, 20.8583, "...", -20.8583, -21.1679, -21.4764 ], "beam_azimuth_angles": [ 4.2521, 1.4197 "...", -1.4197, -4.2521 ]
}
get_imu_intrinsics
Returns JSON-formatted IMU transformation matrix needed to transform to the Sensor Coordinate Frame.
{ "imu_to_sensor_transform": [ 1, 0, 0, 6.253, 0, 1, 0, -11.775, 0, 0, 1, 7.645, 0, 0, 0, 1 ]
}
continues on next page
6
Table 1 continued from previous page
Command
Description
Response Example
get_lidar_intrinsics
Returns JSON-formatted lidar transformation matrix needed to transform to the Sensor Coordinate Frame.
{ "lidar_to_sensor_transform": [ -1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1, 36.18, 0, 0, 0, 1 ]
}
continues on next page
7
Command
get_alerts <START_CURSOR>
Table 1 continued from previous page
Description
Response Example
Returns JSON-formatted sensor diagnostic information. The log list contains alerts when they were activated or deactivated. An optional START_CURSOR argument specifies where the log should start. The active list contains all currently active alerts.
{ "next_cursor": 2, "active": [ { "category": "UDP_TRANSMISSION", "msg": "Received an unknown error
when trying to send lidar data UDP packet; closing socket.",
"realtime": "1569631015375767040", "cursor": 0, "id": "0x01000017", "active": true, "msg_verbose": "192.0.2.123:7502", "level": "WARNING" }, ], "log": [ { "category": "UDP_TRANSMISSION", "msg": "Received an unknown error when trying to send lidar data UDP packet; closing socket.", "realtime": "1569631015375767040", "cursor": 0, "id": "0x01000017", "active": true, "msg_verbose": "192.0.2.123:7502", "level": "WARNING" }, { "category": "UDP_TRANSMISSION", "msg": "Received an unknown error when trying to send IMU UDP packet; closing socket.", "realtime": "1569631015883802368", "cursor": 1, "id": "0x0100001a", "active": false, "msg_verbose": "192.0.2.123:7503", "level": "WARNING" } ] }
continues on next page
8
Table 1 continued from previous page
Command
Description
Response Example
get_lidar_data_format Returns JSON-formatted re-
sponse that describes the
structure of a lidar packet.
columns_per_frame: Number of
measurement columns per
frame. This can be 512, 1024,
or 2048, depending upon the
set lidar mode.
columns_per_packet: Number
of measurement blocks con-
tained in a single lidar packet.
Currently in v2.0.0 and ear-
lier, this is 16.
pixel_shift_by_row: Offset in
terms of pixel count. Can
be used to destagger image.
Varies by lidar mode. Length
of this array is equal to the
number of channels of the
sensor.
pixels_per_column: Number of
channels of the sensor.
column_window:
Index of
measurement blocks that
are active. Default is [0,
lidar_mode-1], e.g. [0,1023].
If there is azimuth window
set, this parameter will re-
flect which measurement
blocks of data are within the
region of interest.
{ "columns_per_frame": 1024, "columns_per_packet": 16, "pixel_shift_by_row": [ 18, 12, 6, 0, "...", 18, 12, 6, 0 ], "pixels_per_column": 128, "column_window": [0, 1023]
}
1.2 Querying Active or Staged Parameters
Sensor configurations and operating modes can also be queried over TCP. Below is the command format: get_config_param active <parameter> will return the current active configuration parameter values. get_config_param staged <parameter> will return the parameter values that will take place after issuing a reinitialize command or after sensor reset.
9
Warning: The command get_config_txt is deprecated in favor of get_config_param active, which provides the same response. get_config_txt will be removed in a future firmware.
An example session using the unix netcat utility is shown below:
$ nc os-991900123456 7501 get_config_param active lidar_mode 1024x10
The following commands will return sensor active or staged configuration parameters:
Table2: Sensor Configurations
get_config_param Command Description
Response
udp_dest
Returns the destination to which the sensor sends UDP traffic. Note: udp_ip is the deprecated parameter name whose value will always be the same as udp_dest.
"" (default)
udp_port_lidar
Returns the port number of lidar 7502 (default) UDP data packets.
udp_port_imu
Returns the port number of IMU 7503 (default) UDP data packets.
lidar_mode
Returns a string indicating the horizontal resolution and rotation frequency [Hz].
One of 512x10, 1024x10, 2048x10, 512x20, or 1024x20
timestamp_mode
Returns the method used to timestamp measurements.
One of TIME_FROM_INTERNAL_OSC,
TIME_FROM_PTP_1588,
or
TIME_FROM_SYNC_PULSE_IN
nmea_in_polarity
Returns the polarity of NMEA UART input messages. See Time Synchronization section in sensor user manual for NMEA use case. Use ACTIVE_HIGH if UART is active high, idle low, and start bit is after a falling edge.
Either ACTIVE_HIGH (default) or AC-
TIVE_LOW
nmea_ignore_valid_char
Returns 0 if NMEA UART input $GPRMC messages should be ignored if valid character is not set, and 1 if messages should be used for time syncing regardless of the valid character.
Either 0 (default) or 1
continues on next page
10
get_config_param
nmea_baud_rate nmea_leap_seconds
operating_mode
azimuth_window phase_lock_enable phase_lock_offset
Table 2 continued from previous page
Command Description
Response
Returns BAUD_9600 (default) or BAUD_115200 for the expected baud rate the sensor is attempting to decode for NMEA UART input $GPRMC messages.
Either BAUD_9600 or BAUD_115200
Returns the number of leap seconds that will be added to the UDP timestamp when calculating seconds since 00:00:00 Thursday, 1 January 1970. For Unix Epoch time, this should be set to 0.
Either 0 (default) or 1
Returns the operating mode that the sensor is in. "NORMAL" is default value. "STANDBY" is a low power (5W) operating mode. Note: auto_start_flag is the deprecated parameter name where auto_start_flag 0 is equivalent to operating_mode "STANDBY" and auto_start_flag 1 is equivalent to operating_mode "NORMAL".
Either "NORMAL" (default) or "STANDBY" (low power/standby state)
Returns the visible region of interest of the sensor in millidegrees. Only data within the specified bounds of the region of interest is sent from the sensor.
[0,360000] (defaults to an azimuth window of 360°)
Returns whether phase locking is Either false (default) or true enabled.
Returns the the angle in the Lidar Coordinate Frame that sensors are locked to in millidegrees if phase locking is enabled.
Integer between 0 and 360000 inclusive
11
Table3: Sensor Modes
Command
Command Description
Response
multipurpose_io_mode
Returns the configured mode of the MULTIPURPOSE_IO pin. See Time Synchronization section in sensor user manual for a detailed description of each option.
One of OFF (default),
INPUT_NMEA_UART,
OUT-
PUT_FROM_INTERNAL_OSC,
OUT-
PUT_FROM_SYNC_PULSE_IN, OUT-
PUT_FROM_PTP_1588, or OUT-
PUT_FROM_ENCODER_ANGLE
sync_pulse_out_polarity
Returns the polarity of SYNC_PULSE_OUT output, if sensor is using this for time synchronization.
One of ACTIVE_HIGH or ACTIVE_LOW (default)
sync_pulse_out_frequency
Returns
the
output 1 (default)
SYNC_PULSE_OUT pulse rate
in Hz.
sync_pulse_out_angle
Returns the angle in terms of degrees that the sensor traverses between each SYNC_PULSE_OUT pulse. E.g. a value of 180 means a sync pulse is sent out every 180° for a total of two pulses per revolution and angular frequency of 20 Hz if the sensor is 1024x10 Hz lidar mode.
360 (default)
sync_pulse_out_pulse_width Returns
the
output
SYNC_PULSE_OUT pulse width
in ms.
10 (ms, default)
12
1.3 Setting Configuration Parameters
set_config_param <parameter> <value> will set new values for configuration parameters, which will take effect after issuing the reinitialize command or after sensor reset. reinitialize will reinitialize the sensor so the staged values of the parameters will take effect immediately. save_config_params will write new values of active parameters into a configuration file, so they will persist after sensor reset. In order to permanently change a parameter in the configuration file, first use set_config_param to update the parameter in a staging area, then use reinitialize to make that parameter active. Only after the parameter is made active will save_config_params capture it to persist after reset.
Warning: The command write_config_txt will be deprecated in a future firmware. The command save_config_params provides the same response.
set_udp_dest_auto will automatically determine the sender's IP address at the time the command was sent, and set it as the destination of UDP traffic. This takes effect after issuing a reinitialize command. Using this command has the same effect as using set_config_param udp_dest <ip address>. An example session using the unix netcat utility is shown below:
$ nc os-991900123456 7501 set_config_param lidar_mode 512x20 set_config_param set_udp_dest_auto set_udp_dest_auto reinitialize reinitialize save_config_params save_config_params
The following commands will set sensor configuration parameters:
13
set_config_param
udp_dest <destination>
udp_port_lidar <port> udp_port_imu <port> lidar_mode <mode>
timestamp_mode <mode> sync_pulse_in_polarity <1/ 0>
Table4: Setting Config Params
Command Description
Set the <destination> to which the sensor sends UDP traffic. On boot, the sensor will not output data until this is set. If the IP address is not known, this can also be accomplished with the set_udp_dest_auto command (details above). The sensor supports unicast, IPv4 broadcast (255.255.255.255), IPv4 multicast (239.x.x.x), and IPv6 multicast (ff02::01) addresses. Note: udp_ip is the deprecated parameter name. However during the deprecation phase, either udp_ip or udp_dest may be used. When either one is updated, the other parameter value will be updated to match upon setting the parameter value.
Set the <port> on udp_dest to which lidar data will be sent (7502, default).
Set the <port> on udp_dest to which IMU data will be sent (7503, default).
Set the horizontal resolution and rotation rate of the sensor. Valid modes are 512x10, 1024x10, 2048x10, 512x20, and 1024x20. The effective range of the sensor is increased by 15-20% for every halving of the number of points gathered e.g. 512x10 has 15-20% longer range than 512x20.
Set the method used to times-
tamp measurements.
Valid
modes are TIME_FROM_INTERNAL_OSC,
TIME_FROM_SYNC_PULSE_IN,
or
TIME_FROM_PTP_1588.
Set the polarity of SYNC_PULSE_IN
input,
which controls polar-
ity of SYNC_PULSE_IN pin
when timestamp_mode is set in
TIME_FROM_SYNC_PULSE_IN.
Response set_config_param on success, error: otherwise
set_config_param on success, error: otherwise set_config_param on success, error: otherwise set_config_param on success, error: otherwise
set_config_param on success, error: otherwise
set_config_param on success, error: otherwise
continues on next page
14
Table 4 continued from previous page
set_config_param
Command Description
Response
nmea_in_polarity <1/0>
Set the polarity of NMEA UART input $GPRMC messages. See Time Synchronization section in sensor user manual for NMEA use case. Use ACTIVE_HIGH if UART is active high, idle low, and start bit is after a falling edge.
set_config_param on success, error: otherwise
nmea_ignore_valid_char <1/ 0>
Set 0 if NMEA UART input $GPRMC messages should be ignored if valid character is not set, and 1 if messages should be used for time syncing regardless of the valid character.
set_config_param on success, error: otherwise
nmea_baud_rate <rate in Set BAUD_9600 (default) or BAUD_115200 for set_config_param on suc-
baud/s>
the expected baud rate the sensor is at- cess, error: otherwise
tempting to decode for NMEA UART in-
put $GPRMC messages.
nmea_leap_seconds <s>
Set an integer number of leap seconds that will be added to the UDP timestamp when calculating seconds since 00:00:00 Thursday, 1 January 1970. For Unix Epoch time, this should be set to 0.
set_config_param on success, error: otherwise
multipurpose_io_mode <mode>
Configure the mode of the MULTIPUR-
POSE_IO pin. Valid modes are OFF, IN-
PUT_NMEA_UART, OUTPUT_FROM_INTERNAL_OSC,
OUTPUT_FROM_SYNC_PULSE_IN,
OUT-
PUT_FROM_PTP_1588,
or
OUT-
PUT_FROM_ENCODER_ANGLE.
set_config_param on success, error: otherwise
operating_mode "STANDBY">
<"NORMAL"/
Set "NORMAL" to put the sensor into a normal operating mode or "STANDBY" to put the sensor into a low power (5W) operating mode where motor does not spin and lasers do not fire. Note: auto_start_flag <1/0> is the deprecated parameter name where auto_start_flag 0 is equivalent to operating_mode "STANDBY" and auto_start_flag 1 is equivalent to operating_mode "NORMAL". However, during the deprecation phase, either operating_mode or auto_start_flag may be used. When either one is updated, the other parameter value will be updated to match upon setting the parameter value.
set_config_param on success, error: otherwise
continues on next page
15
Table 4 continued from previous page
set_config_param
Command Description
azimuth_window <[min_bound_millideg, max_bound_millideg]>
Sets the visible region of interest of the sensor in millidegrees. Only data from the within the specified azimuth window bounds is sent.
phase_lock_enable false>
<true/ Sets whether phase locking is enabled. See Software User Manual for more details on using phase lock.
phase_lock_offset <angle in millideg>
Sets the angle in the Lidar Coordinate Frame that sensors are locked to in millidegrees if phase locking is enabled. Angle is traversed at the top of the second.
Response [0,360000] (defaults to an azimuth window of 360°)
set_config_param on success, error: otherwise
set_config_param on success, error: otherwise
Table5: Setting Sync
set_config_param
Command Description
Response
sync_pulse_out_polarity <1/0>
Set the polarity of SYNC_PULSE_OUT output, if sensor is set as the master sensor used for time synchronization.
set_config_param on success, error: otherwise
sync_pulse_out_frequency in Hz>
<rate
Set output SYNC_PULSE_OUT rate. Valid inputs are integers >0 Hz, but also limited by the criteria described in the Time Synchronization section of the Software User Manual.
set_config_param on success, error: otherwise
sync_pulse_out_angle <angle in deg>
Set output SYNC_PULSE_OUT rate defined by rotation angle. E.g. a value of 180 means a sync pulse is sent out every 180° for a total of two pulses per revolution and angular frequency of 20 Hz if the sensor is 1024x10 Hz lidar mode. Valid inputs are integers between 0 and 360 inclusive but also limited by the criteria described in the Time Synchronization section of Software User Manual.
set_config_param on success, error: otherwise
continues on next page
16
Table 5 continued from previous page
set_config_param
Command Description
Response
sync_pulse_out_pulse_width <width in ms>
Set output SYNC_PULSE_OUT pulse width in ms, in 1 ms increments. Valid inputs are integers greater than 0 ms, but also limited by the criteria described in the Time Synchronization section of Software User Manual.
set_config_param on success, error: otherwise
Table6: Reinitialize, Write Configuration, and Auto Destination UDP
Command
Command Description
Response
reinitialize or reinit
Restarts the sensor. Changes to lidar, multipurpose_io, and timestamp modes will only take effect after reinitialization.
reinitialize or reinit on success
save_config_params
Makes all current parameter set- save_config_params on success tings persist after reboot.
set_udp_dest_auto
Set the destination of UDP traffic to the destination address that issued the command.
set_udp_dest_auto on success
17
2 HTTP API Reference
HTTP API developer reference guide. This documents the interface for HTTP API and is accessible via /api/v1 on the sensor hosted HTTP server.
2.1 system/firmware
GET /api/v1/system/firmware
GET 192.0.2.123/api/v1/system/firmware
Get the firmware version of the sensor
GET /api/v1/system/firmware HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK Host: 192.0.2.123 content-type: application/json; charset=UTF-8
{ "fw": "ousteros-image-prod-aries-v2.0.0"
}
Response JSON Object
fw (string) Running firmware image name and version. Status Codes
200 OK No error
2.2 diagnostics
GET /api/v1/diagnostics/dump
GET 192.0.2.123/api/v1/diagnostics/dump
Get the diagnostics files of the sensor
GET /api/v1/diagnostics/dump HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-disposition: attachment; filename="192.0.2.123_diagnostics-dump_29811b9e-2afc-11eb-ae01bc0fa700190c.bin" content-type: application/octet-stream
(continues on next page)
18
{binary data}
Status Codes
200 OK No error
(continued from previous page)
2.3 system/network
GET /api/v1/system/network
GET 192.0.2.123/api/v1/system/network
Get the system network configuration.
GET /api/v1/system/network HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
{ "carrier": true, "duplex": "full", "ethaddr": "bc:0f:a7:00:01:2c", "hostname": "os-991900123456", "ipv4": { "addr": "192.0.2.123/24", "link_local": "169.254.245.183/16", "override": null }, "ipv6": { "link_local": "fe80::be0f:a7ff:fe00:12c/64" }, "speed": 1000
}
Response JSON Object
carrier (boolean) State of Ethernet link, true when physical layer is connected. duplex (string) Duplex mode of Ethernet link, half or full. ethaddr (string) Ethernet hardware (MAC) address. hostname (string) Hostname of the sensor, also used when requesting DHCP address and registering mDNS hostname. ipv4 (object) See ipv4 object ipv6.link_local (string) Link-local IPv6 address. speed (integer) Ethernet physical layer speed in Mbps, should be 1000 Mbps. Status Codes 200 OK No error
19
GET /api/v1/system/network/ipv4
GET 192.0.2.123/api/v1/system/network/ipv4
Get the IPv4 network configuration.
GET /api/v1/system/network/ipv4 HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
{ "addr": "192.0.2.123/23", "link_local": "169.254.245.183/16", "override": null
}
Response JSON Object
addr (string) Current global or private IPv4 address. link_local (string) Link-local IPv4 address. override (string) Static IP override value, this should match addr. This value will be null when unset and operating in DHCP or link-local modes. Status Codes 200 OK No error
GET /api/v1/system/network/ipv4/override
GET 192.0.2.123/api/v1/system/network/ipv4/override
Get the current IPv4 static IP address override.
GET /api/v1/system/network/ipv4/override HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
null
Response JSON Object
string Static IP override value, this should match addr. This value will be null when unset and operating in DHCP mode. Status Codes 200 OK No error
20
PUT /api/v1/system/network/ipv4/override
PUT 192.0.2.123/api/v1/system/network/ipv4/override
Override the default dynamic behavior and set a static IP address.
Note: The sensor will reset the network configuration after a short sub second delay (to allow for the HTTP response to be sent). After this delay the sensor will only be reachable on the newly set IPv4 address. The sensor needs to be reachable either by link-local or dynamic DHCP configuration or by an existing static IP override from the host reconfiguring the sensor.
Warning: If an unreachable network address is set, the sensor will become unreachable. Tools such as avahi-browse, dns-sd, or mDNS browser can help with finding a sensor on a network. Static IP override should only be used in special use cases. The link-local configuration is recommended where possible.
PUT /api/v1/system/network/ipv4/override HTTP/1.1 Content-Type: application/json Host: 192.0.2.123
"192.0.2.100/24"
Request JSON Object
string Static IP override value with subnet mask Response JSON Object
string Static IP override value that system will set after a short delay. Status Codes
200 OK No error
DELETE /api/v1/system/network/ipv4/override
DELETE 192.0.2.123/api/v1/system/network/ipv4/override
Delete the static IP override value and return to dynamic configuration.
Note: The sensor will reset the network configuration after a short sub second delay (to allow for the HTTP response to be sent). After this delay the sensor will only be reachable on the newly set IPv4 address. The sensor may be unreachable for several seconds while a link-local lease is obtained from the network or client machine.
DELETE /api/v1/system/network/ipv4/override HTTP/1.1 Host: 192.0.2.123
21
Status Codes
204 No Content No error, no content
2.4 time
GET /api/v1/time
GET 192.0.2.123/api/v1/time
Get the system time configuration for all timing components of the sensor.
GET /api/v1/time HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
{ "ptp": { "current_data_set": { "mean_path_delay": 37950, "offset_from_master": -211488, "steps_removed": 1 }, "parent_data_set": { "gm_clock_accuracy": 33, "gm_clock_class": 6, "gm_offset_scaled_log_variance": 20061, "grandmaster_identity": "001747.fffe.700038", "grandmaster_priority1": 128, "grandmaster_priority2": 128, "observed_parent_clock_phase_change_rate": 2147483647, "observed_parent_offset_scaled_log_variance": 65535, "parent_port_identity": "001747.fffe.700038-1", "parent_stats": 0 }, "port_data_set": { "announce_receipt_timeout": 3, "delay_mechanism": 1, "log_announce_interval": 1, "log_min_delay_req_interval": 0, "log_min_pdelay_req_interval": 0, "log_sync_interval": 0, "peer_mean_path_delay": 0, "port_identity": "bc0fa7.fffe.00012c-1", "port_state": "SLAVE", "version_number": 2 }, "time_properties_data_set": { "current_utc_offset": 37, "current_utc_offset_valid": 1,
(continues on next page)
22
"frequency_traceable": 1, "leap59": 0, "leap61": 0, "ptp_timescale": 1, "time_source": 32, "time_traceable": 1 }, "time_status_np": { "cumulative_scaled_rate_offset": 0, "gm_identity": "001747.fffe.700038", "gm_present": true, "gm_time_base_indicator": 0, "ingress_time": 1552413985821448000, "last_gm_phase_change": "0x0000'0000000000000000.0000", "master_offset": -211488, "scaled_last_gm_phase_change": 0 } }, "sensor": { "nmea": { "baud_rate": "BAUD_9600", "diagnostics": {
"decoding": { "date_decoded_count": 0, "last_read_message": "", "not_valid_count": 0, "utc_decoded_count": 0
}, "io_checks": {
"bit_count": 1, "bit_count_unfiltered": 0, "char_count": 0, "start_char_count": 0 } }, "ignore_valid_char": 0, "leap_seconds": 0, "locked": 0, "polarity": "ACTIVE_HIGH" }, "sync_pulse_in": { "diagnostics": { "count": 1, "count_unfiltered": 0, "last_period_nsec": 0 }, "locked": 0, "polarity": "ACTIVE_HIGH" }, "sync_pulse_out": { "angle_deg": 360, "frequency_hz": 1, "mode": "OFF", "polarity": "ACTIVE_HIGH",
23
(continued from previous page) (continues on next page)
"pulse_width_ms": 10 }, "timestamp": {
"mode": "TIME_FROM_INTERNAL_OSC", "time": 57178.44114677, "time_options": {
"internal_osc": 57178, "ptp_1588": 1552413986, "sync_pulse_in": 1 } } }, "system": { "monotonic": 57191.819600378, "realtime": 1552413949.3948405, "tracking": { "frequency": -7.036, "last_offset": 5.942e-06, "leap_status": "normal", "ref_time_utc": 1552413947.8259742, "reference_id": "70747000", "remote_host": "ptp", "residual_frequency": 0.006, "rms_offset": 5.358e-06, "root_delay": 1e-09, "root_dispersion": 0.000129677, "skew": 1.144, "stratum": 1, "system_time_offset": -2.291e-06, "update_interval": 2 } } }
Response JSON Object
string See sub objects for details. Status Codes
200 OK No error
(continued from previous page)
GET /api/v1/time/system
GET 192.0.2.123/api/v1/time/system
Get the operating system time status. These values relate to the sensor operating system clocks, and not clocks related to hardware timestamp data from the lidar sensor.
GET /api/v1/time/system HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
(continues on next page)
24
(continued from previous page)
{ "monotonic": 345083.599570944, "realtime": 1551814510.730453, "tracking": { "frequency": -6.185, "last_offset": -3.315e-06, "leap_status": "normal", "ref_time_utc": 1551814508.1982567, "reference_id": "70747000", "remote_host": "ptp", "residual_frequency": -0.019, "rms_offset": 4.133e-06, "root_delay": 1e-09, "root_dispersion": 0.000128737, "skew": 1.14, "stratum": 1, "system_time_offset": 4.976e-06, "update_interval": 2 }
}
Response JSON Object
monotonic (float) Monotonic time of operating system. This timestamp never counts backwards and is the time since boot in seconds. realtime (float) Time in seconds since the Unix epoch, should match wall time if synchronized with external time source. tracking (object) Operating system time synchronization tracking status. See chronyc tracking documentation for more information. Status Codes 200 OK No error System tracking fields of interest: Rms_offset Long-term average of the offset value. System_time_offset Time delta (in seconds) between estimate of the operating system time and the current true time. Last_offset Estimated local offset on the last clock update. Ref_time_utc UTC Time at which the last measurement from the reference source was processed. Remote_host This is either ptp if the system is synchronizing to a PTP time source or the address of a remote NTP server the system has selected if the sensor is connected to the Internet.
25
GET /api/v1/time/ptp
GET 192.0.2.123/api/v1/time/ptp
Get the status of the PTP time synchronization daemon.
Note: See the IEEE 1588-2008 standard for more details on the standard management messages.
GET /api/v1/time/ptp HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
{ "current_data_set": { "mean_path_delay": 30110, "offset_from_master": 224159, "steps_removed": 1 }, "parent_data_set": { "gm_clock_accuracy": 33, "gm_clock_class": 6, "gm_offset_scaled_log_variance": 20061, "grandmaster_identity": "001747.fffe.700038", "grandmaster_priority1": 128, "grandmaster_priority2": 128, "observed_parent_clock_phase_change_rate": 2147483647, "observed_parent_offset_scaled_log_variance": 65535, "parent_port_identity": "001747.fffe.700038-1", "parent_stats": 0 }, "port_data_set": { "announce_receipt_timeout": 3, "delay_mechanism": 1, "log_announce_interval": 1, "log_min_delay_req_interval": 0, "log_min_pdelay_req_interval": 0, "log_sync_interval": 0, "peer_mean_path_delay": 0, "port_identity": "bc0fa7.fffe.00012c-1", "port_state": "SLAVE", "version_number": 2 }, "time_properties_data_set": { "current_utc_offset": 37, "current_utc_offset_valid": 1, "frequency_traceable": 1, "leap59": 0, "leap61": 0, "ptp_timescale": 1, "time_source": 32,
(continues on next page)
26
"time_traceable": 1 }, "time_status_np": {
"cumulative_scaled_rate_offset": 0, "gm_identity": "001747.fffe.700038", "gm_present": true, "gm_time_base_indicator": 0, "ingress_time": 1551814546772493800, "last_gm_phase_change": "0x0000'0000000000000000.0000", "master_offset": 224159, "scaled_last_gm_phase_change": 0 } }
(continued from previous page)
Response JSON Object
current_data_set (object) Result of the PMC GET CURRENT_DATA_SET command. parent_data_set (object) Result of the PMC GET PARENT_DATA_SET command. port_data_set (object) Result of the PMC GET PORT_DATA_SET command. time_properties_data_set (object) Result of the PMC GET TIME_PROPERTIES_DATA_SET command. time_status_np (object) Result of the PMC GET TIME_STATUS_NP command. This is a linuxptp non-portable command. Status Codes
200 OK No error
Fields of interest:
Current_data_set.offset_from_master Offset from master time source in nanoseconds as calculated during the last update from master.
Parent_data_set.grandmaster_identity This should match the local grandmaster clock. If this displays the sensor's clock identity (derived from Ethernet hardware address) then this indicates the sensor is not properly synchronized to a grandmaster.
Parent_data_set Various information about the selected master clock. Port_data_set.port_state This value will be SLAVE when a remote master clock is selected. See par-
ent_data_set for selected master clock. Port_data_set Local sensor PTP configuration values. Grandmaster clock needs to match these for
proper time synchronization. Time_properties_data_set PTP properties as given by master clock. Time_status_np.gm_identity Selected grandmaster clock identity. Time_status_np.gm_present True when grandmaster has been detected. This may stay true even if
grandmaster goes off-line. Use port_data_set.port_state to determine up-to-date synchronization status. When this is false then the local clock is selected. Time_status_np.ingress_time Indicates when last PTP message was received. Units are in nanoseconds. Time_status_np Linux PTP specific diagnostic values. The Red Hat manual provides some more information on these fields
27
GET /api/v1/time/sensor
GET 192.0.2.123/api/v1/time/sensor
Get the lidar sensor time status. These values relate to the hardware timestamping mechanism of the sensor.
GET /api/v1/system/time/sensor HTTP/1.1 Host: 192.0.2.123
HTTP/1.1 200 OK content-type: application/json; charset=UTF-8
{ "nmea": { "baud_rate": "BAUD_9600", "diagnostics": { "decoding": { "date_decoded_count": 0, "last_read_message": "", "not_valid_count": 0, "utc_decoded_count": 0 }, "io_checks": { "bit_count": 1, "bit_count_unfiltered": 0, "char_count": 0, "start_char_count": 0 } }, "ignore_valid_char": 0, "leap_seconds": 0, "locked": 0, "polarity": "ACTIVE_HIGH" }, "sync_pulse_in": { "diagnostics": { "count": 1, "count_unfiltered": 0, "last_period_nsec": 0 }, "locked": 0, "polarity": "ACTIVE_HIGH" }, "sync_pulse_out": { "angle_deg": 360, "frequency_hz": 1, "mode": "OFF", "polarity": "ACTIVE_HIGH", "pulse_width_ms": 10 }, "timestamp": { "mode": "TIME_FROM_INTERNAL_OSC", "time": 57178.44114677, "time_options": {
(continues on next page)
28
"internal_osc": 57178, "ptp_1588": 1552413986, "sync_pulse_in": 1 } } }
(continued from previous page)
For more information on these parameters refer to the get_time_info TCP command.
29
3 API Changelog
Version v1.6.0 Date 2018-08-16 Description
Add get_sensor_info command gives prod_line info.
Version v1.7.0 Date 2018-09-05 Description
No TCP command change.
Version v1.8.0 Date 2018-10-11 Description
get_sensor_info command gives INITIALIZING, UPDATING, RUNNING, ERROR and UNCONFIGURED status.
Version v1.9.0 Date 2018-10-24 Description
No TCP command change.
Version v1.10.0 Date 2018-12-11 Description
Remove all references of pulse_mode. Add get_alerts, pps_rate and pps_angle usage commands and expected output.
30
Remove TCP commands prior to v1.5.1.
Version v1.11.0 Date 2019-03-25 Description
Add section on HTTP API commands. TCP Port now hardcoded to 7501; port is no longer configurable. Update to SYNC_PULSE_IN and MULTIPURPOSE_IO interface and configuration parameters (see details below). Configuration parameters name changes: pps_in_polarity changed to sync_pulse_in_polarity pps_out_mode changed to multipurpose_io_mode pps_out_polarity changed to sync_pulse_out_polarity pps_rate changed to sync_pulse_out_frequency pps_angle changed to sync_pulse_out_angle pps_pulse_width changed to sync_pulse_out_pulse_width New configuration parameters: nmea_in_polarity nmea_ignore_valid_char nmea_baud_rate nmea_leap_seconds Configuration parameters option changes: timestamp_mode
TIME_FROM_PPS changed to TIME_FROM_SYNC_PULSE_IN multipurpose_io_mode (formerly pps_out_mode)
OUTPUT_PPS_OFF changed to OFF OUTPUT_FROM_PPS_IN_SYNCED changed to OUTPUT_FROM_SYNC_PULSE_IN Removed OUTPUT_FROM_PPS_DEFINED_RATE Added INPUT_NMEA_UART TCP command changes: Added commands:
get_time_info
Changed commands:
31
get_config_txt (returned dictionary keys match parameter changes) Removed commands:
set_pps_in_polarity get_pps_out_mode set_pps_out_mode get_timestamp_mode set_timestamp_mode
Polarity changes: sync_pulse_in_polarity was corrected to match parameter naming. sync_pulse_out_polarity was corrected to match parameter naming.
Version v1.12.0 Date Description
Corrected IMU axis directions to match Sensor Coordinate Frame. Sensor Coordinate Frame section of sensor user manual for details on sensor coordinate frame. This change inverts IMU X, Y, and Z axis relative to v1.11.0.
Version v1.13.0 Date Description
Add TCP command set_udp_dest_auto TCP command get_alerts, includes more descriptive errors for troubleshooting Packet Status now called Azimuth Data Block Status and is calculated differently Packets with bad CRC are now dropped upstream and replaced with 0 padded packets to ensure all packets are sent for each frame. Return format of TCP command get_time_info updated Removed reference to window_rejection_enable
Version v2.0.0 Date 2020-11-20
32
Added Add TCP command get_lidar_data_format. Add in azimuth_window documentation. Add in commands phase_lock_enable and phase_lock_offset and their documentation. Add in verbose responses to parameter validation for TCP commands. Add in command save_config_params in favor of the deprecated command write_config_txt, which will be deleted in future firmware. Add in command get_config_param active in favor of the deprecated command get_config_txt, which will be deleted in future firmware. Add in new STANDBY and WARMUP statuses. Add in parameter operating_mode in favor of the deprecated parameter auto_start_flag, which will be deleted in future firmware. Add in parameter udp_dest in favor of the deprecated parameter udp_ip, which will be deleted in future firmware. This is to be consistent with the set_udp_dest_auto parameter and to be reflect that valid values can be hostnames in addition to ip addresses. Add in HTTP GET api/v1/diagnostic/dump endpoint.
Removed Remove deprecated TCP command set_udp_ip.
Changed TCP command get_beam_intrinsics now returns: 1) lidar_origin_to_beam_origin_mm, distance between the lidar origin and the beam origin in millimeters; and 2) beam altitude and azimuth angle arrays with padded zeros removed. azimuth_window parameter now in terms of millidegrees and implemented CCW.
33
LaTeX with hyperref XeTeX 0.999991