Retry
Fork of ublox-at-cellular-interface by
Embed:
(wiki syntax)
Show/hide line numbers
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:47:11 by
![doxygen](doxygen.png)