Ouster OS-1-16 Software User's Manual
  1. Manuals
  2. Brands
  3. Ouster Manuals
  4. Accessories
  5. OS-1-16
  6. Software user's manual

Ouster OS-1-16 Software User's Manual

High resolution imaging lidar
Hide thumbs Also See for OS-1-16:
Table of Contents

Advertisement

Quick Links

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

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the OS-1-16 and is the answer not in the manual?

Questions and answers

Related Manuals for Ouster OS-1-16

Summary of Contents for Ouster OS-1-16

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

  • Page 2: Table Of Contents

    May 02, 2019 Software User Guide 1 Introduction 2 Safety & Legal Notices 3 Drivers & Interface 3.1 Network Configuration ......... . 3.2 HTTP Interface .
  • Page 3 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.
  • Page 4 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: •...

  • Page 5: Introduction

    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.

  • Page 6: Drivers & Interface

    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 robotics suite. The source code repository can be found at: www.github.com/orgs/ouster-lidar/ouster_example...

  • Page 7: Http Interface

    (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.
  • Page 8 • 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.
  • Page 9 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: •...

  • Page 10: Tcp Api Command Set

    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,...
  • Page 11 Table 1 – continued from previous page Command Description Response Example Return JSON-formatted sen- get_time_info timing configuration status times- "sync_pulse_in": { tamp, synce_pulse_in, "diagnostics": { synce_pulse_out. "count_unfiltered": 0, "last_period_nsec": 0, "count": "polarity": "ACTIVE_HIGH", "locked": "nmea": { "polarity": "ACTIVE_HIGH", "baud_rate": "BAUD_9600", "diagnostics": { "io_checks": { "bit_count": 1,...
  • Page 12 Table 1 – continued from previous page Command Description Response Example Returns JSON-formatted beam get_beam altitude and azimuth offsets, in _intrinsics 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 Returns JSON-formatted imu transformation matrix needed to _intrinsics adjust to the Sensor Coordinate...
  • Page 13 Table 1 – continued from previous page Command Description Response Example Returns JSON-formatted lidar get_lidar transformation matrix needed to _intrinsics adjust to the Sensor Coordinate "lidar_to_sensor_transform": [ Frame. 36.18, Returns JSON-formatted get_alerts alerts sensor get_sensor_info "alerts": [ ERROR. It has a buffer to hold {"cursor": 0, up to 8 errors sequentially.
  • Page 14 UNCONFIG- An error with factory calibration that requires a return. URED 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>...
  • Page 15 Table 2 – continued from previous page get_config_param Command Description Response nmea_leap_seconds Returns the number of leap seconds that will 0 (default) 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.
  • Page 16 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 set_config_param on suc- traffic.
  • Page 17 sync_pulse_out_polarity Set the polarity of SYNC_PULSE_OUT output, set_config_param on suc- <1/0> if sensor is set as the master sensor used for time cess, error: otherwise synchronization sync_pulse_out_frequency Set output SYNC_PULSE_OUT rate. Valid in- set_config_param on suc- <rate in Hz> puts are integers > 0 Hz, but also limited by the cess, error: otherwise criteria described in Section 5.3...

  • Page 18: Lidar Data Format

    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...

  • Page 19: Imu Data Format

    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)

  • Page 20: Lidar Intrinsic Beam Angles

    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.

  • Page 21: Lidar Range Data To Sensor Xyz Coordinate Frame

    Lidar data may be transformed into 3D cartesian ��, ��, �� coordinates in the lidar coordinate frame. Given: • encoder_count of the azimuth block • range from the data block of the i-th channel • beam_altitude_angles and • beam_azimuth_angles from get_beam_intrinsics in the TCP interface described in Section 3.3 the corresponding 3D point can be computed using: ��...

  • Page 22: Time Synchronization

    – Using the IEEE 1588 Precision Time Protocol. PTP provides the convenience of configuring timing over a network that supports IEEE 1588 with no additional hardware signals. Setting Ouster Sensor Time Source The source for measurement timestamps can be configured using the set_timestamp_mode TCP command (see Section 3.3).

  • Page 23: External Trigger Clock Source

    Command Response TIME_FROM_INTERNAL_OSC Use the internal clock. Measurements are time stamped with ns since power- on. Free running counter based on the OS-1’s internal oscillator. Counts seconds and nanoseconds since OS-1 turn on, reported at ns resolution (both a second and nanosecond register in every UDP packet), but min increment is on the order of 10 ns.
  • Page 24 Command Response Do not output a SYNC_PULSE_OUT signal. INPUT_FROM_NMEA_UART Reconifures the MULTIPURPOSE_IO port as an input. See Section 5.2 more information. OUT- Output a SYNC_PULSE_OUT signal synchronized with the internal clock. PUT_FROM_INTERNAL_OSC OUT- Output a SYNC_PULSE_OUT signal synchronized with a SYNC_PULSE_IN PUT_FROM_SYNC_PULSE_IN provided to the unit.

  • Page 25: Nmea Message Format

    5.4 NMEA Message Format The Ouster Sensor expects a standard NMEA $GPRMC UART message. Data (called a sentence) is a simple ASCII string starting with a ‘$’ character and ending with a return character. Fields of the sentence are separated with a ‘,’...

  • Page 26: Updating Firmware

    file as prompted. Always check your firmware version before attempting an update. Only update to a equal or higher version number. Do not roll back firmware to lower numbered versions without having been instructed to do so by Ouster deployment engineering.

  • Page 27: Troubleshooting

    • Home: Current page that lists some basic sensor information, and allows sensor firmware upgrade. • Diagnostics: Diagnostic information and system journal that can be downloaded and included when con- tacting Ouster for service. • Documentation: Sensor User Guide • Reset Configuration: Sensor factory configuration that can be reset to if desired. This will erase any custom configuration that you set on the sensor previously.

  • Page 28: Http Api Reference

    8 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. API Resources • system/firmware • system/network • system/time 8.1 system/firmware GET system/firmware /api/v1/system/network HTTP/1.1 Host: 192.0.2.123...
  • Page 29 (continued from previous page) "ipv4": { "addr": "192.0.2.123/24", "link_local": "169.254.245.183/16", "override": null "ipv6": { "fe80::be0f:a7ff:fe00:12c/64" "link_local": "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. •...
  • Page 30 GET system/network/ipv4/override Get the current IPv4 static IP address override. /api/v1/system/network/ipv4/override HTTP/1.1 Host: 192.0.2.123 HTTP/1.1 200 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.

  • Page 31: System/Time

    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 DHCP lease is obtained from a network DHCP server.
  • Page 32 (continued from previous page) "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, "time_traceable": "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": "sensor": { "nmea": { "baud_rate": "BAUD_9600", "diagnostics": {...
  • Page 33 (continued from previous page) "polarity": "ACTIVE_HIGH", "pulse_width_ms": "timestamp": { "mode": "TIME_FROM_INTERNAL_OSC", "time": 57178.44114677, "time_options": { "internal_osc": 57178, "ptp_1588": 1552413986, "sync_pulse_in": "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,...
  • Page 34 (continued from previous page) "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": Response JSON Object • monotonic (float) – Monotonic time of operating system. This timestamp never counts backwards and is the time since boot in seconds.
  • Page 35 HTTP/1.1 200 content-type: application/json; charset=UTF-8 "current_data_set": { "mean_path_delay": 30110, "offset_from_master": 224159, "steps_removed": "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": "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,...
  • Page 36 command. • parent_data_set (object) – Result of the PMC GET PARENT_DATA_SET com- mand. • port_data_set (object) – Result of the PMC GET PORT_DATA_SET command. • time_properties_data_set (object) – Result 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.
  • Page 37 (continued from previous page) "decoding": { "date_decoded_count": 0, "last_read_message": "", "not_valid_count": 0, "utc_decoded_count": "io_checks": { "bit_count": 1, "bit_count_unfilterd": 0, "char_count": 0, "start_char_count": "ignore_valid_char": 0, "leap_seconds": 0, "locked": 0, "polarity": "ACTIVE_HIGH" "sync_pulse_in": { "diagnostics": { "count": 1, "count_unfiltered": 0, "last_period_nsec": "locked": 0, "polarity": "ACTIVE_HIGH"...

  • Page 38: Ptp Quickstart Guide

    9.2 Physical Network Setup Ensure the Ouster sensor is connected to the PTP master clock with at most one network switch. Ideally the sensor should be connected directly to the PTP grandmaster. Alternatively, a simple layer-2 gigabit Ethernet switch will...

  • Page 39: Third Party Grandmaster Clock

    9.3 Third Party Grandmaster Clock A dedicated grandmaster clock should be used for the highest absolute accuracy often with a GPS receiver. It must be configured with the following parameters which match the linuxptp client defaults: • Transport: UDP IPv4 •...
  • Page 40 +---------------- | +--------------- + The focus is on configuring the Linux PTP service to serve a common clock to all the downstream Ouster OS-1 sensors using the Linux system time from the Ubuntu host machine. Optionally, a grandmaster clock can be added to discipline the system time of the Linux host.
  • Page 41 (continued from previous page) After this operation, 1,319 kB of additional disk space will be used. Get:1 http://us.archive.ubuntu.com/ubuntu bionic/main amd64 ethtool amd64 1:4.15- 0ubuntu1 [114 kB] Get:2 http://us.archive.ubuntu.com/ubuntu bionic/universe amd64 linuxptp amd64 1.8-1 [112 kB] Get:3 http://us.archive.ubuntu.com/ubuntu bionic-updates/main amd64 chrony amd64 3.2- 4ubuntu4.2 [203 kB] Fetched 430 kB in 1s (495 kB/s) Selecting previously unselected package ethtool.
  • Page 42 Modify /etc/linuxptp/ptp4l.conf and append the following, replacing eno1 and eno2 with the appropriate interface names: boundary_clock_jbod 1 [eno1] [eno2] The default systemd service file for Ubuntu 18.04 attempts to use the eth0 address on the command line. Override systemd service file so that the configuration file is used instead of hard coded in the service file. Create a systemd drop-in directory to override the system service file: sudo mkdir -p /etc/systemd/system/ptp4l.service.d Create a file at /etc/systemd/system/ptp4l.service.d/override.conf with the following contents:...
  • Page 43 128. #clockClass clockClass Restart ptp4l so the configuration change takes effect. sudo systemctl restart ptp4l This will configure ptp4l to advertise a master clock on eno2 as a clock that will win the BMCA for an Ouster OS-1 sensor.
  • Page 44 To synchronize the Linux system time to the the PTP hardware clock the phc2sys utility needs to be run. The following configuration will tell phc2sys to take the Linux CLOCK_REALTIME and write that time to the PTP hardware clock in the Ethernet controller for eno2. These interfaces are then connected to PTP slaves such as Ouster OS-1 sensors.
  • Page 45 (continued from previous page) [Install] WantedBy=multi-user.target Then start the newly created service and check that it started. sudo systemctl start phc2shm sudo systemctl status phc2shm Add the PTP time source to the chrony configuration which will read the shared memory region managed by the phc2shm service created above.

  • Page 46: Verifying Operation

    (continued from previous page) ^- io.crash-override.org +441us[ +441us] +/- 58ms ^- hadb2.smatwebdesign.com +1364us[+1364us] +/- 99ms Note that the Reference ID matches the ptp refid from the chrony.conf file and that the sources output shows the ptp reference id as selected (signified by the * state in the second column). Additionally, the NTP time sources show a small relative error to the high accuracy PTP time source.

  • Page 47: Tested Grandmaster Clocks

    (continued from previous page) offsetFromMaster 613554162.0 meanPathDelay 117977.0 bc0fa7.fffe.c48254-1 seq 2 RESPONSE MANAGEMENT PORT_DATA_SET portIdentity bc0fa7.fffe.c48254-1 portState LISTENING logMinDelayReqInterval peerMeanPathDelay logAnnounceInterval announceReceiptTimeout logSyncInterval delayMechanism logMinPdelayReqInterval 0 versionNumber bc0fa7.fffe.c48254-1 seq 3 RESPONSE MANAGEMENT TIME_STATUS_NP master_offset 613554162 ingress_time cumulativeScaledRateOffset +0.000000000 scaledLastGmPhaseChange gmTimeBaseIndicator lastGmPhaseChange 0x0000'0000000000000000.0000 gmPresent...

  • Page 48: Http Routing Table

    HTTP Routing Table /system GET system/firmware, GET system/network, GET system/network/ipv4, GET system/network/ipv4/override, GET system/time, GET system/time/ptp, GET system/time/sensor, GET system/time/system, PUT system/network/ipv4/override, DELETE system/network/ipv4/override,...

This manual is also suitable for:

Os-1-64

Table of Contents