Port API addition and cellular feature for ESP-IDF/Zephyr: PPP-level …

…integration.

This commit introduces the concept of a PPP interface to ubxlib, only for the ESP-IDF and Zephyr platforms and with a cellular transport.  It allows the native application protocols of these platforms to be used with cellular.

The PPP interface is defined as a new port API, which includes a default implementation that does nothing so that no existing ports are adversely affected by it.  This port API is, internally, called from the cellular code, such that when the cellular network is up the PPP interface of the port layer is automatically activated, connecting into the PPP layer at the bottom of the IP stack of the platform.

This is currently only supported with SARA-R5 and SARA-R422 cellular modules.  U_CFG_PPP_ENABLE must be defined when building ubxlib to enable PPP.

Of course, for this to integrate with the platform there will be additional build requirements related to the platform itself (enabling the right components of the platform etc.): see the README.md in the ESP-IDF and Zephyr platform directories for details.

Examples are added to the sockets example set showing how to use native ESP-IDF/Zephyr sockets with PPP.

Test: 1 2 6.1 6.2.0 6.2.1 12.0 13.0.0 18 22.0 22.1 cellPpp.zephyr.espidf.examplePpp

README.md

@@ -162,14 +162,15 @@ Configuration information for the examples and the tests can be found in the `cf
 A number of examples are provided with this repo:
 
 |  Technology  | Example |
-|--------------|----------|
+|--------------|---------|
 | Cellular     | The [sockets](/example/sockets "socket example") example brings up a TCP/UDP socket by using the [device](/common/device "device API"), [network](/common/network "network API") and [sock](/common/sock "sock API") APIs.  |
-| Cellular     | The [PSK generation](/example/security/psk "PSK example") example using the [security](/common/security "security API") API. |
 | Cellular     | A [TLS-secured version](/example/sockets "TLS sockets example") of the sockets example. |
 | Cellular     | A [DTLS-secured version](/example/sockets "DTLS sockets example") of the sockets example. |
+| Cellular     | A [PPP version](/example/sockets "PPP sockets example") of the sockets example that shows how the platform IP stack/applications can use a cellular connection. |
 | Cellular     | An [MQTT/MQTT-SN client](/example/mqtt_client "MQTT/MQTT-SN example") using the [MQTT/MQTT-SN client](/common/mqtt_client "MQTT/MQTT-SN client API") API.|
 | Cellular     | An [HTTP client](/example/http_client "HTTP example") using the [HTTP client](/common/http_client "HTTP client API") API.|
 | Cellular     | [CellLocate](/example/location "CellLocate example") example.|
+| Cellular     | The [PSK generation](/example/security/psk "PSK example") example using the [security](/common/security "security API") API. |
 | Bluetooth    | See the BLE examples in the [XPLR-IOT-1 ubxlib examples repo](https://github.com/u-blox/ubxlib_examples_xplr_iot/tree/master/examples). |
 | Wi-Fi        | The [sockets](/example/sockets "sockets example") example brings up a TCP/UDP socket by using the [device](/common/device "device API"), [network](/common/network "network API") and [sock](/common/sock "sock API") APIs.  |
 | GNSS         | [location](/example/location "location example") example using a GNSS chip connected directly or via a cellular module.|
@@ -227,7 +228,7 @@ The software in this repository is Apache 2.0 licensed and copyright u-blox with
 - The ARM callstack iterator in [port/platform/common/debug_utils/src/arch/arm/u_stack_frame_cortex.c](/port/platform/common/debug_utils/src/arch/arm/u_print_callstack_cortex.c) is copyright Armink, part of [CmBacktrace](https://github.com/armink/CmBacktrace).
 - The FreeRTOS additions [port/platform/common/debug_utils/src/freertos/additions](/port/platform/common/debug_utils/src/freertos/additions) are copied from the Apache licensed [ESP-IDF](https://github.com/espressif/esp-idf).
 - If you compile-in geofencing by defining the conditional compilation flag `U_CFG_GEOFENCE` for your build:
-  - For shapes larger than about 1 km, to employ a true-earth model you may choose to conditionally link the sub-module [common/geofence/geographiclib](geographiclib) from the MIT licensed [GeographicLib](https://github.com/geographiclib) by Charles A. Karney.
+  - For shapes larger than about 1 km, to employ a true-earth model you may choose to conditionally link the sub-module [common/geofence](geographiclib) from the MIT licensed [GeographicLib](https://github.com/geographiclib) by Charles A. Karney.
   - The default functions, which assume a spherical earth, are derived from the valuable advice (though not the code) of https://www.movable-type.co.uk/scripts/latlong.html, MIT licensed and copyright Chris Veness.
 
 In all cases copyright, and our thanks, remain with the original authors.

cell/README.md

@@ -128,4 +128,13 @@ int app_start() {
 
     while(1);
 }
-```
+```
+
+# PPP-Level Integration With A Platform
+PPP-level integration between the bottom of a platform's IP stack and cellular is supported on some platforms and some module types, currently only ESP-IDF with SARA-R5 or SARA-R422.  This allows the native clients of the platform (e.g. MQTT etc.) to be used in your application with a cellular transport beneath them.
+
+To enable this integration you must define `U_CFG_PPP_ENABLE` for your build.  Other switches/components/whatevers may also be required on the platform side: see the README.md in the relevant platform directory for details.
+
+To use the integration, just make a cellular connection with `ubxlib` in the usual way and the connection will be available to the platform.
+
+Note: if you are required to supply a username and password for your connection then, when using PPP, you must call `uCellNetSetAuthenticationMode()` to set the authentication mode explicitly; automatic authentication mode will not work with PPP.

cell/api/u_cell_mux.h

@@ -53,10 +53,10 @@ extern "C" {
 #define U_CELL_MUX_CHANNEL_ID_GNSS 0xFF
 
 #ifndef U_CELL_MUX_MAX_CHANNELS
-/** Enough room for the control channel, an AT channel and a
- * GNSS serial channel.
+/** Enough room for the control channel, an AT channel, a
+ * GNSS serial channel and potentially a PPP data channel.
  */
-# define U_CELL_MUX_MAX_CHANNELS 3
+# define U_CELL_MUX_MAX_CHANNELS 4
 #endif
 
 /* ----------------------------------------------------------------

cell/api/u_cell_net.h

@@ -270,6 +270,10 @@ typedef enum {
 } uCellNetRegDomain_t;
 
 /** The possible authentication modes for the network connection.
+ *
+ * Note: there is also a #uPortPppAuthenticationMode_t enumeration
+ * which is set to match this one.  If you make a change here you
+ * may need to make a change there also.
  */
 typedef enum {
     U_CELL_NET_AUTHENTICATION_MODE_NONE = 0, /**< \deprecated please use #U_CELL_NET_AUTHENTICATION_MODE_NOT_SET. */

cell/src/u_cell.c

@@ -60,6 +60,7 @@
 #include "u_cell_private.h" // don't change it
 #include "u_cell_mux.h"
 #include "u_cell_mux_private.h"
+#include "u_cell_ppp_private.h"
 
 // The headers below necessary to work around an Espressif linker problem, see uCellInit()
 #include "u_sock.h"
@@ -143,6 +144,8 @@ static void removeCellInstance(uCellPrivateInstance_t *pInstance)
             uPortFree(pInstance->pFotaContext);
             // Free any HTTP context
             uCellPrivateHttpRemoveContext(pInstance);
+            // Free any PPP context
+            uCellPppPrivateRemoveContext(pInstance);
             // Free any CMUX context
             uCellMuxPrivateRemoveContext(pInstance);
             // Free any CellTime context