Diff: UbloxCellularBase.h

Revision:

23:eaab8e812a5d

Parent:

22:779971811c46

--- a/UbloxCellularBase.h	Wed Apr 10 12:05:55 2019 +0500
+++ b/UbloxCellularBase.h	Fri May 03 13:43:49 2019 +0500
@@ -75,6 +75,14 @@
         EPS_EMERGENCY_SERVICES_ONLY = 8
     } NetworkRegistrationStatusEps;
 
+    /** modem PSM states.
+     *
+     */
+    typedef enum {
+        AWAKE = 0,
+        ASLEEP = 1
+    } ModemPSMState;
+
     /** Initialise the modem, ready for use.
      *
      *  @param pin     PIN for the SIM card.
@@ -256,11 +264,98 @@
      */
     bool get_modem_rat(int *selected_rat, int *preferred_rat, int *second_preferred_rat);
 
-    /** reboot the modem using AT+CFUN=15.
+    /** reboot the modem using AT+CFUN=15. Application should call init() or connect() before making any other API calls.
      *
      * @return        true if successful, otherwise false.
      */
     bool reboot_modem();
+
+#ifdef TARGET_UBLOX_C030_R412M
+    /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
+     * It is recommended to set a flag/event/signal in callback and application can use that to wake up the modem and re-initialize it
+     *
+     * application callback for modem going in to PSM sleep
+     *
+     * @param func     callback function to be executed when modem is going in to PSM sleep
+     * @param param    parameter to be passed to callback function.
+     */
+    void attach_cb_psm_going_in(Callback<void(void*)> func, void *param)
+    {
+        _func_psm_going_in = func;
+        _cb_param_psm_going_in = param;
+    }
+
+    /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
+     * It is recommended to set a flag/event/signal in callback and application can use that to wake up the modem and re-initialize it
+     *
+     * application callback for modem coming out of PSM sleep
+     *
+     * @param func     callback function to be executed when modem is coming out of PSM sleep.
+     * @param param    parameter to be passed to callback function.
+     */
+    void attach_cb_psm_coming_out(Callback<void(void*)> func, void *param)
+    {
+        _func_psm_coming_out = func;
+        _cb_param_psm_coming_out = param;
+    }
+
+    /** de-register the application callback for modem going in to PSM sleep
+     *
+     */
+    void detach_cb_psm_going_in()
+    {
+        _func_psm_going_in = NULL;
+        _cb_param_psm_going_in = NULL;
+    }
+
+    /** de-register application callback for modem coming out of PSM sleep
+     *
+     */
+    void detach_cb_psm_coming_out()
+    {
+        _func_psm_coming_out = NULL;
+        _cb_param_psm_coming_out = NULL;
+    }
+
+    /** Enable or disable the 3GPP PSM.
+     *
+     *  Note: Application should reboot the module after enabling PSM in order to enter PSM state. (reboot_modem())
+     *  Note: Modem can be woken up by toggling the power-on signal. (wakeup_modem())
+     *  Note: When device enters PSM, all connections(PPP, sockets) and settings that are not saved in NV memory(ATE0, CREG etc) are lost.
+     *        host application should be prepared to re-initialize the modem and re-establish the connections.
+     *  Note: PSM is disabled if both periodic_time and active_time are 0.
+     *  Note: Not all variants/firmware versions support PSM URCs and in that case function will return false.
+     *
+     *  PSM string encoding code is borrowed from AT_CellularPower.cpp
+     *
+     * @param periodic_time    requested periodic TAU in seconds.
+     * @param active_time      requested active time in seconds.
+     * @param func             callback function to execute when modem goes to sleep
+     * @param ptr              parameter to callback function
+     * @return         True if successful, otherwise false.
+     */
+    bool set_power_saving_mode(int periodic_tau, int active_time);
+
+    /** Reads the 3GPP PSM status (enabled or disabled) and returns assigned periodic tau and active time values.
+     *
+     * @param status           0: PSM disabled, 1: PSM enabled
+     * @param periodic_tau     assigned periodic TAU in seconds.
+     * @param active_time      assigned active time in seconds
+     * @return         True if command successful, otherwise false.
+     */
+    bool get_power_saving_mode(int *status, int *periodic_tau, int *active_time);
+
+    /** Wake up the modem from PSM. Ref to comment on set_power_saving_mode, application should call init() or connect()
+     * before making any other API calls.
+     */
+    void wakeup_modem();
+
+    /** True if the modem is not in PSM sleep
+     * otherwise false.
+     */
+    bool is_modem_awake();
+#endif
+
 protected:
 
     #define OUTPUT_ENTER_KEY  "\r"
@@ -323,6 +418,9 @@
         volatile NetworkRegistrationStatusCsd reg_status_csd; //!< Circuit switched attach status.
         volatile NetworkRegistrationStatusPsd reg_status_psd; //!< Packet switched attach status.
         volatile NetworkRegistrationStatusEps reg_status_eps; //!< Evolved Packet Switched (e.g. LTE) attach status.
+#ifdef TARGET_UBLOX_C030_R412M
+        volatile ModemPSMState modem_psm_state; //!< last known modem PSM state
+#endif
     } DeviceInfo;
 
     /* IMPORTANT: the variables below are available to
@@ -492,6 +590,19 @@
      */
     bool initialise_sim_card();
 
+#ifdef TARGET_UBLOX_C030_R412M
+    /** Converts the given uint to binary string. Fills the given str starting from [0] with the number of bits defined by bit_cnt
+     *  For example uint_to_binary_string(9, str, 10) would fill str "0000001001"
+     *  For example uint_to_binary_string(9, str, 3) would fill str "001"
+     *
+     *  @param num       uint to converts to binary string
+     *  @param str       buffer for converted binary string
+     *  @param str_size  size of the str buffer
+     *  @param bit_cnt   defines how many bits are filled to buffer started from lsb
+     */
+    void uint_to_binary_str(uint32_t num, char* str, int str_size, int bit_cnt);
+#endif
+
 private:
 
     void set_nwk_reg_status_csd(int status);
@@ -509,6 +620,15 @@
     void CGREG_URC();
     void CEREG_URC();
     void UMWI_URC();
+#ifdef TARGET_UBLOX_C030_R412M
+    void UUPSMR_URC();
+    bool _psm_status;
+    void *_cb_param_psm_going_in;
+    Callback<void(void*)>    _func_psm_going_in;  /**< Callback. */
+    void *_cb_param_psm_coming_out;
+    Callback<void(void*)>    _func_psm_coming_out;  /**< Callback. */
+    void set_modem_psm_state(int state);
+#endif
 };
 
 #endif // _UBLOX_CELLULAR_BASE_