UbloxCellularBaseN2xx.h

00001 /* Copyright (c) 2017 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_N2XX_
00017 #define _UBLOX_CELLULAR_BASE_N2XX_
00018 
00019 #include "mbed.h"
00020 #include "ATCmdParser.h"
00021 #include "FileHandle.h"
00022 
00023 /**********************************************************************
00024  * CLASSES
00025  **********************************************************************/
00026 
00027 /** UbloxCellularBase class.
00028  *
00029  *  This class provides all the base support for generic u-blox modems
00030  *  on C030 and C027 boards: module identification, power-up, network
00031  *  registration, etc.
00032  */
00033 class UbloxCellularBaseN2xx {
00034 
00035 public:
00036     /** Circuit Switched network registration status (CREG Usage).
00037      * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3).
00038      */
00039     typedef enum {
00040         CSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00041         CSD_REGISTERED = 1,
00042         CSD_NOT_REGISTERED_SEARCHING = 2,
00043         CSD_REGISTRATION_DENIED = 3,
00044         CSD_UNKNOWN_COVERAGE = 4,
00045         CSD_REGISTERED_ROAMING = 5,
00046         CSD_SMS_ONLY = 6,
00047         CSD_SMS_ONLY_ROAMING = 7,
00048         CSD_CSFB_NOT_PREFERRED = 9
00049     } NetworkRegistrationStatusCsd;
00050 
00051     /** Packet Switched network registration status (CGREG Usage).
00052      * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3).
00053      */
00054     typedef enum {
00055         PSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00056         PSD_REGISTERED = 1,
00057         PSD_NOT_REGISTERED_SEARCHING = 2,
00058         PSD_REGISTRATION_DENIED = 3,
00059         PSD_UNKNOWN_COVERAGE = 4,
00060         PSD_REGISTERED_ROAMING = 5,
00061         PSD_EMERGENCY_SERVICES_ONLY = 8
00062     } NetworkRegistrationStatusPsd;
00063 
00064     /** EPS network registration status (CEREG Usage).
00065      * UBX-13001820 - AT Commands Example Application Note (Section 18.36.3).
00066      */
00067     typedef enum {
00068         EPS_NOT_REGISTERED_NOT_SEARCHING = 0,
00069         EPS_REGISTERED = 1,
00070         EPS_NOT_REGISTERED_SEARCHING = 2,
00071         EPS_REGISTRATION_DENIED = 3,
00072         EPS_UNKNOWN_COVERAGE = 4,
00073         EPS_REGISTERED_ROAMING = 5,
00074         EPS_EMERGENCY_SERVICES_ONLY = 8
00075     } NetworkRegistrationStatusEps;
00076 
00077     /** Initialise the modem, ready for use.
00078      *
00079      *  @param pin     PIN for the SIM card.
00080      *  @return        true if successful, otherwise false.
00081      */
00082     bool init(const char *pin = 0);
00083 
00084     /** Perform registration with the network.
00085      *
00086      * @return true if successful, otherwise false.
00087      */
00088     bool nwk_registration();
00089 
00090     /** True if the modem is registered for circuit
00091      * switched data, otherwise false.
00092      */
00093     bool is_registered_csd();
00094 
00095     /** True if the modem is registered for packet
00096      * switched data, otherwise false.
00097      */
00098     bool is_registered_psd();
00099 
00100     /** True if the modem is registered for enhanced
00101      * packet switched data (i.e. LTE and beyond),
00102      * otherwise false.
00103      */
00104     bool is_registered_eps();
00105 
00106     /** Perform deregistration from the network.
00107      *
00108      * @return true if successful, otherwise false.
00109      */
00110     bool nwk_deregistration();
00111 
00112     /** Put the modem into its lowest power state.
00113      */
00114     void deinit();
00115 
00116     /** Set the PIN code for the SIM card.
00117      *
00118      *  @param pin PIN for the SIM card.
00119      */
00120     void set_pin(const char *pin);
00121 
00122     /** Enable or disable SIM pin checking.
00123      *
00124      * @param enableNotDisable true if SIM PIN checking is to be enabled,
00125      *                         otherwise false.
00126      * @return                 true if successful, otherwise false.
00127      */
00128     bool sim_pin_check_enable(bool enableNotDisable);
00129 
00130     /** Change the SIM pin.
00131      *
00132      * @param new_pin the new PIN to use.
00133      * @return        true if successful, otherwise false.
00134      */
00135     bool change_sim_pin(const char *new_pin);
00136     
00137     /** get the Manufacturer Info
00138     *
00139     * @param response the manufacturer
00140     * @return         ture if successful, otherwise false.
00141     */
00142     bool cgmi(const char *response);
00143     
00144     /** get the Module name
00145     *
00146     * @param response the module name
00147     * @return         ture if successful, otherwise false.
00148     */
00149     bool cgmm(const char *response);
00150     
00151     /** get International Module Subscriber Information
00152     *
00153     * @param response the IMSI
00154     * @return         ture if successful, otherwise false.
00155     */
00156     bool cimi(const char *response);
00157     
00158     /** get the serial number 
00159     *
00160     * @param response the serial number
00161     * @return         ture if successful, otherwise false.
00162     */
00163     bool ccid(const char *response);
00164     
00165     /** get the firmware version
00166     *
00167     * @param response the firmware version
00168     * @return         ture if successful, otherwise false.
00169     */
00170     bool cgmr(const char *response);
00171     
00172     /** get the IMEI
00173     *
00174     * @param response the IMEI 
00175     * @return         ture if successful, otherwise false.
00176     */
00177     bool cgsn(int snt, const char *response);    
00178     
00179     /** Connect to the specified PLMN
00180     *
00181     * @param plmn the PLMN to register on
00182     * @return     ture if successful, otherwise false.
00183     */
00184     bool cops(const char*plmn);
00185     
00186     /** Set the mode of operation for registering
00187     *
00188     * @param mode 0=Auto, 1=Manual, 2=Deregister
00189     * @return     ture if successful, otherwise false.
00190     */
00191     bool cops(int mode);
00192     
00193     /** Gets the COPS mode of operation
00194     *
00195     * @param status returns the mode
00196     * @return       ture if successful, otherwise false.
00197     */
00198     bool get_cops(int *status);
00199     
00200     /** Enable or Disable the Radio/Modem
00201     *
00202     * @param mode 0=disable, 1=enable
00203     * @return     ture if successful, otherwise false.
00204     */
00205     bool cfun(int mode);
00206     
00207     /** Reboot the SARA-N2xx module
00208     *    
00209     * @return     ture if successful, otherwise false.
00210     */
00211     bool reboot();
00212     
00213     /** Sets the AUTOCONNECT feature of SARA-N2xx module
00214     *
00215     * @param state true to enable, false to disable
00216     * @return      ture if successful, otherwise false.
00217     */
00218     bool auto_connect(bool state);
00219     
00220     /** Set the specified NCONFIG parameter
00221     *
00222     * @param name  name of the NCONFIG parameter to enable/disable
00223     * @param state true to enable, false to disable
00224     * @return      ture if successful, otherwise false.
00225     */
00226     bool nconfig(const char *name, bool state);    
00227     
00228 
00229     /** Get the IMEI.
00230     *
00231     * @return true if successful, otherwise false.
00232     */
00233     MBED_DEPRECATED("This method is now replaced by const char * imei(), please use that instead")
00234     bool get_imei(char *buffer, int size);
00235     
00236         /** Get the IMEI of the module.
00237      *
00238      * @return a pointer to the IMEI as a null-terminated string.
00239      */
00240     const char *imei();
00241  
00242     /** Get the Mobile Equipment ID (which may be the same as the IMEI).
00243      *
00244      * @return a pointer to the Mobile Equipment ID as a null-terminated string.
00245      */
00246     const char *meid();
00247  
00248     /** Get the IMSI of the SIM.
00249      *
00250      * @return a pointer to the IMSI as a null-terminated string.
00251      */
00252     const char *imsi();
00253  
00254     /** Get the ICCID of the SIM.
00255      *
00256      * @return a pointer to the ICCID as a null-terminated string.
00257      */
00258     const char *iccid();
00259  
00260     /** Get the RSSI.
00261      *
00262      * @return the RSSI in dBm. If it is not possible to obtain an
00263      *         RSSI reading at the time (e.g. because the modem is in
00264      *         data mode rather than AT command mode) then 0 is returned.
00265      */
00266     int rssi();
00267 
00268 protected:
00269 
00270     #define OUTPUT_ENTER_KEY  "\r"
00271 
00272     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00273     #define AT_PARSER_BUFFER_SIZE   MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00274     #else
00275     #define AT_PARSER_BUFFER_SIZE   256
00276     #endif
00277 
00278     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00279     #define AT_PARSER_TIMEOUT       MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00280     #else
00281     #define AT_PARSER_TIMEOUT       8*1000 // Milliseconds
00282     #endif
00283 
00284     /** A string that would not normally be sent by the modem on the AT interface.
00285      */
00286     #define UNNATURAL_STRING "\x01"
00287 
00288     /** Supported u-blox modem variants.
00289      */
00290     typedef enum {
00291         DEV_TYPE_NONE = 0,
00292         DEV_SARA_G35,
00293         DEV_LISA_U2,
00294         DEV_LISA_U2_03S,
00295         DEV_SARA_U2,
00296         DEV_LEON_G2,
00297         DEV_TOBY_L2,
00298         DEV_MPCI_L2,
00299         DEV_SARA_N2,
00300     } DeviceType;
00301 
00302     /** Network registration status.
00303      * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5).
00304      */
00305     typedef enum {
00306        GSM = 0,
00307        COMPACT_GSM = 1,
00308        UTRAN = 2,
00309        EDGE = 3,
00310        HSDPA = 4,
00311        HSUPA = 5,
00312        HSDPA_HSUPA = 6,
00313        LTE = 7
00314     } RadioAccessNetworkType;
00315 
00316     /** Info about the modem.
00317      */
00318     typedef struct {
00319         DeviceType dev;
00320         char iccid[20 + 1];   //!< Integrated Circuit Card ID.
00321         char imsi[15 + 1];    //!< International Mobile Station Identity.
00322         char imei[15 + 1];    //!< International Mobile Equipment Identity.
00323         char meid[18 + 1];    //!< Mobile Equipment IDentifier.
00324         volatile RadioAccessNetworkType rat;  //!< Type of network (e.g. 2G, 3G, LTE).
00325         volatile NetworkRegistrationStatusCsd reg_status_csd; //!< Circuit switched attach status.
00326         volatile NetworkRegistrationStatusPsd reg_status_psd; //!< Packet switched attach status.
00327         volatile NetworkRegistrationStatusEps reg_status_eps; //!< Evolved Packet Switched (e.g. LTE) attach status.
00328     } DeviceInfo;
00329     
00330     typedef struct {
00331         char cgmm[32+1];
00332         char cgmi[32+1];
00333         char cgmr[32+1];
00334         char cgsn[32+1];    
00335     } sara_n2xx_info;
00336 
00337     /* IMPORTANT: the variables below are available to
00338      * classes that inherit this in order to keep things
00339      * simple. However, ONLY this class should free
00340      * any of the pointers, or there will be havoc.
00341      */
00342 
00343     /** Point to the instance of the AT parser in use.
00344      */
00345     ATCmdParser *_at;
00346 
00347     /** The current AT parser timeout value.
00348      */
00349     int _at_timeout;
00350 
00351     /** File handle used by the AT parser.
00352      */
00353     FileHandle *_fh;
00354 
00355     /** The mutex resource.
00356      */
00357     Mutex _mtx;
00358 
00359     /** General info about the modem as a device.
00360      */
00361     DeviceInfo _dev_info;
00362     
00363     /** 
00364      * Information about the SARA-N2xx module
00365      */
00366     sara_n2xx_info _sara_n2xx_info;
00367 
00368     /** The SIM PIN to use.
00369      */
00370     const char *_pin;
00371 
00372     /** Set to true to spit out debug traces.
00373      */
00374     bool _debug_trace_on;
00375 
00376     /** True if the modem is ready register to the network,
00377      * otherwise false.
00378      */
00379     bool _modem_initialised;
00380 
00381     /** True it the SIM requires a PIN, otherwise false.
00382      */
00383     bool _sim_pin_check_enabled;
00384 
00385     /** Sets the modem up for powering on
00386      *
00387      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00388      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00389      */
00390     virtual void modem_init();
00391 
00392     /** Sets the modem in unplugged state
00393      *
00394      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00395      *  and serial port. This puts the modem in lowest power state.
00396      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00397      */
00398     virtual void modem_deinit();
00399 
00400     /** Powers up the modem
00401      *
00402      *  modem_power_up() is equivalent to pressing the soft power button.
00403      *  The driver may repeat this if the modem is not responsive to AT commands.
00404      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00405      */
00406     virtual void modem_power_up();
00407 
00408     /** Powers down the modem
00409      *
00410      *  modem_power_down() is equivalent to turning off the modem by button press.
00411      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00412      */
00413     virtual void modem_power_down();
00414 
00415     /* Note: constructor and destructor protected so that this
00416     * class can only ever be inherited, never used directly.
00417     */
00418     UbloxCellularBaseN2xx();
00419     ~UbloxCellularBaseN2xx();
00420 
00421     /** Initialise this class.
00422      *
00423      * @param tx       the UART TX data pin to which the modem is attached.
00424      * @param rx       the UART RX data pin to which the modem is attached.
00425      * @param baud     the UART baud rate.
00426      * @param debug_on true to switch AT interface debug on, otherwise false.
00427      *
00428      * Note: it would be more natural to do this in the constructor
00429      * however, to avoid the diamond of death, this class is only
00430      * every inherited virtually.  Classes that are inherited virtually
00431      * do not get passed parameters in their constructor and hence
00432      * classInit() must be called separately by the first one to wake
00433      * the beast.
00434      */
00435     void baseClassInit(PinName tx = MDMTXD,
00436                        PinName rx = MDMRXD,
00437                        int baud = MBED_CONF_UBLOX_CELL_N2XX_BAUD_RATE,
00438                        bool debug_on = false);
00439 
00440     /** Set the AT parser timeout.
00441      */
00442     void at_set_timeout(int timeout);
00443 
00444     /** Read up to size characters from buf
00445      * or until the character "end" is reached, overwriting
00446      * the newline with 0 and ensuring a terminator
00447      * in all cases.
00448      *
00449      * @param buf  the buffer to write to.
00450      * @param size the size of the buffer.
00451      * @param end  the character to stop at.
00452      * @return     the number of characters read,
00453      *             not including the terminator.
00454      */
00455     int read_at_to_char(char * buf, int size, char end);
00456 
00457     /** Powers up the modem.
00458      *
00459      * @return true if successful, otherwise false.
00460      */
00461     bool power_up();
00462 
00463     /** Power down the modem.
00464      */
00465     void power_down();
00466 
00467     /** Lock a mutex when accessing the modem.
00468      */
00469     void lock(void)     { _mtx.lock(); }
00470 
00471     /** Helper to make sure that lock unlock pair is always balanced
00472      */
00473     #define LOCK()         { lock()
00474 
00475     /** Unlock the modem when done accessing it.
00476      */
00477     void unlock(void)   { _mtx.unlock(); }
00478 
00479     /** Helper to make sure that lock unlock pair is always balanced
00480      */
00481     #define UNLOCK()       } unlock()
00482 
00483     /** Set the device identity in _dev_info
00484      * based on the ATI string returned by
00485      * the module.
00486      *
00487      * @return true if dev is a known value,
00488      *         otherwise false.
00489      */
00490     bool set_device_identity(DeviceType *dev);
00491 
00492     /** Perform any modem initialisation that is
00493      * specialised by device type.
00494      *
00495      * @return true if successful, otherwise false.
00496      */
00497     bool device_init(DeviceType dev);
00498 
00499     /** Set up the SIM.
00500      *
00501      * @return true if successful, otherwiss false.
00502      */
00503     bool initialise_sim_card();
00504     
00505     int read_at_to_newline(char * buf, int size);
00506 
00507 private:
00508     void set_nwk_reg_status_csd(int status);
00509     void set_nwk_reg_status_psd(int status);
00510     void set_nwk_reg_status_eps(int status);
00511     void set_rat(int AcTStatus);
00512     bool get_iccid();
00513     bool get_imsi();
00514     bool get_imei();
00515     bool get_meid(); // *** NOT IMPLEMENTED, returns false
00516     bool set_sms(); // *** NOT IMPLEMENTED, returns false
00517     void parser_abort_cb();
00518     void CMX_ERROR_URC();
00519     void CEREG_URC();    
00520     
00521     bool get_sara_n2xx_info();        
00522     bool cereg(int n);
00523     nsapi_error_t get_cereg();
00524     nsapi_error_t get_cscon();
00525     nsapi_error_t get_csq();    
00526     
00527     bool at_send(const char *cmd);
00528     bool at_send(const char *cmd, int n);
00529     bool at_send(const char *cmd, const char *arg);
00530     
00531     bool at_req(const char *cmd, const char *recvFormat, const char *response);    
00532     bool at_req(const char *cmd, const char *recvFormat, int *response);
00533 };
00534 
00535 #endif // _UBLOX_CELLULAR_BASE_
00536