package information
-------------------
Driver version is v0.12.0, built using 6.0.10.0 with DW SDK v5.20

requirements
------------
* DRIVEOS 5.20
* Additionally this package depends on `libcurl4-openssl-dev:arm64` for arm processor and `libcurl4-openssl-dev:amd64` for x86

device information
------------------
* Sensor Model: OS1-MAX-RGB
* Serial No: 992611000670
* FW version: v4.0.0-alpha

getting started
---------------
* To connect to a live sensor, first go through the included quick start guide.
Or refer to this page: https://static.ouster.dev/sensor-docs/image_route1/image_route2/connecting/connecting-to-sensors.html
for most up to date documentation.

IMPORTANT: When setting the sensor for the first time, make sure you choose Link-Local Only on the ethernet connection.

setting a static ip:
--------------------
To set the sensor to a static IP for a sensor execute the steps below in the terminal of the host machine, outside of docker
Note: You will need to set the static IP address only one time, the changes will persist even through power cycles.

- Step 1: Physical & Host Setup
Connect the Ouster sensor directly to your computer's Ethernet port or a dedicated switch.
Open your System Network Settings.
Locate the Wired Ethernet connection and set the IPv4 Method to Link-Local Only.
Apply the settings. Your computer will now assign itself an address in the 169.254.x.x range.

- Step 2: Locate the Sensor IP
We will use `avahi-browse` tool to query the sensor. If the tool is not found then install it via the command:
```
sudo apt install -y avahi-utils
```

Open a terminal and run:
```
avahi-browse -rt _ouster-lidar._tcp | grep address | awk -F'[][]' '{print $2}'
```

Your output should look like:
```
fe80::be0f:a7ff:fe00:c053
169.254.169.154
```

Select and copy the address 169.254.x.x

- Step 3: Set the Static IP via API
Replace [SENSOR_IP] with the address you copied and [DESIRED_IP/PREFIX] with your target static IP
```
curl -X PUT http://[SENSOR_IP]/api/v1/system/network/ipv4/override \
     -H "Content-Type: application/json" \
     --data-raw '"[DESIRED_IP/PREFIX]"'
```

Example command:
```
curl -X PUT http://169.254.10.20/api/v1/system/network/ipv4/override \
     -H "Content-Type: application/json" --data-raw '"10.10.0.1/24"'
```

Step 4: Persist and Reinitialize
For the changes to take effect, send the reinitialize command:
```
curl -X POST http://[SENSOR_IP]/api/v1/system/restart
```
Step 5: Finalize Host Settings
Return to your System Network Settings.
Change the IPv4 Method from "Link-Local" to Manual (Static).
Set your computer's IP to be on the same subnet as the sensor (e.g., if the sensor is 10.10.0.1, set your PC to 10.10.0.2 with mask 255.255.255.0).
Apply settings.

Complete guide on setting static ip can be found here: https://static.ouster.dev/sensor-docs/image_route1/image_route2/common_sections/API/http-api-v1.html#setting-static-ip

Once you have successfully verified is accessible from the NVIDIA DriveWorks kit, execute the following command:
```
SENSOR_ADDR=<sensor-ip-address>
HOST_ADDR=<destination-address> # optional
LIDAR_PORT=<lidar-port-value>   # optional (default is 7502)
IMU_PORT=<imu-port-value>       # optional (default is 7503)
ARCH=x86
PLUGIN_PATH=<path-to-plugin>/OS1-MAX-RGB/REV08/dwplugin_v0.12.0/driveworks_5.20/${ARCH}/libouster_lidar_plugin_${ARCH}.so
/usr/local/driveworks/bin/sample_lidar_replay \
    --protocol=lidar.custom  \
    --params=device="CUSTOM_EX",decoder-path="${PLUGIN_PATH}",ip=${SENSOR_ADDR},dip=${HOST_ADDR},lidar_port=${LIDAR_PORT},imu_port=${IMU_PORT}
```

where:
 - SENSOR_ADDR is the sensor hostname or ip address
 - HOST_ADDR is optional parameter that is used to specify the udp destination
 - ARCH should be set either 'x86' or 'arm' based on the computer architecture
 - PLUGIN_PATH is the path to decorder included in the drver
 - LIDAR_PORT is an optional parameter when not specified the plugin assumes the default port (7502) is used.
 - IMU_PORT is an optional parameter when not specified the plugin assumes the default port (7503) is used.

For example, if we are connect to the sensor with the hostname: `os-992611000670.local`, if the sensor
hostname is known to the machine in use then we use it to connect to the sensor, otherwise we obtain
the ip address of the sensor using ping let's assume it 192.168.1.19 then assuming the sensor is configured
with default lidar and imu port values we connect to it as follows:
```
SENSOR_ADDR=192.168.1.19
PLUGIN_PATH=<path-to-plugin>/OS1-MAX-RGB/REV08/dwplugin_v0.12.0/driveworks_5.20/x86/libouster_lidar_plugin_x86.so
/usr/local/driveworks/bin/sample_lidar_replay \
    --protocol=lidar.custom  \
    --params=device="CUSTOM_EX",decoder-path="${PLUGIN_PATH}",ip=${SENSOR_ADDR}
```

> **Note: The lidar port and the imu port are ports on the client device that the sensor will forward lidar data and imu data
to. To use lidar or imu port values other that is different form the default, you will need to access the sensor config page as
indicated in the quickstart guide, update the port values of either or both, then save the config (consider persisting these
values if necessary), then pass the new port values to the plugin launch command using `lidar_port` and `imu_port` params shown
earlier**.

* To replay an existing capture:
```
BIN_FILE=<path-to-bin-file>
ARCH=x86
PLUGIN_PATH=<path-to-plugin>/OS1-MAX-RGB/REV08/dwplugin_v0.12.0/driveworks_5.20/${ARCH}/libouster_lidar_plugin_${ARCH}.so
/usr/local/driveworks/bin/sample_lidar_replay \
    --protocol=lidar.virtual \
    --params=device="CUSTOM_EX",decoder-path="${PLUGIN_PATH}",file="${BIN_FILE}"
```

where:
 - BIN_FILE is the path to the bin to be played by the plugin
 - ARCH should be set either 'x86' or 'arm' based on the computer architecture
 - PLUGIN_PATH is the path to decorder included in the drver

For example, to replay the included `992611000670.bin` under `captures` folder, simply set the path to the bin file
and execute the `sample_lidar_replay` app as shown below:
```
BIN_FILE=<path-to-capture>/captures/992611000670.bin
ARCH=x86
PLUGIN_PATH=<path-to-plugin>/OS1-MAX-RGB/REV08/dwplugin_v0.12.0/driveworks_5.20/${ARCH}/libouster_lidar_plugin_${ARCH}.so
/usr/local/driveworks/bin/sample_lidar_replay \
    --protocol=lidar.virtual \
    --params=device="CUSTOM_EX",decoder-path="${PLUGIN_PATH}",file="${BIN_FILE}"
```

* To make a new capture create a rig file that for the recorder and add the following:
```
{
    "rig": {
        "sensors": [
            {
                "name": "<SESSION_ID>",
                "nominalSensor2Rig_FLU": {
                    "roll-pitch-yaw": [
                        0.0,
                        0.0,
                        0.0
                    ],
                    "t": [
                        0.0,
                        0.0,
                        0.0
                    ]
                },
                "parameter": "device=CUSTOM_EX,decoder-path=<PLUGIN_PATH>,ip=<SENSOR_ADDR>,dip=<HOST_ADDR>,session_id=<SESSION_ID>",
                "properties": null,
                "protocol": "lidar.custom"
            },
        ],
        "vehicle" : {...}
    },
    "version": 2
}
```

Replace the following with approprite values:
 - SESSION_ID is a name that will be used when saving the file
 - PLUGIN_PATH: path to the plugin shared object (i.e the path to `libouster_lidar_plugin_x86.so` or `libouster_lidar_plugin_arm.so`)
 - SENSOR_ADDR: sensor ip or hostname
 - HOST_ADDR: destination ip address (optional)

Then save the rig file and launch the recorder application
```
/usr/local/driveworks/tools/capture/recorder ${SESSION_ID}_ouster_lidar_rig.json
```

Once the driver connects to the sensor press `s` followed by <enter> to start
recording, wait for the period you intend to capture then press `q` followed by
<enter> to stop the capture. Once the script exits a new recording will be saved
to the `captures` folder using the provided <SESSION_ID>

viewing pcap file
-----------------
* First install the latest ouster-sdk using `pip install ouster-sdk`
* Find the included `992611000670.pcap` sample file under `captures` and execute the command:
```
ouster-cli source 992611000670.pcap viz
```
A new window should pop up showing the lidar pcap replay. 

Refer to documentation/README.md for additional information
