TCP API Guide (Important Notice)
Note
TCP API is subject to deprecation starting FW 3.0, please prepare to use HTTP API instead. TCP API will be completely removed and be unavailable for use in Q3, 2023.
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-992244000006.local 7501
get_sensor_info
{"prod_line": "OS-1-128", "prod_pn": "860-105010-07", "prod_sn": "992244000006",
"image_rev": "ousteros-image-prod-bootes-v3.0.0+0123456789",
"build_rev": "v3.0.0", "build_date": "2023-1-15T15:56:07Z", "status": "RUNNING",
"initialization_id": 1128503}
A sensor may have one of the following statuses:
Status |
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 |
|
An error with factory calibration that requires a manual power cycle or reboot |
Note
If the sensor is set to STANDBY mode some of these commands will not return the expected values.
If the sensor is in an ERROR or UNCONFIGURED state, please contact Ouster support with the diagnostic file found at http://os-9919xxxxxxxx/diag for support.
Sensor Config Parameter Interface
get_config_param
Description: Returns all active or staged JSON-formatted sensor configuration.
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 areinitializecommand.
Warning
The command get_config_txt is deprecated and superseded by get_config_param active, which provides the same response. get_config_txt will be removed in a future firmware.
Example 1: Shows how a user can get information of a particular parameter below using the unix netcat utility:
$ nc os-992244000006.local 7501
get_config_param active lidar_mode
1024x10
Example 2: Shows how a user can get all the <active> parameters information below using the unix netcat utility:
$ nc os-992244000006.local 7501
get_config_param active
{
"udp_dest": "169.254.225.4",
"udp_port_lidar": 7502,
"udp_port_imu": 7503,
"udp_profile_lidar": "RNG19_RFL8_SIG16_NIR16_DUAL",
"udp_profile_imu": "LEGACY",
"columns_per_packet": 16,
"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,
"operating_mode": "NORMAL",
"lidar_mode": "1024x10",
"azimuth_window": [0, 360000],
"signal_multiplier": 1,
"phase_lock_enable": false,
"phase_lock_offset": 0
}
set_config_param
set_config_param <parameter> <value> will set new values for configuration parameters, which will take effect after issuing the reinitialize command.
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.
While in STANDBY mode, we can set the config parameters, but it will not take effect until we switch the sensor back to NORMAL mode.
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.
Note
In the example below, to distinguish between the command and expected response, a dash has been added before the expected response. The actual response will be without the dash.
$ nc os-991900123456.local 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
Note
In the example below, see the error message when an invalid value is set i.e., lidar_mode = 511x10.
$ nc os-992244000006.local 7501
set_config_param lidar_mode 511x10
error: '511x10' is not supported
The following commands will set sensor configuration parameters:
Note
Each of the following commands have two responses:
* set_config_param on Success
* error: Otherwise
Command |
Command Description |
|---|---|
|
Restarts the sensor. Changes to lidar, multipurpose_io, and timestamp modes will only take effect after reinitialization. Response on success: |
|
Makes all current parameter settings persist after reboot. Response on success: |
|
Set the destination of UDP traffic to the destination address that issued the command. Response on success: |
Note
Refer to Sensor Configuration for detailed information on all configurable parameters using HTTP or TCP commands.
Sensor Status and Calibration
get_sensor_info
Description: Returns JSON-formatted sensor metadata: serial number, hardware and software revision, and sensor status.
{
"prod_line": "OS-1-128",
"prod_pn": "860-105010-07",
"prod_sn": "992244000006",
"image_rev": "ousteros-image-prod-bootes-v3.0.0+0123456789",
"build_rev": "v3.0.0",
"build_date": "2023-1-15T15:56:07Z",
"status": "RUNNING",
"initialization_id": 1128503
}
get_time_info
Description: Returns JSON-formatted sensor timing configuration and status of udp timestamp, sync_pulse_in, and multipurpose_io.
{
"timestamp":
{
"time": 3657.224442616,
"mode": "TIME_FROM_INTERNAL_OSC",
"time_options":
{
"ptp_1588": 3718,
"sync_pulse_in": 1,
"internal_osc": 3709
}
},
"sync_pulse_in":
{
"locked": 0,
"polarity": "ACTIVE_HIGH",
"diagnostics":
{
"last_period_nsec": 0,
"count": 1,
"count_unfiltered": 0
}
},
"multipurpose_io":
{
"mode": "OFF",
"sync_pulse_out":
{
"polarity": "ACTIVE_HIGH",
"frequency_hz": 1,
"angle_deg": 360,
"pulse_width_ms": 10
},
"nmea":
{
"locked": 0,
"polarity": "ACTIVE_HIGH",
"ignore_valid_char": 0,
"baud_rate": "BAUD_9600",
"leap_seconds": 0,
"diagnostics":
{
"decoding":
{
"utc_decoded_count": 0,
"date_decoded_count": 0,
"not_valid_count": 0,
"last_read_message": ""
},
"io_checks":
{
"start_char_count": 0,
"char_count": 0,
"bit_count": 1,
"bit_count_unfiltered": 0
}
}
}
}
}
get_beam_intrinsics
Description: Returns JSON-formatted beam altitude and azimuth offsets, in degrees. Length of arrays is equal to the number of channels in the sensor. Also returns distance between lidar origin and beam origin in mm, to be used for point cloud calculations.
{
"beam_altitude_angles": [
20.38, 20.12, 19.79, 19.45, 19.14, 18.85, 18.55, 18.2, 17.86, 17.58, 17.27, 16.93,
16.58, 16.29, 15.98, 15.61, 15.27, 14.97, 14.66, 14.3, 13.96, 13.65, 13.33, 12.97,
12.62, 12.31, 11.98, 11.63, 11.27, 10.96, 10.63, 10.26, 9.91, 9.59, 9.26, 8.89,
8.54, 8.21, 7.87, 7.52, 7.15, 6.82, 6.47, 6.11, 5.76, 5.42, 5.08, 4.73, 4.36, 4.03,
3.66, 3.31, 2.96, 2.62, 2.27, 1.91, 1.55, 1.22, 0.85, 0.51, 0.16, -0.2, -0.55, -0.91,
-1.26, -1.62, -1.96, -2.3, -2.66, -3.02, -3.36, -3.72, -4.07, -4.42, -4.77, -5.11,
-5.46, -5.82, -6.16, -6.49, -6.85, -7.21, -7.55, -7.88, -8.23, -8.59, -8.93, -9.25,
-9.6, -9.96, -10.31, -10.63, -10.96, -11.32, -11.67, -11.97, -12.31, -12.68, -13,
-13.32, -13.64, -14, -14.33, -14.63, -14.96, -15.31, -15.64, -15.94, -16.26,
-16.62, -16.93, -17.22, -17.54, -17.9, -18.22, -18.49, -18.8, -19.16, -19.47,
-19.73, -20.04, -20.39, -20.7, -20.94, -21.25, -21.6, -21.9, -22.14],
"beam_azimuth_angles": [
4.24, 1.41, -1.42, -4.23, 4.23, 1.41, -1.41, -4.23, 4.23, 1.41, -1.41, -4.21, 4.23,
1.42, -1.4, -4.23, 4.24, 1.41, -1.4, -4.23, 4.24, 1.42, -1.4, -4.22, 4.23, 1.41,
-1.41, -4.22, 4.23, 1.42, -1.4, -4.22, 4.24, 1.41, -1.4, -4.23, 4.23, 1.41, -1.41,
-4.22, 4.23, 1.41, -1.41, -4.23, 4.23, 1.4, -1.42, -4.23, 4.23, 1.41, -1.42, -4.23,
4.23, 1.4, -1.42, -4.24, 4.22, 1.41, -1.43, -4.24, 4.22, 1.4, -1.42, -4.24, 4.22,
1.4, -1.42, -4.23, 4.22, 1.4, -1.4, -4.24, 4.22, 1.4, -1.42, -4.24, 4.22, 1.41,
-1.41, -4.22, 4.22, 1.39, -1.42, -4.23, 4.22, 1.41, -1.41, -4.22, 4.23, 1.41,
-1.41, -4.23, 4.23, 1.41, -1.41, -4.22, 4.23, 1.41, -1.41, -4.22, 4.22, 1.41,
-1.41, -4.22, 4.23, 1.41, -1.4, -4.23, 4.22, 1.41, -1.41, -4.23, 4.22, 1.4, -1.41,
-4.23, 4.22, 1.4, -1.41, -4.24, 4.22, 1.4, -1.42, -4.24, 4.22, 1.4, -1.42, -4.23],
"beam_to_lidar_transform": [ 1, 0, 0, 15.805999755859375, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1 ],
"lidar_origin_to_beam_origin_mm": 15.8059998
}
get_imu_intrinsics
Description: 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
]
}
get_lidar_intrinsics
Description: 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, 38.195, 0, 0, 0, 1
]
}
get_alerts
Example 1: get_alerts <START_CURSOR> <MODE>
Description: Returns JSON-formatted sensor diagnostic information.
Two lists will be returned, an active list and a log list. The active list will contain alert-trigger events for alerts that are currently active. An alert-trigger event will by-definition always have its active attribute set to true. There is no limit on the number of alert-trigger events that are displayed in the active event list. All currently active alert-trigger events will be displayed in the active event list.
The log list will contain all current and past alert-trigger and alert-clear events. An alert-clear event will by-definition have the exact same attributes and attribute values as its corresponding trigger event, with the exception of the realtime and cursor attributes which should have higher values, since an alert-clear event will always be received after an alert-trigger event. The log list has a length limit of 32 events with the oldest events automatically removed from the log list once a new event needs to be added to the log list and the log list length limit is reached, essentially acting as a FIFO (First In First Out) queue.
In addition to the active and log lists, get_alerts also returns a next_cursor field. Every alert event has a cursor attribute, which increments for every alert event logged. This can be used to track the alert activity that has been viewed and reduce message bandwidth. To do this, users are recommended to save the next_cursor field when calling get_alerts and then use that value as the START_CURSOR argument on the next get_alerts call to fetch only new log entries.
A valid value for MODE is either summary or default.
Additional Information:
The cursor will wrap at 2^32 entries. It is important to understand the behavior during the wrap case, since this may lead to some unexpected consequences:
If START_CURSOR < (next_cursor - 32) % 2^32 then some entries may be filtered. For instance if START_CURSOR=0 and next_cursor=0 no entries will be reported immediately after cursor wrap, even though the log contains 32 entries, where submitting START_CURSOR=4294967264 (next_cursor - 32) % 2^32 will return all logged values.
If START_CURSOR > next_cursor all 32 entries will be reported.
The recommended approach to using the interface is to always base queries on the previous value of next_cursor.
Note
Valid uses of get_alerts:
Example: Calling get_alerts with START_CURSOR=1
get_alerts 1Example: Calling get_alerts with START_CURSOR=2 and MODE=summary
get_alerts 2 summary
Invalid uses of get_alerts:
Example: Calling get_alerts with START_CURSOR=summary and MODE=2
get_alerts summary 2
Note
The position of START_CURSOR and MODE is important to follow when using TCP Commands and is irrelevant when calling the equivalent /api/v1/sensor/alerts HTTP endpoint, meaning for an HTTP GET call the position is insensitive.
The example in the code block is for get_alerts.
{
"log":
[
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 0,
"id": "0x01000018",
"level": "WARNING",
"msg": "Client machine announced
it is not reachable on the
provided not reachable on
IMU data port; check that
udp_dest and udp_port_imu
configured on the sensor matches
client IP and port.",
"msg_verbose": "Failed to send
imu UDP data to destination
host 169.254.225.4:7503",
"realtime": "39850161524"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 1,
"id": "0x01000015",
"level": "WARNING",
"msg": "Client machine announced
it is not reachable on the
provided lidar data port;
check that udp_dest and
udp_port_lidar configured on
the sensor matches client IP
and port.",
"msg_verbose": "Failed to send
lidar UDP data to destination
host 169.254.225.4:7502",
"realtime": "40842065146"
},
{
"active": true,
"category": "ETHERNET_LINK_BAD",
"cursor": 2,
"id": "0x01000011",
"level": "WARNING",
"msg": "Ethernet link bad, please
check network switch and
harnessing can support
1 Gbps Ethernet.",
"msg_verbose": "Link transitioned
to 0/Unknown",
"realtime": "414257307390"
},
{
"active": true,
"category": "ETHERNET_LINK_BAD",
"cursor": 2,
"id": "0x01000011",
"level": "WARNING",
"msg": "Ethernet link bad, please
check network switch and
harnessing can support
1 Gbps Ethernet.",
"msg_verbose": "Link transitioned
to 0/Unknown",
"realtime": "414257307390"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 3,
"id": "0x01000016",
"level": "WARNING",
"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 169.254.225.4:7502",
"realtime": "414261086316"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 4,
"id": "0x01000019",
"level": "WARNING",
"msg": "Could not send IMU UDP
packet to host; check
that network is up.",
"msg_verbose": "Failed to send imu
UDP data to destination
host 169.254.225.4:7503",
"realtime": "414266339945"
},
{
"active": false,
"category": "ETHERNET_LINK_BAD",
"cursor": 5,
"id": "0x01000011",
"level": "WARNING",
"msg": "Ethernet link bad,
please check network switch
and harnessing can support
1 Gbps Ethernet.",
"msg_verbose": "Link transitioned
to 1000/Full",
"realtime": "416337486469"
}
],
"next_cursor": 6,
"active":
[
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 1,
"id": "0x01000015",
"level": "WARNING",
"msg": "Client machine announced
it is not reachable on the
provided lidar data port;
check that udp_dest and
udp_port_lidar configured
on the sensor matches
client IP and port.",
"msg_verbose": "Failed to send
lidar UDP data to destination
host 169.254.225.4:7502",
"realtime": "40842065146"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 3,
"id": "0x01000016",
"level": "WARNING",
"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 169.254.225.4:7502",
"realtime": "414261086316"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 0,
"id": "0x01000018",
"level": "WARNING",
"msg": "Client machine announced
it is not reachable on the provided
not reachable on IMU data port;
check that udp_dest and
udp_port_imu configured on the
sensor matches client IP
and port.",
"msg_verbose": "Failed to send imu
UDP data to destination host
169.254.225.4:7503",
"realtime": "39850161524"
},
{
"active": true,
"category": "UDP_TRANSMISSION",
"cursor": 4,
"id": "0x01000019",
"level": "WARNING",
"msg": "Could not send IMU UDP
packet to host; check that
network is up.",
"msg_verbose": "Failed to send
imu UDP data to destination
host 169.254.225.4:7503",
"realtime": "414266339945"
}
]
}
Example 2: get_alerts <START_CURSOR> <MODE>
Description: Returns JSON-formatted sensor diagnostic information. A valid value for MODE is either summary or default. Setting the MODE argument to SUMMARY provides a less verbose version of the get_alerts <START_CURSOR> command as referenced above.
Note
Valid uses of get_alerts:
Example: Calling get_alerts with START_CURSOR=1
get_alerts 1Example: Calling get_alerts with START_CURSOR=2 and MODE=summary
get_alerts 2 summary
Invalid uses of get_alerts:
Example: Calling get_alerts with START_CURSOR=summary and MODE=2
get_alerts summary 2
Note
The order in which the START_CURSOR and MODE arguments are specified for the get_alerts TCP command must be followed when providing both arguments, with START_CURSOR preceding the MODE. The arguments can be specified in any order when calling the equivalent /api/v1/sensor/alerts HTTP endpoint.
The example shown in the code block is for get_alerts summary.
{
"log":
[
{
"cursor": 0,
"id": "0x01000018",
"realtime": "80395661548",
"active": true
},
{
"cursor": 1,
"id": "0x01000015",
"realtime": "81386289401",
"active": true
},
{
"cursor": 2,
"id": "0x01000014",
"realtime": "2730854039127",
"active": true
},
{
"cursor": 3,
"id": "0x01000014",
"realtime": "2740849252064",
"active": false
},
{
"cursor": 4,
"id": "0x01000011",
"realtime": "8835209059341",
"active": true
},
{
"cursor": 5,
"id": "0x01000016",
"realtime": "8835240707086",
"active": true
},
{
"cursor": 6,
"id": "0x01000019",
"realtime": "8835245794318",
"active": true
},
{
"cursor": 7,
"id": "0x01000011",
"realtime": "8837298086954",
"active": false
},
{
"cursor": 8,
"id": "0x01000015",
"realtime": "10742075130316",
"active": false
},
{
"cursor": 9,
"id": "0x01000016",
"realtime": "10742075535820",
"active": false
},
{
"cursor": 10,
"id": "0x01000018",
"realtime": "10742075793868",
"active": false
},
{
"cursor": 11,
"id": "0x01000019",
"realtime": "10742076051916",
"active": false
},
{
"cursor": 12,
"id": "0x01000015",
"realtime": "10799083353303",
"active": true
},
{
"cursor": 13,
"id": "0x01000018",
"realtime": "10799092477143",
"active": true
},
{
"cursor": 14,
"id": "0x01000016",
"realtime": "11782640857349",
"active": true
}
],
"next_cursor": 15,
"active":
[
{
"cursor": 12,
"id": "0x01000015",
"realtime": "10799083353303"
},
{
"cursor": 14,
"id": "0x01000016",
"realtime": "11782640857349"
},
{
"cursor": 13,
"id": "0x01000018",
"realtime": "10799092477143"
}
]
}
get_lidar_data_format
Description: Returns JSON-formatted response 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 contained in a single lidar packet. Currently in v2.2.0 and earlier, this is 16. Note: This is not user configurable.
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. Note: The new value is centered around zero with both positive and negative values such that the destaggered image corresponds to the sensor’s azimuth angles. The old destagger values introduced an offset to shift the pixel_shift_by_row values so they are all non-negative.
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 an azimuth window set, this parameter will reflect which measurement blocks of data are within the region of interest.
udp_profile_lidar- Lidar data profile format [Default “RNG19_RFL8_SIG16_NIR16”].
udp_profile_imu- IMU data profile format [Default LEGACY].
Note
This command only works when the sensor is in RUNNING status.
{
"column_window": [0, 1023],
"columns_per_frame": 1024,
"columns_per_packet": 16,
"pixel_shift_by_row": [ 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4, -12,
12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4,
-12, 12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4,
-12, 12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4,
-12, 12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4,
-12, 12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12, 12, 4, -4, -12, 12, 4, -4,
-12, 12, 4, -4, -12, 12, 4, -4, -12, 12,
4, -4, -12],
"pixels_per_column": 128,
"udp_profile_imu": "LEGACY",
"udp_profile_lidar": "RNG19_RFL8_SIG16_NIR16_DUAL"
}
get_calibration_status
Description: Returns JSON-formatted calibration status of the sensor reflectivity. valid: true/false depending on calibration status. timestamp: if valid is true; time at which the calibration was completed.
{
"reflectivity":
{
"valid": true,
"timestamp": "2022-11-18T20:31:06"
}
}
get_telemetry
Description: Returns JSON-formatted response that provides sensor system state information. This includes the FPGA Timestamp in ns (Nanoseconds) at which the information was collected from the FPGA, Lidar Input Voltage in mv (Millivolt), Lidar Input Current in ma (Milliamp), Internal Temperature of the sensor in ºC (Degree Celsius) and Phase Lock status namely LOCKED, LOST, DISABLED.
Note
Using get_telemetry, Internal temperature can only be measured with Rev 06 and above sensors.
Note
Phase lock output will not indicate loss of lock if the PTP source is lost.
{
"input_current_ma": 644,
"input_voltage_mv": 23624,
"internal_temperature_deg_c": 48,
"phase_lock_status": "DISABLED",
"timestamp_ns": 2093396806056
}