Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
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_
Generated on Tue Jul 12 2022 12:45:42 by
