Yes. Full support for Python (Python 3.6 or later) and Python specific APIs are part of our SDK release.

Yes. Javascript bindings to SDK is currently in pre-release beta, available upon request.

Yes. C# bindings to SDK is currently in pre-release beta, available upon request.

Yes. Ruby bindings to SDK is currently in pre-release beta, available upon request.

Yes. Full support for MATLAB with MATLAB specific APIs are part of our SDK release.

Cepton has an experimental implementation for RTMaps middleware for current Cepton devices. Please contact our business development team for more information.

Cepton ROS drivers are supported on ROS Melodic and Noetic, and ROS2 Foxy, Galactic, and Humble.

Cepton currently does not support the Apollo platform.

Cepton currently does not support the Autoware platform.

Cepton supports NVIDIA Driveworks. Contact software support for more information.

Live data can be captured in several ways 1. with Wireshark 2. with SDK tools 3. with the capturing functionalities in CeptonViewer (which uses the SDK). The captured data usually are created in .pcap format and could be replayed by CeptonViewer.

We will make data samples available for most current sensors. Please check back the SDK page for updates.

Please use the cepton_exporter tool provided in the SDK package to convert PCAP files to CSV.

By default Cepton lidars are plug and play. There is no need to configure your local networking except for making sure the firewall is disabled for CeptonViewer or your application using SDK.

SDK2 is not compatible with SDK1. Changes needed to migrate existing SDK1 code to SDK2 are usually straight-forward. Cepton application engineers will be happy to help with the migration effort if needed. For more details, please check out <a href="/blog/future_proof_cepton_lidar_applications_sdk">Future-proof Cepton lidar applications with SDK v2</a>

# Overview
Cepton’s lidar sensors send out two kinds of packet on a regular basis: Point Data Packet and INFO Data Packet. Please refer [Data Format](https://developer.cepton.com/doc/data_format) for detailed structure information. Chapter 2 in this document outlines the implementation of Precision Time Protocol (PTP) in Cepton’s products to illustrate the generation of critical PTP related values reported in those two kinds of packets. These values are mainly used for displaying real-time system information, or run-time self-monitoring and diagnostic. Chapter 3 gives an example of how to use those reported values to calculate universal PTP timestamp for each point. Chapter 2 is for your better understanding, but you can skip this Chapter and directly refer to chapter 3 for usage only. 

# Reported Value Generation 
## Clock adjustment
Each slave clock maintains a local counter calculating the number of microseconds (us) since the sensor last booted up. When connection with PTP master clock becomes active, the clock adjustments shall perform synchronization and syntonization. Therefore, the universal PTP timestamp calculation is generally composed of three parts: 
<center>

$ptp\_timestamp = local\_counter + synchronization\_correction + syntonization\_correction$

</center>

Synchronization eliminates the offset between slave’s counter and master’s clock. Syntonization matches the frequency of local clock to that of the Grandmaster Clock in the domain, which is measured by the slave's counter increases every drift interval, it is one nanosecond slower than the master's clock. Thus, the formula becomes more concrete: 
<center>

$ptp\_timestamp = local\_counter + master\_slave\_offset + \frac{local\_counter\_increase}{drift\_interval}$

</center>

Clock adjustments are carried out through a sequence of PTP timing messages exchange between upstream PTP Instance and local slave. The basic message exchange pattern is illustrated in IEEE Std 1588-2019 Figure 16 as shown below : 

 <img width="460" src="/images/ptp/message_exchange.png">
 

(a) The Master PTP Instance sends a Sync message to the Slave PTP Instance and notes the time `t1` at which it was sent. The timestamp `t1` can be embedded in the `Sync` message or in a `Follow_Up` message. 

(b) The Slave PTP Instance receives the `Sync` message and notes the time of reception `t2`. 

(c) The Slave PTP Instance sends a `Delay_Req` message to the Master PTP Instance and notes the time `t3` at which it was sent. 

(d) The Master PTP Instance receives the `Delay_Req` message and notes the time of reception `t4`. The Master PTP Instance conveys to the Slave PTP Instance the timestamp `t4` by embedding it in a `Delay_Resp` message or in a `Delay_Resp_Follow_Up` message.

The message exchange pattern illustrated in 2.1 is repeated contiguously to maintain latest `master_slave_offset` and `drift_interval`, which will be explained in 2.2 and 2.3 independently.

## Update `master_slave_offset` 
Say master sends a message to the slave at PTP time `m1`, after a communication link propagation delay `d`, the slave receives message at its local counter time `c1`, then the offset currently equals to: $Δ1 = c1 - (m1+d)$. The link propagation delay is required for updating the offset. Assuming symmetric link, that link delay is a mean of tms
 and tsm. However, (t1, t4) and (t2, t3) follows different time metrics, therefore, the delay is calculated by: 
<center>

$d = \frac{{(t_2 - t_1) + (t_4 - t_3)}}{2} = \frac{{(t_2 - t_3) + (t_4 - t_1)}}{2}$

</center>

Initially, it’s set to zero. 

Since link delay can only be updated every time a complete group of $<t1, t2, t3, t4>$ is obtained, the newest offset is calculated based on the last group of $<t1, t2, t3, t4>$.

## Update `drift_interval`
Differentiate from offset, which depends only on the last group of message exchange, The drift_interval that will be reported is an accumulated value, which is updated every time a new pair of (t1, t2) is recorded. As mentioned in 2.1, the slave's counter increases every drift interval, it becomes one nanosecond slower or faster than the master's clock. According to this, what is being maintained is drift_interval, but what is being added to timestamp calculation is: $\frac{local\_counter\_increase}{drift\_interval}$.
The `drift_interval` represents a time range of counter in nanosecond unit and is updated as follows: 
<center>

$drift\_interval = \frac{counter\_range}{master\_range - counter\_range}$

</center>

where:

<center>

$master\_range = current\_master\_arrival\_timestamp - last\_master\_arrival\_timestamp$

$counter\_range = current\_counter\_ns - last\_counter\_ns$

</center>

The drift_interval can be a positive value or negative value: 

 - when drift_interval is positive, it means counter timestamp is increasing slower than master clock; 

 - when drift_interval is negative, it means counter timestamp is increasing faster than master clock; 

 - when drift_interval is zero, which means counter timestamp is increasing in the same speed as master clock, syntonization_correction will also be zero.
 
## Report PTP relevant values 
Recall the PTP timestamp calculation formula: 

<center>

$ptp\_timestamp = local\_counter + master\_slave\_offset + \frac{local\_counter\_increase}{drift\_interval}$

</center>

We have explained the generation of master_slave_offset in 2.2 and the generation of drift_interval in 2.3. The local_counter is the slave’s internal non-decreasing counter timestamp (currently using emac system time, in us unit). The value counts the time interval between the moment of power-up (emac power-up) to the moment of INFO packet sent-out. 

Cepton’s lidar sensors send out two kinds of packet on a regular basis: Point Data Packet and INFO Data Packet. 

In INFO packet header, there are three fields containing PTP related information, which are filled in the local_counter value, master_slave_offset value, and drift_interval value correspondingly: 
| Field Name | Unit | 
|-------------------------|--------|
| time_since_powerup | us |
| time_offset_from_master | us | 
| time_drift_correction | per ns | 

In Point Data Packet’s payload, each point has a relative_timestamp field that holds the relative counter value from the time since last point in the packet. For the very first point, it is time since the packet header's reference time. 

# PTP Usage Example
The Cepton SDK usage is almost all about using Callback APIs, please refer [SDK Guide](https://developer.cepton.com/doc/sdk_guide) for more information. Here, only point’s PTP timestamp calculation relevant part will be explained. 

The master_slave_offset and drift_interval is only reported in INFO packet, therefore, to calculate following points’ timestamp, a local copy of previous INFO packet information is needed, the callback looks like this: 

```c
int64_t last_info_offset = 0;
int64_t last_info_drift = 0; 
int64_t last_info_counter = 0; 

void infoCallback(CeptonSensorHandle handle, 
 const struct CeptonSensor *info, void *user_data) {
 last_info_counter = info->power_up_timestamp; 
 last_info_offset = info->time_sync_offset; 
 last_info_drift = info->time_sync_drift; 
} 
```
Since the calculation is based on previous INFO packet, the local counter increase in the formula becomes the time difference between each point’s counter and the counter timestamp when the previous INFO packet is sent out. Therefore, the power_up_timestamp in INFO packet must also be recorded. 

Each point’s counter timestamp calculation is a litter bit confusing. Recall that each point has a relative_timestamp field that holds the relative counter value from the time since last point in the packet. For the very first point, it is time since the packet header's reference time. Here is how you can get each point’s counter value: 

```c
int64_t prev_point_counter = 0; 

void pointCallback(CeptonSensorHandle handle,
 int64_t start_timestamp, size_t n_points,
 size_t stride, const uint8_t *points,
 void *user_data){
 prev_point_counter = start_timestamp; 
 for (size_t i = 0; i < n_points; i++) { 
 struct CeptonPoint point = *(struct CeptonPoint const*)(points + i * stride); 
 int64_t point_counter = prev_point_counter + (int64_t)point.relative_timestamp; 
 prev_point_counter = point_counter; 
 } 
}
```

Based on above obtained value and formula, each point’s timestamp can be calculated as: 
```c
#include <stdio.h>
int64_t drift_correction = (last_info_drift==0) ? 0 :
 (point_counter - last_info_counter)*1000 / last_info_drift; 
printf("calculated point PTP timestamp(ns): %lld \n", 
 (last_info_counter - last_info_offset)*1000 + drift_correction 
); 
```
Pay attention to the unit conversion. 

Finnally, a complete sample code for your reference: 

```c
#include <stdio.h>
#include <stdlib.h>

#include "cepton_sdk2.h"

void check_api_error(int err, char const *api) {
 if (err != CEPTON_SUCCESS) {
 printf("API Error for %s: %s\n", api, CeptonGetErrorCodeName(err));
 exit(1);
 }
}

void sensorErrorCallback(CeptonSensorHandle handle, int error_code,
 const char *error_msg, const void *error_data,
 size_t error_data_size) {
 printf("Got error: %s\n", error_msg);
}

int n_info = 0;

//(per ns)
int64_t last_info_drift = 0; 
//(1us)
int64_t last_info_counter = 0; 
int64_t last_info_offset = 0;
int64_t prev_point_counter = 0;

void infoCallback(CeptonSensorHandle handle, 
 const struct CeptonSensor *info, void *user_data) {
 printf("Got %d info:", ++n_info);
 printf("ts_info_counter: %lld ts_offset: %lld ts_drift: %lld\n", 
 info->power_up_timestamp, 
 info->time_sync_offset,
 info->time_sync_drift
 );
 last_info_counter = info->power_up_timestamp;
 last_info_offset = info->time_sync_offset;
 last_info_drift = info->time_sync_drift;
 
}

void pointCallback(CeptonSensorHandle handle,
 int64_t start_timestamp, size_t n_points,
 size_t stride, const uint8_t *points,
 void *user_data){
 prev_point_counter = start_timestamp;
 for (size_t i = 0; i < n_points; i++) {
 struct CeptonPoint point = *(struct CeptonPoint const*)(points + i * stride);
 int64_t point_counter = prev_point_counter + (int64_t)point.relative_timestamp; 
 if (i == 0 || i == n_points-1) {
 printf("the raw counter(us) of point %d is: %lld\n", (int)i, point_counter);
 int64_t drift_correction = (last_info_drift==0) ? 0 : (point_counter - last_info_counter)*1000 / last_info_drift;
 printf("calculated point PTP timestamp(ns): %lld \n", 
 (last_info_counter - last_info_offset)*1000 + drift_correction 
 );//temporary - offset
 
 }
 prev_point_counter = point_counter;
 }
}

int main() {
 int ret;

 // Initialize
 ret = CeptonInitialize(CEPTON_API_VERSION, sensorErrorCallback);
 check_api_error(ret, "CeptonInitialize");

 ret = CeptonEnableLegacyTranslation();
 check_api_error(ret, "EnableLegacyTranslation");

 // Start networking listener thread
 ret = CeptonStartNetworking();
 check_api_error(ret, "CeptonStartNetworking");

 // Listen for points
 ret = CeptonListenPoints(pointCallback, 0);
 check_api_error(ret, "CeptonListenPoints");

 // Listen for info
 ret = CeptonListenSensorInfo(infoCallback, 0);
 check_api_error(ret, "CeptonListenSensorInfo");
 
 // Sleep
 while (n_info < 10)
 ;

 // Deinitialize
 ret = CeptonDeinitialize();
 check_api_error(ret, "CeptonDeinitialize");
 return 0;
}
```
This example prints the counter, offset and drift in each INFO packet, and the raw counter and calculated timestamp of the first and last points in each Point Data packet, feel free to modify the output to best fulfil your requirement.

PTP Implementation and Point Timestamp Calculation

**tl;dr** Please use Cepton SDK v2 to write your lidar applications even if you are working with Vista-P series products.

Since the very beginning of the company's history, Cepton has been releasing lidar sensors every few months. Over the last 4-5 years, we have released HR80 series (5T, W, 4T), Sora series, Vista-P series (860, P60, P90, P61, P91), and now Vista-X series (X90) and Nova. It has been our goal from day one that the software should work across all lidar sensors without API changes. With this goal in mind, we released [Cepton SDK v1](https://github.com/ceptontech/cepton_sdk_redist) in 2017. The SDKv1 supports all Cepton sensors up to Vista-P series.

In 2020, to support Vista-X series sensors, we have released an all new SDKv2 (SDKv2 will be available for download at developer.cepton.com). SDKv2 is a new SDK with a modular design to facilitate easier integration with all the 3rd party frameworks. Another goal is to be free of legacy proprietary code so that we can open source the SDK in the near future. Although different in API interfaces, SDKv2 has full support for all our old sensor products through a `LegacyTranslation` mode. We still fully support SDKv1 for our earlier generations of sensors, but we ask all new developers to use SDKv2 to be future proofed and better supported by us.

Comparison between SDKv2 and SDKv1 features:

| | SDKv2 | SDKv1 |
| ------------------------ | ----- | ----- |
| Support Vista-X and Nova | Yes | No |
| Support Vista-P and Sora | Yes | Yes |
| Modular Design | Yes | No |
| Advanced Capture Replay | Yes | No |
| Open Source | Yes* | No |

(*Source code of SDKv2 will be provided in the near future)

Comparison between these two styles of SDKs (both extracted from cepton_exporter sample app):

SDKv2:
```cpp
int InitializeSDK() {
 int err;
 err = CeptonInitialize(CEPTON_API_VERSION, CbCeptonSensorError);
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonInitialize", true);
 sdk_initialized = true;

 // Enable legacy
 CeptonEnableLegacyTranslation();

 // Listen to point data
 if (streaming) {
 err = CeptonListenPoints(CbCeptonSensorImageData, nullptr);
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonListenPoints", true);
 } else {
 err = CeptonListenFrames(aggregation_mode, CbCeptonSensorImageData, nullptr);
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonListenFrames", true);
 }

 // Listen to sensor detection
 CeptonListenSensorInfo(CbCeptonSensorInfo, nullptr);

 if (!capture_file.empty()) {
 err = CeptonReplayLoadPcap(capture_file.c_str(), 0, &capture_handle);
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonReplayLoadPcap", true);
 err = CeptonReplaySetSpeed(capture_handle, 0); // No delay replay
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonReplaySetSpeed", true);
 err = CeptonReplayPlay(capture_handle);
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonStartReplay", true);
 } else {
 err = CeptonStartNetworking();
 if (err != CEPTON_SUCCESS) ReportError(err, "CeptonStartNetworking", true);
 }
 return 0;
}
```

SDKv1:
```cpp
int InitializeSDK() {
 CeptonSensorErrorCode err;
 CeptonSDKOptions opts = cepton_sdk_create_options();
 if (streaming) {
 opts.frame.mode = CEPTON_SDK_FRAME_STREAMING;
 } else {
 // Use cover mode as the default mode
 opts.frame.mode = CEPTON_SDK_FRAME_COVER;
 }

 if (!capture_file.empty())
 opts.control_flags |= CEPTON_SDK_CONTROL_DISABLE_NETWORK;
 err = cepton_sdk_initialize(CEPTON_SDK_VERSION, &opts, CbCeptonSensorError,
 nullptr);
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "initialize");
 return -1;
 }

 if (!capture_file.empty()) {
 // attempt to discover the sensors in the pcap
 err = cepton_sdk_capture_replay_open(capture_file.c_str());
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "load capture");
 return -1;
 }
 err = cepton_sdk_capture_replay_set_speed(0);
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "set replay speed");
 return -1;
 }
 err = cepton_sdk_capture_replay_resume_blocking(2.0f);
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "pre-replay");
 return -1;
 }
 err = cepton_sdk_capture_replay_seek(0);
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "rewind");
 return -1;
 }
 }

 err = cepton_sdk_listen_image_frames(CbCeptonSensorImageData, nullptr);
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "listen frames");
 return -1;
 }

 if (!capture_file.empty()) {
 err = cepton_sdk_capture_replay_resume();
 if (err != CEPTON_SUCCESS) {
 ReportError(err, "load capture");
 return -1;
 }
 }

 return 0;
}
```

For more information, please visit [SDKv2 page](https://developer.cepton.com/sdk)

Future-proof Cepton lidar applications with SDK v2

Cepton Sensor Communication Specifications

Migrate SDK v1 to SDK v2: A Quick Guide

Software Development Kit

Download Cepton SDK

Documentations

Related pages

Blogs

Videos

FAQs

Join Our Team