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.
Fork of ublox-at-cellular-interface by
UbloxATCellularInterface.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_AT_CELLULAR_INTERFACE_ 00017 #define _UBLOX_AT_CELLULAR_INTERFACE_ 00018 00019 #include "UbloxCellularBase.h" 00020 #include "CellularBase.h" 00021 #include "NetworkStack.h" 00022 00023 /** UbloxATCellularInterface class. 00024 * 00025 * This uses the cellular-tuned IP stack that 00026 * is on-board the cellular modem instead of the 00027 * LWIP stack on the mbed MCU. 00028 * 00029 * There are three advantages to using this mechanism: 00030 * 00031 * 1. Since the modem interface remains in AT mode 00032 * throughout, it is possible to continue using 00033 * any AT commands (e.g. send SMS, use the module's 00034 * file system, etc.) while the connection is up. 00035 * 00036 * 2. The UbloxATCellularInterfaceExt class can 00037 * be used to perform very simple HTTP and FTP 00038 * operations using the modem's on-board clients. 00039 * 00040 * 3. LWIP is not required (and hence RAM is saved). 00041 * 00042 * The disadvantage is that some additional parsing 00043 * (at the AT interface) has to go on in order to exchange 00044 * IP packets, so this is less efficient under heavy loads. 00045 * Also TCP Server and getting/setting of socket options is 00046 * currently not supported. 00047 */ 00048 00049 // Forward declaration 00050 class NetworkStack; 00051 00052 /* 00053 * NOTE: order is important in the inheritance below! PAL takes this class 00054 * and casts it to CellularInterface and so CellularInterface has to be first 00055 * in the last for that to work. 00056 */ 00057 00058 /** UbloxATCellularInterface class. 00059 * 00060 * This class implements the network stack interface into the cellular 00061 * modems on the C030 and C027 boards for 2G/3G/4G modules using 00062 * the IP stack running on the cellular module. 00063 */ 00064 class UbloxATCellularInterface : public CellularBase, public NetworkStack, virtual public UbloxCellularBase { 00065 00066 public: 00067 /** Constructor. 00068 * 00069 * @param tx the UART TX data pin to which the modem is attached. 00070 * @param rx the UART RX data pin to which the modem is attached. 00071 * @param baud the UART baud rate. 00072 * @param debug_on true to switch AT interface debug on, otherwise false. 00073 */ 00074 UbloxATCellularInterface(PinName tx = MDMTXD, 00075 PinName rx = MDMRXD, 00076 int baud = MBED_CONF_UBLOX_CELL_BAUD_RATE, 00077 bool debug_on = false); 00078 00079 /* Destructor. 00080 */ 00081 virtual ~UbloxATCellularInterface(); 00082 00083 /** The amount of extra space needed in terms of AT interface 00084 * characters to get a chunk of user data (i.e. one UDP packet 00085 * or a portion of a TCP packet) across the AT interface. 00086 */ 00087 #define AT_PACKET_OVERHEAD 77 00088 00089 /** The profile to use (on board the modem). 00090 */ 00091 #define PROFILE "0" 00092 00093 /** Translates a host name to an IP address with specific IP version. 00094 * 00095 * The host name may be either a domain name or an IP address. If the 00096 * host name is an IP address, no network transactions will be performed. 00097 * 00098 * If no stack-specific DNS resolution is provided, the host name 00099 * will be resolved using a UDP socket on the stack. 00100 * 00101 * @param host Host name to resolve. 00102 * @param address Destination for the host SocketAddress. 00103 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates 00104 * version is chosen by the stack (defaults to NSAPI_UNSPEC). 00105 * @return 0 on success, negative error code on failure. 00106 */ 00107 virtual nsapi_error_t gethostbyname(const char *host, 00108 SocketAddress *address, 00109 nsapi_version_t version = NSAPI_UNSPEC); 00110 00111 /** Set the authentication scheme. 00112 * 00113 * @param auth The authentication scheme, chose from 00114 * NSAPI_SECURITY_NONE, NSAPI_SECURITY_PAP, 00115 * NSAPI_SECURITY_CHAP or NSAPI_SECURITY_UNKNOWN; 00116 * use NSAPI_SECURITY_UNKNOWN to try all of none, 00117 * PAP and CHAP. 00118 */ 00119 virtual void set_authentication(nsapi_security_t auth); 00120 00121 /** Set the cellular network credentials. 00122 * 00123 * Please check documentation of connect() for default behaviour of APN settings. 00124 * 00125 * @param apn Access point name. 00126 * @param uname Optionally, user name. 00127 * @param pwd Optionally, password. 00128 */ 00129 virtual void set_credentials(const char *apn, const char *uname = 0, 00130 const char *pwd = 0); 00131 00132 /** Set the PIN code for the SIM card. 00133 * 00134 * @param sim_pin PIN for the SIM card. 00135 */ 00136 virtual void set_sim_pin(const char *sim_pin); 00137 00138 /** Connect to the cellular network and start the interface. 00139 * 00140 * Attempts to connect to a cellular network. Note: if init() has 00141 * not been called beforehand, connect() will call it first. 00142 * 00143 * @param sim_pin PIN for the SIM card. 00144 * @param apn Optionally, access point name. 00145 * @param uname Optionally, user name. 00146 * @param pwd Optionally, password. 00147 * @return NSAPI_ERROR_OK on success, or negative error code on failure. 00148 */ 00149 virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, 00150 const char *uname = 0, const char *pwd = 0); 00151 00152 /** Attempt to connect to the cellular network. 00153 * 00154 * Brings up the network interface. Connects to the cellular radio 00155 * network and then brings up IP stack on the cellular modem to be used 00156 * indirectly via AT commands, rather than LWIP. Note: if init() has 00157 * not been called beforehand, connect() will call it first. 00158 * NOTE: even a failed attempt to connect will cause the modem to remain 00159 * powered up. To power it down, call deinit(). 00160 * 00161 * For APN setup, default behaviour is to use 'internet' as APN string 00162 * and assuming no authentication is required, i.e., user name and password 00163 * are not set. Optionally, a database lookup can be requested by turning 00164 * on the APN database lookup feature. The APN database is by no means 00165 * exhaustive (feel free to submit a pull request with additional values). 00166 * It contains a short list of some public APNs with publicly available 00167 * user names and passwords (if required) in some particular countries only. 00168 * Lookup is done using IMSI (International mobile subscriber identifier). 00169 * 00170 * The preferred method is to setup APN using 'set_credentials()' API. 00171 * 00172 * If you find that the AT interface returns "CONNECT" but shortly afterwards 00173 * drops the connection then 99% of the time this will be because the APN 00174 * is incorrect. 00175 * 00176 * @return 0 on success, negative error code on failure. 00177 */ 00178 virtual nsapi_error_t connect(); 00179 00180 /** Attempt to disconnect from the network. 00181 * 00182 * Brings down the network interface. 00183 * Does not bring down the Radio network. 00184 * 00185 * @return 0 on success, negative error code on failure. 00186 */ 00187 virtual nsapi_error_t disconnect(); 00188 00189 /** Adds or removes a SIM facility lock. 00190 * 00191 * Can be used to enable or disable SIM PIN check at device startup. 00192 * 00193 * @param set Can be set to true if the SIM PIN check is supposed 00194 * to be enabled and vice versa. 00195 * @param immediate If true, change the SIM PIN now, else set a flag 00196 * and make the change only when connect() is called. 00197 * If this is true and init() has not been called previously, 00198 * it will be called first. 00199 * @param sim_pin The current SIM PIN, must be a const. If this is not 00200 * provided, the SIM PIN must have previously been set by a 00201 * call to set_sim_pin(). 00202 * @return 0 on success, negative error code on failure. 00203 */ 00204 nsapi_error_t set_sim_pin_check(bool set, bool immediate = false, 00205 const char *sim_pin = NULL); 00206 00207 /** Change the PIN for the SIM card. 00208 * 00209 * Provide the new PIN for your SIM card with this API. It is ONLY possible to 00210 * change the SIM PIN when SIM PIN checking is ENABLED. 00211 * 00212 * @param new_pin New PIN to be used in string format, must be a const. 00213 * @param immediate If true, change the SIM PIN now, else set a flag 00214 * and make the change only when connect() is called. 00215 * If this is true and init() has not been called previously, 00216 * it will be called first. 00217 * @param old_pin Old PIN, must be a const. If this is not provided, the SIM PIN 00218 * must have previously been set by a call to set_sim_pin(). 00219 * @return 0 on success, negative error code on failure. 00220 */ 00221 nsapi_error_t set_new_sim_pin(const char *new_pin, bool immediate = false, 00222 const char *old_pin = NULL); 00223 00224 /** Check if the connection is currently established or not. 00225 * 00226 * @return True if connected to a data network, otherwise false. 00227 */ 00228 virtual bool is_connected(); 00229 00230 /** Get the local IP address 00231 * 00232 * @return Null-terminated representation of the local IP address 00233 * or null if no IP address has been received. 00234 */ 00235 virtual const char *get_ip_address(); 00236 00237 /** Get the local network mask. 00238 * 00239 * @return Null-terminated representation of the local network mask 00240 * or null if no network mask has been received. 00241 */ 00242 virtual const char *get_netmask(); 00243 00244 /** Get the local gateways. 00245 * 00246 * @return Null-terminated representation of the local gateway 00247 * or null if no network mask has been received. 00248 */ 00249 virtual const char *get_gateway(); 00250 00251 /** Call back in case connection is lost. 00252 * 00253 * @param cb The function to call. 00254 */ 00255 void connection_status_cb(Callback<void(nsapi_error_t)> cb); 00256 00257 protected: 00258 00259 /** Socket "unused" value. 00260 */ 00261 #define SOCKET_UNUSED -1 00262 00263 /** Socket timeout value in milliseconds. 00264 * Note: the sockets layer above will retry the 00265 * call to the functions here when they return NSAPI_ERROR_WOULD_BLOCK 00266 * and the user has set a larger timeout or full blocking. 00267 */ 00268 #define SOCKET_TIMEOUT 1000 00269 00270 /** The maximum number of bytes in a packet that can be written 00271 * to the AT interface in one go. 00272 */ 00273 #define MAX_WRITE_SIZE 1024 00274 00275 /** The maximum number of bytes in a packet that can be read from 00276 * from the AT interface in one go. 00277 */ 00278 #define MAX_READ_SIZE 1024 00279 00280 /** Management structure for sockets. 00281 */ 00282 typedef struct { 00283 int modem_handle; //!< The modem's handle for the socket. 00284 volatile nsapi_size_t pending; //!< The number of received bytes pending. 00285 void (*callback)(void *); //!< A callback for events. 00286 void *data; //!< A data pointer that must be passed to the callback. 00287 } SockCtrl; 00288 00289 /** Sockets storage. 00290 */ 00291 SockCtrl _sockets[7]; 00292 00293 /** Storage for a single IP address. 00294 */ 00295 char *_ip; 00296 00297 /** The APN to use. 00298 */ 00299 const char *_apn; 00300 00301 /** The user name to use. 00302 */ 00303 const char *_uname; 00304 00305 /** The password to use. 00306 */ 00307 const char *_pwd; 00308 00309 /** The type of authentication to use. 00310 */ 00311 nsapi_security_t _auth; 00312 00313 /** Get the next set of credentials from the database. 00314 */ 00315 virtual void get_next_credentials(const char ** config); 00316 00317 /** Activate one of the on-board modem's connection profiles. 00318 * 00319 * @param apn The APN to use. 00320 * @param username The user name to use. 00321 * @param password The password to use. 00322 * @param auth The authentication method to use 00323 * (NSAPI_SECURITY_NONE, NSAPI_SECURITY_PAP, 00324 * NSAPI_SECURITY_CHAP or NSAPI_SECURITY_UNKNOWN). 00325 * @return True if successful, otherwise false. 00326 */ 00327 virtual bool activate_profile(const char* apn, const char* username, 00328 const char* password, nsapi_security_t auth); 00329 00330 /** Activate a profile using the existing external connection. 00331 * 00332 * @return true if successful, otherwise false. 00333 */ 00334 virtual bool activate_profile_reuse_external(void); 00335 00336 /** Activate a profile based on connection ID. 00337 * 00338 * @param cid The connection ID. 00339 * @param apn The APN to use. 00340 * @param username The user name to use. 00341 * @param password The password to use. 00342 * @param auth The authentication method to use. 00343 * @return True if successful, otherwise false. 00344 */ 00345 virtual bool activate_profile_by_cid(int cid, const char* apn, const char* username, 00346 const char* password, nsapi_security_t auth); 00347 00348 /** Connect the on board IP stack of the modem. 00349 * 00350 * @return True if successful, otherwise false. 00351 */ 00352 virtual bool connect_modem_stack(); 00353 00354 /** Disconnect the on board IP stack of the modem. 00355 * 00356 * @return True if successful, otherwise false. 00357 */ 00358 virtual bool disconnect_modem_stack(); 00359 00360 /** Provide access to the NetworkStack object 00361 * 00362 * @return The underlying NetworkStack object. 00363 */ 00364 virtual NetworkStack *get_stack(); 00365 00366 protected: 00367 00368 /** Open a socket. 00369 * 00370 * Creates a network socket and stores it in the specified handle. 00371 * The handle must be passed to following calls on the socket. 00372 * 00373 * @param handle Destination for the handle to a newly created socket. 00374 * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP. 00375 * @return 0 on success, negative error code on failure. 00376 */ 00377 virtual nsapi_error_t socket_open(nsapi_socket_t *handle, 00378 nsapi_protocol_t proto); 00379 00380 /** Close a socket. 00381 * 00382 * Closes any open connection and deallocates any memory associated 00383 * with the socket. 00384 * 00385 * @param handle Socket handle. 00386 * @return 0 on success, negative error code on failure. 00387 */ 00388 virtual nsapi_error_t socket_close(nsapi_socket_t handle); 00389 00390 /** Bind a specific port to a socket. 00391 * 00392 * Binding a socket specifies port on which to receive 00393 * data. The IP address is ignored. Note that binding 00394 * a socket involves closing it and reopening and so the 00395 * bind operation should be carried out before any others. 00396 * 00397 * @param handle Socket handle. 00398 * @param address Local address to bind (of which only the port is used). 00399 * @return 0 on success, negative error code on failure. 00400 */ 00401 virtual nsapi_error_t socket_bind(nsapi_socket_t handle, 00402 const SocketAddress &address); 00403 00404 /** Connects TCP socket to a remote host. 00405 * 00406 * Initiates a connection to a remote server specified by the 00407 * indicated address. 00408 * 00409 * @param handle Socket handle. 00410 * @param address The SocketAddress of the remote host. 00411 * @return 0 on success, negative error code on failure. 00412 */ 00413 virtual nsapi_error_t socket_connect(nsapi_socket_t handle, 00414 const SocketAddress &address); 00415 00416 /** Send data over a TCP socket. 00417 * 00418 * The socket must be connected to a remote host. Returns the number of 00419 * bytes sent from the buffer. This class sets no upper buffer limit on 00420 * buffer size and the maximum packet size is not connected with the 00421 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size 00422 * definitions. 00423 * 00424 * @param handle Socket handle. 00425 * @param data Buffer of data to send to the host. 00426 * @param size Size of the buffer in bytes. 00427 * @return Number of sent bytes on success, negative error 00428 * code on failure. 00429 */ 00430 virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle, 00431 const void *data, nsapi_size_t size); 00432 00433 /** Send a packet over a UDP socket. 00434 * 00435 * Sends data to the specified address. Returns the number of bytes 00436 * sent from the buffer. 00437 * 00438 * PACKET SIZES: the maximum packet size that can be sent in a single 00439 * UDP packet is limited by the configuration value 00440 * platform.buffered-serial-txbuf-size (defaults to 256). 00441 * The maximum UDP packet size is: 00442 * 00443 * platform.buffered-serial-txbuf-size - AT_PACKET_OVERHEAD 00444 * 00445 * ...with a limit of 1024 bytes (at the AT interface). So, to allow sending 00446 * of a 1024 byte UDP packet, edit your mbed_app.json to add a target override 00447 * setting platform.buffered-serial-txbuf-size to 1101. However, for 00448 * UDP packets, 508 bytes is considered a more realistic size, taking into 00449 * account fragmentation sizes over the public internet, which leads to a 00450 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size 00451 * setting of 585. 00452 * 00453 * If size is larger than this limit, the data will be split across separate 00454 * UDP packets. 00455 * 00456 * @param handle Socket handle. 00457 * @param address The SocketAddress of the remote host. 00458 * @param data Buffer of data to send to the host. 00459 * @param size Size of the buffer in bytes. 00460 * @return Number of sent bytes on success, negative error 00461 * code on failure. 00462 */ 00463 virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, 00464 const SocketAddress &address, 00465 const void *data, 00466 nsapi_size_t size); 00467 00468 /** Receive data over a TCP socket. 00469 * 00470 * The socket must be connected to a remote host. Returns the number of 00471 * bytes received into the buffer. This class sets no upper limit on the 00472 * buffer size and the maximum packet size is not connected with the 00473 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size 00474 * definitions. 00475 * 00476 * @param handle Socket handle. 00477 * @param data Destination buffer for data received from the host. 00478 * @param size Size of the buffer in bytes. 00479 * @return Number of received bytes on success, negative error 00480 * code on failure. 00481 */ 00482 virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle, 00483 void *data, nsapi_size_t size); 00484 00485 /** Receive a packet over a UDP socket. 00486 * 00487 * Receives data and stores the source address in address if address 00488 * is not NULL. Returns the number of bytes received into the buffer. 00489 * 00490 * PACKET SIZES: the maximum packet size that can be retrieved in a 00491 * single call to this method is limited by the configuration value 00492 * platform.buffered-serial-rxbuf-size (default 256). The maximum 00493 * UDP packet size is: 00494 * 00495 * platform.buffered-serial-rxbuf-size - AT_PACKET_OVERHEAD 00496 * 00497 * ...with a limit of 1024 (at the AT interface). So to allow reception of a 00498 * 1024 byte UDP packet in a single call, edit your mbed_app.json to add a 00499 * target override setting platform.buffered-serial-rxbuf-size to 1101. 00500 * 00501 * If the received packet is larger than this limit, any remainder will 00502 * be returned in subsequent calls to this method. Once a single UDP 00503 * packet has been received, this method will return. 00504 * 00505 * @param handle Socket handle. 00506 * @param address Destination for the source address or NULL. 00507 * @param data Destination buffer for data received from the host. 00508 * @param size Size of the buffer in bytes. 00509 * @return Number of received bytes on success, negative error 00510 * code on failure. 00511 */ 00512 virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, 00513 SocketAddress *address, 00514 void *data, nsapi_size_t size); 00515 00516 /** Register a callback on state change of the socket. 00517 * 00518 * The specified callback will be called on state changes such as when 00519 * the socket can recv/send/accept successfully and on when an error 00520 * occurs. The callback may also be called spuriously without reason. 00521 * 00522 * The callback may be called in an interrupt context and should not 00523 * perform expensive operations such as recv/send calls. 00524 * 00525 * @param handle Socket handle. 00526 * @param callback Function to call on state change. 00527 * @param data Argument to pass to callback. 00528 */ 00529 virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), 00530 void *data); 00531 00532 /** Listen for connections on a TCP socket. 00533 * 00534 * Marks the socket as a passive socket that can be used to accept 00535 * incoming connections. 00536 * 00537 * @param handle Socket handle. 00538 * @param backlog Number of pending connections that can be queued 00539 * simultaneously, defaults to 1. 00540 * @return 0 on success, negative error code on failure. 00541 */ 00542 virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog); 00543 00544 /** Accepts a connection on a TCP socket. 00545 * 00546 * The server socket must be bound and set to listen for connections. 00547 * On a new connection, creates a network socket and stores it in the 00548 * specified handle. The handle must be passed to following calls on 00549 * the socket. 00550 * 00551 * A stack may have a finite number of sockets, in this case 00552 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available. 00553 * 00554 * This call is non-blocking. If accept would block, 00555 * NSAPI_ERROR_WOULD_BLOCK is returned immediately. 00556 * 00557 * @param server Socket handle to server to accept from. 00558 * @param handle Destination for a handle to the newly created socket. 00559 * @param address Destination for the remote address or NULL. 00560 * @return 0 on success, negative error code on failure. 00561 */ 00562 virtual nsapi_error_t socket_accept(nsapi_socket_t server, 00563 nsapi_socket_t *handle, 00564 SocketAddress *address = 0); 00565 00566 /** Set stack-specific socket options. 00567 * 00568 * The setsockopt allow an application to pass stack-specific hints 00569 * to the underlying stack. For unsupported options, 00570 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified. 00571 * 00572 * @param handle Socket handle. 00573 * @param level Stack-specific protocol level. 00574 * @param optname Stack-specific option identifier. 00575 * @param optval Option value. 00576 * @param optlen Length of the option value. 00577 * @return 0 on success, negative error code on failure. 00578 */ 00579 virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, 00580 int optname, const void *optval, 00581 unsigned optlen); 00582 00583 /** Get stack-specific socket options. 00584 * 00585 * The getstackopt allow an application to retrieve stack-specific hints 00586 * from the underlying stack. For unsupported options, 00587 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified. 00588 * 00589 * @param handle Socket handle. 00590 * @param level Stack-specific protocol level. 00591 * @param optname Stack-specific option identifier. 00592 * @param optval Destination for option value. 00593 * @param optlen Length of the option value. 00594 * @return 0 on success, negative error code on failure. 00595 */ 00596 virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, 00597 int optname, void *optval, 00598 unsigned *optlen); 00599 00600 private: 00601 00602 // u_ added to namespace us somewhat as this darned macro 00603 // is defined by everyone and their dog 00604 #define u_stringify(a) str(a) 00605 #define str(a) #a 00606 00607 bool _sim_pin_check_change_pending; 00608 bool _sim_pin_check_change_pending_enabled_value; 00609 bool _sim_pin_change_pending; 00610 const char *_sim_pin_change_pending_new_pin_value; 00611 Thread event_thread; 00612 void handle_event(); 00613 SockCtrl * find_socket(int modem_handle = SOCKET_UNUSED); 00614 void clear_socket(SockCtrl * socket); 00615 bool check_socket(SockCtrl * socket); 00616 int nsapi_security_to_modem_security(nsapi_security_t nsapi_security); 00617 Callback<void(nsapi_error_t)> _connection_status_cb; 00618 void UUSORD_URC(); 00619 void UUSORF_URC(); 00620 void UUSOCL_URC(); 00621 void UUPSDD_URC(); 00622 }; 00623 00624 #endif // _UBLOX_AT_CELLULAR_INTERFACE_ 00625
Generated on Fri Jul 15 2022 01:17:32 by
 1.7.2
 1.7.2 
    