GENIVI SensorsService

Component Specification

Release 3.0.0
Status: Draft 
20.01.2015

Accepted for release by:
This document has is a draft of the SensorsService API 3.0.0 defined by the GENIVI expert group Location Based Services (LBS).

Abstract:
This document describes the API of the SensorsService Abstract Component.
Keywords: 
SensorsService, Sensors, Positioning API. 

SPDX-License-Identifier: CC-BY-SA-4.0
 
Copyright (C) 2012, BMW Car IT GmbH, Continental Automotive GmbH, PCA Peugeot Citroën, XS Embedded GmbH

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License

To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/
or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
Table of Contents

Change History	5
1.	Introduction	6
2.	Terminology	7
3.	Requirements	8
1.	Requirements Diagram	8
AGPS Support	10
Forward a Set of Sensor Values	10
Provides Data via IPC	10
Support of different Global Navigation Satellite Systems (GNSS) to calculate the current position.	10
Accelerator Sensor	10
Access to Sensor Services	11
Car Configuration Data	11
Data Latency for GNSS and DR Signals	11
Enhanced Position	12
Extended Acceleration Sensor	12
Extended GNSS Service	12
Extended Gyroscope Sensor Service	13
GNSS Service	13
PPS Signal	13
Inclination Sensor	14
Odometer Sensor	14
ReverseGear Sensor	14
Sensor Directory	14
Sensor Meta-Data	15
Sensor Signal Timestamp	15
Signal Measurement Units	15
Signal Values Type Compatibility	16
Simple Gyroscope Sensor Service	16
Slip Angle Sensor	16
SteeringAngle Sensor	16
Vehicle State Sensor	17
VehicleSpeed Sensor	17
Wheel Tick/Speed Sensor Service	17
4.	Architecture	18
1.	SensorsService	18
2.	SensorsService Diagram	18
3.	Traceability Diagram	19
1.	Context	20
2.	Context Diagram	20

Change History

Version	Date	Author	Change	
0.1	27.08.2013	MResidori	Document Created	
0.2	18.11.2013	MResidori	Document generated from the Entrprise Architect Model	
0.3	27.03.2014	MResidori	Added copyright notes	
3.0.0-alpha	24.04.2014	MResidori	Changed license version from 3.0 to 4.0	
3.0.0	10.12.2014	MResidori	Updated API description	
3.0.0	20.01.2015	HSchmidt	Fix copy/paste error	

1.	Introduction
This document describes the API of the SensorsService component.

2.	Terminology

Term	Description	
GNSS	Global Navigation Satellite System	

		

		

  

3.	Requirements
1.	Requirements Diagram
This diagram shows an overview of all requirements in the area of positioning.

The requirements are organized in four groups:
1.	SW-POS: general requirements
2.	SW-GNSS: requirements related to the GNSS receiver
3.	SW-SNS: requirements related to the vehicle sensors
4.	SW-ENP: requirements related to enhanced positioning

Figure: 1

 AGPS Support  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides the possibility to inject AGPS "Assisted GPS" data to the GPS device.

Rationale:
This allows to speed up the time to get a valid (fixed) GPS position.	

 Forward a Set of Sensor Values  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The Enhanced Position contains in addition to the Position and Course values as well a set of sensor data.
- yawRate in degrees per second
- filter status
- accuracy information in form of sigma values for every direction [m] and the covariance between latitude and longitude in m^2. 
- number of used, tracked and visible satellites.

Rational:
Some clients (e.g. Map Matcher) needs the basic DR filtered position specific sensor values as additional input for the decision algorithm.	

 Provides Data via IPC  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The enhanced position is accessible for multiple clients on the platform at the same time.
An IPC is used to deliver to the clients the Enhanced Position data fields.

Rational:
Several SW components in the system are clients for the result of the filtered position and need to access the data.	

 Support of different Global Navigation Satellite Systems (GNSS) to calculate the current position.  	
«GFunctionalRequirement»	Priority: Medium		
The interfaces are defined in such a way that client applications don´t need to know the details of the GNSS in use (e.g. GPS, Galileo, GLONASS, Compass).	

 Accelerator Sensor  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides a sensor, which delivers the vehicle acceleration in the driving direction (x Axis, see reference system). The sensor value is delivered in m/s^2. Sensor value of temperature near the sensor is optional. 
Configuration data about placement and orientation of the sensor can be provided optionally.

Rational:
Used for optimizing the dead reckoning solution.	

 Access to Sensor Services  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform delivers signals to multiple client applications concurrently by the Sensor Service.

Rational:
This allows for multiple Client Applications to share a single Sensor.	

 Car Configuration Data  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides car configuration data, that contains general vehicle details (e.g. physical dimensions of car, distance of axis, driven axis, etc). 
Sensor related configuration data depends on the specific sensor requirements (e.g. position of sensor) and is included with the specific sensors. 
- Position of center of gravity 
- Position of front and rear axle 
- driven axles 
- seat count 
- vehicle mass 
- vehicle width 
- track width 

Rational:
DR module needs the detailed information for more accurate calculations.	

 Data Latency for GNSS and DR Signals  	
«GNonFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides the signals of the GNSS, Extended GNSS and enhanced position in less than 300 ms after acquisition.

Rational:
This guarantees that the tracked current position does not deviate much from the actual position.	

 Enhanced Position  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform delivers the filtered (i.e. combined GNSS and vehicle sensor) position as the Enhanced Position, which is the result of the dead reckoning calculation. The Enhanced Position contains: 
- Position expressed as WGS 84 longitude and latitude (unit is tenth of microdegree (degree x 10^-7^)) 
- the Altitude 'above mean sea level' in meters (corrected by GeoID)
- Heading in degrees relative to the true north 
- Climb 
- Speed in meters per seconds, positive in the forward direction 

Rational:
Other SW-components on the same platform want to access the improved GNSS position, which is calculated by a dead reckoning algorithm.	

 Extended Acceleration Sensor  	
«GFunctionalRequirement»	Priority: Low		
Description:
The software platform provides a sensor, which provides the acceleration on the additional axis y (left-side) and z (up). 
The position of the sensor in 3D space in relation to the reference point is given. The angles of the sensor can be specified in the car configuration data. The standard deviations for the sensors can be specified for each axis. 

Rational:
Used for optimizing the dead reckoning solution. 	

 Extended GNSS Service  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides an extension to the GNSS Service with optional information. 

Accuracy: 
- fixStatus 
- hdop, pdop, vdop 
- numberOfSatellites 
- sigmaLatitude, sigmaLongitude, sigmaAltitude

Satellite Details: 
- Information per satellite: azimuth, elevation, inUse, SatelliteId, signalNoiseRatio 

Course Details: 
- speed for 3-axis

Antenna: 
- Antenna Position in 3D coordinates in relation to the reference point (see reference system).

Updated at least with 1Hz frequency additionally to the Signals provided by GNSS-Only Service. 
The GNSS Service should provide the capability to switch between different GNSS-Devices (e.g. Galileo, GPS, etc)

Rational:
These data are used for improved positioning based on GNSS.	

 Extended Gyroscope Sensor Service  	
«GFunctionalRequirement»	Priority: Low		
Description:
The software platform includes the sensor that delivers
- pitch rate
- roll rate

This sensor values extend the simple gyroscope sensor.
Sign of is defined by rule of right hand (thumb direction: left and front, see reference system).
Car configuration data need to provide position angles according to vehicle reference system.

Rational:
This Sensor Service is used in Dead Reckoning calculations of the vehicle position.	

 GNSS Service  	
«GFunctionalRequirement»	Priority: High		
Description:
The software platform includes a service that provides the following GNSS Signals updated at least with 1Hz frequency: 
Position: 
- position expressed as WGS 84 altitude, longitude and latitude in tenth of microdegree (degree x 10^-7^) 

Course:
- speed in meters per second 
- climb 
- heading relative to true north expressed in degrees  

Timestamp and date as UTC. 

Rational:
These data are contained in NMEA 0183 $GPGGA and $GPRMC messages and provide the minimum information required for GNSS-only vehicle positioning.	

 PPS Signal  	
«GFunctionalRequirement»	Priority: Medium		
Description:
1) For accurate timing the 1 PPS (pulse per second) signal from the GPS receiver is provided within the positioning framework.
The PPS is a hardware signal which is a UTC synchronized pulse.
The duration between the pulses is 1s +/- 40ns and the duration of the pulse isconfigurable (e.g. it could be 100ms or 200ms).
The pulses occur exactly at the UTC full second timeslots.

2) One option is to provide this signal in the positioning framework as an interrupt service routine and the difference to the system time can be accessed by a getter. This provides a synchronization of the system time to UTC.

Rationale:
Used for synchronizing the timing of the ECU.	

 Inclination Sensor  	
«GFunctionalRequirement»	Priority: Low		
Description:
The software platform provides the inclination of the road in longitudinal direction, i.e. in the direction of movement [°]. Estimated gradient of the road in transverse direction [°]. In unstable driving situations this value might not be available.

Rational:
This Sensor is used for optimizations in Dead Reckoning calculations of the vehicle position.	

 Odometer Sensor  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform includes a Sensor that delivers the traveled distance. 
Distance in [cm] with at least 5Hz as a running counter with overflow to support multiple clients.

Rational:
Odometer is sometimes the only speed related Signal available to the head unit. 	

 ReverseGear Sensor  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform includes a Sensor that delivers the information if the reverse gear is enabled or not.

Rational:
The direction of movement is included in the vehicle speed. This information is only used to detect reverse gear or not.	

 Sensor Directory  	
«GFunctionalRequirement»	Priority: Medium		
Description:
Client Applications are able to query what Sensors are currently available.

Rational:
This allows for development of flexible applications that do not know what sensor data are available in the vehicle a priori. Client shall checks first this directory to find out which ones are available; use meta-data to choose one of interest and use provided data to connect to necessary services.	

 Sensor Meta-Data   	
«GFunctionalRequirement»	Priority: High		
Description:
The software platform provides the following information about the Sensor and the related output Signals: 
- Sensor Identifier that is unique within the system
- Sensor Category (Physical/Logical)
- Sensor Type (GPS, Odometer, Map Matching, etc.)
- Sensor Sub-Type (ordinary GPS, differential GPS, etc.)
- Output Signals (Longitude, Latitude, Course, Speed, etc.)
- Output Signal Sampling Frequency (1 Hz, 10 Hz, irregular, etc.)
- Output Signal Measurement Units (kilometers per hour; meters per second; etc.)

Rational:
Sensor clients need that information in order to correctly handle data provided by sensor service and to adapt to the variation in the signal data delivery.	

 Sensor Signal Timestamp  	
«GFunctionalRequirement»	Priority: High		
Description:
The software platform provides for each sample returned by the Sensor Service the timestamp, when it is accompanied. The timestamp corresponds to the time point of the sample acquisition or calculation. Timestamps are derived from the same clock that is accessible to the Client Applications. 
Timestamp is delivered with a accuracy of milliseconds.

Rational:
Measurement timestamps are important for proper functioning of most processing algorithms. For instance, algorithms for sensor calibration and dead reckoning typically use data from multiple sensors in conjunction, e.g. logical sensor.	

 Signal Measurement Units  	
«GFunctionalRequirement»	Priority: High		
Description:
The software platform delivers signal values in universal, implementation independent units. It's preferred to use SI-units. 
For example, a gyroscope signal should be measured in millidegrees per second instead of A/D converter counts.

Rational:
This decouples the client applications from the implementation details of individual sensor devices.	

 Signal Values Type Compatibility  	
«GFunctionalRequirement»	Priority: Medium		
Description:
All Sensor Services that provide Signals referring to the same physical quantity deliver their data in the same format (including API signatures, data type and measurement units). However, sampling frequency, accuracy etc. can differ.

Rational:
Sensor service clients are able to use multiple Sensor Services without changes in the interfaces.	

 Simple Gyroscope Sensor Service  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform includes the Sensor that delivers 
- yaw rate: the rate of the vehicle heading change 
-temperature
- status:(temperature compensated or not, etc) 
at the frequency of at least 5Hz. Unit of yaw rate is "degrees per second". 

Sign of yaw rate is defined by rule of right hand (thumb direction: up)
(see reference system)

Rational:
This Sensor Service is used in Dead Reckoning calculations of the vehicle position.	

 Slip Angle Sensor  	
«GFunctionalRequirement»	Priority: Low		
Description:
Platform provides a sensor, which delivers the value slip angle in degrees [°]. It is defined as the angle between the fixed car axis (direction of driving) and the real direction of vehicle movement. The direction and sign is defined equal to the yaw rate (See reference system).

Rational:
This Sensor is used for optimizations in Dead Reckoning calculations of the vehicle position. 	

 SteeringAngle Sensor  	
«GFunctionalRequirement»	Priority: Low		
Description:
This sensor provides the angles of the front and rear wheels and the steering wheel in degrees.
Configuration values can be provided for sigmas and steering ratio.

Rational:
Is used as additional element for plausibilisation of the yaw rate in the dead reckoning module.	

 Vehicle State Sensor  	
«GFunctionalRequirement»	Priority: Low		
Description:
The software platform provides a sensor, giving the state of certain vehicle systems: 
ABS: on/off 
ESP: on/off 
ASC: on/off (stability control)
breaks: on/off

Rational:
This Sensor is used for optimizations in Dead Reckoning calculations of the vehicle position.	

 VehicleSpeed Sensor  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform includes a Sensor that delivers the vehicle speed. Filtered vehicle speed in [m/s] with a frequency of at least 5Hz. Direction is given by the sign of this value.

Rational:
Vehicle speed is sometimes the only speed related signal available to the head unit.	

 Wheel Tick/Speed Sensor Service  	
«GFunctionalRequirement»	Priority: Medium		
Description:
The software platform provides a Sensor that delivers the running counter of partial wheel revolutions at the frequency of at least 5Hz or the already calculated wheelspeed (speed in [m/s] or angular speed).

The resolution of a single wheel revolution (i.e. the number of ticks per revolution) is included with the Sensor Service meta-data.

This identifiers specify the wheel of measurement:
0: Average of non driven axle 
1: Left front wheel 
2: Right front wheel 
3: Left rear wheel 
4: Right rear wheel 
Unit: [ticks].

Rational:
This Sensor typically registers ‘ticks’ from a wheel, adds them up and sends to the vehicle bus with a certain interval. The number of ‘ticks’ per complete wheel revolution is known in advance. In some cases, the data from multiple wheels are averaged. Other implementations send the already precalculated speed per wheel or axle, which is a valid replacement for most use cases.	

4.	Architecture
1.	SensorsService

The SensorsService is a component that is responsible for retrieving data from the available vehicle sensors and making them available to other client applications. It hides dependencies to hardware and IPC mechanism. 

In systems that implement the EnhancedPositionService component, the SensorsService is typically implemented as a C library that is dynamically linked by the EnhancedPositionService.

2.	SensorsService Diagram

Figure: 2

3.	Traceability Diagram

Figure: 3

1.	Context

This diagram shows how the SensorsService interacts with its client application: the EnhancedPositionService.

2.	Context Diagram

Figure: 4