Ouster OS-1-16 Safety guide

Software User Guide
Release v1.12.0
OS-1-64/16 High Resolution Imaging Lidar

May 02, 2019
Software User Guide
1 Introduction 5
2 Safety & Legal Notices 5
3 Drivers & Interface 6
3.1 Network Configuration .......................................... 6
3.2 HTTP Interface .............................................. 7
3.3 TCP API Command Set .......................................... 10
3.4 Lidar Data Format ............................................. 18
3.5 IMU Data Format ............................................. 19
3.6 Data Rates ................................................. 19
4 Coordinate Frames 19
4.1 Sensor Coordinate Frame ......................................... 19
4.2 Lidar Intrinsic Beam Angles ....................................... 20
4.3 Lidar Range Data To XYZ Lidar Coordinate Frame ........................... 20
4.4 Lidar Range Data To Sensor XYZ Coordinate Frame .......................... 21
4.5 IMU Data To Sensor XYZ Coordinate Frame .............................. 21
5 Time Synchronization 22
5.1 Timing Overview Diagram ........................................ 22
5.2 Sensor Time Source ............................................ 22
5.3 External Trigger Clock Source ...................................... 23
5.4 NMEA Message Format ......................................... 25
6 Updating Firmware 26
7 Troubleshooting 27
8 HTTP API Reference 28
8.1 system/firmware .......................................... 28
8.2 system/network ........................................... 28
8.3 system/time .............................................. 31
9 PTP Quickstart Guide 38
9.1 Assumptions ............................................... 38
9.2 Physical Network Setup .......................................... 38
9.3 Third Party Grandmaster Clock ...................................... 39
9.4 Linux PTP Grandmaster Clock ...................................... 39
9.5 Verifying Operation ............................................ 46
9.6 Tested Grandmaster Clocks ........................................ 47
HTTP Routing Table 48
2

Change Log
Version v1.6.0
Date 2018-08-16
Desciption Add: get_sensor_info command gives prod_line info.
Version v1.7.0
Date 2018-09-05
Desciption No TCP command change.
Version v1.8.0
Date 2018-10-11
Desciption Add: get_sensor_info command gives INITIALIZING,UPDATING,RUNNING,
ERROR and UNCONFIGURED status.
Version v1.9.0
Date 2018-10-24
Desciption No TCP command change.
Version v1.10.0
Date 2018-12-11
Desciption Remove all references of “pulse_mode”.
Add “get_alerts”, “pps_rate” and “pps_angle” usage commands and expected output.
Remove TCP commands prior to v1.5.1.
Version v1.11.0
Date 2019-03-25
Desciption 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).
3

Details on interface changes:
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 “OUT-
PUT_FROM_SYNC_PULSE_IN”
–Removed “OUTPUT_FROM_PPS_DEFINED_RATE”
–Added “INPUT_NMEA_UART”
TCP command changes:
•Added commands:
–“get_time_info”
•Changed commands:
–“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
Desciption Corrected IMU axis directions to match sensor coordinate frame. See section Section 4.1 for
details on sensor coordinate frame. This change inverts IMU X, Y, and Z axis relative to v1.11.0.
4

1 Introduction
The OS-1 family of sensors offer a market leading combination of price, performance, reliability and SWaP (Size,
Weight, and Power). They are designed for indoor/outdoor all-weather environments and long lifetime. As the smallest
high performance lidar on the market, the OS-1 can be directly integrated into vehicle fascias, windshields, side
mirrors, and headlight clusters. The OS-1 family of sensors consist of two models, the OS-1-16 and OS-1-64, with
differing resolution, but of identical mechanical dimensions.
HIGHLIGHTS
• Fixed resolution per frame operating mode
• Camera-grade intensity, ambient, and range data
• Multi-sensor crosstalk immunity
• Simultaneous and co-calibrated 2D and 3D output
• Industry leading intrinsic calibration
• Example client code available
For the purposes of this document, the term “OS-1” refers to the family of sensors, and only where there is a difference
in performance will each model be referred to by its specific model designation.
2 Safety & Legal Notices
The OS-1-16 and OS-1-64 are Class 1 laser products per IEC 60825-1:2014 and operate in the 850nm band.
FDA 21CFR1040 Notice: OS-1-16 and OS-1-64 comply with FDA performance standards for laser products except
for deviations pursuant to Laser Notice No. 50, dated July 26th, 2001.
WARNING: The OS-1 is a sealed unit, and is not user-serviceable.
Your use of the OS-1 is subject to the Terms of Sale that you signed with Ouster or your distributor/integrator. Included
in these terms is the prohibition on removing or otherwise opening the sensor housing, inspecting the internals of the
sensor, reverse-engineering any part of the sensor, or permitting any third party to do any of the foregoing.
“Ouster” and “OS-1” are both registered trademarks of Ouster, Inc. They may not be used without express permission
from Ouster, Inc.
If you have any questions about the above points, contact us at [e-mail]
5

3 Drivers & Interface
By default, when newly provided power by the Interface Box, the sensor will start-up and then automatically start
taking measurements, request an IP address, and stream UDP data packets to the configured destination address.
Settings can be modified using a simple plaintext protocol over TCP.
Ouster provides sample code for connecting to the sensor, visualizing the output data, and interfacing with the popular
ROS robotics suite. The source code repository can be found at: www.github.com/orgs/ouster-lidar/ouster_example
3.1 Network Configuration
Before attempting to configure and stream data from the sensor, please ensure that it is reachable over the network from
the client PC. The OS-1 requires a network that can provide data throughput of approximately 129 Mbps between client
and the sensor, and a DHCP server to reliably connect and stream data. Gigabit Ethernet hardware is recommended.
In a typical network environment, the OS-1 should obtain a DHCP lease and be reachable over the network a few
moments after being plugged in. If your network is set up to provide DNS for DHCP clients, you should be able to
check for connectivity using e.g.:
$ ping -c1 os1-991900123456
PING os1-991900123456 (10.5.5.94) 56(84) bytes of data.
64 bytes from os1-991900123456 (10.5.5.94): icmp_seq=1 ttl=64 time=0.163 ms
--- os1-991900123456 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.163/0.163/0.163/0.000 ms
where “991900123456” is the serial number printed on the top of the sensor.
Running A Local DHCP Server
If the sensor is plugged directly into the client machine, you will have to install and run a local DHCP server or use
the IPV4 override mechanism described below. A common choice is dnsmasq, which is available for a variety of
platforms. To connect to the sensor using a local dnsmasq instance on Linux:
1. Identify the ethernet interface to be used on the client (Linux) machine, e.g. enp6s0f1
2. Check that the sensor is not plugged in to the ethernet interface on the client machine
3. Make sure that the ethernet interface is “down” and not yet configured:
$ ip addr flush dev enp6s0f1
$ ip addr show dev enp6s0f1
2: enp6s0f1: <BROADCAST,MULTICAST> ... state DOWN group default qlen 1000
4. Assign a static IP to the chosen interface:
$ sudo ip addr add 10.5.5.1/24 dev enp6s0f1
5. Connect an ethernet cable between the sensor and the designated ethernet interface on the client machine. Power-
on the sensor. Ensure that the link is now “up”:
$ sudo ip link set enp6s0f1 up
$ ip addr show dev enp6s0f1
2: enp6s0f1: <BROADCAST,MULTICAST,UP> ... state UP group default qlen 1000
(continues on next page)
6

(continued from previous page)
link/ether xx:xx:xx:xx:xx:xx brd ff:ff:ff:ff:ff:ff
inet 10.5.5.1/24 scope global enp6s0f1
valid_lft forever preferred_lft forever
6. Run dnsmasq to listen for DHCP requests on the chosen interface:
$ sudo dnsmasq -C /dev/null -kd -F 10.5.5.50,10.5.5.100 -i enp6s0f1 --bind-dynamic
7. Within 10-15 seconds, you should see the DHCP negotiation take place:
dnsmasq-dhcp: DHCP, IP range 10.5.5.50 -- 10.5.5.100, lease time 1h
dnsmasq-dhcp: DHCP, sockets bound exclusively to interface enp6s0f1
dnsmasq: reading /etc/resolv.conf
dnsmasq: using nameserver 127.0.1.1#53
dnsmasq: read /etc/hosts - 7 addresses
dnsmasq-dhcp: DHCPDISCOVER(enp6s0f1) xx:xx:xx:xx:xx:xx
dnsmasq-dhcp: DHCPOFFER(enp6s0f1) 10.5.5.94 xx:xx:xx:xx:xx:xx
dnsmasq-dhcp: DHCPREQUEST(enp6s0f1) 10.5.5.94 xx:xx:xx:xx:xx:xx
dnsmasq-dhcp: DHCPACK(enp6s0f1) 10.5.5.94 xx:xx:xx:xx:xx:xx os1-991900123456
8. Check connectivity via the assigned IP address:
$ ping -c1 10.5.5.94
PING 10.5.5.94 (10.5.5.94) 56(84) bytes of data.
64 bytes from 10.5.5.94: icmp_seq=1 ttl=64 time=0.404 ms
--- 10.5.5.94 ping statistics ---
1 packets transmitted, 1 received, 0% packet loss, time 0ms
rtt min/avg/max/mdev = 0.404/0.404/0.404/0.000 ms
9. See the documentation for your operating system on how to make these changes persistent, e.g., by using a
network configuration daemon like NetworkManager.
3.2 HTTP Interface
The lidar sensor hosts a HTTP server that implements a versioned RESTful API to enable programmatic command
and control of the sensor.
This HTTP interface is a convenient way to query the sensor for various information. The query can be done from the
command line, programmatically or from within a web browser.
All of the responses are JSON objects and best handled with an HTTP client that can interpret and present JSON
objects.
Note: See the HTTP API Reference for more information on usage of individual resources.
Clients and Tools
Many readily available tools exist to facilitate communication with the HTTP API.
7

•Web browser
•Command line
•Programmatic access
Web browser
The simplest way to access the API is to issue a GET request using the web browser.
For example, to view the network configuration of a sensor load the following URL in a web browser:
http://192.0.2.123/api/v1/system/network
Extensions aid in viewing the JSON objects. Firefox includes a JSON formatter by default and the Chrome web store
offers the JSON Formatter.
To send HTTP requests using things other then GET method REST clients are available as well. The Chrome web
store offers the Advanced REST client.
Command line
For automated access from the command line a number exists for HTTP client as well as JSON formatters.
The httpie tool serves as a HTTP client as well as JSON formatter. Example usage:
$http http://192.0.2.123/api/v1/system/network
HTTP/1.1 200 OK
content-length: 260
content-type: application/json; charset=UTF-8
{
"carrier": true,
"duplex": "full",
"ethaddr": "bc:0f:a7:00:01:2c",
"hostname": "os1-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
}
Curl is a popular and high performance command line tool (backed by libcurl), example usage is as follows:
$curl -s http://192.0.2.123/api/v1/system/network
{"ipv6": {"link_local": "fe80::be0f:a7ff:fe00:12c/64"}, "ethaddr": "bc:0f:a7:00:01:2c
˓→", "ipv4": {"override": null, "link_local": "169.254.245.183/16", "addr": "192.0.2.
˓→123/24"}, "speed": 1000, "duplex": "full", "carrier": true, "hostname": "os1-
˓→991900123456"}
The unformatted JSON output is hard to read, but this can be improved with the command line jq formatter:
8

$curl -s http://192.0.2.123/api/v1/system/network | jq -S
{
"carrier": true,
"duplex": "full",
"ethaddr": "bc:0f:a7:00:01:2c",
"hostname": "os1-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
}
Programmatic access
Several popular libraries are available for interfacing with the sensor interface via common programming languages:
• C-libcurl
• Python - requests
Response Codes
The HTTP API uses HTTP response codes to provide result status information. The sensor will return HTTP response
codes that comply with the HTTP standards.
The http command shows the response code as part of the returned response in the console.
Common response code classes:
2XX Request was success (e.g., when a GET command succeeded)
4XX Client request error not allowed (e.g., when a POST on system/time is attempted)
5XX Server errors
9

3.3 TCP API Command Set
Querying Sensor Info and Intrinsic Calibration
The sensor can be queried and configured using a simple plaintext protocol over TCP on port 7501. The following
commands will return sensor configuration and calibration information:
Command Description Response Example
get_config_txt Return JSON-formatted sensor
{
"auto_start_flag":1,
"lidar_mode":"1024x10",
"multipurpose_io_mode":"OUTPUT_OFF",
"sync_pulse_in_polarity":"ACTIVE_HIGH
˓→",
"sync_pulse_out_angle":360,
"sync_pulse_out_frequency":1,
"sync_pulse_out_polarity":"ACTIVE_HIGH
˓→",
"sync_pulse_out_pulse_width":10,
"tcp_port":7501,
"timestamp_mode":"TIME_FROM_INTERNAL_
˓→OSC",
"udp_ip":"",
"udp_port_imu":7503,
"udp_port_lidar":7502,
"window_rejection_enable":1
}
get_sensor
_info
Return JSON-formatted sensor
metadata: serial number, hard-
ware and software revision, and
sensor status.
{
"base_pn":"000-101323-01",
"base_sn":"11E0211",
"build_date":"2018-05-02T18:37:13Z",
"build_rev":"v1.2.0",
"image_rev":"ousteros-image-prod-
˓→aries-v1.2.0-201804232039",
"prod_line":"OS-1-64",
"prod_pn":"840-101396-02",
"prod_sn":"991900123456",
"proto_rev":"v1.1.0",
"status":"RUNNING"
}
Continued on next page
10

Table 1 – continued from previous page
Command Description Response Example
get_time_info Return JSON-formatted sen-
sor timing configuration
and status of udp times-
tamp, synce_pulse_in, and
synce_pulse_out.
{
"sync_pulse_in": {
"diagnostics": {
"count_unfiltered":0,
"last_period_nsec":0,
"count":1
},
"polarity":"ACTIVE_HIGH",
"locked":0
},
"nmea": {
"polarity":"ACTIVE_HIGH",
"baud_rate":"BAUD_9600",
"diagnostics": {
"io_checks": {
"bit_count":1,
"start_char_count":0,
"bit_count_unfilterd":0,
"char_count":0
},
"decoding": {
"not_valid_count":0,
"last_read_message":"",
"utc_decoded_count":0,
"date_decoded_count":0
}
},
"leap_seconds":0,
"ignore_valid_char":0,
"locked":0
},
"sync_pulse_out": {
"frequency_hz":1,
"angle_deg":360,
"pulse_width_ms":10,
"polarity":"ACTIVE_HIGH",
"mode":"OFF"
},
"timestamp": {
"time_options": {
"ptp_1588":1552926167,
"sync_pulse_in":1,
"internal_osc":53
},
"mode":"TIME_FROM_INTERNAL_OSC",
"time":53.71712347
}
}
Continued on next page
11

Table 1 – continued from previous page
Command Description Response Example
get_beam
_intrinsics
Returns JSON-formatted beam
altitude and azimuth offsets, in
degrees.
{
"beam_altitude_angles": [
16.926,
16.313,
"...",
-16.078,
-16.689
],
"beam_azimuth_angles": [
3.052,
0.857,
"...",
-0.868,
-3.051
]
}
get_imu
_intrinsics
Returns JSON-formatted imu
transformation matrix needed to
adjust 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
]
}
Continued on next page
12

Table 1 – continued from previous page
Command Description Response Example
get_lidar
_intrinsics
Returns JSON-formatted lidar
transformation matrix needed to
adjust 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
]
}
get_alerts Returns JSON-formatted
alerts of the sensor if
get_sensor_info is
ERROR. It has a buffer to hold
up to 8 errors sequentially.
{
"alerts": [
{"cursor":0,
"code":"ETHERNET_LINK_BAD",
"level":"Warning",
"realtime":"1552568810910286848",
"brief":"Ethernet Link Bad",
"description":"Link transitioned
˓→to 0/Unknown which != 1000/Full"
}
],
"next_cursor":1
}
An example session using the unix netcat utility is shown below:
$nc os1-991900123456 7501
get_sensor_info
{``prod_line``: ``OS-1-64``, "prod_pn": "840-101396-02", "prod_sn": "991900123456",
"base_pn": "000-101323-01", "base_sn": "11E0211",
"image_rev": "ousteros-image-prod-aries-v1.2.0-201804232039", "build_rev": "v1.2.0",
"proto_rev": "v1.1.0", "build_date": "2018-05-02T18:37:13Z", "status": "RUNNING"}
Potentially, sensor may have the following status:
13

Status Occurs . . .
INITIALIZING When the sensor is booting and not yet outputting data.
UPDATING When the sensor is updating the FPGA firmware on the first reboot after a firmware upgrade.
RUNNING When the sensor has reached the final running state where it can output data.
ERROR Check error codes in the errors field for more information.
UNCONFIG-
URED
An error with factory calibration that requires a return.
If sensor is in an ERROR or UNCONFIGURED state, please contact Ouster with the output of get_sensor_info
and get_alerts for support.
Querying Active or Staged Parameters
Sensor configurations / operating modes can also be queried over TCP. Below is the latest 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
reinitialize command or after sensor reset.
get_config_param Command Description Response
udp_ip Returns the ip to which the sensor sends
UDP traffic..
"" (default)
udp_port_lidar Returns the port number of Lidar UDP data
packets
7502 (default)
udp_port_imu Returns the port number of IMU UDP data
packets
7503 (default)
lidar_mode Returns a string indicating the horizontal
resolution
One of 512x10,1024x10,
2048x10,512x20,1024x20
timestamp_mode Get the method used to timestamp measure-
ments. See Section 5.2 for a detailed de-
scription of each option.
One of
TIME_FROM_INTERNAL_OSC,
TIME_FROM_PTP_1588,
TIME_FROM_SYNC_PULSE_IN
sync_pulse_in_polarity Returns 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.
One of ACTIVE_HIGH
or ACTIVE_LOW. Default
ACTIVE_LOW.
nmea_in_polarity Returns the polarity of NMEA UART in-
put $GPRMC messages. See Section 5.2
NMEA use case. Use ACTIVE_HIGH if
UART is active high, idle low, and start bit
is after a falling edge.
One of ACTIVE_HIGH
or ACTIVE_LOW. Default
ACTIVE_HIGH.
nmea_ignore_valid_char Returns 0if NMEA UART input $GPRMC
messages should be ignored if valid charac-
ter is not set, and “1” if messages should be
used for time syncing regardless of the valid
character.
0 (default)
nmea_baud_rate Returns “BAUD_9600” (default) or
“BAUD_115200” for the expected baud
rate the sensor is attempting to decode for
NMEA UART input $GPRMC messages.
One of “BAUD_9600”,
“BAUD_115200”
Continued on next page
14

Table 2 – continued from previous page
get_config_param Command Description Response
nmea_leap_seconds Returns the number of leap seconds that will
be added to the UDP timestamp when cal-
culating seconds since 00:00:00 Thursday,
1 January 1970. For Unix Epoch time, this
should be set to 0.
0 (default)
multipurpose_io_mode Returns the source of the the
SYNC_PULSE_OUT signal output by
the sensor. See Section 5.3 for a detailed
description of each option.
One of
OUTPUT_FROM_INTERNAL_OSC,
OUTPUT_FROM_SYNC_PULSE_IN,
OFF,OUTPUT_FROM_PTP_1588
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
ACTIVE_LOW.
sync_pulse_out_frequency Returns the output SYNC_PULSE_OUT
pulse rate in Hz
1 (default)
sync_pulse_out_angle Returns the output SYNC_PULSE_OUT
pulse rate defined in rotation angles.
360 (default)
sync_pulse_out_pulse_width Returns the output SYNC_PULSE_OUT
pulse width in ms.
10 (ms, default)
auto_start_flag Returns 1if sensor is on auto start, and 0if
not. Normal operation is to use auto start. If
not in auto start, the sensor must be manu-
ally commanded in order to operate.
1 (default)
window_rejection_enable 1: The default. Enabled. Allows the sen-
sor to achieve full spec. 0: Disabled. Re-
duces the sensor range to zero meters but
also causes the sensor to select the window
return echo instead of a target return echo
if the window echo is stronger. Depending
on window cleanliness this can significantly
reduce sensor range. No sensor specs are
guaranteed in this mode.
1 (default)
An example session using the unix netcat utility is shown below:
$nc os1-991900123456 7501
get_config_param active lidar_mode
1024x10
15

Setting Configuration Parameters
set_config_param <parameter> <value> will set new values for configuration parameters, which will
take effect after issuing reinitialize command, or after sensor reset.
set_config_param Command Description Response
udp_ip <ip address> Specifies the ip to which the sensor sends UDP
traffic. On boot, the sensor will not output data
until this is set.
set_config_param on suc-
cess, error: otherwise
udp_port_lidar <port> Lidar data will be sent to <udp_ip>: set_config_param on suc-
cess, error: otherwise
udp_port_imu <port> Imu data will be sent to <udp_ip>: set_config_param on suc-
cess, error: otherwise
lidar_mode <mode> Set the horizontal resolution and rotation rate of
the sensor. Valid modes are 512x10,1024x10,
2048x10 512x20,1024x20. Each 50% the
total number of points gathered is reduced - e.g.,
from 2048x10 to 1024x10 - extends range by 15-
20%.
set_config_param on suc-
cess, error: otherwise
timestamp_mode <mode> 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_config_param on suc-
cess, error: otherwise
sync_pulse_in_polarity
<1/0>
Set the polarity of SYNC_PULSE_IN input,
which controls polarity of SYNC_PULSE_IN
pin when timestamp_mode is set in
TIME_FROM_SYNC_PULSE_IN.
set_config_param on suc-
cess, error: otherwise
nmea_in_polarity <1/0> Set the polarity of NMEA UART input $GPRMC
messages. See Section 5.2 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 suc-
cess, error: otherwise
nmea_ignore_valid_char
<1/0>
Set 0if 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 suc-
cess, error: otherwise
nmea_baud_rate <rate in
baud/s>
Set “BAUD_9600” (default) or “BAUD_115200”
for the expected baud rate the sensor is attempt-
ing to decode for NMEA UART input $GPRMC
messages.
set_config_param on suc-
cess, error: otherwise
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 suc-
cess, error: otherwise
multipurpose_io_mode
<mode>
Set the source of the SYNC_PULSE_OUT
signal. Valid modes are
OUTPUT_OFF, “INPUT_NMEA_UART”,
OUTPUT_FROM_INTERNAL_OSC,
OUTPUT_FROM_SYNC_PULSE_IN,
OUTPUT_FROM_PTP_1588, or
OUTPUT_FROM_ENCODER_ANGLE
set_config_param on suc-
cess, error: otherwise
16

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 suc-
cess, error: otherwise
sync_pulse_out_frequency
<rate in Hz>
Set output SYNC_PULSE_OUT rate. Valid in-
puts are integers > 0 Hz, but also limited by the
criteria described in Section 5.3 of this user man-
ual.
set_config_param on suc-
cess, error: otherwise
sync_pulse_out_angle
<angle in deg>
Set output SYNC_PULSE_OUT rate defined by
rotation angle. Valid inputs are integers < 360 de-
grees, but also limited by the criteria described in
Section 5.3 of this user manual.
set_config_param on suc-
cess, error: otherwise
sync_pulse_out_pulse_width
<width in ms>
Set output SYNC_PULSE_OUT pulse width in
ms, in 1ms increments. Valid inputs are integers >
0 ms, but also limited by the criteria described in
Section 5.3 of this user manual.
set_config_param on suc-
cess, error: otherwise
window_rejection_enable
<1/0>
1: The default. Enabled. Allows the sensor to
achieve full spec. 0: Disabled. Reduces the sen-
sor range to zero meters but also causes the sen-
sor to select the window return echo instead of a
target return echo if the window echo is stronger.
Depending on window cleanliness this can signif-
icantly reduce sensor range. No sensor specs are
guaranteed in this mode.
set_config_param on suc-
cess, error: otherwise
reinitialize will reinitialize the sensor so the staged values of the parameters will take effect immediately.
write_config_txt 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 write_config_txt capture it to take effect on reset.
set_config_param
Command
Description Response
reinitialize Restarts the sensor. Changes to lidar, sync_pulse_out, and timestamp
modes will only take effect after reinitialization.
reinitialize
on success
write_config_txt Make the current settings persist until the next reboot. write_config_txt
on success
$nc os1-991900123456 7501
set_config_param lidar_mode 512x20
set_config_param
set_config_param udp_ip 10.5.5.1
set_config_param
reinitialize
reinitialize
write_config_txt
write_config_txt
17

3.4 Lidar Data Format
By default UDP data is forwarded to Port 7502. Lidar data packets consist of 16 azimuth blocks and are always 12608
Bytes in length. The packet rate is dependent on the output mode. Words are 32 bits in length.
Word Azimuth Block 0 Azimuth Block 1 . . . Azimuth Block 15
(Word 0,1) Timestamp Timestamp . . . Timestamp
(Word 2[0:15]) Measurement ID Measurement ID . . . Measurement ID
(Word 2[16:31]) Frame ID Frame ID . . . Frame ID
(Word 3) Encoder Count Encoder Count . . . Encoder Count
(Word 4,5,6) Channel 0 Data Block Channel 0 Data Block . . . Channel 0 Data Block
(Word 7,8,9) Channel 1 Data Block Channel 1 Data Block . . . Channel 1 Data Block
. . .
(Word 193, 194, 195) Channel 63 Data Block Channel 63 Data Block . . . Channel 63 Data Block
(Word 196) Packet Status Packet Status . . . Packet Status
Each azimuth block contains:
• Timestamp [64 bit unsigned int] - Timestamp of the measurement in nanoseconds
• Measurement ID[16 bit unsigned int] - a sequentially incrementing azimuth measurement counting up from 0
to 511, or 0 to 1023, or 0 to 2047 depending on lidar_mode.
• Frame ID[16 bit unsigned int] - index of the lidar scan. Increments every time the sensor completes a rotation,
crossing the zero point of the encoder.
• Encoder Count[32 bit unsigned int] - an azimuth angle as a raw encoder count, starting from 0 with a max value
of 90111 - incrementing 44 ticks every azimuth angle in 2048 mode, 88 ticks in 1024 mode, and 176 ticks in
512 mode.
• Data Block[96 bits] - 3 data words for each of the 16 or 64 pixels. See Table below for full definition.
–Range [20 bits] - Range in millimeters, discretized to the nearest 12 millimeters.
–Reflectivity [16 bits] - Sensor signal_photon measurements are scaled based on measured range and sensor
sensitivity at that range, providing an indication of target reflectivity. Calibration of this measurement has
not currently been rigorously implemented, but this will be updated in a future firmware release.
–Signal Photons [16 bits] - Signal photons in the signal return measurement are reported
–Ambient Noise Photons [16 bits] - Ambient noise photons in the ambient noise return measurement are
reported.
• Packet Status- indicates whether the azimuth block is good or bad. Good = 0xFFFFFFFF, Bad = 0x0. If a packet
is bad Measurement ID, Encoder Count, and Data Bock:Range and Data Block:Reflectivity will also be set to
0x0.
Full Description of Data Block:
Word Byte 3 Byte 2 Byte 1 Byte 0
(Word 0) unused[31:24] unused[23:20]
range_mm[19:16]
range_mm[15:8] range_mm[7:0]
(Word 1) signal_photons[31:24] signal_photons[23:16] reflectivity[15:8] reflectivity[7:0]
(Word 2) unused[31:24] unused[23:16] noise_photons[15:8] noise_photons[7:0]
18

3.5 IMU Data Format
UDP Packets - 48 Bytes - Port 7503 - at 100 Hz
Word IMU and Gyro Data Block
(Word 0,1) 64-bit unsigned integer for IMU read time (ns, monotonic system time since boot)
(Word 2,3) 64-bit unsigned integer for accelerometer read time (ns, relative to timestamp_mode)
(Word 4,5) 64-bit unsigned integer for gyroscope read time (ns, relative to timestamp_mode)
(Word 6) 32-bit float for acceleration in x-axis (g)
(Word 7) 32-bit float for acceleration in y-axis (g)
(Word 8) 32-bit float for acceleration in z-axis (g)
(Word 9) 32-bit float for angular velocity about in x-axis (deg per sec)
(Word 10) 32-bit float for angular velocity about in y-axis (deg per sec)
(Word 11) 32-bit float for angular velocity about in z-axis (deg per sec)
3.6 Data Rates
Based on 12,608 Bytes/packet and 1280 packets/sec, in 2048x10 or 1048x20 mode the OS-1 outputs 16.138 MB/s
(129 Mbps). For this reason a gigabit ethernet network is required for reliable performance.
4 Coordinate Frames
4.1 Sensor Coordinate Frame
The Sensor Coordinate Frame follows the right-hand rule convention and is defined at the center of the sensor housing
on the bottom, with the x-axis pointed forward, y-axis pointed to the left and z-axis pointed towards the top of the
sensor. The external connector is located in the negative x direction. The Sensor Coordinate Frame is marked in the
diagram below with XS, YS, ZS.
The Lidar Coordinate Frame follows the right-hand rule convention and is defined at the intersection of the lidar axis
of rotation and the lidar optical midplane (a plane parallel to Sensor Coordinate Frame XY plane and coincident with
the 0 deg elevation beam angle of the lidar). The Lidar Coordinate Frame axes are arranged with the x-axis pointed
at encoder angle 0, the y-axis pointed to the right and the z-axis pointed towards the top of the sensor. The external
connector is located in the positive x direction. The Lidar Coordinate Frame is marked in the diagram below with XL,
YL, ZL.
19

NOTE: The Lidar Coordinate Frame’s positive x-axis (0 encoder value) is opposite the Sensor Coordinate Frame’s
positive x-axis to center lidar data about the Sensor Coordinate Frame’s positive x-axis. A single measurement frame
starts at the Lidar Coordinate Frame’s 0 degree position and ends at the 360 degree position. This is convenient when
viewing a “range image” of the Ouster Sensor measurements, allowing the “range image” to be centered in the Sensor
Coordinate Frame’s positive x-axis, which is generally forward facing in most robotic systems.
NOTE: The Ouster Sensor scans in the clockwise direction when viewed from the top, which is a negative rotational
velocity about the z-axis. Thus, as encoder ticks increases from 0 to 90111, the actual angle about the z-axis in the
Lidar Coordinate Frame will decrease.
4.2 Lidar Intrinsic Beam Angles
The intrinsic beam angles for each beam may be queried with a TCP command (see OS-1 Software User Guide) and
provide an azimuth and elevation adjustment to the each beam. The azimuth adjustment is referenced off of the current
encoder angle and the elevation adjustment is referenced from the XY plane in the Sensor and lidar Coordinate Frames.
4.3 Lidar Range Data To XYZ Lidar Coordinate Frame
The origin and axes of the lidar Coordinate Frame are defined by the position of the lidar lens aperture stop in the
sensor and the 0º position of the rotary encoder, which is aligned with the sensor connector and the negative X axis of
the Sensor Coordinate Frame.
For many applications, it is sufficient to calculate the XYZ point cloud in the lidar Coordinate Frame using a combi-
nation of the intrinsic beam angles and the encoder reading. The intrinsic azimuth and elevation beam angles may be
queried over TCP as two vectors each 64 elements long.
20