PPPCellularInterface.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 PPP_CELLULAR_INTERFACE_
00017 #define PPP_CELLULAR_INTERFACE_
00018 
00019 #include "CellularBase.h"
00020 #include "platform/ATCmdParser.h"
00021 #include "mbed.h"
00022 
00023 #if NSAPI_PPP_AVAILABLE
00024 
00025 // Forward declaration
00026 class NetworkStack;
00027 
00028 /**
00029  * Network registration status
00030  * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5)
00031  */
00032 typedef enum {
00033    GSM=0,
00034    COMPACT_GSM=1,
00035    UTRAN=2,
00036    EDGE=3,
00037    HSDPA=4,
00038    HSUPA=5,
00039    HSDPA_HSUPA=6,
00040    LTE=7
00041 } radio_access_nwk_type;
00042 
00043 /**
00044  * Used in registration process to tell which type of network
00045  * to connect.
00046  */
00047 typedef enum {
00048     CIRCUIT_SWITCHED=0,
00049     PACKET_SWITCHED
00050 } nwk_type;
00051 
00052 /**
00053  * Circuit Switched network registration status (CREG Usage)
00054  * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3)
00055  */
00056 typedef enum {
00057     CSD_NOT_REGISTERED_NOT_SEARCHING=0,
00058     CSD_REGISTERED=1,
00059     CSD_NOT_REGISTERED_SEARCHING=2,
00060     CSD_REGISTRATION_DENIED=3,
00061     CSD_UNKNOWN_COVERAGE=4,
00062     CSD_REGISTERED_ROAMING=5,
00063     CSD_SMS_ONLY=6,
00064     CSD_SMS_ONLY_ROAMING=7,
00065     CSD_CSFB_NOT_PREFERRED=9
00066 } nwk_registration_status_csd;
00067 
00068 /**
00069  * Packet Switched network registration status (CGREG Usage)
00070  * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3)
00071  */
00072 typedef enum {
00073     PSD_NOT_REGISTERED_NOT_SEARCHING=0,
00074     PSD_REGISTERED=1,
00075     PSD_NOT_REGISTERED_SEARCHING=2,
00076     PSD_REGISTRATION_DENIED=3,
00077     PSD_UNKNOWN_COVERAGE=4,
00078     PSD_REGISTERED_ROAMING=5,
00079     PSD_EMERGENCY_SERVICES_ONLY=8
00080 } nwk_registration_status_psd;
00081 
00082 typedef struct {
00083     char ccid[20+1];    //!< Integrated Circuit Card ID
00084     char imsi[15+1];    //!< International Mobile Station Identity
00085     char imei[15+1];    //!< International Mobile Equipment Identity
00086     char meid[18+1];    //!< Mobile Equipment IDentifier
00087     int flags;
00088     radio_access_nwk_type rat;
00089     nwk_registration_status_csd reg_status_csd;
00090     nwk_registration_status_psd reg_status_psd;
00091 } device_info;
00092 
00093 /** PPPCellularInterface class
00094  *
00095  *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00096  *
00097  *  This interface serves as the controller/driver for the Cellular
00098  *  modems (tested with UBLOX_C027 and MTS_DRAGONFLY_F411RE).
00099  *
00100  *  The driver will work with any generic FileHandle, and can be
00101  *  derived from in order to provide forms for specific interfaces, as well as
00102  *  adding extra power and reset controls alongside the FileHandle.
00103  */
00104 
00105 class PPPCellularInterface : public CellularBase {
00106 
00107 public:
00108 
00109     /** Constructor for a generic modem, using a single FileHandle for commands and PPP data.
00110      *
00111      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00112      *
00113      * The file handle pointer is not accessed within the constructor, only recorded for later
00114      * use - this permits a derived class to pass a pointer to a not-yet-constructed member object.
00115      */
00116     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00117     PPPCellularInterface(FileHandle *fh, bool debug = false);
00118 
00119     /** Destructor
00120      *
00121      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00122      */
00123     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00124     virtual ~PPPCellularInterface();
00125 
00126     /** Set the Cellular network credentials
00127      *
00128      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00129      *
00130      *  Please check documentation of connect() for default behaviour of APN settings.
00131      *
00132      *  @param apn      Access point name
00133      *  @param uname    optionally, Username
00134      *  @param pwd      optionally, password
00135      */
00136     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00137     virtual void set_credentials(const char *apn, const char *uname = 0,
00138                                                   const char *pwd = 0);
00139 
00140     /** Set the pin code for SIM card
00141      *
00142      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00143      *
00144      *  @param sim_pin      PIN for the SIM card
00145      */
00146     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00147     virtual void set_sim_pin(const char *sim_pin);
00148 
00149     /** Start the interface
00150      *
00151      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00152      *
00153      *  Attempts to connect to a Cellular network.
00154      *  This driver is written mainly for data network connections as CellularBase
00155      *  is NetworkInterface. That's why connect() call internally calls nwk_registration()
00156      *  method with parameter PACKET_SWITCHED network. Circuit switched hook and registration
00157      *  process is implemented and left in the driver for future extension/subclass support,e.g.,
00158      *  an SMS or GPS extension.
00159      *
00160      *  @param sim_pin     PIN for the SIM card
00161      *  @param apn         optionally, access point name
00162      *  @param uname       optionally, Username
00163      *  @param pwd         optionally, password
00164      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00165      */
00166     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00167     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00168                                   const char *uname = 0, const char *pwd = 0);
00169 
00170     /** Attempt to connect to the Cellular network
00171      *
00172      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00173      *
00174      *  Brings up the network interface. Connects to the Cellular Radio
00175      *  network and then brings up the underlying network stack to be used
00176      *  by the cellular modem over PPP interface.
00177      *
00178      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00179      *  For APN setup, default behaviour is to use 'internet' as APN string and assuming no authentication
00180      *  is required, i.e., username and password are not set. Optionally, a database lookup can be requested
00181      *  by turning on the APN database lookup feature. In order to do so, add 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP'
00182      *  in your mbed_app.json. APN database is by no means exhaustive. It contains a short list of some public
00183      *  APNs with publicly available usernames and passwords (if required) in some particular countries only.
00184      *  Lookup is done using IMSI (International mobile subscriber identifier).
00185      *  Please note that even if 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP' config option is set, 'set_credentials()' api still
00186      *  gets the precedence. If the aforementioned API is not used and the config option is set but no match is found in
00187      *  the lookup table then the driver tries to resort to default APN settings.
00188      *
00189      *  Preferred method is to setup APN using 'set_credentials()' API.
00190      *  @return         0 on success, negative error code on failure
00191      */
00192     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00193     virtual nsapi_error_t connect();
00194 
00195     /** Attempt to disconnect from the network
00196      *
00197      *  Brings down the network interface. Shuts down the PPP interface
00198      *  of the underlying network stack. Does not bring down the Radio network
00199      *
00200      *  @return         0 on success, negative error code on failure
00201      */
00202     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00203     virtual nsapi_error_t disconnect();
00204 
00205     /** Adds or removes a SIM facility lock
00206      *
00207      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00208      *
00209      * Can be used to enable or disable SIM pin check at device startup.
00210      * This API sets up flags for the driver which would either enable or disable
00211      * SIM pin checking depending upon the user provided argument while establishing
00212      * connection. It doesn't do anything immediately other than setting up flags.
00213      *
00214      * @param set        can be set to true if the SIM pin check is supposed to be enabled
00215      *                   and vice versa.
00216      */
00217     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00218     void set_sim_pin_check(bool set);
00219 
00220     /** Change the pin for the SIM card
00221      *
00222      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00223      *
00224      * Provide the new pin for your SIM card with this API. Old pin code will be assumed to
00225      * be set using set_SIM_pin() API. This API have no immediate effect. While establishing
00226      * connection, driver will change the SIM pin for the next boot.
00227      *
00228      * @param new_pin     new pin to be used in string format
00229      */
00230     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00231     void set_new_sim_pin(const char *new_pin);
00232 
00233     /** Check if the connection is currently established or not
00234      *
00235      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00236      *
00237      * @return true/false   If the cellular module have successfully acquired a carrier and is
00238      *                      connected to an external packet data network using PPP, isConnected()
00239      *                      API returns true and false otherwise.
00240      */
00241     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00242     virtual bool is_connected();
00243 
00244     /** Get the local IP address
00245      *
00246      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00247      *
00248      *  @return         Null-terminated representation of the local IP address
00249      *                  or null if no IP address has been received
00250      */
00251     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00252     virtual const char *get_ip_address();
00253 
00254     /** Get the local network mask
00255      *
00256      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00257      *
00258      *  @return         Null-terminated representation of the local network mask
00259      *                  or null if no network mask has been received
00260      */
00261     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00262     virtual const char *get_netmask();
00263 
00264     /** Get the local gateways
00265      *
00266      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00267      *
00268      *  @return         Null-terminated representation of the local gateway
00269      *                  or null if no network mask has been received
00270      */
00271     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00272     virtual const char *get_gateway();
00273 
00274 
00275     /** Turn modem debug traces on
00276      *
00277      *  @param on         set true to enable debug traces
00278      */
00279     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00280     void modem_debug_on(bool on);
00281 
00282     /** Register callback for status reporting
00283      *
00284      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00285      *
00286      *  @param status_cb The callback for status changes
00287      */
00288     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00289     virtual void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
00290 
00291     /** Get the connection status
00292      *
00293      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00294      *
00295      *  @return         The connection status according to nsapi_connection_status_t
00296      */
00297     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00298     virtual nsapi_connection_status_t get_connection_status() const;
00299 
00300     /** Set blocking status of connect() which by default should be blocking
00301      *
00302      *  @deprecated This API will be deprecated in mbed-os-5.9. Use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.
00303      *
00304      *  @param blocking true if connect is blocking
00305      *  @return         0 on success, negative error code on failure
00306      */
00307     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00308     virtual nsapi_error_t set_blocking(bool blocking);
00309 
00310 private:
00311     FileHandle *_fh;
00312     ATCmdParser *_at;
00313     const char *_new_pin;
00314     const char *_pin;
00315     const char *_apn;
00316     const char *_uname;
00317     const char *_pwd;
00318     bool _debug_trace_on;
00319     nsapi_ip_stack_t _stack;
00320     Callback<void(nsapi_event_t, intptr_t)> _connection_status_cb;
00321     nsapi_connection_status_t _connect_status;
00322     bool _connect_is_blocking;
00323     void base_initialization();
00324     void setup_at_parser();
00325     void shutdown_at_parser();
00326     nsapi_error_t initialize_sim_card();
00327     nsapi_error_t setup_context_and_credentials();
00328     bool power_up();
00329     void power_down();
00330     void ppp_status_cb(nsapi_event_t, intptr_t);
00331 
00332 protected:
00333     /** Enable or disable hang-up detection
00334      *
00335      * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
00336      * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
00337      * signaling is not desired. enable_hup() controls whether this function should be
00338      * active.
00339      *
00340      * Meant to be overridden.
00341      */
00342     virtual void enable_hup(bool enable);
00343 
00344     /** Sets the modem up for powering on
00345      *
00346      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00347      *  It is meant to be overridden.
00348      *  If the modem is on-board, an implementation of onboard_modem_api.h
00349      *  will override this.
00350      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00351      *  class will override.
00352      */
00353     virtual void modem_init();
00354 
00355     /** Sets the modem in unplugged state
00356      *
00357      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00358      *  and serial port. This puts the modem in lowest power state.
00359      *  It is meant to be overridden.
00360      *  If the modem is on-board, an implementation of onboard_modem_api.h
00361      *  will override this.
00362      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00363      *  class will override.
00364      */
00365     virtual void modem_deinit();
00366 
00367     /** Powers up the modem
00368      *
00369      *  modem_power_up() is equivalent to pressing the soft power button.
00370      *  The driver may repeat this if the modem is not responsive to AT commands.
00371      *  It is meant to be overridden.
00372      *  If the modem is on-board, an implementation of onboard_modem_api.h
00373      *  will override this.
00374      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00375      *  class will override.
00376      */
00377     virtual void modem_power_up();
00378 
00379     /** Powers down the modem
00380      *
00381      *  modem_power_down() is equivalent to turning off the modem by button press.
00382      *  It is meant to be overridden.
00383      *  If the modem is on-board, an implementation of onboard_modem_api.h
00384      *  will override this.
00385      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00386      *  class will override.
00387      */
00388     virtual void modem_power_down();
00389 
00390     /** Provide access to the underlying stack
00391      *
00392      *  @return The underlying network stack
00393      */
00394     virtual NetworkStack *get_stack();
00395 
00396     /** Starts network registration process.
00397      *
00398      * Potential users could be subclasses who are not network interface
00399      * but would like to use CellularBase infrastructure to register
00400      * with a cellular network, e.g., an SMS extension to CellularBase.
00401      *
00402      * @param nwk_type type of network to connect, defaults to packet switched network
00403      *
00404      * @return true if registration is successful
00405      */
00406     bool nwk_registration(uint8_t nwk_type=PACKET_SWITCHED);
00407 
00408 };
00409 
00410 #endif //NSAPI_PPP_AVAILABLE
00411 
00412 #endif //PPP_CELLULAR_INTERFACE_