Cellular: Power API updated to match onboard_modem_api

Author: Ari Parkkila

UNITTESTS/features/cellular/framework/AT/at_cellulardevice/at_cellulardevicetest.cpp

@@ -209,13 +209,6 @@ TEST_F(TestAT_CellularDevice, test_AT_CellularDevice_init)
     EXPECT_EQ(dev.init(), NSAPI_ERROR_OK);
 }
 
-TEST_F(TestAT_CellularDevice, test_AT_CellularDevice_reset)
-{
-    FileHandle_stub fh1;
-    AT_CellularDevice dev(&fh1);
-    EXPECT_EQ(dev.reset(), NSAPI_ERROR_OK);
-}
-
 TEST_F(TestAT_CellularDevice, test_AT_CellularDevice_shutdown)
 {
     FileHandle_stub fh1;

UNITTESTS/stubs/AT_CellularDevice_stub.cpp

@@ -179,15 +179,6 @@ nsapi_error_t AT_CellularDevice::init()
     return AT_CellularDevice_stub::nsapi_error_value;
 }
 
-nsapi_error_t AT_CellularDevice::reset()
-{
-    if (AT_CellularDevice_stub::init_module_failure_count) {
-        AT_CellularDevice_stub::init_module_failure_count--;
-        return NSAPI_ERROR_DEVICE_ERROR;
-    }
-    return AT_CellularDevice_stub::nsapi_error_value;
-}
-
 nsapi_error_t AT_CellularDevice::shutdown()
 {
     if (AT_CellularDevice_stub::init_module_failure_count) {
@@ -223,12 +214,22 @@ nsapi_error_t AT_CellularDevice::get_sim_state(SimState &state)
     return AT_CellularDevice_stub::nsapi_error_value;
 }
 
-nsapi_error_t AT_CellularDevice::power_on()
+nsapi_error_t AT_CellularDevice::hard_power_on()
 {
-    return NSAPI_ERROR_UNSUPPORTED;
+    return NSAPI_ERROR_OK;
 }
 
-nsapi_error_t AT_CellularDevice::power_off()
+nsapi_error_t AT_CellularDevice::hard_power_off()
 {
-    return NSAPI_ERROR_UNSUPPORTED;
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t AT_CellularDevice::soft_power_on()
+{
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t AT_CellularDevice::soft_power_off()
+{
+    return NSAPI_ERROR_OK;
 }

UNITTESTS/target_h/myCellularDevice.h

@@ -112,29 +112,34 @@ class myCellularDevice : public CellularDevice {
         return NSAPI_ERROR_OK;
     }
 
-    virtual nsapi_error_t reset()
+    virtual nsapi_error_t shutdown()
     {
         return NSAPI_ERROR_OK;
     }
 
-    virtual nsapi_error_t shutdown()
+    virtual nsapi_error_t is_ready()
     {
         return NSAPI_ERROR_OK;
     }
 
-    virtual nsapi_error_t is_ready()
+    virtual nsapi_error_t hard_power_on()
+    {
+        return NSAPI_ERROR_OK;
+    }
+
+    virtual nsapi_error_t hard_power_off()
     {
         return NSAPI_ERROR_OK;
     }
 
-    virtual nsapi_error_t power_on()
+    virtual nsapi_error_t soft_power_on()
     {
-        return NSAPI_ERROR_UNSUPPORTED;
+        return NSAPI_ERROR_OK;
     }
 
-    virtual nsapi_error_t power_off()
+    virtual nsapi_error_t soft_power_off()
     {
-        return NSAPI_ERROR_UNSUPPORTED;
+        return NSAPI_ERROR_OK;
     }
 
     virtual void set_ready_cb(Callback<void()> callback)

features/cellular/TESTS/api/cellular_device/main.cpp

@@ -108,8 +108,6 @@ static void shutdown_reset()
     TEST_ASSERT(device->set_device_ready() == NSAPI_ERROR_OK);
     TEST_ASSERT(device->shutdown() == NSAPI_ERROR_OK);
     TEST_ASSERT(device->set_device_ready() == NSAPI_ERROR_OK);
-    TEST_ASSERT(device->reset() == NSAPI_ERROR_OK);
-    TEST_ASSERT(device->set_device_ready() == NSAPI_ERROR_OK);
 }
 
 static void delete_device()

features/cellular/framework/API/CellularDevice.h

@@ -84,23 +84,42 @@ class CellularDevice {
      */
     virtual ~CellularDevice();
 
-    /** Set cellular device power on.
+    /** Set cellular device power supply on.
      *
-     *  @post init must be called after power_on to setup module
+     *  CellularStateMachine calls hard_power_on, soft_power_on and init when requested to connect
+     *  if the modem is not responding.
+     *
+     *  @post You must call soft_power_on to power on the modem after calling hard_power_on.
+     *
+     *  @return         NSAPI_ERROR_OK on success
+     */
+    virtual nsapi_error_t hard_power_on() = 0;
+
+    /** Set cellular device power supply off.
+     *
+     *  CellularStateMachine disconnect does not shutdown or power off the modem.
+     *
+     *  @pre You must call soft_power_off to power off the modem before calling hard_power_off.
+     *
+     *  @return         NSAPI_ERROR_OK on success
+     */
+    virtual nsapi_error_t hard_power_off() = 0;
+
+    /** Set cellular device power on, i.e. start the modem.
+     *
+     *  @post You must call init to setup the modem.
      *
      *  @return         NSAPI_ERROR_OK on success
-     *                  NSAPI_ERROR_UNSUPPORTED if there is no implementation
      */
-    virtual nsapi_error_t power_on() = 0;
+    virtual nsapi_error_t soft_power_on() = 0;
 
     /** Set cellular device power off.
      *
-     *  @pre shutdown must be called before power_down to quit cellular network
+     *  @pre You must call shutdown to prepare the modem for power off.
      *
      *  @return         NSAPI_ERROR_OK on success
-     *                  NSAPI_ERROR_UNSUPPORTED if there is no implementation
      */
-    virtual nsapi_error_t power_off() = 0;
+    virtual nsapi_error_t soft_power_off() = 0;
 
     /** Open the SIM card by setting the pin code for SIM.
      *
@@ -290,28 +309,28 @@ class CellularDevice {
      */
     virtual void modem_debug_on(bool on) = 0;
 
-    /** Initialize cellular device must be called right after module is ready.
+    /** Initialize cellular device must be called right after the module is ready.
+     *
      *  For example, when multiple cellular modules are supported in a single driver this function
      *  detects and adapts to an actual module at runtime.
      *
+     *  CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
+     *  until the modem responds.
+     *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
-     *                  NSAPI_ERROR_UNSUPPORTED if current model is not detected
+     *                  NSAPI_ERROR_UNSUPPORTED if current cellular module type is not detected
      *                  NSAPI_ERROR_DEVICE_ERROR if model information could not be read
      *
      */
     virtual nsapi_error_t init() = 0;
 
-    /** Reset and wake-up cellular device.
+    /** Shutdown cellular device to minimum functionality.
      *
-     *  @remark reset calls shutdown implicitly.
+     *  Actual functionality is modem specific, for example UART may is not be responsive without
+     *  explicit wakeup signal (such as RTS) after shutdown.
      *
-     *  @return         NSAPI_ERROR_OK on success
-     *                  NSAPI_ERROR_DEVICE_ERROR on failure
-     */
-    virtual nsapi_error_t reset() = 0;
-
-    /** Shutdown cellular device to minimum functionality.
+     *  @remark You must call shutdown before power off to prepare the modem and to quit cellular network.
      *
      *  @return         NSAPI_ERROR_OK on success
      *                  NSAPI_ERROR_DEVICE_ERROR on failure

features/cellular/framework/AT/AT_CellularDevice.cpp

@@ -69,14 +69,24 @@ AT_CellularDevice::~AT_CellularDevice()
     release_at_handler(_at);
 }
 
-nsapi_error_t AT_CellularDevice::power_on()
+nsapi_error_t AT_CellularDevice::hard_power_on()
 {
-    return NSAPI_ERROR_UNSUPPORTED;
+    return NSAPI_ERROR_OK;
 }
 
-nsapi_error_t AT_CellularDevice::power_off()
+nsapi_error_t AT_CellularDevice::hard_power_off()
 {
-    return NSAPI_ERROR_UNSUPPORTED;
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t AT_CellularDevice::soft_power_on()
+{
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t AT_CellularDevice::soft_power_off()
+{
+    return NSAPI_ERROR_OK;
 }
 
 // each parser is associated with one filehandle (that is UART)
@@ -355,15 +365,6 @@ nsapi_error_t AT_CellularDevice::init()
     return _at->unlock_return_error();
 }
 
-nsapi_error_t AT_CellularDevice::reset()
-{
-    _at->lock();
-    shutdown();
-    _at->cmd_start("AT+CFUN=1,1");// reset to full functionality
-    _at->cmd_stop_read_resp();
-    return _at->unlock_return_error();
-}
-
 nsapi_error_t AT_CellularDevice::shutdown()
 {
     _at->lock();

features/cellular/framework/AT/AT_CellularDevice.h

@@ -39,9 +39,13 @@ class AT_CellularDevice : public CellularDevice {
     AT_CellularDevice(FileHandle *fh);
     virtual ~AT_CellularDevice();
 
-    virtual nsapi_error_t power_on();
+    virtual nsapi_error_t hard_power_on();
 
-    virtual nsapi_error_t power_off();
+    virtual nsapi_error_t hard_power_off();
+
+    virtual nsapi_error_t soft_power_on();
+
+    virtual nsapi_error_t soft_power_off();
 
     virtual nsapi_error_t set_pin(const char *sim_pin);
 
@@ -73,8 +77,6 @@ class AT_CellularDevice : public CellularDevice {
 
     virtual nsapi_error_t init();
 
-    virtual nsapi_error_t reset();
-
     virtual nsapi_error_t shutdown();
 
     virtual nsapi_error_t is_ready();

features/cellular/framework/device/CellularStateMachine.cpp

@@ -109,13 +109,9 @@ void CellularStateMachine::stop()
 
 bool CellularStateMachine::power_on()
 {
-    _cb_data.error = _cellularDevice.power_on();
-    if (_cb_data.error != NSAPI_ERROR_OK && _cb_data.error != NSAPI_ERROR_UNSUPPORTED) {
-        tr_warn("Power on failed. Try to power off/on.");
-        _cb_data.error = _cellularDevice.power_off();
-        if (_cb_data.error != NSAPI_ERROR_OK && _cb_data.error != NSAPI_ERROR_UNSUPPORTED) {
-            tr_error("Power off failed!");
-        }
+    _cb_data.error = _cellularDevice.hard_power_on();
+    if (_cb_data.error != NSAPI_ERROR_OK) {
+        tr_warn("Power on failed.");
         return false;
     }
     return true;
@@ -384,14 +380,16 @@ bool CellularStateMachine::device_ready()
 void CellularStateMachine::state_device_ready()
 {
     _cellularDevice.set_timeout(TIMEOUT_POWER_ON);
-    _cb_data.error = _cellularDevice.init();
+    _cb_data.error = _cellularDevice.soft_power_on();
     if (_cb_data.error == NSAPI_ERROR_OK) {
-        if (device_ready()) {
-            enter_to_state(STATE_SIM_PIN);
-        } else {
-            retry_state_or_fail();
+        _cb_data.error = _cellularDevice.init();
+        if (_cb_data.error == NSAPI_ERROR_OK) {
+            if (device_ready()) {
+                enter_to_state(STATE_SIM_PIN);
+            }
         }
-    } else {
+    }
+    if (_cb_data.error != NSAPI_ERROR_OK) {
         if (_retry_count == 0) {
             _cellularDevice.set_ready_cb(callback(this, &CellularStateMachine::device_ready_cb));
         }

features/cellular/framework/targets/QUECTEL/BC95/QUECTEL_BC95.cpp

@@ -91,16 +91,6 @@ nsapi_error_t QUECTEL_BC95::init()
     return _at->unlock_return_error();
 }
 
-nsapi_error_t QUECTEL_BC95::reset()
-{
-    _at->lock();
-    AT_CellularDevice::shutdown();
-    _at->cmd_start("AT+NRB"); // reset to full power levels
-    _at->cmd_stop();
-    _at->resp_start("REBOOTING", true);
-    return _at->unlock_return_error();
-}
-
 #if MBED_CONF_QUECTEL_BC95_PROVIDE_DEFAULT
 #include "UARTSerial.h"
 CellularDevice *CellularDevice::get_default_instance()

features/cellular/framework/targets/QUECTEL/BC95/QUECTEL_BC95.h

@@ -43,7 +43,6 @@ class QUECTEL_BC95 : public AT_CellularDevice {
     virtual AT_CellularContext *create_context_impl(ATHandler &at, const char *apn, bool cp_req = false, bool nonip_req = false);
     virtual AT_CellularInformation *open_information_impl(ATHandler &at);
     virtual nsapi_error_t init();
-    virtual nsapi_error_t reset();
 
 public: // NetworkInterface
     void handle_urc(FileHandle *fh);

targets/TARGET_NXP/TARGET_LPC176X/TARGET_UBLOX_C027/ONBOARD_UBLOX_PPP.cpp

@@ -25,17 +25,27 @@ ONBOARD_UBLOX_PPP::ONBOARD_UBLOX_PPP(FileHandle *fh) : UBLOX_PPP(fh)
 {
 }
 
-nsapi_error_t ONBOARD_UBLOX_PPP::power_on()
+nsapi_error_t ONBOARD_UBLOX_PPP::hard_power_on()
 {
     ::onboard_modem_init();
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t ONBOARD_UBLOX_PPP::hard_power_off()
+{
+    ::onboard_modem_deinit();
+    return NSAPI_ERROR_OK;
+}
+
+nsapi_error_t ONBOARD_UBLOX_PPP::soft_power_on()
+{
     ::onboard_modem_power_up();
     return NSAPI_ERROR_OK;
 }
 
-nsapi_error_t ONBOARD_UBLOX_PPP::power_off()
+nsapi_error_t ONBOARD_UBLOX_PPP::soft_power_off()
 {
     ::onboard_modem_power_down();
-    ::onboard_modem_deinit();
     return NSAPI_ERROR_OK;
 }
 

targets/TARGET_NXP/TARGET_LPC176X/TARGET_UBLOX_C027/ONBOARD_UBLOX_PPP.h

@@ -24,8 +24,11 @@ namespace mbed {
 class ONBOARD_UBLOX_PPP : public UBLOX_PPP {
 public:
     ONBOARD_UBLOX_PPP(FileHandle *fh);
-    virtual nsapi_error_t power_on();
-    virtual nsapi_error_t power_off();
+
+    virtual nsapi_error_t hard_power_on();
+    virtual nsapi_error_t hard_power_off();
+    virtual nsapi_error_t soft_power_on();
+    virtual nsapi_error_t soft_power_off();
 };
 
 } // namespace mbed