Introduction
GPS chips are ubiquitous today in all devices, from smartphones to wearables. While many SoC vendors provide integrated GPS modules within the SoC, for some applications, the SoC may not contain an internal GPS. In this case, an external GPS chip needs to be connected. This document explains the basics of GPS and how to integrate the GPS hardware to the Android stack for use with Android location service.
What is GPS?
GPS is the colloquial term used to refer to satellite navigation. Satellite navigation refers to location determination using time signals transmitted along lines of sight from satellites. The correct technical term for such navigation systems is GNSS: Global Navigation Satellite Systems.
A GPS chip is a piece of silicon that, with the help of a front-end antenna, acts as a receiver for the satellite’s navigation data. A GPS chip typically obtains a ‘lock’ when at least 3 satellites are in its line of sight. Once the lock is obtained, the GPS chip can calculate the location and transmit this data to the host (your computer or a SoC-running Android) using a number of protocols. Common GPS data formats are NMEA (National Marine Electronics Association Format), RINEX (Receiver Independent Exchange Format), or proprietary to the GPS chip manufacturer. Most GPS chips use the NMEA format.
The GPS chips interface with the host via a serial data protocol, typically UART or I2C. In this article, we focus on the UART interface. Most steps of integration remain the same irrespective of the interface type.
Bringing up the GPS chip on the Android platform consists of two steps:
- Enabling the hardware interface between GPS chip and host
- Integrating the HAL layer for the GPS chip to Android.
Enabling the hardware interface between GPS chip and host
(a) Enable the required kernel driverMake sure that the required kernel configuration is enabled for the interface being used by the GPS chip. For example, for a GPS chip using serial via USB, we need to enable the following kernel configurations:
CONFIG_SERIAL_CORE
CONFIG_SERIAL_CORE_CONSOLE
CONFIG_USB_SERIAL_FTDI_SIO
(b) Ensure power and clock to the GPS chipIf clock and power are being provided by SoC, check that the corresponding pins are enabled.
(c) Serial port configurationThe serial port configuration on the SoC should match the one on the GPS chip. This would generally be a configuration setting when building the GPS HAL. Below is an example serial configuration of NMEA:
Baud rate : 4800
Parity : None
Data bits : 8
Stop bits : 1
Handshake : None
Integrating the HAL layer to Android Build
Once the GPS chip is powered on, it will transmit messages in the chosen protocol format at a regular interval. It is the responsibility of the user space code to interpret these messages and translate them into location information (latitude and longitude). In Android, the hardware abstraction layer (HAL) is the user space code that interprets the GPS protocol and translates it into usable information for Android Location Service.
More on Android HAL and Location Manager
Android gives your applications access to the location services supported by the device through classes in the android.location package. The central component of the location framework is the LocationManager system service, which provides APIs to determine the location and bearing of the underlying device (if available).
The LocationManager relies on android.hardware.gnss* service to provide the location information, which it can then pass on to the application.
This service is the HAL or hardware abstraction layer. The Location Manager checks for a service by this name to ascertain that GNSS is present.
HAL defines a standard interface for hardware vendors to implement, which enables Android to be agnostic about lower-level driver implementations. Using a HAL allows you to implement functionality without affecting or modifying the higher-level system.
In Android 8.0 and higher, the lower-level layers are re-written to adopt a new, more modular architecture. Devices running Android 8.0 and higher must support HALs written in the HIDL language, with few exceptions.
The GNSS HAL code is expected to provide implementations for android.hardware.gnss interfaces such as IAGnss (Assisted GNSS callbacks), IGnssGeofencing, IGnssMeasurement etc.
Integrating HAL code
The HAL code for the GPS module is provided by the GPS chip vendor.
Place the HAL code under the hardware/ folder.
Run make from the Android source code folder. Make sure the required targets, like the android.hardware.gnss@1.0-service-<vendor>.rc service and android.hardware.gnss@1.0-impl-<vendor>.so library, are built based on the proper Android OS. version.Service is placed in /system/vendor/bin/hw and .so lib is placed in /system/vendor/lib64/hw.
Make sure your HAL is being built along with the Android.
1) HAL code does not get built as part of the Android image.
Make sure HAL code is placed directly under the hardware/ folder. If your service is not being built, then run mm command in your HAL directory to build its modules and then run the Android source make.
2) GNSS service dies due to permission errors on /dev/<serial_dev>
Initial integration can be done with selinux mode set to permissive. In the permissive mode, sepolicy denials are logged but not enforced. sepolicy denials appear under dmesg as logs of the format “avc: denied”. Run these logs through audit2allow tool to generate sepolicy strings. Most vendors will provide the sepolicy .te files required for the GPS service.
If .te files are not provided by the vendor, then we can generate using this command.
adb logcat -b all -d | audit2allow -p <policy_directory_path>/<name of te file> Append file_contexts of the gps sepolicy to linux file_contexts file in /system/sepolicy/vendor and copy the .te file generated to /system/sepolicy/vendor/ folder.
4) Remove any other GNSS service from the manifest files:
- Android Location Manager by default will be waiting for data provided by any one of the location services. If there are any default services being run, then disable that service and enable the service required by your module.
- The manifest files are present under /device/<vendor>/<vendor_product>/ folder as manifest*.xml
Testing of the integrated GNSS module
After the process of Integration, the next step is to test the module. The following steps help in testing the given GPS module.
- The first step is to install the appropriate Android Apk eg:Google Maps, Spyzie in a board, which can analyse the location data and display. Some vendors provide their own Android apk to test the chip.
- The ADB tool helps users to check whether the required processes and services are being run or not.
- Logcat can be used to analyse failures or crashes in the GNSS service.
References
https://stackoverflow.com/questions/46338547/wheres-the-right-place-in-an-android-aosp-build-to-set-ownership-on-a-device-inhttps://source.android.com/devices/architecture/vintf/objects https://source.android.com/devices/architecture/kernel/config
