UbloxCellularBase.h

00001 /* Copyright (c) 2019 ARM Limited
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef _UBLOX_CELLULAR_BASE_
00017 #define _UBLOX_CELLULAR_BASE_
00018 
00019 #include "mbed.h"
00020 #include "mbed_toolchain.h" // for MBED_DEPRECATED
00021 #include "UbloxATCmdParser.h"
00022 #include "FileHandle.h"
00023 
00024 #ifdef TARGET_UBLOX_C030_R410M
00025 #define MAX_NUM_PROFILES 12 //ref to enum MNOProfile
00026 #elif TARGET_UBLOX_C030_R412M
00027 #define MAX_NUM_PROFILES 7
00028 #endif
00029 
00030 /**********************************************************************
00031  * CLASSES
00032  **********************************************************************/
00033 
00034 /** UbloxCellularBase class.
00035  *
00036  *  This class provides all the base support for generic u-blox modems
00037  *  on C030 and C027 boards: module identification, power-up, network
00038  *  registration, etc.
00039  */
00040 class UbloxCellularBase {
00041 
00042 public:
00043     /** Circuit Switched network registration status (CREG Usage).
00044      * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3).
00045      */
00046     typedef enum {
00047         CSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00048         CSD_REGISTERED = 1,
00049         CSD_NOT_REGISTERED_SEARCHING = 2,
00050         CSD_REGISTRATION_DENIED = 3,
00051         CSD_UNKNOWN_COVERAGE = 4,
00052         CSD_REGISTERED_ROAMING = 5,
00053         CSD_SMS_ONLY = 6,
00054         CSD_SMS_ONLY_ROAMING = 7,
00055         CSD_CSFB_NOT_PREFERRED = 9
00056     } NetworkRegistrationStatusCsd;
00057 
00058     /** Packet Switched network registration status (CGREG Usage).
00059      * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3).
00060      */
00061     typedef enum {
00062         PSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00063         PSD_REGISTERED = 1,
00064         PSD_NOT_REGISTERED_SEARCHING = 2,
00065         PSD_REGISTRATION_DENIED = 3,
00066         PSD_UNKNOWN_COVERAGE = 4,
00067         PSD_REGISTERED_ROAMING = 5,
00068         PSD_EMERGENCY_SERVICES_ONLY = 8
00069     } NetworkRegistrationStatusPsd;
00070 
00071     /** EPS network registration status (CEREG Usage).
00072      * UBX-13001820 - AT Commands Example Application Note (Section 18.36.3).
00073      */
00074     typedef enum {
00075         EPS_NOT_REGISTERED_NOT_SEARCHING = 0,
00076         EPS_REGISTERED = 1,
00077         EPS_NOT_REGISTERED_SEARCHING = 2,
00078         EPS_REGISTRATION_DENIED = 3,
00079         EPS_UNKNOWN_COVERAGE = 4,
00080         EPS_REGISTERED_ROAMING = 5,
00081         EPS_EMERGENCY_SERVICES_ONLY = 8
00082     } NetworkRegistrationStatusEps;
00083 
00084     /** modem PSM states.
00085      *
00086      */
00087     typedef enum {
00088         AWAKE = 0,
00089         ASLEEP = 1
00090     } ModemPSMState;
00091 
00092     /**
00093      * edrx access technology
00094      */
00095     typedef enum {
00096         EDRXGSM_EC_GSM_IoT_mode = 1,
00097         EDRXGSM_A_Gb_mode,
00098         EDRXUTRAN_Iu_mode,
00099         EDRXEUTRAN_WB_S1_mode,
00100         EDRXEUTRAN_NB_S1_mode
00101     }tEDRXAccessTechnology;
00102 
00103 #ifdef TARGET_UBLOX_C030_R41XM
00104     /** Supported MNO profiles for SARA-R4.
00105      */
00106     typedef enum {
00107         SW_DEFAULT = 0,
00108         SIM_ICCID = 1,
00109         ATT = 2,
00110         TMO = 5,
00111         VODAFONE = 19,
00112         DT = 31,
00113         STANDARD_EU = 100
00114 #ifdef TARGET_UBLOX_C030_R410M
00115         , VERIZON = 3,
00116         TELSTRA = 4,
00117         CT = 6,
00118         SPRINT = 8,
00119         TELUS = 21
00120 #endif
00121     } MNOProfile;
00122 
00123     typedef enum {
00124         UBANDMASK_RAT_LTE_CATM1 = 0,
00125         UBANDMASK_RAT_LTE_CATNB1 = 1
00126 
00127     } UBandmaskRAT;
00128 #endif
00129 
00130     /** Initialise the modem, ready for use.
00131      *
00132      *  @param pin     PIN for the SIM card.
00133      *  @return        true if successful, otherwise false.
00134      */
00135     bool init(const char *pin = 0);
00136 
00137     /** Perform registration with the network.
00138      *
00139      * @return true if successful, otherwise false.
00140      */
00141     bool nwk_registration();
00142 
00143     /** True if the modem is registered for circuit
00144      * switched data, otherwise false.
00145      */
00146     bool is_registered_csd();
00147 
00148     /** True if the modem is registered for packet
00149      * switched data, otherwise false.
00150      */
00151     bool is_registered_psd();
00152 
00153     /** True if the modem is registered for enhanced
00154      * packet switched data (i.e. LTE and beyond),
00155      * otherwise false.
00156      */
00157     bool is_registered_eps();
00158 
00159     /** Perform deregistration from the network.
00160      *
00161      * @return true if successful, otherwise false.
00162      */
00163     bool nwk_deregistration();
00164 
00165     /** Put the modem into its lowest power state.
00166      */
00167     void deinit();
00168 
00169     /** Set the PIN code for the SIM card.
00170      *
00171      *  @param pin PIN for the SIM card.
00172      */
00173     void set_pin(const char *pin);
00174 
00175     /** Enable or disable SIM pin checking.
00176      *
00177      * @param enableNotDisable true if SIM PIN checking is to be enabled,
00178      *                         otherwise false.
00179      * @return                 true if successful, otherwise false.
00180      */
00181     bool sim_pin_check_enable(bool enableNotDisable);
00182 
00183     /** Change the SIM pin.
00184      *
00185      * @param new_pin the new PIN to use.
00186      * @return        true if successful, otherwise false.
00187      */
00188     bool change_sim_pin(const char *new_pin);
00189 
00190     /** Get the IMEI.
00191      *
00192      * @return true if successful, otherwise false.
00193      */
00194     MBED_DEPRECATED("This method is now replaced by const char * imei(), please use that instead")
00195     bool get_imei(char *imei_to_send, int size);
00196 
00197     /** Get the IMEI of the module.
00198      *
00199      * @return a pointer to the IMEI as a null-terminated string.
00200      */
00201     const char *imei();
00202 
00203     /** Get the Mobile Equipment ID (which may be the same as the IMEI).
00204      *
00205      * @return a pointer to the Mobile Equipment ID as a null-terminated string.
00206      */
00207     const char *meid();
00208 
00209     /** Get the IMSI of the SIM.
00210      *
00211      * @return a pointer to the IMSI as a null-terminated string.
00212      */
00213     const char *imsi();
00214 
00215     /** Get the ICCID of the SIM.
00216      *
00217      * @return a pointer to the ICCID as a null-terminated string.
00218      */
00219     const char *iccid();
00220 
00221     /** Get the RSSI.
00222      *
00223      * @return the RSSI in dBm. If it is not possible to obtain an
00224      *         RSSI reading at the time (e.g. because the modem is in
00225      *         data mode rather than AT command mode) then 0 is returned.
00226      */
00227     int rssi();
00228 
00229     /** RAT values for +URAT command
00230      * R412M only supports value 7 (CatM1), 8 (NB1), and 9 (GPRS)
00231      */
00232     typedef enum {
00233         GSM_GPRS_EGPRS = 0,
00234         GSM_UMTS = 1,
00235         UMTS = 2,
00236         URAT_LTE = 3,
00237         GSM_UMTS_LTE = 4,
00238         GSM_LTE = 5,
00239         UMTS_LTE = 6,
00240         LTE_CATM1 = 7,
00241         LTE_CATNB1 = 8,
00242         GPRS_EGPRS = 9,
00243         NOT_USED = -1
00244     } RAT;
00245 
00246     /** Module functionality modes. Ref to section 5.3.3 of UBX-13002752 for details.
00247      */
00248     typedef enum {
00249         FUNC_MIN = 0,
00250         FUNC_FULL = 1,
00251         FUNC_AIRPLANE = 4,
00252         FUNC_EN_SIM_TLKT_DEDICATED = 6,
00253         FUNC_DS_SIM_TLKT = 7,
00254         FUNC_EN_SIM_TLKT_RAW = 9,
00255         FUNC_RESET = 15,
00256         FUNC_RESET_WITH_SIM = 16,
00257         FUNC_MIN_WITH_SIM = 19,
00258         FUNC_HALT = 127
00259     } FunctionalityMode;
00260 
00261 #ifdef TARGET_UBLOX_C030_R41XM
00262     /** Set MNO profile. Profile will be applied on next boot.
00263      *
00264      * User can also specify profile in mbed_app.json ("default-mno-profile": 100) and in that case profile will be applied in init().
00265      * Modem will also be rebooted so that profile parameters can be applied.
00266      *
00267      * Note: MNO profile should only be set in detached state and a reboot is required for settings to take effect
00268      * Note 2: ref to UBX-17003787 B.5, setting MNO profile can change other parameters such as PSM, Band mask, URAT etc.
00269      *         Application must always set a profile first and if required, change parameters afterwards.
00270      * Note 3: ref to UBX-17003787 B.5, some profiles have locked parameters and modem will return ERROR if you try to change those.
00271      *         It is suggested to switch to a profile e.g. STANDARD_EU (100) and then change the parameters as required.
00272      * @param profile MNO profile to use
00273      * @return    true if operation was successful, false if there was an error
00274      */
00275     bool set_mno_profile(MNOProfile profile);
00276 
00277     /** Get current MNO profile.
00278      *
00279      * @param profile pointer to variable that can hold the value for returned profile
00280      * @return    true if operation was successful, false if there was an error
00281      */
00282     bool get_mno_profile(int *profile);
00283 
00284     /** Enable or disable the UPSV Power Saving Mode.
00285      *
00286      * @param idle_mode_value  1: enable idle mode
00287      *                         0: disable idle mode
00288      * @return                 true if successful, otherwise false.
00289      */
00290     bool set_idle_mode(bool enable = false);
00291 
00292     /** Queries the modem for idle mode status.
00293      *
00294      * @param status pointer to variable that can hold the value for idle mode status
00295      *                         1: enabled
00296      *                         0: disabled
00297      * @return                 true if successful, otherwise false.
00298      */
00299     bool get_idle_mode(int *status);
00300 #endif
00301 
00302     /** Set Radio Access Technology on modem.
00303      *
00304      * Note: RAT should only be set in detached state and a reboot is required for settings to take effect
00305      *
00306      * @param selected_rat Radio Access Technology to use
00307      * @param preferred_rat Radio Access Technology to use if selected_rat is not available
00308      * @param second_preferred_rat Radio Access Technology to use if selected_rat and preferred_rat are not available
00309      *
00310      * @return        true if successful, otherwise false.
00311      */
00312     bool set_modem_rat(RAT selected_rat, RAT preferred_rat = NOT_USED, RAT second_preferred_rat = NOT_USED);
00313 
00314     /** Get last saved values for RAT using +URAT read command. Note: The current selected RAT is indicated by DeviceInfo.rat
00315      *
00316      * @param selected_rat pointer to variable that can hold the value for selected_rat
00317      * @param preferred_rat pointer to variable that can hold the value for preferred_rat
00318      * @param second_preferred_rat pointer to variable that can hold the value for second_preferred_rat
00319      *
00320      * Note: NOT_USED will be returned in the variables if dual or tri modes are not enabled.
00321      *
00322      * @return        true if successful, otherwise false.
00323      */
00324     bool get_modem_rat(int *selected_rat, int *preferred_rat, int *second_preferred_rat);
00325 
00326     /** Sets the modem to specified functionality mode.
00327      *
00328      * @return true if successful, otherwise false.
00329      */
00330     bool set_functionality_mode(FunctionalityMode mode);
00331 
00332     /** Get the modem functionality mode
00333      *
00334      * @return true if successful, otherwise false.
00335      */
00336     bool get_functionality_mode(int *mode);
00337 
00338     /** reboot the modem using AT+CFUN=15. Application should call init() or connect() before making any other API calls.
00339      *
00340      * @return        true if successful, otherwise false.
00341      */
00342     bool reboot_modem();
00343 
00344 #ifdef TARGET_UBLOX_C030_R412M
00345     /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
00346      * 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
00347      *
00348      * application callback for modem going in to PSM sleep
00349      *
00350      * @param func     callback function to be executed when modem is going in to PSM sleep
00351      * @param param    parameter to be passed to callback function.
00352      */
00353     void attach_cb_psm_going_in(Callback<void(void*)> func, void *param)
00354     {
00355         _func_psm_going_in = func;
00356         _cb_param_psm_going_in = param;
00357     }
00358 
00359     /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
00360      * 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
00361      *
00362      * application callback for modem coming out of PSM sleep
00363      *
00364      * @param func     callback function to be executed when modem is coming out of PSM sleep.
00365      * @param param    parameter to be passed to callback function.
00366      */
00367     void attach_cb_psm_coming_out(Callback<void(void*)> func, void *param)
00368     {
00369         _func_psm_coming_out = func;
00370         _cb_param_psm_coming_out = param;
00371     }
00372 
00373     /** de-register the application callback for modem going in to PSM sleep
00374      *
00375      */
00376     void detach_cb_psm_going_in()
00377     {
00378         _func_psm_going_in = NULL;
00379         _cb_param_psm_going_in = NULL;
00380     }
00381 
00382     /** de-register application callback for modem coming out of PSM sleep
00383      *
00384      */
00385     void detach_cb_psm_coming_out()
00386     {
00387         _func_psm_coming_out = NULL;
00388         _cb_param_psm_coming_out = NULL;
00389     }
00390 
00391     /** Enable or disable the 3GPP PSM.
00392      *
00393      *  Note: Application should reboot the module after enabling PSM in order to enter PSM state. (reboot_modem())
00394      *  Note: Modem can be woken up by toggling the power-on signal. (wakeup_modem())
00395      *  Note: When device enters PSM, all connections(PPP, sockets) and settings that are not saved in NV memory(ATE0, CREG etc) are lost.
00396      *        host application should be prepared to re-initialize the modem and re-establish the connections.
00397      *  Note: PSM is disabled if both periodic_time and active_time are 0.
00398      *  Note: Not all variants/firmware versions support PSM URCs and in that case function will return false.
00399      *
00400      *  PSM string encoding code is borrowed from AT_CellularPower.cpp
00401      *
00402      * @param periodic_time    requested periodic TAU in seconds.
00403      * @param active_time      requested active time in seconds.
00404      * @param func             callback function to execute when modem goes to sleep
00405      * @param ptr              parameter to callback function
00406      * @return         True if successful, otherwise false.
00407      */
00408     bool set_power_saving_mode(int periodic_tau, int active_time);
00409 
00410     /** Reads the 3GPP PSM status (enabled or disabled) and returns assigned periodic tau and active time values.
00411      *
00412      * @param status           0: PSM disabled, 1: PSM enabled
00413      * @param periodic_tau     assigned periodic TAU in seconds.
00414      * @param active_time      assigned active time in seconds
00415      * @return         True if command successful, otherwise false.
00416      */
00417     bool get_power_saving_mode(int *status, int *periodic_tau, int *active_time);
00418 
00419     /** Wake up the modem from PSM. Ref to comment on set_power_saving_mode, application should call init() or connect()
00420      * before making any other API calls.
00421      */
00422     void wakeup_modem();
00423 
00424     /** True if the modem is not in PSM sleep
00425      * otherwise false.
00426      */
00427     bool is_modem_awake();
00428 #endif
00429 
00430 #ifdef TARGET_UBLOX_C030_R41XM
00431     /** Set discontinuous reception time on cellular device.
00432      * SARA-R404M / SARA-R410M-02B / SARA-R410M-52B / SARA-R412M / SARA-N4 : The <Paging_time_window> parameter cannot be set by means of the set command.
00433      *
00434      *
00435      *  @remark See 3GPP TS 27.007 eDRX for details.
00436      *
00437      *  @param mode          disable or enable the use of eDRX
00438      *  @param act_type      type of access technology
00439      *  @param edrx_value    requested edxr value. Extended DRX parameters information element.
00440      *
00441      *  @return              0 on success
00442      *                       1 on failure
00443      */
00444     int set_receive_period(int mode, tEDRXAccessTechnology act_type, uint8_t edrx_value);
00445 
00446     /** Set discontinuous reception time on cellular device.
00447      *
00448      *  @remark See 3GPP TS 27.007 eDRX for details.
00449      *
00450      *  @param mode          disable or enable the use of eDRX
00451      *  @param act_type      type of access technology
00452      *
00453      *  @return              0 on success
00454      *                       1 on failure
00455      */
00456     int set_receive_period(int mode, tEDRXAccessTechnology act_type);
00457 
00458     /** Set discontinuous reception time on cellular device. (Disable)
00459      *
00460      *  @remark See 3GPP TS 27.007 eDRX for details.
00461      *
00462      *  @param mode          disable or enable the use of eDRX
00463      *
00464      *  @return              0 on success
00465      *                       1 on failure
00466      */
00467     int set_receive_period(int mode);
00468 
00469     /** get discontinuous reception time on cellular device.
00470      *
00471      *  @remark See 3GPP TS 27.007 eDRX for details.
00472      *
00473      *  @return              uint32_t
00474      */
00475     uint32_t get_receive_period();
00476 
00477     /** set band select bitmask
00478      *
00479      *  @param RAT        RAT type
00480      *  @param bitmask    bitmask
00481      *  @return           True if successful, otherwise false.
00482      */
00483     bool set_band_bitmask(RAT rat, uint64_t bitmask);
00484 
00485     /** get band select bitmasks
00486      *
00487      *  @param m1_bitmask     pointer to band select bitmask of M1
00488      *  @param nb1_bitmask    pointer to band select bitmask of NB1
00489      *  @return           True if successful, otherwise false.
00490      */
00491     bool get_band_bitmask(uint64_t *m1_bitmask, uint64_t *nb1_bitmask);
00492 
00493     /** disables the PSM
00494      *
00495      *  @return           True if successful, otherwise false.
00496      */
00497     bool disable_power_saving_mode();
00498 #endif
00499 
00500 protected:
00501 
00502     #define OUTPUT_ENTER_KEY  "\r"
00503 
00504     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00505     #define AT_PARSER_BUFFER_SIZE   MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00506     #else
00507     #define AT_PARSER_BUFFER_SIZE   256
00508     #endif
00509 
00510     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00511     #define AT_PARSER_TIMEOUT       MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00512     #else
00513     #define AT_PARSER_TIMEOUT       8*1000 // Milliseconds
00514     #endif
00515 
00516     /** A string that would not normally be sent by the modem on the AT interface.
00517      */
00518     #define UNNATURAL_STRING "\x01"
00519 
00520     /** Supported u-blox modem variants.
00521      */
00522     typedef enum {
00523         DEV_TYPE_NONE = 0,
00524         DEV_SARA_G35,
00525         DEV_LISA_U2,
00526         DEV_LISA_U2_03S,
00527         DEV_SARA_U2,
00528         DEV_SARA_R4,
00529         DEV_LEON_G2,
00530         DEV_TOBY_L2,
00531         DEV_MPCI_L2
00532     } DeviceType;
00533 
00534     /** Network registration status.
00535      * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5).
00536      */
00537     typedef enum {
00538        GSM = 0,
00539        COMPACT_GSM = 1,
00540        UTRAN = 2,
00541        EDGE = 3,
00542        HSDPA = 4,
00543        HSUPA = 5,
00544        HSDPA_HSUPA = 6,
00545        LTE = 7,
00546        EC_GSM_IoT = 8,
00547        E_UTRAN_NB_S1 = 9
00548     } RadioAccessNetworkType;
00549 
00550     /** Info about the modem.
00551      */
00552     typedef struct {
00553         DeviceType dev;
00554         char iccid[20 + 1];   //!< Integrated Circuit Card ID.
00555         char imsi[15 + 1];    //!< International Mobile Station Identity.
00556         char imei[15 + 1];    //!< International Mobile Equipment Identity.
00557         char meid[18 + 1];    //!< Mobile Equipment IDentifier.
00558         volatile RadioAccessNetworkType rat;  //!< Type of network (e.g. 2G, 3G, LTE).
00559         volatile NetworkRegistrationStatusCsd reg_status_csd; //!< Circuit switched attach status.
00560         volatile NetworkRegistrationStatusPsd reg_status_psd; //!< Packet switched attach status.
00561         volatile NetworkRegistrationStatusEps reg_status_eps; //!< Evolved Packet Switched (e.g. LTE) attach status.
00562 #ifdef TARGET_UBLOX_C030_R412M
00563         volatile ModemPSMState modem_psm_state; //!< last known modem PSM state
00564 #endif
00565     } DeviceInfo;
00566 
00567     /* IMPORTANT: the variables below are available to
00568      * classes that inherit this in order to keep things
00569      * simple. However, ONLY this class should free
00570      * any of the pointers, or there will be havoc.
00571      */
00572 
00573     /** Point to the instance of the AT parser in use.
00574      */
00575 #ifdef TARGET_UBLOX_C030_R41XM
00576     UbloxATCmdParser *_at;
00577 #else
00578     ATCmdParser *_at;
00579 #endif
00580 
00581     /** The current AT parser timeout value.
00582      */
00583     int _at_timeout;
00584 
00585     /** File handle used by the AT parser.
00586      */
00587     FileHandle *_fh;
00588 
00589     /** The mutex resource.
00590      */
00591     Mutex _mtx;
00592 
00593     /** General info about the modem as a device.
00594      */
00595     DeviceInfo _dev_info;
00596 
00597     /** The SIM PIN to use.
00598      */
00599     const char *_pin;
00600 
00601     /** Set to true to spit out debug traces.
00602      */
00603     bool _debug_trace_on;
00604     
00605     /** The baud rate to the modem.
00606      */
00607     int _baud;
00608 
00609     /** True if the modem is ready register to the network,
00610      * otherwise false.
00611      */
00612     bool _modem_initialised;
00613 
00614     /** True it the SIM requires a PIN, otherwise false.
00615      */
00616     bool _sim_pin_check_enabled;
00617 
00618     /** Sets the modem up for powering on
00619      *
00620      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00621      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00622      */
00623     virtual void modem_init();
00624 
00625     /** Sets the modem in unplugged state
00626      *
00627      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00628      *  and serial port. This puts the modem in lowest power state.
00629      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00630      */
00631     virtual void modem_deinit();
00632 
00633     /** Powers up the modem
00634      *
00635      *  modem_power_up() is equivalent to pressing the soft power button.
00636      *  The driver may repeat this if the modem is not responsive to AT commands.
00637      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00638      */
00639     virtual void modem_power_up();
00640 
00641     /** Powers down the modem
00642      *
00643      *  modem_power_down() is equivalent to turning off the modem by button press.
00644      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00645      */
00646     virtual void modem_power_down();
00647 
00648     /* Note: constructor and destructor protected so that this
00649     * class can only ever be inherited, never used directly.
00650     */
00651     UbloxCellularBase();
00652     ~UbloxCellularBase();
00653 
00654     /** Initialise this class.
00655      *
00656      * @param tx       the UART TX data pin to which the modem is attached.
00657      * @param rx       the UART RX data pin to which the modem is attached.
00658      * @param baud     the UART baud rate.
00659      * @param debug_on true to switch AT interface debug on, otherwise false.
00660      *
00661      * Note: it would be more natural to do this in the constructor
00662      * however, to avoid the diamond of death, this class is only
00663      * every inherited virtually.  Classes that are inherited virtually
00664      * do not get passed parameters in their constructor and hence
00665      * classInit() must be called separately by the first one to wake
00666      * the beast.
00667      */
00668     void baseClassInit(PinName tx = MDMTXD,
00669                        PinName rx = MDMRXD,
00670                        int baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
00671                        bool debug_on = false);
00672 
00673     /** Set the AT parser timeout.
00674      */
00675     void at_set_timeout(int timeout);
00676 
00677     /** Read up to size characters from buf
00678      * or until the character "end" is reached, overwriting
00679      * the newline with 0 and ensuring a terminator
00680      * in all cases.
00681      *
00682      * @param buf  the buffer to write to.
00683      * @param size the size of the buffer.
00684      * @param end  the character to stop at.
00685      * @return     the number of characters read,
00686      *             not including the terminator.
00687      */
00688     int read_at_to_char(char * buf, int size, char end);
00689 
00690     /** Powers up the modem.
00691      *
00692      * @return true if successful, otherwise false.
00693      */
00694     bool power_up();
00695 
00696     /** Setup the modem baudrate, echo and flow control
00697      *
00698      * @return true if successful, otherwise false.
00699      */
00700     bool setup_modem();
00701 
00702     /** Check if modem is accepting AT commands
00703      *
00704      * @return true if successful, otherwise false.
00705      */
00706     bool is_modem_ready();
00707 
00708     /** Powers up the modem and set it up for application use.
00709      *
00710      * @return true if successful, otherwise false.
00711      */
00712     bool initialize_modem();
00713 
00714     /** Power down the modem.
00715      */
00716     void power_down();
00717 
00718     /** Lock a mutex when accessing the modem.
00719      */
00720     void lock(void)     { _mtx.lock(); }
00721 
00722     /** Helper to make sure that lock unlock pair is always balanced
00723      */
00724     #define LOCK()         { lock()
00725 
00726     /** Unlock the modem when done accessing it.
00727      */
00728     void unlock(void)   { _mtx.unlock(); }
00729 
00730     /** Helper to make sure that lock unlock pair is always balanced
00731      */
00732     #define UNLOCK()       } unlock()
00733 
00734     /** Set the device identity in _dev_info
00735      * based on the ATI string returned by
00736      * the module.
00737      *
00738      * @return true if dev is a known value,
00739      *         otherwise false.
00740      */
00741     bool set_device_identity(DeviceType *dev);
00742 
00743     /** Perform any modem initialisation that is
00744      * specialised by device type.
00745      *
00746      * @return true if successful, otherwise false.
00747      */
00748     bool device_init(DeviceType dev);
00749 
00750     /** Set up the SIM.
00751      *
00752      * @return true if successful, otherwiss false.
00753      */
00754     bool initialise_sim_card();
00755 
00756 #ifdef TARGET_UBLOX_C030_R41XM
00757     /** Converts the given uint to binary string. Fills the given str starting from [0] with the number of bits defined by bit_cnt
00758      *  For example uint_to_binary_string(9, str, 10) would fill str "0000001001"
00759      *  For example uint_to_binary_string(9, str, 3) would fill str "001"
00760      *
00761      *  @param num       uint to converts to binary string
00762      *  @param str       buffer for converted binary string
00763      *  @param str_size  size of the str buffer
00764      *  @param bit_cnt   defines how many bits are filled to buffer started from lsb
00765      */
00766     void uint_to_binary_str(uint32_t num, char* str, int str_size, int bit_cnt);
00767 
00768     /** Converts the given binary string to uint.
00769      *  For example binary_str_to_uint("0000001001", 10) would return 9
00770      *
00771      *  @param binary_string           binary string from where chars are converted to uint
00772      *  @param binary_string_length    length of the param binary_string
00773      *  @return                        uint represented by the binary string
00774      */
00775     uint32_t binary_str_to_uint(const char *binary_string, int binary_string_length);
00776 
00777 #endif
00778 
00779 private:
00780 
00781     void set_nwk_reg_status_csd(int status);
00782     void set_nwk_reg_status_psd(int status);
00783     void set_nwk_reg_status_eps(int status);
00784     void set_rat(int AcTStatus);
00785     bool get_iccid();
00786     bool get_imsi();
00787     bool get_imei();
00788     bool get_meid();
00789     bool set_sms();
00790     void parser_abort_cb();
00791     void CMX_ERROR_URC();
00792     void CREG_URC();
00793     void CGREG_URC();
00794     void CEREG_URC();
00795     void UMWI_URC();
00796 #ifdef TARGET_UBLOX_C030_R412M
00797     bool set_psm_urcs(bool enable);
00798     void UUPSMR_URC();
00799     void *_cb_param_psm_going_in;
00800     Callback<void(void*)>    _func_psm_going_in;  /**< Callback. */
00801     void *_cb_param_psm_coming_out;
00802     Callback<void(void*)>    _func_psm_coming_out;  /**< Callback. */
00803     void set_modem_psm_state(int state);
00804 #endif
00805 #ifdef TARGET_UBLOX_C030_R41XM
00806     bool _default_profile_is_set;
00807     typedef enum {
00808        DISABLED = 0,
00809        ENABLED = 1,
00810        UNKNOWN = 2
00811     } PSMStatus;
00812     PSMStatus _psm_status;
00813 #endif
00814 };
00815 
00816 #endif // _UBLOX_CELLULAR_BASE_
00817