| Table of Contents |
|---|
Introduction
Accurate and reliable global positioning of moving vehicle is of great importance across many domains. Here, Global Navigation Satellite Systems (GNNS) like GPS and Galileo provide ways to locate vehicles worldwide. However, there are applications where either the GNNS’s update rate, precision, stability or reliability are not sufficient or other positioning systems, like optical ones, are available and need to be integrated to achieve the best possible quality of the estimated location.
...
Important note: If the IG1 is removed from the car and/or installed in another place, this calibration procedure needs to be repeated.
Web Application Programming Interface
A C-API is provided to integrate the functionalities into your own applications. This API allows to load an existing configuration file, further configure the system, start the sensor fusion and query the current position and orientation of the vehicle.
The example folder provided with the release of LpGlobalFusion contains a complete example program of the API usage. In the following the most relevant API commands will be described.
Library and Fusion Lifecycle
lpgfFusionManager
This function must be called to create an instance of the library and returns a pointer which needs to be provided to all further API calls. This function only needs to be called once during the lifetime of your application.
lpgfFusionManagerReadConfigurationFile
This function will read the system configuration about connected sensors and the sensor fusion configuration from a text file. Within this call, all data sources will be created and the function will return false if a sensor could not be properly connected.
This method should be called before the sensor fusion is started.
lpgfFusionManagerStart
To start the data acquisition from the connected sensor this method will be called. The sensor processing will run in a background thread and this function call will return as soon as all sensors were started.
After a call to this function, the most recent system state can be acquired with a call to the lpgfFusionManagerGetStateEstimate method.
lpgfFusionManagerStop
Stops processing of sensor data. After a call to this function, no updated state estimates will be computed any more. The lpgfFusionManagerStart can be called to start the data acquisition and sensor fusion again.
lpgfDestroyFusionManager
This function is called to release all resources held by the library. After this call, no resources associated with the instance of this library can be used any more.
Access to Fusion State
Once lpgfFusionManagerStart has been called, the fusion of the connected sensor’s data will occur in the background with the rate at which the sensors provide their values.
lpgfFusionManagerGetStateEstimate
The most recent result of the sensor fusion can be queried via a call to this function. It returns the lpgf_state_estimate data structure which contains the global and local position of the vehicle as well as its orientation.
Providing Odometry Measurements
Wheel odometry measurements to improve the sensor fusion quality can either be provided via a connected data source (for example a CAN bus encoder) or via API calls. When integrating into a larger existing system, it may be more convenient to use API calls instead of using a dedicated data source.
Wheel odometry information for idealized one-wheeled vehicles, two-wheeled vehicles or vehicles with four wheels can be provided. The correct vehicle model needs to be selected and configure in the library for the respective API call. So if a two-wheeled vehicle model is configure, only the API call lpgfFusionManagerAddTwoWheelOdometry may be used.
lpgfFusionManagerAddOneWheelOdometry
Use this function to provide one wheeled odometry measurement to the sensor fusion.
lpgfFusionManagerAddTwoWheelOdometry
Use this function to provide two wheeled odometry measurement to the sensor fusion.
lpgfFusionManagerAddFourWheelOdometry
Use this function to provide four wheeled odometry measurement to the sensor fusion.
Control of Mapping Functionality
If a camera or lidar based mapping functionality should be used together with the sensor fusion library, these function calls allow to control the process of map creation and where to load and store it.
Except for lpgfMappingGetStatus, all the function calls to configure the mapping behavior need to be done before the sensor fusion is started. So before the call to lpgfFusionManagerStart.
lpgfMappingSetFilename
This function call allows to set the filename from which a previously created map is loaded and where an updated map is stored to after the sensor fusion was stopped. If the mapping mode is enabled (see next function call), either a new map is created or stored if no previous map file is found or an existing map file is updated with the additional information gathered during this run of the sensor fusion.
If the mapping mode is disabled (see next function call), the map will be loaded and used to localize the vehicle in the environment. However, the map will not be updated or saved when stopping the library.
lpgfMappingSetMode
Allows to enable or disable the mapping feature. If mapping is enabled, new content is added to the internal map which allows the vehicle to be localized in new environments. For environments where no previous map is available, the mapping mode must be enabled to create an initial map of the relevant areas of the environment.
If mapping mode is disabled, a pre-existing map (see function lpgfMappingSetFilename) needs to be loaded which can be used by the vehicle to determine orientation and position within this map
lpgfMappingGetStatus
Returns the data structure which contains information about the performance (frames per seconds and frame processing time) and whether the localization using the mapped data is active or not.
Version History
...
Version
...
Date
...
Changes
...
1.0
...
2019/2/10
...
Initial version
...
1.1
...
2019/7/19
...
Added data source documentation
...
1.2
...
2020/09/20
...
Added documentation for camera SLAM
Appendix
Open Source Licenses
See the folder licenses in the release archive for details on the conditions of the used Open Source Licenses.
About Us
This manual was created by LP-RESEARCH Inc. If you have any feedback or questions please contact us.
...
Email:
...
...
Tel:
...
+81-3-6804-1610
...
Address:
...
#303 Y-Flat, 1-11-15, Nishiazabu, Minato-ku, Tokyo, 106-0031 Japan
If the webserver component of the LPNAV system is started, multiple HTTP endpoints are available to query the system status, configure its components or provide additional measurements to the system.
The base address is formed by host name and port number then the name of the endpoint is attached. For example, if the LPNAV webserver is hosted on the address 192.168.1.5 and port 9091, the base address would be:
http://192.168.1.5:9091/
Now the name of the endpoint (for example “lpglobalfusion/sensorvalues”) to form the full URL to call:
http://192.168.1.5:9091/lpglobalfusion/sensorvalues
Information Endpoints
lpglobalfusion/sensorvalues
Provides a JSON result which contains the most up-to-date values of all connected sensors.
lpglobalfusion/sensorconfig
Provides a JSON result which contains information of the configuration of all connected sensors.
lpglobalfusion/status
Provides a JSON result which contains information on the current system status and the most recent result of the position and orientation sensor fusion.
Measurement Endpoints
Measurement values can be provided to the LPNAV system via HTTP POST calls. The parameters for this wall are transferred as part of the query string.
lpglobalfusion/set_one_wheel_odometry
Provide the wheel velocity of a one wheeled vehicle to the sensor fusion.
Parameter Name | Description |
|---|---|
sigma | uncertainty of wheel velocity measurement at one sigma of the standard error in meter/seconds |
wheel | wheel velocity in meter/seconds |
lpglobalfusion/set_two_wheel_odometry
Parameter Name | Description |
|---|---|
sigma | uncertainty of wheel velocity measurement at one sigma of the standard error in meter/seconds |
left_wheel | wheel velocity in meter/seconds |
right_wheel |
lpglobalfusion/set_four_wheel_odometry
Parameter Name | Description |
|---|---|
sigma | uncertainty of wheel velocity measurement at one sigma of the standard error in meter/seconds |
left_front_wheel | wheel velocity in meter/seconds |
right_front_wheel | |
left_rear_wheel | |
right_rear_wheel |
Example
Here is a complete example how Odometry data for a twot-wheeled vehicle can be transferred with python:
| Code Block | ||
|---|---|---|
| ||
from urllib.request import urlretrieve
from urllib.parse import urlencode
## fill with the last measurements from odometry
# units is meter / second
odometry_dict = {
'sigma' : 0.02,
'left_wheel': 0.4,
'right_wheel': 0.5}
qstr = urlencode(odometry_dict)
# forward the measurement to LPNAV with a POST call
# by providing an empty data dictionary, a POST call will be used
ret = urlretrieve("http://localhost:9091/lpglobalfusion/set_two_wheel_odometry?" + qstr,
data={})
|
C-Library Application Programming Interface
A C-API is provided to integrate the functionalities into your own applications. This API allows to load an existing configuration file, further configure the system, start the sensor fusion and query the current position and orientation of the vehicle.
The example folder provided with the release of LpGlobalFusion contains a complete example program of the API usage. In the following the most relevant API commands will be described.
Library and Fusion Lifecycle
lpgfFusionManager
This function must be called to create an instance of the library and returns a pointer which needs to be provided to all further API calls. This function only needs to be called once during the lifetime of your application.
lpgfFusionManagerReadConfigurationFile
This function will read the system configuration about connected sensors and the sensor fusion configuration from a text file. Within this call, all data sources will be created and the function will return false if a sensor could not be properly connected.
This method should be called before the sensor fusion is started.
lpgfFusionManagerStart
To start the data acquisition from the connected sensor this method will be called. The sensor processing will run in a background thread and this function call will return as soon as all sensors were started.
After a call to this function, the most recent system state can be acquired with a call to the lpgfFusionManagerGetStateEstimate method.
lpgfFusionManagerStop
Stops processing of sensor data. After a call to this function, no updated state estimates will be computed any more. The lpgfFusionManagerStart can be called to start the data acquisition and sensor fusion again.
lpgfDestroyFusionManager
This function is called to release all resources held by the library. After this call, no resources associated with the instance of this library can be used any more.
Access to Fusion State
Once lpgfFusionManagerStart has been called, the fusion of the connected sensor’s data will occur in the background with the rate at which the sensors provide their values.
lpgfFusionManagerGetStateEstimate
The most recent result of the sensor fusion can be queried via a call to this function. It returns the lpgf_state_estimate data structure which contains the global and local position of the vehicle as well as its orientation.
Providing Odometry Measurements
Wheel odometry measurements to improve the sensor fusion quality can either be provided via a connected data source (for example a CAN bus encoder) or via API calls. When integrating into a larger existing system, it may be more convenient to use API calls instead of using a dedicated data source.
Wheel odometry information for idealized one-wheeled vehicles, two-wheeled vehicles or vehicles with four wheels can be provided. The correct vehicle model needs to be selected and configure in the library for the respective API call. So if a two-wheeled vehicle model is configure, only the API call lpgfFusionManagerAddTwoWheelOdometry may be used.
lpgfFusionManagerAddOneWheelOdometry
Use this function to provide one wheeled odometry measurement to the sensor fusion.
lpgfFusionManagerAddTwoWheelOdometry
Use this function to provide two wheeled odometry measurement to the sensor fusion.
lpgfFusionManagerAddFourWheelOdometry
Use this function to provide four wheeled odometry measurement to the sensor fusion.
Control of Mapping Functionality
If a camera or lidar based mapping functionality should be used together with the sensor fusion library, these function calls allow to control the process of map creation and where to load and store it.
Except for lpgfMappingGetStatus, all the function calls to configure the mapping behavior need to be done before the sensor fusion is started. So before the call to lpgfFusionManagerStart.
lpgfMappingSetFilename
This function call allows to set the filename from which a previously created map is loaded and where an updated map is stored to after the sensor fusion was stopped. If the mapping mode is enabled (see next function call), either a new map is created or stored if no previous map file is found or an existing map file is updated with the additional information gathered during this run of the sensor fusion.
If the mapping mode is disabled (see next function call), the map will be loaded and used to localize the vehicle in the environment. However, the map will not be updated or saved when stopping the library.
lpgfMappingSetMode
Allows to enable or disable the mapping feature. If mapping is enabled, new content is added to the internal map which allows the vehicle to be localized in new environments. For environments where no previous map is available, the mapping mode must be enabled to create an initial map of the relevant areas of the environment.
If mapping mode is disabled, a pre-existing map (see function lpgfMappingSetFilename) needs to be loaded which can be used by the vehicle to determine orientation and position within this map
lpgfMappingGetStatus
Returns the data structure which contains information about the performance (frames per seconds and frame processing time) and whether the localization using the mapped data is active or not.
Appendix
Open Source Licenses
See the folder licenses in the release archive for details on the conditions of the used Open Source Licenses.