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

…integration. (#1067)

See ADDITIONAL NOTES at the end of this commit message for information on other, consequential, changes included in this commit.

This commit introduces the concept of a PPP interface to ubxlib, only for the ESP-IDF and Zephyr platforms (see note about Zephyr below) and with a cellular transport.  It allows the native application protocols of these platforms to be used with cellular.  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.

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 (and uNetworkInterfaceUp() will return an error if it does not).

NOTE TO ZEPHYR USERS:
There is an issue in Zephyr PPP, discussed here zephyrproject-rtos/zephyr#67627, which means that Zephyr does not shut the PPP link down properly, leaving the module connected, so it will not connect again next time around unless the module is power cycled or rebooted.  A workaround for the problem is included in this commit, so everything works fine, _except_ that when a cellular connection is disconnected Zephyr must be allowed 20 seconds for its side of the PPP connection to time out; this delay is included within the ubxlib code.  If you do not want this delay (e.g. because you are going to switch the cellular module off anyway, or because your application is not going to connect again for at least 20 seconds) then you can remove it by defining U_CFG_PPP_ZEPHYR_TERMINATE_WAIT_DISABLE.

Once the Zephyr issue is fixed and the fix is available in a version of Zephyr that forms a part of nRFConnect SDK the delay will be removed.

ADDITIONAL NOTES:
- CMUX is now fixed to have separate mutexes for Tx and Rx paths; a single mutex was fine as a simplification when relatively low-bandwidth applications were in play but it is no longer good enough with bi-directional, higher speed, PPP traffic,
- additional debug has been added to the CMUX: see U_CELL_MUX_ENABLE_USER_TX_DEBUG and U_CELL_MUX_HEX_DEBUG (as well as the existing U_CELL_MUX_ENABLE_USER_TX_DEBUG) in u_cell_mux.c,
- in the "runner" build for nRF5SDK we have moved 1 kbytes from main task stack to heap, otherwise our test requirements that at least 5 kbytes of heap and 5 kbytes of main task stack remain for the user application were not being met; obviously you will have tuned these values for your application in any case,
- we notice that the stack size requirements for ESP-IDF tasks, even ones apparently unrelated to IP, increase somewhat when the IP stack is compiled-in; beware!

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.

ble/src/u_ble_sps_extmod.c

@@ -60,7 +60,7 @@
 
 #define U_SHORT_RANGE_BT_ADDRESS_SIZE 14
 
-#define U_BLE_SPS_EVENT_STACK_SIZE 1536
+#define U_BLE_SPS_EVENT_STACK_SIZE 2048
 #define U_BLE_SPS_EVENT_PRIORITY (U_CFG_OS_PRIORITY_MAX - 5)
 
 /* ----------------------------------------------------------------

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
 
 /* ----------------------------------------------------------------
@@ -232,6 +232,14 @@ int32_t uCellMuxRemoveChannel(uDeviceHandle_t cellHandle,
  * originally passed to uCellAdd(); uCellAtClientHandleGet() will reflect
  * this change.
  *
+ * IMPORTANT: if you have compiled with U_CFG_ENABLE_PPP, in order to
+ * use the native OS IP stack with a cellular connection, you should
+ * NOT call this function; it would result in the PPP connection, which
+ * uses the multiplexer, being terminated without notice and you will
+ * find that any subsequent attempt to make a PPP connection to the
+ * module will fail (since the previous one is still up), until you
+ * have power-cycled or rebooted the module.
+ *
  * @param cellHandle the handle of the cellular instance.
  * @return           zero on success or negative error code on failure.
  */

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