308 lines
9.8 KiB
C
308 lines
9.8 KiB
C
/*
|
|
Copyright 2025 Manifold Tech Ltd.(www.manifoldtech.com.co)
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
*/
|
|
#ifndef LIDAR_API_H
|
|
#define LIDAR_API_H
|
|
|
|
/**
|
|
* @file lidar_api.h
|
|
* @brief LiDAR device API for controlling and accessing LiDAR sensor data
|
|
*
|
|
* This header provides the public interface for interacting with LiDAR devices.
|
|
* It includes functions for device management, data streaming control, and
|
|
* device configuration.
|
|
*
|
|
* @copyright Copyright (c) 2025, Manifold Tech Limited, All Rights Reserved
|
|
* @version 1.0
|
|
*/
|
|
|
|
#include "lidar_api_type.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @brief Initialize the LiDAR system
|
|
*
|
|
* Must be called before any other lidar function to set up the system resources.
|
|
*
|
|
* @param cb Callback function for device events (connection, disconnection)
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_system_init(lidar_device_callback_t cb);
|
|
|
|
/**
|
|
* @brief Deinitialize the LiDAR system
|
|
*
|
|
* Releases all resources allocated by the system. Should be called when
|
|
* application is shutting down.
|
|
*
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_system_deinit(void);
|
|
|
|
/**
|
|
* @brief Create a handle for a LiDAR device
|
|
*
|
|
* @param dev_info Information about the LiDAR device to create
|
|
* @param device Pointer to receive the device handle upon success
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_create_device(lidar_device_info_t *dev_info, device_handle *device);
|
|
|
|
/**
|
|
* @brief Destroy a LiDAR device handle
|
|
*
|
|
* Releases resources associated with the device handle. Must be called
|
|
* when the device is no longer needed.
|
|
*
|
|
* @param device Handle to the device to destroy
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_destory_device(device_handle device);
|
|
|
|
/**
|
|
* @brief Register callback function for receiving LiDAR data streams
|
|
*
|
|
* Sets up a callback function that will be called when new data is available.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param cb Callback information containing function pointers for different data types
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_register_stream_callback(device_handle device, lidar_data_callback_info_t cb);
|
|
|
|
/**
|
|
* @brief Unregister stream callback for a device
|
|
*
|
|
* Stops the device from calling back when new data is available.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_unregister_stream_callback(device_handle device);
|
|
|
|
/**
|
|
* @brief Open a LiDAR device for communication
|
|
*
|
|
* Establishes a connection to the physical device.
|
|
*
|
|
* @param device Handle to the device to open
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_open_device(device_handle device);
|
|
|
|
/**
|
|
* @brief Close a LiDAR device
|
|
*
|
|
* Closes the connection to the physical device.
|
|
*
|
|
* @param device Handle to the device to close
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_close_device(device_handle device);
|
|
|
|
/**
|
|
* @brief Set the operating mode of the LiDAR device
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param mode Operating mode to set (see mode definitions in lidar_api_type.h)
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_set_mode(device_handle device, int mode);
|
|
|
|
/**
|
|
* @brief Start data streaming from the device
|
|
*
|
|
* Begins the flow of data from the device for the specified type.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param type Type of data stream to start (see stream type definitions in lidar_api_type.h)
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_start_stream(device_handle device, int type, uint32_t &dtof_subframe_odr);
|
|
|
|
/**
|
|
* @brief Stop data streaming from the device
|
|
*
|
|
* Stops the flow of data from the device for the specified type.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param type Type of data stream to stop
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_stop_stream(device_handle device, int type);
|
|
|
|
/**
|
|
* @brief Activate a specific stream type on the device
|
|
*
|
|
* Enables a specific data stream type in the device configuration.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param type Type of data stream to activate
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_activate_stream_type(device_handle device, int type);
|
|
|
|
/**
|
|
* @brief Deactivate a specific stream type on the device
|
|
*
|
|
* Disables a specific data stream type in the device configuration.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param type Type of data stream to deactivate
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_deactivate_stream_type(device_handle device, int type);
|
|
|
|
/**
|
|
* @brief Get calibration file from the device
|
|
*
|
|
* Retrieves the calibration file from the device.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param path Path to save the calibration file
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_get_calib_file(device_handle device, const char* path);
|
|
|
|
/**
|
|
* @brief Set log verbosity level
|
|
*
|
|
* Controls the amount of log information generated by the LiDAR API.
|
|
*
|
|
* @param level Log level to set (see level definitions in lidar_api_type.h)
|
|
*/
|
|
void lidar_log_set_level(lidar_log_level_e level);
|
|
|
|
/**
|
|
* @brief Get the version information of the LiDAR device
|
|
*
|
|
* Retrieves version information including firmware, system, and application versions.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param version struct Pointer to receive the version information
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_get_version(device_handle device,lidar_fireware_version_t *version);
|
|
|
|
/**
|
|
* @brief Set custom algorithm parameters for the device
|
|
*
|
|
* Sends custom parameter settings to the device.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param param_name String name of the parameter to set
|
|
* @param value_data Pointer to the value data to set for the parameter
|
|
* @param value_length Length of the value data in bytes
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_set_custom_parameter(device_handle device, const char* param_name, const void* value_data, size_t value_length);
|
|
|
|
/**
|
|
* @brief Get custom algorithm parameters for the device
|
|
*
|
|
* Get custom parameter settings from the device.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param param_name String name of the parameter to get
|
|
* @param value Integer value to get for the parameter
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_get_custom_parameter(device_handle device, const char* param_name, int* value);
|
|
|
|
/**
|
|
* @brief Set the map file used for relocalization
|
|
*
|
|
* Read & send specified map file to device for relocalization
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param abs_path Absolute path to the map file
|
|
* @return int 0 on success, otherwise on failure
|
|
*/
|
|
int lidar_set_relocalization_map(device_handle device, const char* abs_path);
|
|
|
|
/**
|
|
* @brief Get the mapping result file from device
|
|
*
|
|
* Read & send specified map file from device to host
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param dest_dir Destination directory to save the map file
|
|
* @param file_name File name to save the map file
|
|
* @return int 0 on success, -1 on failure without error code, error code (> 0) otherwise
|
|
*/
|
|
int lidar_get_mapping_result(device_handle device, const char* dest_dir, const char* file_name);
|
|
|
|
/**
|
|
* @brief Set the image mask file for the device
|
|
*
|
|
* Read & send specified image mask file to device
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param abs_path Absolute path to the image mask file (e.g., mask.png)
|
|
* @return int 0 on success, -1 on failure, -2 if file transfer in progress
|
|
*/
|
|
int lidar_set_image_mask(device_handle device, const char* abs_path);
|
|
|
|
|
|
/**
|
|
* @brief enable device log
|
|
*
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param dest_dir Destination directory to save the logs
|
|
* @return int 0 on success, -1 on failure
|
|
*/
|
|
int lidar_enable_encrypted_device_log(device_handle device, const char* dest_dir);
|
|
|
|
|
|
/**
|
|
* @brief Set the depth parameters for the device
|
|
*
|
|
* This function must be called before starting data stream.
|
|
*
|
|
* @param device Handle to the target device
|
|
* @param params Pointer to the depth parameters to set
|
|
* @return int 0 on success, negative error code on failure
|
|
*/
|
|
int lidar_set_depth_parameter(device_handle device, const lidar_depth_para_t *params);
|
|
|
|
/**
|
|
* @brief Enable or disable IMU smooth sending feature
|
|
*
|
|
* When enabled, IMU data will be sent at precise intervals (default 400Hz)
|
|
* using a dedicated high-priority thread to reduce jitter and timing variance.
|
|
* When disabled, IMU data will be sent immediately upon reception.
|
|
*
|
|
* @param enable 1 to enable smooth sending, 0 to disable
|
|
* @return int 0 on success, -1 on failure
|
|
*/
|
|
int lidar_enable_imu_smooth_sending(int enable);
|
|
|
|
/**
|
|
* @brief Set IMU smooth sending frequency
|
|
*
|
|
* Set the target frequency for IMU smooth sending. Only effective when
|
|
* smooth sending is enabled via lidar_enable_imu_smooth_sending().
|
|
*
|
|
* @param frequency_hz Target frequency in Hz (1-1000 Hz, recommended 400 Hz)
|
|
* @return int 0 on success, -1 on failure
|
|
*/
|
|
int lidar_set_imu_smooth_frequency(uint32_t frequency_hz);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif // LIDAR_API_H
|