HPS-3D160 Solid-state Depth camera SDK manual
目录 1. SDK introduction ...................................................................................................................... - 4 2. Integrate SDK into IDE .............................................................................................................. - 4 2.1 Environment configuration and integration into the IDE under Linux platform ............. - 4 2.1.1 HPS3D160 device connection .............................................................................. - 4 2.1.
.9 Get current device support ROI number and threshold number ................................. - 40 3.9.1 Sample code ...................................................................................................... - 40 3.9.2 Running result ................................................................................................... - 40 3.10 Set/ Get output/ input settings .................................................................................. - 41 3.10.1 Sample code ..............
1. SDK introduction The SDK provides the application interface of the HPS3D160 Solid-State Depth camera, which is currently available on the Linux platform, the Windows platform, the ROS platform, and most of the microcontrollers that do not run the operating system; the SDK is a secondary development kit tool, and the interface provided includes Most of the operating instructions of the HPS3D160 SolidState Depth camera developed by our company, please read this manual carefully; 2.
2.1.2 Engineering environment configuration and integration In ubuntu eclipse build project (other IDE tools are available), here eclipse as an example, after the following configuration, click finish to complete the project. Copy the api.h and libhps3d.
Open the terminal, type sudo cp libhps3d.so /usr/local/lib/, copy libhps3d.so to the /usr/local/lib/ directory; then execute sudo ldconfig to load it. After writing the test code in main.c, type: gcc main.c -L./ -lhps3d -o app in the terminal, compile the connection, and then use sudo ./app to execute the program. Select the connectable device. After the initialization is successful, the measurement result can be output normally: 2.1.3 Use SDK in user project 1.
HPS3D_HandleTypeDef handle; RET_StatusTypeDef ret = RET_OK; ret = HPS3D_Connect(&handle); if(RET_OK != ret) { printf("Connect Failed！ ret = %d\n",ret); break; } 3.
②RUN_SINGLE_SHOT: Single measurement mode, in which the camera takes a measurement and then automatically switches to RUN_IDLE. There are two ways to measure, one is synchronous measurement and the other is asynchronous measurement (default is asynchronous).
\n",event->MeasureData.full_depth_data->distance_average); break; case SIMPLE_DEPTH_PACKET: break; case NULL_PACKET: break; default: printf("system error\n"); break; } } return 0; } ③Observer initialization ,code is as follow: /*Observer initialization*/ AsyncIObserver_t My_Observer; /*Define observer */ /*An observer subscribes to an event as a data receive event*/ My_Observer.AsyncEvent = ISubject_Event_DataRecvd; My_Observer.
roi_conf.left_top_x = 10; roi_conf.left_top_y = 10; roi_conf.right_bottom_x = 30; roi_conf.right_bottom_y = 20; HPS3D_SetROIRegion(&handle, roi_conf); HPS3D_SetROIEnable(&handle, roi_conf.roi_id, true); (3) To configure the point cloud data output, you need to call the optical parameter enable function HPS3D_SetOpticalEnable and the function HPS3D_SetPointCloudEn to enable point cloud data output before setting the running mode.
2.2 Integrate SDK Lite into IDE SDK Lite provides a lightweight application interface for the HPS3D160 Depth camera. It is suitable for most microcontroller platforms without running the operating system. In view of the differences in various MCU platforms, a source-level SDK is provided, so it needs to be integrated into the user's project. The source code is compiled. SDK Lite is a lightweight secondary development package that provides only the basic operation interface.
Above pic is 3DToF_SDK_Lite_Test, the project’s root directory - 12 -
2.2.
2.2.3 Port to the user’s platform SDK Lite only supports HPS3D160 Depth camera with RS232 and RS485, due to the differences between platforms, bottom layer such as communication interfaces need to be ported 1、 Edit HPS3DToFSDKLite/src/hal.c file 2、 Adapt Uart_Read and Uart_Write interfaces is fine，Take an example based on HAL library STM32 platform 2.2.4 Use SDK in user’s project 1. The source file includes head file, sample code： #include "HPS3DToFSDKLite/inc/api.h" 2.
2) RUN_SINGLE_SHOT: Single measurement mode. After setting this mode, the camera takes a measurement and then automatically switches to RUN_IDLE. 3) RUN_CONTINUOUS: Continuous measurement mode. After setting this mode, the camera will automatically make continuous measurement until the user manually sets it to RUN_IDLE or RUN_SINGLE_SHOT mode. In this mode, the data will continuously output measurement data through RS485 or RS232. 2. The serial port receives the measurement data packet.
implementation of the mechanism needs to open the serial port interrupt. The serial port buffers the data into the FIFO every time the serial port generates the receiving interrupt. The main program only needs to check and judge the data length of the FIFO, and can fully utilize the waiting time of the mode 1), which has higher Time utilization, but at the expense of space utilization.
2.3 Integrate SDK to IDE under Windows platform Xxx.dll is suitable for use on the Windows operating system platform. Here is an example of eclipse under Windows. This example is written based on the SDK with API version number 2018.12.08 V1.0.0. 2.3.1 Add xxx.dll dynamic link library and api.h head files to the project The xxx.dll dynamic link library file can also be placed under other paths, and the absolute path can be filled when called; 2.3.
RET_StatusTypeDef(*ConfigInit)(HPS3D_HandleTypeDef *handle) = NULL; RET_StatusTypeDef (*AddObserver)(void * (*fun)(HPS3D_HandleTypeDef *, AsyncIObserver_t *), HPS3D_HandleTypeDef *handle, AsyncIObserver_t *Observer_t) = NULL; RET_StatusTypeDef(*SetRunMode)(HPS3D_HandleTypeDef *handle) = NULL; RET_StatusTypeDef(*RemoveDevice)(HPS3D_HandleTypeDef *handle) = NULL; RET_StatusTypeDef(*SingleMeasurement)(HPS3D_HandleTypeDef *handle, MeasureDataTypeDef *MeasureData, RetPacketTypedef *PacketType) = NULL; uint32_t (
handle.DeviceName = "\\\\.\\COMxx"; /*port number*/ ret = Connect(&handle); /*device connect*/ if (ret != RET_OK) { printf("device connect failed！ret = %d\n", ret); } ② device initialization, the default configuration is standby mode and asynchronous communication mode, mainly to create an asynchronous thread, obtain the device address (the rest of the commands use the device address), allocate memory space, etc.
printf("distance average: %d\n",event->MeasureData.full_roi_data[0].distance_average); break; case FULL_DEPTH_PACKET: printf("distance average: %d\n",event->MeasureData.full_depth_data->distance_average); break; case SIMPLE_DEPTH_PACKET: printf("distance average: %d\n",event->MeasureData.simple_depth_data->distance_average); break; case NULL_PACKET: break; default: printf("system error\n"); break; } } } /*Observer initialization*/ AsyncIObserver_t My_Observer; /*An observer subscribes to an event as a data
printf("Simple Roi measure distance average:%d \n",handle.MeasureData.simple_roi_data[0].distance_average); break; case FULL_ROI_PACKET: printf("Full Roi measure distance average:%d \n",handle.MeasureData.full_roi_data[0].distance_average); break; case FULL_DEPTH_PACKET: printf("Full depth measure distance average:%d \n",handle.MeasureData.full_depth_data->distance_average); break; case SIMPLE_DEPTH_PACKET: printf("simple depth measure distance average:%d \n",handle.MeasureData.
For device connection, please refer to "2.1.1 HPS3D160 Device Connection" in this document. 2.4.1 Create a work space Before creating a workspace, first look at the environment variables, enter echo $ROS_PACKAGE_PATH in the terminal, and view the environment variables on Linux, as shown below: Then check if the catkin tool is installed. If it is not installed, please install the catkin tool first.
(4) Through the above configuration, you can create a workspace, and go to the created workspace, enter cd ~ / HPS3D_SDK_ROS_Demo /; although this space is empty, we can still build it, input catkin_make, as shown below: (5)Enter ls to view the current working directory, you will find two extra folders "build" and "devel". In the devel folder, you can see a lot of setup.*sh files. Enter source devel/setup.
Note: If the rospack depends hps_camera is executed, the following error occurs (when the ros* command is used, an error occurs, it may be that the workspace has failed, it can be re-validated, or it can be written into the ros environment variable) Go back to the workspace directory and execute source devel/setup.bash again to make the workspace work, as shown in the following figure: 2.4.
（2）Enter sudo gedit package.xml in the terminal, configure package.xml, add the following two lines of code to the file, as shown below: message_generation message_runtime Then, package.xml configuration is completed, save and exit. Enter sudo gedit CMakeLists.txt in the terminal, configure CMakeLists.txt, and find the corresponding location to modify.
Add it to the new created distance.msg message file, as below: ④Find the code part as below： Modify it as below: Then CMakeLists.txt configuration is completed, save and quit。 （3）Check new created msg message，enter rosmsg show distance in terminal，as below： 2、 Create ROS service srv (1) In the created package, create a service srv directory to store the srv file.
place and modify. Find code part as below： Add it to the new created camera.srv service file，shown as below： Now CMakeLists.
2.4.4 Create ROS Depth camera client node and server Routines are provided in this section. Users can modify or write their own programs as needed. The procedures for the Depth camera client node and server routines given in this document are: (1) The client node is configured with the data that the user needs to collect (or configured by the command sent by the server); (2) After the client logs in, connect the optional device file.
Now CMakeLists.txt configuration is completed，save and quit。 2、Create ROS Depth camera client node and server （ 1 ） In the src directory of the package directory, create ros_camera_client.cpp and ros_camera_server.cpp, and enter sudo touch src/ros_camera_client.cpp src/ros_camera_server.cpp in the terminal of the package directory, as shown below: (2) Enter sudo gedit CMakeLists.txt in the terminal of the package directory, configure the CMakeLists.txt file, and add the following code to the CMakeLists.
#include "hps_camera/distance.h"//msg #include "hps_camera/camera.h"//srv ②ROS Initialize in the main function, create node, create topic and etc., code as below: ros::init(argc, argv, "ros_camera_server"); ros::NodeHandle n; ros::ServiceServer service = n.advertiseService("client_login", send_cmd); ros::Subscriber sub = n.
ros::NodeHandle n; ...... std::stringstream sclient_name; ros::ServiceClient client = n.serviceClient("client_login"); hps_camera::camera srv; sclient_name<<"camera_client"; printf("send name = %s\n",sclient_name.str().c_str()); srv.request.client_node_name = sclient_name.str(); camera_pub = n.advertise("camera", 1000); ...... if (client.call(srv)) { while(ros::ok()) { printf("rev cmd = %s\n",srv.response.control_cmd.c_str()); if( strcmp(srv.response.control_cmd.
case SIMPLE_ROI_PACKET: printf("distance = %d event->RetPacketType = %d\n", event->MeasureData.simple_roi_data[0].distance_average,event->RetPacketType); break; case FULL_ROI_PACKET: msg.distance_average = event->MeasureData.full_roi_data[0].distance_average; printf("distance = %d\n",msg.distance_average); camera_pub.publish(msg); break; case FULL_DEPTH_PACKET: printf("distance = %d event->RetPacketType = %d\n", event->MeasureData.
（3）New open a terminal input roscore，run ros bus，shown as below： （4） New open two terminals, all enter cd ~/HPS3D_SDK_ROS_Demo/ into workspace, all enter source devel/setup.
3、Command function interface The command function interface is the basic command in the HPS3D depth camera; each command function interface contains command packet packing and return packet parsing for the command. If the function interface integrated in api.h is not enough for the user to use, the user can configure the new interface according to the command function interface. (Note: After sending the command, you need to reset the running mode!!!) 3.1 Set running mode 3.1.
3.2 Get/set device address 3.2.1 Sample code /*get device address*/ ret = HPS3D_GetDevAddr(&handle); printf("1handle.DeviceAddr = %#x\n",handle.DeviceAddr); /*set device address*/ ret = HPS3D_SetDevAddr(&handle, 0x01); ret = HPS3D_GetDevAddr(&handle); printf("2handle.DeviceAddr = %#x\n",handle.DeviceAddr); 3.2.2 Running result 3.3 Get device version information 3.3.1 Sample code /*get device version*/ Version_t version_t; HPS3D_GetDeviceVersion(&handle, &version_t); printf("version_t.year = %d\n", versio
3.4 Get/set data packet type 3.4.1 Sample code /*get packet type*/ HPS3D_GetPacketType(&handle); printf("1handle.PacketType = %d\n", handle.PacketType);//PACKET_FULL = 0 /*set packet type*/ handle.PacketType = PACKET_SIMPLE;/*simple packet*/ HPS3D_SetPacketType(&handle); HPS3D_GetPacketType(&handle); printf("2handle.PacketType = %d\n", handle.PacketType); 3.4.2 Running result 3.5 Save/Clear/Reset factory setting 3.5.
3.6.2 Running result 3.7 Get ROI group/get current ROI group ID 3.7.1 Sample code uint8_t group_id = 0; /*select group ID*/ HPS3D_SelectROIGroup(&handle, 3); /*get group ID*/ HPS3D_GetROIGroupID(&handle, &group_id); printf("group_id = %d\n",group_id); 3.7.2 Running result 3.8 ROI relative settings 3.8.
roi_conf1.roi_id = 0; roi_conf1.left_top_x = 10; roi_conf1.left_top_y = 10; roi_conf1.right_bottom_x = 30; roi_conf1.right_bottom_y = 20; HPS3D_SetROIRegion(&handle, roi_conf1); roi_conf2.roi_id = 2; roi_conf2.left_top_x = 40; roi_conf2.left_top_y = 30; roi_conf2.right_bottom_x = 80; roi_conf2.
printf("roi_conf1.alarm_type[2] = %d\n", roi_conf1.alarm_type[2]); printf("roi_conf1.roi_conf1.ref_type[2] = %d\n", roi_conf1.ref_type[2]); printf("roi_conf1.roi_conf1.pixel_number_threshold[2] = %d\n", roi_conf1.pixel_number_threshold[2]); printf("roi_conf1.hysteresis_conf[2].enable = %d\n", roi_conf1.hysteresis_conf[2].enable); printf("roi_conf1.hysteresis_conf[2].threshold_value = %d\n", roi_conf1.hysteresis_conf[2].threshold_value); printf("roi_conf1.hysteresis_conf[2].positive = %d\n", roi_conf1.
3.9 Get current device support ROI number and threshold number 3.9.1 Sample code /*Get the number of ROI and thresholds currently support this device*/ uint8_t roi_number, threshold_number; HPS3D_GetNumberOfROI(&handle, &roi_number, &threshold_number); printf("roi_number = %d\n", roi_number); printf("threshold_number = %d\n", threshold_number); 3.9.
3.10 Set/ Get output/ input settings 3.10.1 Sample code /*get GPOUT parameter */ GPIOOutConfTypeDef gpio_out_conf; gpio_out_conf.gpio = GPOUT_1; HPS3D_GetGPIOOutConf(&handle, &gpio_out_conf); printf("1gpio_out_conf.function = %d\n",gpio_out_conf.function); printf("1gpio_out_conf.polarity = %d\n",gpio_out_conf.polarity); /*get GPIN parameter */ GPIOInConfTypeDef gpio_in_conf; gpio_in_conf.gpio = GPIN_1; HPS3D_GetGPIOInConf(&handle, &gpio_in_conf); printf("1gpio_in_conf.function = %d\n",gpio_in_conf.
3.10.2 Running result 3.11 Set HDR mode 3.11.1 Sample code /*Get HDR mode*/ HDRConf hdr_conf; HPS3D_GetHDRConfig(&handle, &hdr_conf); printf("1hdr_conf.hdr_mode = %d\n",hdr_conf.hdr_mode); /*set AUTO_HDR mode*/ HPS3D_SetHDRMode(&handle, AUTO_HDR);/*AUTO_HDR = 1*/ HPS3D_GetHDRConfig(&handle, &hdr_conf); printf("2hdr_conf.hdr_mode = %d\n",hdr_conf.hdr_mode); 3.11.2 Running result 3.12 Set/get HDR configuration 3.12.
= %f\n",hdr_conf.qualtity_overexposed_serious);//800 printf("1hdr_conf.qualtity_weak = %f\n",hdr_conf.qualtity_weak);//90 printf("1hdr_conf.qualtity_weak_serious = %f\n",hdr_conf.qualtity_weak_serious);//50 printf("1hdr_conf.simple_hdr_max_integration = %d\n",hdr_conf.simple_hdr_max_integration);//2000 printf("1hdr_conf.simple_hdr_min_integration = %d\n",hdr_conf.simple_hdr_min_integration);//100 printf("1hdr_conf.super_hdr_frame_number = %d\n",hdr_conf.super_hdr_frame_number);//4 printf("1hdr_conf.
printf("4hdr_conf.hdr_mode = %d\n",hdr_conf.hdr_mode); printf("4hdr_conf.simple_hdr_max_integration = %d\n",hdr_conf.simple_hdr_max_integration); printf("4hdr_conf.simple_hdr_min_integration = %d\n",hdr_conf.simple_hdr_min_integration); /*4、mode = SUPER-HDR*/ set_conf.hdr_mode = SUPER_HDR; set_conf.super_hdr_frame_number = 2; set_conf.super_hdr_max_integration = 15000; HPS3D_SetHDRConfig(&handle, set_conf); HPS3D_GetHDRConfig(&handle, &hdr_conf); printf("5hdr_conf.hdr_mode = %d\n",hdr_conf.
printf("1distance_filter_conf.filter_type = %d\n",distance_filter_conf.filter_type);//0 printf("1distance_filter_conf.kalman_K = %f\n",distance_filter_conf.kalman_K);//0.1 printf("1distance_filter_conf.kalman_threshold = %d\n",distance_filter_conf.kalman_threshold);//100 printf("1distance_filter_conf.num_check = %d\n",distance_filter_conf.
printf("1smooth_filter_conf.arg1 = %d\n",smooth_filter_conf.arg1);/*0*/ /*set smooth filter parameter*/ set_conf.type = SMOOTH_FILTER_AVERAGE; set_conf.arg1 = 200; HPS3D_SetSmoothFilter(&handle, set_conf); HPS3D_GetSmoothFilterConf(&handle, &smooth_filter_conf); printf("2smooth_filter_conf.type = %d\n",smooth_filter_conf.type); printf("2smooth_filter_conf.arg1 = %d\n",smooth_filter_conf.arg1); 3.14.2 Running result 3.15 Set optical parameter enable/get optical parameter 3.15.
3.16 Set/get distance compensation 3.16.1 Sample code /*get distance offset*/ int16_t offset; HPS3D_GetDistanceOffset(&handle, &offset); printf("1offset = %d\n",offset); /*set distance offset*/ HPS3D_SetDistanceOffset(&handle, 20); HPS3D_GetDistanceOffset(&handle, &offset); printf("2offset = %d\n",offset); 3.16.2 Running result 3.17 Set/get multi-machine interference parameters 3.17.
HPS3D_GetInterferenceDetectConf(&handle, &interference_detect_conf); printf("2interference_detect_conf.enable = %d\n",interference_detect_conf.enable); /* get interference detect integ. time*/ HPS3D_SetInterferenceDetectIntegTime(&handle, 200); HPS3D_GetInterferenceDetectConf(&handle, &interference_detect_conf); printf("2interference_detect_conf.integ_time = %d\n",interference_detect_conf.
MountingAngleParamTypeDef mounting_angle_param_conf, set_conf; HPS3D_GetMountingParamConf(&handle, &mounting_angle_param_conf); printf("1mounting_angle_param_conf.enable = %d\n",mounting_angle_param_conf.enable); printf("1mounting_angle_param_conf.angle_vertical = %d\n",mounting_angle_param_conf.angle_vertical); /*set assemble angle enable*/ HPS3D_SetMountingAngleEnable(&handle, true); /*set assemble angle parameter*/ set_conf.
4. Q&A 4.1 The encoding format does not match? We provide SDK encoding format is UTF-9, if the encoding format error occurs when using the API provided by the SDK, please create a new api.h file in the project, and copy the api.h content provided by the SDK to the new api.h file to solve the compilation error.
5. Revision Date Revision Description 2018/12/11 1.0.
IMPORTANT NOTICE – PLEASE READ CAREFULLY Hypersen Technologies Co., Ltd. reserve the right to make changes, corrections, enhancements, modifications, and improvements to Hypersen products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on Hypersen products before placing orders. Hypersen products are sold pursuant to Hypersen’s terms and conditions of sale in place at the time of order acknowledgement.
