Cellular: Add API to clear CellularDevice

A new API `CellularDevice::clear()` to clean-up the modem to a default initial state.
Function is virtual so it can be overridden. The default implementation clears all PDP contexts,
but the the first one if that has APN defined as `nsapi.default-cellular-apn`.

CellularStateMachine calls `clear()` to clean-up the modem on initial `connect()`,
if the flag `cellular.clear-on-connect: true` is defined.

Author: Ari Parkkila

features/cellular/framework/API/CellularDevice.h

@@ -90,6 +90,18 @@ class CellularDevice {
      */
     virtual ~CellularDevice();
 
+    /** Clear modem to a default initial state
+     *
+     *  Clear persistent user data from the modem, such as PDP contexts.
+     *
+     *  @pre All open network services on modem, such as contexts and sockets, must be closed.
+     *  @post Modem power off/on may be needed to clear modem's runtime state.
+     *  @remark CellularStateMachine calls this on connect when `cellular.clear-on-connect: true`.
+     *
+     *  @return         NSAPI_ERROR_OK on success, otherwise modem may be need power cycling
+     */
+    virtual nsapi_error_t clear();
+
     /** Sets the modem up for powering on
      *  This is equivalent to plugging in the device, i.e., attaching power and serial port.
      *  In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer

features/cellular/framework/AT/AT_CellularDevice.cpp

@@ -613,3 +613,12 @@ void AT_CellularDevice::cellular_callback(nsapi_event_t ev, intptr_t ptr, Cellul
     }
     CellularDevice::cellular_callback(ev, ptr, ctx);
 }
+
+nsapi_error_t AT_CellularDevice::clear()
+{
+    AT_CellularNetwork *net = static_cast<AT_CellularNetwork *>(open_network());
+    nsapi_error_t err = net->clear();
+    close_network();
+
+    return err;
+}

features/cellular/framework/AT/AT_CellularDevice.h

@@ -39,6 +39,8 @@ class AT_CellularDevice : public CellularDevice {
     AT_CellularDevice(FileHandle *fh);
     virtual ~AT_CellularDevice();
 
+    virtual nsapi_error_t clear();
+
     virtual nsapi_error_t hard_power_on();
 
     virtual nsapi_error_t hard_power_off();

features/cellular/framework/AT/AT_CellularNetwork.cpp

@@ -630,3 +630,63 @@ nsapi_error_t AT_CellularNetwork::set_packet_domain_event_reporting(bool on)
 
     return _at.at_cmd_discard("+CGEREP", "=", "%d", on ? 1 : 0);
 }
+
+nsapi_error_t AT_CellularNetwork::clear()
+{
+    tr_info("AT_CellularNetwork::clear");
+
+    _at.lock();
+    _at.cmd_start_stop("+CGDCONT", "?");
+    _at.resp_start("+CGDCONT:");
+
+    struct context_s {
+        context_s() : id(-1), next(0)
+        {
+        }
+        int id;
+        context_s *next;
+    };
+    CellularList<context_s> contexts;
+    while (_at.info_resp()) {
+        int cid = _at.read_int();
+        // clear all but the default context
+        if (cid <= 0) {
+            continue;
+        } else if (cid == 1) {
+#ifndef MBED_CONF_NSAPI_DEFAULT_CELLULAR_APN
+            continue;
+#else
+            char pdp_type_from_context[10];
+            int pdp_type_len = _at.read_string(pdp_type_from_context, sizeof(pdp_type_from_context));
+            if (pdp_type_len > 0) {
+                char apn[MAX_ACCESSPOINT_NAME_LENGTH];
+                int apn_len = _at.read_string(apn, sizeof(apn));
+                if (apn_len >= 0) {
+                    if (strcmp(apn, MBED_CONF_NSAPI_DEFAULT_CELLULAR_APN) == 0) {
+                        continue;
+                    }
+                }
+            }
+#endif
+        }
+        contexts.add_new()->id = cid;
+    }
+    _at.resp_stop();
+    if (contexts.get_head()) {
+        // detach from network before delete contexts
+        CellularNetwork::AttachStatus status = CellularNetwork::Detached;
+        if (get_attach(status) == NSAPI_ERROR_OK && status == CellularNetwork::Attached) {
+            if (_at.at_cmd_discard("+CGATT", "=0") != NSAPI_ERROR_OK) {
+                tr_warn("Failed to detach from network");
+            }
+        }
+        context_s *context = contexts.get_head();
+        while (context) {
+            if (_at.at_cmd_discard("+CGDCONT", "=", "%d", context->id) != NSAPI_ERROR_OK) {
+                tr_warn("Clear context %d failed", context->id);
+            }
+            context = context->next;
+        }
+    }
+    return _at.unlock_return_error();
+}

features/cellular/framework/AT/AT_CellularNetwork.h

@@ -110,6 +110,13 @@ class AT_CellularNetwork : public CellularNetwork, public AT_CellularBase {
      *  Can be overridden by the target class.
      */
     virtual void get_context_state_command();
+
+    /** Clear the network and contexts to a known default state
+     *
+     *  @return         NSAPI_ERROR_OK on success
+     */
+    nsapi_error_t clear();
+
 private:
     void urc_creg();
     void urc_cereg();

features/cellular/framework/device/CellularDevice.cpp

@@ -247,4 +247,9 @@ void CellularDevice::set_retry_timeout_array(const uint16_t timeout[], int array
     }
 }
 
+nsapi_error_t CellularDevice::clear()
+{
+    return NSAPI_ERROR_OK;
+}
+
 } // namespace mbed

features/cellular/framework/device/CellularStateMachine.cpp

@@ -345,6 +345,16 @@ bool CellularStateMachine::device_ready()
     }
 #endif // MBED_CONF_CELLULAR_DEBUG_AT
 
+#ifdef MBED_CONF_CELLULAR_CLEAR_ON_CONNECT
+    if (_cellularDevice.clear() != NSAPI_ERROR_OK) {
+        tr_warning("Failed to clear cellular device, now power cycling");
+        (void) _cellularDevice.shutdown();
+        (void) _cellularDevice.soft_power_off();
+        (void) _cellularDevice.hard_power_off();
+        return false;
+    }
+#endif
+
     send_event_cb(CellularDeviceReady);
     _cellularDevice.set_ready_cb(0);
 

features/cellular/mbed_lib.json

@@ -24,6 +24,10 @@
         "offload-dns-queries" : {
             "help": "Use modem IP stack for DNS queries, null or numeric simultaneous queries",
             "value": null
+        },
+        "clear-on-connect" : {
+            "help": "Clear modem to a known default state on connect()",
+            "value": true
         }
     }
 }