Release: v3.4.4 (#15)

See CHANGELOG.md for changes.
Ericsson · Mar 6, 2024 · 5058cd7 · 5058cd7
1 parent 465a959
commit 5058cd7
Show file tree

Hide file tree

Showing 21 changed files with 717 additions and 222 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,17 @@
 # Changelog
 
-## [3.4.*]
+## [3.4.4]
 - Fixed message nullptr exception.
 - IMSI and MSISDN used `unsigned long` which doesn't have enough bits to store all possible values. Changed to `unsigned long long`.
 - Added support to use 5G NR cells in addition to LTE cells.
+- Reworked `LocationInformation` structure to be more aligned to the 3GPP LPP specification. It now supports more location coordinate and velocity types. All example function to fill in the `LocationInformation` structure have been updated to reflect this change.
+- Changed `--location-info` to `--fake-location-info` (or `-fli`).
+- Changed `--latitude` to `--fake-latitude` (or `-flat`).
+- Changed `--longitude` to `--fake-longitude` (or `-flon`).
+- Changed `--altitude` to `--fake-altitude` (or `-falt`).
+- Added `--location-report-unlocked` to always use the server provided location information update interval. Otherwise, the update interval will be set locked to 1 second.
+- Added support to parse request periodicity from RequestLocationInformation message.
+- When using the u-Blox receiver in `example-lpp`, it will not load the receiver configuration. This behavior is unchanged for `example-ublox` but can still be disabled with `--disable-config`.
 
 ## [3.4.3]
 - Added option to export NMEA sentences to a unix socket or a TCP connection. See `--nmea-export-*` command-line arguments. This requires the use of the NMEA receiver.

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -28,7 +28,8 @@ find_package(OpenSSL REQUIRED)
 endif (USE_OPENSSL)
 
 add_definitions(-D_POSIX_C_SOURCE=200809L)
-add_definitions(-DCLIENT_VERSION="3.4.3")
+add_definitions(-DCLIENT_VERSION="3.4.4")
+add_definitions(-DCLIENT_VERSION_INT=0x030404)
 
 if(${ASN_DEBUG})
    add_definitions(-DASN_EMIT_DEBUG=1)

diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # SUPL 3GPP LPP client
 
-![version](https://img.shields.io/badge/version-3.4.3-green)
+![version](https://img.shields.io/badge/version-3.4.4-green)
 ![license](https://img.shields.io/badge/license-MXM-blue)
 
 This project is a set of libraries, examples and tools to facilitate the development of 3GPP LPP clients. 

diff --git a/examples/lpp/README.md b/examples/lpp/README.md
@@ -14,7 +14,7 @@ There are a few required arguments:
 ```
   ./example-lpp COMMAND {OPTIONS}
 
-    3GPP LPP Example (3.4.3) - This sample code is a simple client that asks for
+    3GPP LPP Example (3.4.4) - This sample code is a simple client that asks for
     assistance data from a location server. It can handle OSR, SSR, and AGNSS
     requests. The assistance data can converted to RTCM or SPARTN before being
     sent to a GNSS receiver or other interface. The client also supports to 3GPP
@@ -49,6 +49,7 @@ There are a few required arguments:
         -n[mnc], --mnc=[mnc]              Mobile Network Code
         -t[tac], --lac=[tac], --tac=[tac] Tracking Area Code
         -i[ci], --ci=[ci]                 Cell Identity
+        --nr                              The cell specified is a 5G NR cell
       Modem:
         --modem=[device]                  Device
         --modem-baud=[baud_rate]          Baud Rate
@@ -130,14 +131,21 @@ There are a few required arguments:
         Stdout:
           --stdout                          Stdout
       Location Infomation:
-        --location-info                   Location Information
+        --fake-location-info, --fli       Enable sending fake location
+                                          information. Configure with '--fake-*'
+                                          options.
         --force-location-info             Force Location Information (always
                                           send even if not requested)
-        --latitude=[latitude]             Latitude
+        --location-report-unlocked        Send location reports without locking
+                                          the update rate. By default, the
+                                          update rate is locked to 1 second.
+        --fake-latitude=[latitude],
+        --flat=[latitude]                 Fake Latitude
                                           Default: 69.0599730655754
-        --longitude=[longitude]           Longitude
+        --fake-longitude=[longitude],
+        --flon=[longitude]                Fake Longitude
                                           Default: 20.54864403253676
-        --altitude=[altitude]             Altitude
+        --fake-altitude=[altitude],
+        --falt=[altitude]                 Fake Altitude
                                           Default: 0
-
 ```
diff --git a/examples/lpp/location_information.cpp b/examples/lpp/location_information.cpp
@@ -10,6 +10,8 @@
 #include "options.hpp"
 #include "utility/types.h"
 
+using namespace location_information;
+
 bool provide_location_information_callback(UNUSED LocationInformation& location,
                                            UNUSED HaGnssMetrics& metrics, UNUSED void* userdata) {
 #if 0
@@ -52,39 +54,37 @@ bool provide_location_information_callback_ublox(UNUSED LocationInformation& loc
         return false;
     }
 
-    location.tai_time                  = nav_pvt->tai_time();
-    location.latitude                  = nav_pvt->latitude();
-    location.longitude                 = nav_pvt->longitude();
-    location.altitude                  = nav_pvt->altitude();
-    location.horizontal_accuracy       = nav_pvt->h_acc();
-    location.horizontal_speed          = nav_pvt->h_vel();
-    location.horizontal_speed_accuracy = nav_pvt->h_vel_acc();
-    location.bearing                   = nav_pvt->head_mot();
-    location.vertical_accuracy         = nav_pvt->v_acc();
-    location.vertical_speed            = fabs(nav_pvt->v_vel());
-    location.vertical_speed_accuracy   = nav_pvt->v_vel_acc();
-    location.vertical_velocity_direction =
-        nav_pvt->v_vel() > 0 ? VerticalDirection::DOWN : VerticalDirection::UP;
-
-    metrics.fixq = FixQuality::INVALID;
+    auto location_shape = LocationShape::ha_ellipsoid_altitude_with_uncertainty(
+        nav_pvt->latitude(), nav_pvt->longitude(), nav_pvt->altitude(),
+        HorizontalAccuracy::from_ellipse(nav_pvt->h_acc(), nav_pvt->h_acc(), 0),
+        VerticalAccuracy::from_1sigma(nav_pvt->v_acc()));
+
+    auto velocity_shape = VelocityShape::horizontal_vertical_with_uncertainty(
+        nav_pvt->h_vel(), nav_pvt->h_vel_acc(), nav_pvt->head_mot(), fabs(nav_pvt->v_vel()),
+        nav_pvt->v_vel_acc(),
+        nav_pvt->v_vel() > 0 ? VerticalDirection::Down : VerticalDirection::Up);
+
+    location.time     = nav_pvt->tai_time();
+    location.location = location_shape;
+    location.velocity = velocity_shape;
+
+    metrics.fix_quality = FixQuality::INVALID;
     if (nav_pvt->fix_type() == 3) {
         if (nav_pvt->carr_soln() == 2) {
-            metrics.fixq = FixQuality::RTK_FIX;
+            metrics.fix_quality = FixQuality::RTK_FIX;
         } else if (nav_pvt->carr_soln() == 1) {
-            metrics.fixq = FixQuality::RTK_FLOAT;
+            metrics.fix_quality = FixQuality::RTK_FLOAT;
         } else {
-            metrics.fixq = FixQuality::STANDALONE;
+            metrics.fix_quality = FixQuality::STANDALONE;
         }
     } else if (nav_pvt->fix_type() == 2) {
-        metrics.fixq = FixQuality::STANDALONE;
+        metrics.fix_quality = FixQuality::STANDALONE;
     } else if (nav_pvt->fix_type() == 1) {
-        metrics.fixq = FixQuality::DEAD_RECKONING;
+        metrics.fix_quality = FixQuality::DEAD_RECKONING;
     }
 
-    metrics.sats = nav_pvt->num_sv();
-    metrics.age  = 0;  // TODO(ewasjon): requires another message
-    metrics.hdop = 0;
-    metrics.pdop = nav_pvt->p_dop();
+    metrics.number_of_satellites = nav_pvt->num_sv();
+    metrics.pdop                 = nav_pvt->p_dop();
     return true;
 }
 
@@ -102,51 +102,45 @@ bool provide_location_information_callback_nmea(LocationInformation& location,
         return false;
     }
 
-    location.tai_time                  = gga->time_of_day();
-    location.latitude                  = gga->latitude();
-    location.longitude                 = gga->longitude();
-    location.altitude                  = gga->altitude();
-    location.horizontal_accuracy       = gst->horizontal_position_error();
-    location.horizontal_speed          = vtg->speed_over_ground();
-    location.horizontal_speed_accuracy = 0;
-    location.bearing                   = vtg->true_course_over_ground();
-
-    // TODO(ewasjon): Are these not available in NMEA?
-    location.vertical_accuracy           = gst->vertical_position_error();
-    location.vertical_speed              = 0;
-    location.vertical_speed_accuracy     = 0;
-    location.vertical_velocity_direction = VerticalDirection::UP;
+    location.time     = gga->time_of_day();
+    location.location = LocationShape::ha_ellipsoid_altitude_with_uncertainty(
+        gga->latitude(), gga->longitude(), gga->altitude(),
+        HorizontalAccuracy::from_ellipse(gst->semi_major(), gst->semi_minor(), gst->orientation()),
+        VerticalAccuracy::from_1sigma(gst->vertical_position_error()));
+    location.velocity =
+        VelocityShape::horizontal(vtg->speed_over_ground(), vtg->true_course_over_ground());
 
     switch (gga->fix_quality()) {
-    case receiver::nmea::GgaFixQuality::Invalid: metrics.fixq = FixQuality::INVALID; break;
-    case receiver::nmea::GgaFixQuality::GpsFix: metrics.fixq = FixQuality::STANDALONE; break;
-    case receiver::nmea::GgaFixQuality::DgpsFix: metrics.fixq = FixQuality::DGPS_FIX; break;
-    case receiver::nmea::GgaFixQuality::PpsFix: metrics.fixq = FixQuality::PPS_FIX; break;
-    case receiver::nmea::GgaFixQuality::RtkFixed: metrics.fixq = FixQuality::RTK_FIX; break;
-    case receiver::nmea::GgaFixQuality::RtkFloat: metrics.fixq = FixQuality::RTK_FLOAT; break;
+    case receiver::nmea::GgaFixQuality::Invalid: metrics.fix_quality = FixQuality::INVALID; break;
+    case receiver::nmea::GgaFixQuality::GpsFix: metrics.fix_quality = FixQuality::STANDALONE; break;
+    case receiver::nmea::GgaFixQuality::DgpsFix: metrics.fix_quality = FixQuality::DGPS_FIX; break;
+    case receiver::nmea::GgaFixQuality::PpsFix: metrics.fix_quality = FixQuality::PPS_FIX; break;
+    case receiver::nmea::GgaFixQuality::RtkFixed: metrics.fix_quality = FixQuality::RTK_FIX; break;
+    case receiver::nmea::GgaFixQuality::RtkFloat:
+        metrics.fix_quality = FixQuality::RTK_FLOAT;
+        break;
     case receiver::nmea::GgaFixQuality::DeadReckoning:
-        metrics.fixq = FixQuality::DEAD_RECKONING;
+        metrics.fix_quality = FixQuality::DEAD_RECKONING;
         break;
-    default: metrics.fixq = FixQuality::INVALID;
+    default: metrics.fix_quality = FixQuality::INVALID;
     }
 
-    metrics.sats = static_cast<u8>(gga->satellites_in_view());
-    metrics.age  = 0;  // TODO: ?
-    metrics.hdop = gga->h_dop();
-    metrics.pdop = 0;
+    metrics.number_of_satellites = gga->satellites_in_view();
+    metrics.hdop                 = gga->h_dop();
     return true;
 }
 
-bool provide_location_information_callback_fake(UNUSED LocationInformation& location,
+bool provide_location_information_callback_fake(LocationInformation&  location,
                                                 UNUSED HaGnssMetrics& metrics, void* userdata) {
     auto options = reinterpret_cast<LocationInformationOptions*>(userdata);
     if (!options) return false;
 
-    location.tai_time  = TAI_Time::now();
-    location.latitude  = options->latitude;
-    location.longitude = options->longitude;
-    location.altitude  = options->altitude;
+    location.time     = TAI_Time::now();
+    location.location = LocationShape::ha_ellipsoid_altitude_with_uncertainty(
+        options->latitude, options->longitude, options->altitude,
+        HorizontalAccuracy::from_ellipse(0.5, 0.5, 0), VerticalAccuracy::from_1sigma(0.5));
 
+    metrics.fix_quality = FixQuality::STANDALONE;
     return true;
 }
 

diff --git a/examples/lpp/location_information.h b/examples/lpp/location_information.h
@@ -1,16 +1,23 @@
 #pragma once
 
+namespace location_information {
 struct LocationInformation;
 struct HaGnssMetrics;
 struct ECIDInformation;
+}  // namespace location_information
+
 struct LocationInformationOptions;
 
-bool provide_location_information_callback(LocationInformation& location, HaGnssMetrics& metrics,
-                                           void* userdata);
-bool provide_location_information_callback_ublox(LocationInformation& location,
-                                                 HaGnssMetrics& metrics, void* userdata);
-bool provide_location_information_callback_nmea(LocationInformation& location,
-                                                HaGnssMetrics& metrics, void* userdata);
-bool provide_location_information_callback_fake(LocationInformation& location,
-                                                HaGnssMetrics& metrics, void* userdata);
-bool provide_ecid_callback(ECIDInformation& ecid, void* userdata);
+bool provide_location_information_callback(location_information::LocationInformation& location,
+                                           location_information::HaGnssMetrics&       metrics,
+                                           void*                                      userdata);
+bool provide_location_information_callback_ublox(
+    location_information::LocationInformation& location,
+    location_information::HaGnssMetrics& metrics, void* userdata);
+bool provide_location_information_callback_nmea(location_information::LocationInformation& location,
+                                                location_information::HaGnssMetrics&       metrics,
+                                                void* userdata);
+bool provide_location_information_callback_fake(location_information::LocationInformation& location,
+                                                location_information::HaGnssMetrics&       metrics,
+                                                void* userdata);
+bool provide_ecid_callback(location_information::ECIDInformation& ecid, void* userdata);
diff --git a/examples/lpp/options.cpp b/examples/lpp/options.cpp
@@ -307,8 +307,11 @@ args::Group location_infomation{
 };
 
 args::Flag li_enable{
-    location_infomation, "location-info",       "Location Information",
-    {"location-info"},   args::Options::Single,
+    location_infomation,
+    "location-info",
+    "Enable sending fake location information. Configure with '--fake-*' options.",
+    {"fake-location-info", "fli"},
+    args::Options::Single,
 };
 args::Flag li_force{
     location_infomation,
@@ -317,12 +320,29 @@ args::Flag li_force{
     {"force-location-info"},
     args::Options::Single,
 };
-args::ValueFlag<double> li_latitude{
-    location_infomation, "latitude", "Latitude", {"latitude"}, args::Options::Single};
-args::ValueFlag<double> li_longitude{
-    location_infomation, "longitude", "Longitude", {"longitude"}, args::Options::Single};
-args::ValueFlag<double> li_altitude{
-    location_infomation, "altitude", "Altitude", {"altitude"}, args::Options::Single};
+args::Flag li_unlocked{
+    location_infomation,
+    "unlocked",
+    "Send location reports without locking the update rate. By default, the update rate is locked "
+    "to 1 second.",
+    {"location-report-unlocked"},
+    args::Options::Single,
+};
+args::ValueFlag<double> li_latitude{location_infomation,
+                                    "latitude",
+                                    "Fake Latitude",
+                                    {"fake-latitude", "flat"},
+                                    args::Options::Single};
+args::ValueFlag<double> li_longitude{location_infomation,
+                                     "longitude",
+                                     "Fake Longitude",
+                                     {"fake-longitude", "flon"},
+                                     args::Options::Single};
+args::ValueFlag<double> li_altitude{location_infomation,
+                                    "altitude",
+                                    "Fake Altitude",
+                                    {"fake-altitude", "falt"},
+                                    args::Options::Single};
 
 //
 // Options
@@ -738,11 +758,16 @@ static LocationInformationOptions parse_location_information_options() {
     location_information.longitude = 20.54864403253676;
     location_information.altitude  = 0;
     location_information.force     = false;
+    location_information.unlock_update_rate = false;
 
     if (li_force) {
         location_information.force = true;
     }
 
+    if(li_unlocked) {
+        location_information.unlock_update_rate = true;
+    }
+
     if (li_enable) {
         location_information.enabled = true;
         if (li_latitude) {

diff --git a/examples/lpp/options.hpp b/examples/lpp/options.hpp
@@ -91,6 +91,8 @@ struct LocationInformationOptions {
     double longitude;
     /// Fake altitude.
     double altitude;
+    /// Unlock update rate.
+    bool unlock_update_rate;
 };
 
 /// Options.

diff --git a/examples/lpp/osr_example.cpp b/examples/lpp/osr_example.cpp
@@ -191,6 +191,13 @@ void execute(Options options, osr_example::Format format, osr_example::MsmType m
         printf("  force: false\n");
     }
 
+    if(location_information_options.unlock_update_rate) {
+        client.unlock_update_rate();
+        printf("  unlock update rate: true\n");
+    } else {
+        printf("  unlock update rate: false\n");
+    }
+
     client.provide_ecid_callback(gModem.get(), provide_ecid_callback);
 
     if (!client.connect(location_server_options.host.c_str(), location_server_options.port,

diff --git a/examples/lpp/ssr_example.cpp b/examples/lpp/ssr_example.cpp
@@ -172,6 +172,13 @@ void execute(Options options, ssr_example::Format format, int ura_override,
         printf("  force: false\n");
     }
 
+    if (location_information_options.unlock_update_rate) {
+        client.unlock_update_rate();
+        printf("  unlock update rate: true\n");
+    } else {
+        printf("  unlock update rate: false\n");
+    }
+
     client.provide_ecid_callback(gModem.get(), provide_ecid_callback);
 
     if (!client.connect(location_server_options.host.c_str(), location_server_options.port,

diff --git a/examples/ublox/options.cpp b/examples/ublox/options.cpp
@@ -17,11 +17,12 @@ args::Group configuration_group{
     args::Options::Global,
 };
 
-args::Flag disable_config{configuration_group,
-                          "disable",
-                          "Disable configuration",
-                          {"disable-config"},
-                          args::Options::Single};
+args::Flag disable_config{
+    configuration_group,
+    "disable",
+    "Disable loading and storing of configuration. Without this UBX-NAV-PVT will _not_ be enabled.",
+    {"disable-config"},
+    args::Options::Single};
 
 //
 
@@ -213,7 +214,8 @@ static std::unique_ptr<UbloxReceiver> create_receiver() {
 
     auto receiver = std::unique_ptr<UbloxReceiver>(new UbloxReceiver(port, std::move(interface)));
     if (!disable_config) {
-        receiver->configure();
+        receiver->load_configuration();
+        receiver->store_configuration();
     }
 
     return receiver;