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