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