u-blox / ublox-at-cellular-interface-n2xx

Implementation of the CellularInterface for u-blox C030 boards with N2xx modems. Note: requires the N211 module firmware to be at least 06.57 A01.02.

Dependents:   example-ublox-cellular-interface HelloMQTT example-ublox-cellular-interface_r410M example-ublox-mbed-client ... more

UbloxATCellularInterfaceN2xx.h@11:4be20bab5138, 2017-09-28 (annotated)

Committer:
philware
Date:
Thu Sep 28 15:30:22 2017 +0100
Revision:
11:4be20bab5138
Parent:
7:69e676f4af84
Child:
14:7fb0bbdc4242
Changed default baud rate to use the N2xx #define MBED_CONF_UBLOX_CELL_N2XX_BAUD_RATE

Who changed what in which revision?

UserRevisionLine numberNew contents of line
philware 1:8ea78dce6b36 1 /* Copyright (c) 2017 ARM Limited
philware 1:8ea78dce6b36 2 *
philware 1:8ea78dce6b36 3 * Licensed under the Apache License, Version 2.0 (the "License");
philware 1:8ea78dce6b36 4 * you may not use this file except in compliance with the License.
philware 1:8ea78dce6b36 5 * You may obtain a copy of the License at
philware 1:8ea78dce6b36 6 *
philware 1:8ea78dce6b36 7 * http://www.apache.org/licenses/LICENSE-2.0
philware 1:8ea78dce6b36 8 *
philware 1:8ea78dce6b36 9 * Unless required by applicable law or agreed to in writing, software
philware 1:8ea78dce6b36 10 * distributed under the License is distributed on an "AS IS" BASIS,
philware 1:8ea78dce6b36 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
philware 1:8ea78dce6b36 12 * See the License for the specific language governing permissions and
philware 1:8ea78dce6b36 13 * limitations under the License.
philware 1:8ea78dce6b36 14 */
philware 1:8ea78dce6b36 15
philware 1:8ea78dce6b36 16 #ifndef _UBLOX_AT_CELLULAR_INTERFACE_N2XX_
philware 1:8ea78dce6b36 17 #define _UBLOX_AT_CELLULAR_INTERFACE_N2XX_
philware 1:8ea78dce6b36 18
philware 1:8ea78dce6b36 19 #include "UbloxCellularBaseN2xx.h"
philware 1:8ea78dce6b36 20 #include "CellularBase.h"
philware 1:8ea78dce6b36 21 #include "NetworkStack.h"
philware 1:8ea78dce6b36 22
philware 1:8ea78dce6b36 23 /** UbloxATCellularInterface class.
philware 1:8ea78dce6b36 24 *
philware 1:8ea78dce6b36 25 * This uses the cellular-tuned IP stack that
philware 1:8ea78dce6b36 26 * is on-board the cellular modem instead of the
philware 1:8ea78dce6b36 27 * LWIP stack on the mbed MCU.
philware 1:8ea78dce6b36 28 *
philware 1:8ea78dce6b36 29 * There are three advantages to using this mechanism:
philware 1:8ea78dce6b36 30 *
philware 1:8ea78dce6b36 31 * 1. Since the modem interface remains in AT mode
philware 1:8ea78dce6b36 32 * throughout, it is possible to continue using
philware 1:8ea78dce6b36 33 * any AT commands (e.g. send SMS, use the module's
philware 1:8ea78dce6b36 34 * file system, etc.) while the connection is up.
philware 1:8ea78dce6b36 35 *
philware 1:8ea78dce6b36 36 * 2. The UbloxATCellularInterfaceExt class can
philware 1:8ea78dce6b36 37 * be used to perform very simple HTTP and FTP
philware 1:8ea78dce6b36 38 * operations using the modem's on-board clients.
philware 1:8ea78dce6b36 39 *
philware 1:8ea78dce6b36 40 * 3. LWIP is not required (and hence RAM is saved).
philware 1:8ea78dce6b36 41 *
philware 1:8ea78dce6b36 42 * The disadvantage is that some additional parsing
philware 1:8ea78dce6b36 43 * (at the AT interface) has to go on in order to exchange
philware 1:8ea78dce6b36 44 * IP packets, so this is less efficient under heavy loads.
philware 1:8ea78dce6b36 45 * Also TCP Server and getting/setting of socket options is
philware 1:8ea78dce6b36 46 * currently not supported.
philware 1:8ea78dce6b36 47 */
philware 1:8ea78dce6b36 48
philware 1:8ea78dce6b36 49 // Forward declaration
philware 1:8ea78dce6b36 50 class NetworkStack;
philware 1:8ea78dce6b36 51
philware 1:8ea78dce6b36 52 /*
philware 1:8ea78dce6b36 53 * NOTE: order is important in the inheritance below! PAL takes this class
philware 1:8ea78dce6b36 54 * and casts it to CellularInterface and so CellularInterface has to be first
philware 1:8ea78dce6b36 55 * in the last for that to work.
philware 1:8ea78dce6b36 56 */
philware 1:8ea78dce6b36 57
philware 1:8ea78dce6b36 58 /** UbloxATCellularInterface class.
philware 1:8ea78dce6b36 59 *
philware 1:8ea78dce6b36 60 * This class implements the network stack interface into the cellular
philware 1:8ea78dce6b36 61 * modems on the C030 and C027 boards for 2G/3G/4G modules using
philware 1:8ea78dce6b36 62 * the IP stack running on the cellular module.
philware 1:8ea78dce6b36 63 */
philware 1:8ea78dce6b36 64 class UbloxATCellularInterfaceN2xx : public CellularBase, public NetworkStack, virtual public UbloxCellularBaseN2xx {
philware 1:8ea78dce6b36 65
philware 1:8ea78dce6b36 66 public:
philware 1:8ea78dce6b36 67
philware 1:8ea78dce6b36 68 /** Constructor.
philware 1:8ea78dce6b36 69 *
philware 1:8ea78dce6b36 70 * @param tx the UART TX data pin to which the modem is attached.
philware 1:8ea78dce6b36 71 * @param rx the UART RX data pin to which the modem is attached.
philware 1:8ea78dce6b36 72 * @param baud the UART baud rate.
philware 1:8ea78dce6b36 73 * @param debug_on true to switch AT interface debug on, otherwise false.
philware 1:8ea78dce6b36 74 */
philware 1:8ea78dce6b36 75 UbloxATCellularInterfaceN2xx(PinName tx = MDMTXD,
philware 1:8ea78dce6b36 76 PinName rx = MDMRXD,
philware 11:4be20bab5138 77 int baud = MBED_CONF_UBLOX_CELL_N2XX_BAUD_RATE,
philware 1:8ea78dce6b36 78 bool debug_on = false);
philware 1:8ea78dce6b36 79
philware 1:8ea78dce6b36 80 /* Destructor.
philware 1:8ea78dce6b36 81 */
philware 1:8ea78dce6b36 82 virtual ~UbloxATCellularInterfaceN2xx();
philware 1:8ea78dce6b36 83
philware 1:8ea78dce6b36 84 /** The amount of extra space needed in terms of AT interface
philware 1:8ea78dce6b36 85 * characters to get a chunk of user data (i.e. one UDP packet
philware 1:8ea78dce6b36 86 * or a portion of a TCP packet) across the AT interface.
philware 1:8ea78dce6b36 87 */
philware 1:8ea78dce6b36 88 #define AT_PACKET_OVERHEAD 77
philware 1:8ea78dce6b36 89
philware 1:8ea78dce6b36 90 /** The profile to use (on board the modem).
philware 1:8ea78dce6b36 91 */
philware 1:8ea78dce6b36 92 #define PROFILE "0"
philware 1:8ea78dce6b36 93
philware 1:8ea78dce6b36 94 /** Translates a host name to an IP address with specific IP version.
philware 1:8ea78dce6b36 95 *
philware 1:8ea78dce6b36 96 * The host name may be either a domain name or an IP address. If the
philware 1:8ea78dce6b36 97 * host name is an IP address, no network transactions will be performed.
philware 1:8ea78dce6b36 98 *
philware 1:8ea78dce6b36 99 * If no stack-specific DNS resolution is provided, the host name
philware 1:8ea78dce6b36 100 * will be resolved using a UDP socket on the stack.
philware 1:8ea78dce6b36 101 *
philware 1:8ea78dce6b36 102 * @param host Host name to resolve.
philware 1:8ea78dce6b36 103 * @param address Destination for the host SocketAddress.
philware 1:8ea78dce6b36 104 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
philware 1:8ea78dce6b36 105 * version is chosen by the stack (defaults to NSAPI_UNSPEC).
philware 1:8ea78dce6b36 106 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 107 */
philware 1:8ea78dce6b36 108 virtual nsapi_error_t gethostbyname(const char *host,
philware 1:8ea78dce6b36 109 SocketAddress *address,
philware 1:8ea78dce6b36 110 nsapi_version_t version = NSAPI_UNSPEC);
philware 1:8ea78dce6b36 111
philware 1:8ea78dce6b36 112 /** Set the authentication scheme.
philware 1:8ea78dce6b36 113 *
philware 1:8ea78dce6b36 114 * @param auth The authentication scheme, chose from
philware 1:8ea78dce6b36 115 * NSAPI_SECURITY_NONE, NSAPI_SECURITY_PAP,
philware 1:8ea78dce6b36 116 * NSAPI_SECURITY_CHAP or NSAPI_SECURITY_UNKNOWN;
philware 1:8ea78dce6b36 117 * use NSAPI_SECURITY_UNKNOWN to try all of none,
philware 1:8ea78dce6b36 118 * PAP and CHAP.
philware 1:8ea78dce6b36 119 */
philware 1:8ea78dce6b36 120 virtual void set_authentication(nsapi_security_t auth);
philware 1:8ea78dce6b36 121
philware 1:8ea78dce6b36 122 /** Set the cellular network credentials.
philware 1:8ea78dce6b36 123 *
philware 1:8ea78dce6b36 124 * Please check documentation of connect() for default behaviour of APN settings.
philware 1:8ea78dce6b36 125 *
philware 1:8ea78dce6b36 126 * @param apn Access point name.
philware 1:8ea78dce6b36 127 * @param uname Optionally, user name.
philware 1:8ea78dce6b36 128 * @param pwd Optionally, password.
philware 1:8ea78dce6b36 129 */
philware 1:8ea78dce6b36 130 virtual void set_credentials(const char *apn, const char *uname = 0,
philware 1:8ea78dce6b36 131 const char *pwd = 0);
philware 1:8ea78dce6b36 132
philware 1:8ea78dce6b36 133 /** Set the PIN code for the SIM card.
philware 1:8ea78dce6b36 134 *
philware 1:8ea78dce6b36 135 * @param sim_pin PIN for the SIM card.
philware 1:8ea78dce6b36 136 */
philware 1:8ea78dce6b36 137 virtual void set_sim_pin(const char *sim_pin);
philware 1:8ea78dce6b36 138
philware 1:8ea78dce6b36 139 /** Set the local listen port when opening a UDP socket
philware 1:8ea78dce6b36 140 *
philware 1:8ea78dce6b36 141 */
philware 1:8ea78dce6b36 142 void set_LocalListenPort(int port);
philware 4:2bf3875a13f1 143
philware 4:2bf3875a13f1 144 /**
philware 4:2bf3875a13f1 145 * Turns on the modem and reads the module information
philware 4:2bf3875a13f1 146 */
philware 4:2bf3875a13f1 147 bool initialise();
philware 1:8ea78dce6b36 148
philware 1:8ea78dce6b36 149 /** Connect to the cellular network and start the interface.
philware 1:8ea78dce6b36 150 *
philware 4:2bf3875a13f1 151 * Attempts to connect to a cellular network. Note: if initialise() has
philware 1:8ea78dce6b36 152 * not been called beforehand, connect() will call it first.
philware 1:8ea78dce6b36 153 *
philware 1:8ea78dce6b36 154 * @param sim_pin PIN for the SIM card.
philware 1:8ea78dce6b36 155 * @param apn Optionally, access point name.
philware 1:8ea78dce6b36 156 * @param uname Optionally, user name.
philware 1:8ea78dce6b36 157 * @param pwd Optionally, password.
philware 1:8ea78dce6b36 158 * @return NSAPI_ERROR_OK on success, or negative error code on failure.
philware 1:8ea78dce6b36 159 */
philware 1:8ea78dce6b36 160 virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
philware 1:8ea78dce6b36 161 const char *uname = 0, const char *pwd = 0);
philware 1:8ea78dce6b36 162
philware 1:8ea78dce6b36 163 /** Attempt to connect to the cellular network.
philware 1:8ea78dce6b36 164 *
philware 1:8ea78dce6b36 165 * Brings up the network interface. Connects to the cellular radio
philware 1:8ea78dce6b36 166 * network and then brings up IP stack on the cellular modem to be used
philware 1:8ea78dce6b36 167 * indirectly via AT commands, rather than LWIP. Note: if init() has
philware 1:8ea78dce6b36 168 * not been called beforehand, connect() will call it first.
philware 1:8ea78dce6b36 169 * NOTE: even a failed attempt to connect will cause the modem to remain
philware 1:8ea78dce6b36 170 * powered up. To power it down, call deinit().
philware 1:8ea78dce6b36 171 *
philware 1:8ea78dce6b36 172 * For APN setup, default behaviour is to use 'internet' as APN string
philware 1:8ea78dce6b36 173 * and assuming no authentication is required, i.e., user name and password
philware 1:8ea78dce6b36 174 * are not set. Optionally, a database lookup can be requested by turning
philware 1:8ea78dce6b36 175 * on the APN database lookup feature. The APN database is by no means
philware 1:8ea78dce6b36 176 * exhaustive (feel free to submit a pull request with additional values).
philware 1:8ea78dce6b36 177 * It contains a short list of some public APNs with publicly available
philware 1:8ea78dce6b36 178 * user names and passwords (if required) in some particular countries only.
philware 1:8ea78dce6b36 179 * Lookup is done using IMSI (International mobile subscriber identifier).
philware 1:8ea78dce6b36 180 *
philware 1:8ea78dce6b36 181 * The preferred method is to setup APN using 'set_credentials()' API.
philware 1:8ea78dce6b36 182 *
philware 1:8ea78dce6b36 183 * If you find that the AT interface returns "CONNECT" but shortly afterwards
philware 1:8ea78dce6b36 184 * drops the connection then 99% of the time this will be because the APN
philware 1:8ea78dce6b36 185 * is incorrect.
philware 1:8ea78dce6b36 186 *
philware 1:8ea78dce6b36 187 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 188 */
philware 1:8ea78dce6b36 189 virtual nsapi_error_t connect();
philware 1:8ea78dce6b36 190
philware 1:8ea78dce6b36 191 /** Attempt to disconnect from the network.
philware 1:8ea78dce6b36 192 *
philware 1:8ea78dce6b36 193 * Brings down the network interface.
philware 1:8ea78dce6b36 194 * Does not bring down the Radio network.
philware 1:8ea78dce6b36 195 *
philware 1:8ea78dce6b36 196 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 197 */
philware 1:8ea78dce6b36 198 virtual nsapi_error_t disconnect();
philware 1:8ea78dce6b36 199
philware 1:8ea78dce6b36 200 /** Adds or removes a SIM facility lock.
philware 1:8ea78dce6b36 201 *
philware 1:8ea78dce6b36 202 * Can be used to enable or disable SIM PIN check at device startup.
philware 1:8ea78dce6b36 203 *
philware 1:8ea78dce6b36 204 * @param set Can be set to true if the SIM PIN check is supposed
philware 1:8ea78dce6b36 205 * to be enabled and vice versa.
philware 1:8ea78dce6b36 206 * @param immediate If true, change the SIM PIN now, else set a flag
philware 1:8ea78dce6b36 207 * and make the change only when connect() is called.
philware 1:8ea78dce6b36 208 * If this is true and init() has not been called previously,
philware 1:8ea78dce6b36 209 * it will be called first.
philware 1:8ea78dce6b36 210 * @param sim_pin The current SIM PIN, must be a const. If this is not
philware 1:8ea78dce6b36 211 * provided, the SIM PIN must have previously been set by a
philware 1:8ea78dce6b36 212 * call to set_sim_pin().
philware 1:8ea78dce6b36 213 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 214 */
philware 1:8ea78dce6b36 215 nsapi_error_t set_sim_pin_check(bool set, bool immediate = false,
philware 1:8ea78dce6b36 216 const char *sim_pin = NULL);
philware 1:8ea78dce6b36 217
philware 1:8ea78dce6b36 218 /** Change the PIN for the SIM card.
philware 1:8ea78dce6b36 219 *
philware 1:8ea78dce6b36 220 * Provide the new PIN for your SIM card with this API. It is ONLY possible to
philware 1:8ea78dce6b36 221 * change the SIM PIN when SIM PIN checking is ENABLED.
philware 1:8ea78dce6b36 222 *
philware 1:8ea78dce6b36 223 * @param new_pin New PIN to be used in string format, must be a const.
philware 1:8ea78dce6b36 224 * @param immediate If true, change the SIM PIN now, else set a flag
philware 1:8ea78dce6b36 225 * and make the change only when connect() is called.
philware 1:8ea78dce6b36 226 * If this is true and init() has not been called previously,
philware 1:8ea78dce6b36 227 * it will be called first.
philware 1:8ea78dce6b36 228 * @param old_pin Old PIN, must be a const. If this is not provided, the SIM PIN
philware 1:8ea78dce6b36 229 * must have previously been set by a call to set_sim_pin().
philware 1:8ea78dce6b36 230 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 231 */
philware 1:8ea78dce6b36 232 nsapi_error_t set_new_sim_pin(const char *new_pin, bool immediate = false,
philware 1:8ea78dce6b36 233 const char *old_pin = NULL);
philware 1:8ea78dce6b36 234
philware 1:8ea78dce6b36 235 /** Check if the connection is currently established or not.
philware 1:8ea78dce6b36 236 *
philware 1:8ea78dce6b36 237 * @return True if connected to a data network, otherwise false.
philware 1:8ea78dce6b36 238 */
philware 1:8ea78dce6b36 239 virtual bool is_connected();
philware 1:8ea78dce6b36 240
philware 1:8ea78dce6b36 241 /** Get the local IP address
philware 1:8ea78dce6b36 242 *
philware 1:8ea78dce6b36 243 * @return Null-terminated representation of the local IP address
philware 1:8ea78dce6b36 244 * or null if no IP address has been received.
philware 1:8ea78dce6b36 245 */
philware 1:8ea78dce6b36 246 virtual const char *get_ip_address();
philware 1:8ea78dce6b36 247
philware 1:8ea78dce6b36 248 /** Get the local network mask.
philware 1:8ea78dce6b36 249 *
philware 1:8ea78dce6b36 250 * @return Null-terminated representation of the local network mask
philware 1:8ea78dce6b36 251 * or null if no network mask has been received.
philware 1:8ea78dce6b36 252 */
philware 1:8ea78dce6b36 253 virtual const char *get_netmask();
philware 1:8ea78dce6b36 254
philware 1:8ea78dce6b36 255 /** Get the local gateways.
philware 1:8ea78dce6b36 256 *
philware 1:8ea78dce6b36 257 * @return Null-terminated representation of the local gateway
philware 1:8ea78dce6b36 258 * or null if no network mask has been received.
philware 1:8ea78dce6b36 259 */
philware 1:8ea78dce6b36 260 virtual const char *get_gateway();
philware 1:8ea78dce6b36 261
philware 1:8ea78dce6b36 262 /** Call back in case connection is lost.
philware 1:8ea78dce6b36 263 *
philware 1:8ea78dce6b36 264 * @param cb The function to call.
philware 1:8ea78dce6b36 265 */
philware 1:8ea78dce6b36 266 void connection_status_cb(Callback<void(nsapi_error_t)> cb);
philware 1:8ea78dce6b36 267
philware 1:8ea78dce6b36 268 protected:
philware 1:8ea78dce6b36 269
philware 1:8ea78dce6b36 270 /** Socket "unused" value.
philware 1:8ea78dce6b36 271 */
philware 1:8ea78dce6b36 272 #define SOCKET_UNUSED -1
philware 1:8ea78dce6b36 273
philware 1:8ea78dce6b36 274 /** Socket timeout value in milliseconds.
philware 1:8ea78dce6b36 275 * Note: the sockets layer above will retry the
philware 1:8ea78dce6b36 276 * call to the functions here when they return NSAPI_ERROR_WOULD_BLOCK
philware 1:8ea78dce6b36 277 * and the user has set a larger timeout or full blocking.
philware 1:8ea78dce6b36 278 */
philware 1:8ea78dce6b36 279 #define SOCKET_TIMEOUT 1000
philware 1:8ea78dce6b36 280
philware 1:8ea78dce6b36 281 /** The maximum number of bytes in a packet that can be written
philware 1:8ea78dce6b36 282 * to the AT interface in one go.
philware 1:8ea78dce6b36 283 */
rob.meades@u-blox.com 7:69e676f4af84 284 #define MAX_WRITE_SIZE_N2XX 512
philware 1:8ea78dce6b36 285
philware 1:8ea78dce6b36 286 /** The maximum number of bytes in a packet that can be read from
philware 1:8ea78dce6b36 287 * from the AT interface in one go.
philware 1:8ea78dce6b36 288 */
rob.meades@u-blox.com 7:69e676f4af84 289 #define MAX_READ_SIZE_N2XX 512
philware 1:8ea78dce6b36 290
philware 1:8ea78dce6b36 291 /** Management structure for sockets.
philware 1:8ea78dce6b36 292 */
philware 1:8ea78dce6b36 293 typedef struct {
philware 1:8ea78dce6b36 294 int modem_handle; //!< The modem's handle for the socket.
philware 1:8ea78dce6b36 295 volatile nsapi_size_t pending; //!< The number of received bytes pending.
philware 1:8ea78dce6b36 296 void (*callback)(void *); //!< A callback for events.
philware 1:8ea78dce6b36 297 void *data; //!< A data pointer that must be passed to the callback.
philware 1:8ea78dce6b36 298 } SockCtrl;
philware 1:8ea78dce6b36 299
philware 1:8ea78dce6b36 300 /** Sockets storage.
philware 1:8ea78dce6b36 301 */
philware 1:8ea78dce6b36 302 SockCtrl _sockets[7];
philware 1:8ea78dce6b36 303
philware 1:8ea78dce6b36 304 /** Storage for a single IP address.
philware 1:8ea78dce6b36 305 */
philware 1:8ea78dce6b36 306 char *_ip;
philware 1:8ea78dce6b36 307
philware 1:8ea78dce6b36 308 /** The APN to use.
philware 1:8ea78dce6b36 309 */
philware 1:8ea78dce6b36 310 const char *_apn;
philware 1:8ea78dce6b36 311
philware 1:8ea78dce6b36 312 /** The user name to use.
philware 1:8ea78dce6b36 313 */
philware 1:8ea78dce6b36 314 const char *_uname;
philware 1:8ea78dce6b36 315
philware 1:8ea78dce6b36 316 /** The password to use.
philware 1:8ea78dce6b36 317 */
philware 1:8ea78dce6b36 318 const char *_pwd;
philware 1:8ea78dce6b36 319
philware 1:8ea78dce6b36 320 /** The type of authentication to use.
philware 1:8ea78dce6b36 321 */
philware 1:8ea78dce6b36 322 nsapi_security_t _auth;
philware 1:8ea78dce6b36 323
philware 1:8ea78dce6b36 324 /** Get the next set of credentials from the database.
philware 1:8ea78dce6b36 325 */
philware 1:8ea78dce6b36 326 virtual void get_next_credentials(const char * config);
philware 1:8ea78dce6b36 327
philware 1:8ea78dce6b36 328 /** Provide access to the NetworkStack object
philware 1:8ea78dce6b36 329 *
philware 1:8ea78dce6b36 330 * @return The underlying NetworkStack object.
philware 1:8ea78dce6b36 331 */
philware 1:8ea78dce6b36 332 virtual NetworkStack *get_stack();
philware 1:8ea78dce6b36 333
philware 1:8ea78dce6b36 334 protected:
philware 1:8ea78dce6b36 335
philware 1:8ea78dce6b36 336 /** Open a socket.
philware 1:8ea78dce6b36 337 *
philware 1:8ea78dce6b36 338 * Creates a network socket and stores it in the specified handle.
philware 1:8ea78dce6b36 339 * The handle must be passed to following calls on the socket.
philware 1:8ea78dce6b36 340 *
philware 1:8ea78dce6b36 341 * @param handle Destination for the handle to a newly created socket.
philware 1:8ea78dce6b36 342 * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP.
philware 1:8ea78dce6b36 343 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 344 */
philware 1:8ea78dce6b36 345 virtual nsapi_error_t socket_open(nsapi_socket_t *handle,
philware 1:8ea78dce6b36 346 nsapi_protocol_t proto);
philware 1:8ea78dce6b36 347
philware 1:8ea78dce6b36 348 /** Close a socket.
philware 1:8ea78dce6b36 349 *
philware 1:8ea78dce6b36 350 * Closes any open connection and deallocates any memory associated
philware 1:8ea78dce6b36 351 * with the socket.
philware 1:8ea78dce6b36 352 *
philware 1:8ea78dce6b36 353 * @param handle Socket handle.
philware 1:8ea78dce6b36 354 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 355 */
philware 1:8ea78dce6b36 356 virtual nsapi_error_t socket_close(nsapi_socket_t handle);
philware 1:8ea78dce6b36 357
philware 1:8ea78dce6b36 358 /** Bind a specific port to a socket.
philware 1:8ea78dce6b36 359 *
philware 1:8ea78dce6b36 360 * Binding a socket specifies port on which to receive
philware 1:8ea78dce6b36 361 * data. The IP address is ignored. Note that binding
philware 1:8ea78dce6b36 362 * a socket involves closing it and reopening and so the
philware 1:8ea78dce6b36 363 * bind operation should be carried out before any others.
philware 1:8ea78dce6b36 364 *
philware 1:8ea78dce6b36 365 * @param handle Socket handle.
philware 1:8ea78dce6b36 366 * @param address Local address to bind (of which only the port is used).
philware 1:8ea78dce6b36 367 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 368 */
philware 1:8ea78dce6b36 369 virtual nsapi_error_t socket_bind(nsapi_socket_t handle,
philware 1:8ea78dce6b36 370 const SocketAddress &address);
philware 1:8ea78dce6b36 371
philware 1:8ea78dce6b36 372 /** Connects TCP socket to a remote host.
philware 1:8ea78dce6b36 373 *
philware 1:8ea78dce6b36 374 * Initiates a connection to a remote server specified by the
philware 1:8ea78dce6b36 375 * indicated address.
philware 1:8ea78dce6b36 376 *
philware 1:8ea78dce6b36 377 * @param handle Socket handle.
philware 1:8ea78dce6b36 378 * @param address The SocketAddress of the remote host.
philware 1:8ea78dce6b36 379 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 380 */
philware 1:8ea78dce6b36 381 virtual nsapi_error_t socket_connect(nsapi_socket_t handle,
philware 1:8ea78dce6b36 382 const SocketAddress &address);
philware 1:8ea78dce6b36 383
philware 1:8ea78dce6b36 384 /** Send data over a TCP socket.
philware 1:8ea78dce6b36 385 *
philware 1:8ea78dce6b36 386 * The socket must be connected to a remote host. Returns the number of
philware 1:8ea78dce6b36 387 * bytes sent from the buffer. This class sets no upper buffer limit on
philware 1:8ea78dce6b36 388 * buffer size and the maximum packet size is not connected with the
philware 1:8ea78dce6b36 389 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size
philware 1:8ea78dce6b36 390 * definitions.
philware 1:8ea78dce6b36 391 *
philware 1:8ea78dce6b36 392 * @param handle Socket handle.
philware 1:8ea78dce6b36 393 * @param data Buffer of data to send to the host.
philware 1:8ea78dce6b36 394 * @param size Size of the buffer in bytes.
philware 1:8ea78dce6b36 395 * @return Number of sent bytes on success, negative error
philware 1:8ea78dce6b36 396 * code on failure.
philware 1:8ea78dce6b36 397 */
philware 1:8ea78dce6b36 398 virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle,
philware 1:8ea78dce6b36 399 const void *data, nsapi_size_t size);
philware 1:8ea78dce6b36 400
philware 1:8ea78dce6b36 401 /** Send a packet over a UDP socket.
philware 1:8ea78dce6b36 402 *
philware 1:8ea78dce6b36 403 * Sends data to the specified address. Returns the number of bytes
philware 1:8ea78dce6b36 404 * sent from the buffer.
philware 1:8ea78dce6b36 405 *
philware 1:8ea78dce6b36 406 * PACKET SIZES: the maximum packet size that can be sent in a single
philware 1:8ea78dce6b36 407 * UDP packet is limited by the configuration value
philware 1:8ea78dce6b36 408 * platform.buffered-serial-txbuf-size (defaults to 256).
philware 1:8ea78dce6b36 409 * The maximum UDP packet size is:
philware 1:8ea78dce6b36 410 *
philware 1:8ea78dce6b36 411 * platform.buffered-serial-txbuf-size - AT_PACKET_OVERHEAD
philware 1:8ea78dce6b36 412 *
philware 1:8ea78dce6b36 413 * ...with a limit of 1024 bytes (at the AT interface). So, to allow sending
philware 1:8ea78dce6b36 414 * of a 1024 byte UDP packet, edit your mbed_app.json to add a target override
philware 1:8ea78dce6b36 415 * setting platform.buffered-serial-txbuf-size to 1101. However, for
philware 1:8ea78dce6b36 416 * UDP packets, 508 bytes is considered a more realistic size, taking into
philware 1:8ea78dce6b36 417 * account fragmentation sizes over the public internet, which leads to a
philware 1:8ea78dce6b36 418 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size
philware 1:8ea78dce6b36 419 * setting of 585.
philware 1:8ea78dce6b36 420 *
philware 1:8ea78dce6b36 421 * If size is larger than this limit, the data will be split across separate
philware 1:8ea78dce6b36 422 * UDP packets.
philware 1:8ea78dce6b36 423 *
philware 1:8ea78dce6b36 424 * @param handle Socket handle.
philware 1:8ea78dce6b36 425 * @param address The SocketAddress of the remote host.
philware 1:8ea78dce6b36 426 * @param data Buffer of data to send to the host.
philware 1:8ea78dce6b36 427 * @param size Size of the buffer in bytes.
philware 1:8ea78dce6b36 428 * @return Number of sent bytes on success, negative error
philware 1:8ea78dce6b36 429 * code on failure.
philware 1:8ea78dce6b36 430 */
philware 1:8ea78dce6b36 431 virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle,
philware 1:8ea78dce6b36 432 const SocketAddress &address,
philware 1:8ea78dce6b36 433 const void *data,
philware 1:8ea78dce6b36 434 nsapi_size_t size);
philware 1:8ea78dce6b36 435
philware 1:8ea78dce6b36 436 /** Receive data over a TCP socket.
philware 1:8ea78dce6b36 437 *
philware 1:8ea78dce6b36 438 * The socket must be connected to a remote host. Returns the number of
philware 1:8ea78dce6b36 439 * bytes received into the buffer. This class sets no upper limit on the
philware 1:8ea78dce6b36 440 * buffer size and the maximum packet size is not connected with the
philware 1:8ea78dce6b36 441 * platform.buffered-serial-txbuf-size/platform.buffered-serial-rxbuf-size
philware 1:8ea78dce6b36 442 * definitions.
philware 1:8ea78dce6b36 443 *
philware 1:8ea78dce6b36 444 * @param handle Socket handle.
philware 1:8ea78dce6b36 445 * @param data Destination buffer for data received from the host.
philware 1:8ea78dce6b36 446 * @param size Size of the buffer in bytes.
philware 1:8ea78dce6b36 447 * @return Number of received bytes on success, negative error
philware 1:8ea78dce6b36 448 * code on failure.
philware 1:8ea78dce6b36 449 */
philware 1:8ea78dce6b36 450 virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle,
philware 1:8ea78dce6b36 451 void *data, nsapi_size_t size);
philware 1:8ea78dce6b36 452
philware 1:8ea78dce6b36 453 /** Receive a packet over a UDP socket.
philware 1:8ea78dce6b36 454 *
philware 1:8ea78dce6b36 455 * Receives data and stores the source address in address if address
philware 1:8ea78dce6b36 456 * is not NULL. Returns the number of bytes received into the buffer.
philware 1:8ea78dce6b36 457 *
philware 1:8ea78dce6b36 458 * PACKET SIZES: the maximum packet size that can be retrieved in a
philware 1:8ea78dce6b36 459 * single call to this method is limited by the configuration value
philware 1:8ea78dce6b36 460 * platform.buffered-serial-rxbuf-size (default 256). The maximum
philware 1:8ea78dce6b36 461 * UDP packet size is:
philware 1:8ea78dce6b36 462 *
philware 1:8ea78dce6b36 463 * platform.buffered-serial-rxbuf-size - AT_PACKET_OVERHEAD
philware 1:8ea78dce6b36 464 *
philware 1:8ea78dce6b36 465 * ...with a limit of 1024 (at the AT interface). So to allow reception of a
philware 1:8ea78dce6b36 466 * 1024 byte UDP packet in a single call, edit your mbed_app.json to add a
philware 1:8ea78dce6b36 467 * target override setting platform.buffered-serial-rxbuf-size to 1101.
philware 1:8ea78dce6b36 468 *
philware 1:8ea78dce6b36 469 * If the received packet is larger than this limit, any remainder will
philware 1:8ea78dce6b36 470 * be returned in subsequent calls to this method. Once a single UDP
philware 1:8ea78dce6b36 471 * packet has been received, this method will return.
philware 1:8ea78dce6b36 472 *
philware 1:8ea78dce6b36 473 * @param handle Socket handle.
philware 1:8ea78dce6b36 474 * @param address Destination for the source address or NULL.
philware 1:8ea78dce6b36 475 * @param data Destination buffer for data received from the host.
philware 1:8ea78dce6b36 476 * @param size Size of the buffer in bytes.
philware 1:8ea78dce6b36 477 * @return Number of received bytes on success, negative error
philware 1:8ea78dce6b36 478 * code on failure.
philware 1:8ea78dce6b36 479 */
philware 1:8ea78dce6b36 480 virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle,
philware 1:8ea78dce6b36 481 SocketAddress *address,
philware 1:8ea78dce6b36 482 void *data, nsapi_size_t size);
philware 1:8ea78dce6b36 483
philware 1:8ea78dce6b36 484 /** Register a callback on state change of the socket.
philware 1:8ea78dce6b36 485 *
philware 1:8ea78dce6b36 486 * The specified callback will be called on state changes such as when
philware 1:8ea78dce6b36 487 * the socket can recv/send/accept successfully and on when an error
philware 1:8ea78dce6b36 488 * occurs. The callback may also be called spuriously without reason.
philware 1:8ea78dce6b36 489 *
philware 1:8ea78dce6b36 490 * The callback may be called in an interrupt context and should not
philware 1:8ea78dce6b36 491 * perform expensive operations such as recv/send calls.
philware 1:8ea78dce6b36 492 *
philware 1:8ea78dce6b36 493 * @param handle Socket handle.
philware 1:8ea78dce6b36 494 * @param callback Function to call on state change.
philware 1:8ea78dce6b36 495 * @param data Argument to pass to callback.
philware 1:8ea78dce6b36 496 */
philware 1:8ea78dce6b36 497 virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *),
philware 1:8ea78dce6b36 498 void *data);
philware 1:8ea78dce6b36 499
philware 1:8ea78dce6b36 500 /** Listen for connections on a TCP socket.
philware 1:8ea78dce6b36 501 *
philware 1:8ea78dce6b36 502 * Marks the socket as a passive socket that can be used to accept
philware 1:8ea78dce6b36 503 * incoming connections.
philware 1:8ea78dce6b36 504 *
philware 1:8ea78dce6b36 505 * @param handle Socket handle.
philware 1:8ea78dce6b36 506 * @param backlog Number of pending connections that can be queued
philware 1:8ea78dce6b36 507 * simultaneously, defaults to 1.
philware 1:8ea78dce6b36 508 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 509 */
philware 1:8ea78dce6b36 510 virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog);
philware 1:8ea78dce6b36 511
philware 1:8ea78dce6b36 512 /** Accepts a connection on a TCP socket.
philware 1:8ea78dce6b36 513 *
philware 1:8ea78dce6b36 514 * The server socket must be bound and set to listen for connections.
philware 1:8ea78dce6b36 515 * On a new connection, creates a network socket and stores it in the
philware 1:8ea78dce6b36 516 * specified handle. The handle must be passed to following calls on
philware 1:8ea78dce6b36 517 * the socket.
philware 1:8ea78dce6b36 518 *
philware 1:8ea78dce6b36 519 * A stack may have a finite number of sockets, in this case
philware 1:8ea78dce6b36 520 * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
philware 1:8ea78dce6b36 521 *
philware 1:8ea78dce6b36 522 * This call is non-blocking. If accept would block,
philware 1:8ea78dce6b36 523 * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
philware 1:8ea78dce6b36 524 *
philware 1:8ea78dce6b36 525 * @param server Socket handle to server to accept from.
philware 1:8ea78dce6b36 526 * @param handle Destination for a handle to the newly created socket.
philware 1:8ea78dce6b36 527 * @param address Destination for the remote address or NULL.
philware 1:8ea78dce6b36 528 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 529 */
philware 1:8ea78dce6b36 530 virtual nsapi_error_t socket_accept(nsapi_socket_t server,
philware 1:8ea78dce6b36 531 nsapi_socket_t *handle,
philware 1:8ea78dce6b36 532 SocketAddress *address = 0);
philware 1:8ea78dce6b36 533
philware 1:8ea78dce6b36 534 /** Set stack-specific socket options.
philware 1:8ea78dce6b36 535 *
philware 1:8ea78dce6b36 536 * The setsockopt allow an application to pass stack-specific hints
philware 1:8ea78dce6b36 537 * to the underlying stack. For unsupported options,
philware 1:8ea78dce6b36 538 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
philware 1:8ea78dce6b36 539 *
philware 1:8ea78dce6b36 540 * @param handle Socket handle.
philware 1:8ea78dce6b36 541 * @param level Stack-specific protocol level.
philware 1:8ea78dce6b36 542 * @param optname Stack-specific option identifier.
philware 1:8ea78dce6b36 543 * @param optval Option value.
philware 1:8ea78dce6b36 544 * @param optlen Length of the option value.
philware 1:8ea78dce6b36 545 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 546 */
philware 1:8ea78dce6b36 547 virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
philware 1:8ea78dce6b36 548 int optname, const void *optval,
philware 1:8ea78dce6b36 549 unsigned optlen);
philware 1:8ea78dce6b36 550
philware 1:8ea78dce6b36 551 /** Get stack-specific socket options.
philware 1:8ea78dce6b36 552 *
philware 1:8ea78dce6b36 553 * The getstackopt allow an application to retrieve stack-specific hints
philware 1:8ea78dce6b36 554 * from the underlying stack. For unsupported options,
philware 1:8ea78dce6b36 555 * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
philware 1:8ea78dce6b36 556 *
philware 1:8ea78dce6b36 557 * @param handle Socket handle.
philware 1:8ea78dce6b36 558 * @param level Stack-specific protocol level.
philware 1:8ea78dce6b36 559 * @param optname Stack-specific option identifier.
philware 1:8ea78dce6b36 560 * @param optval Destination for option value.
philware 1:8ea78dce6b36 561 * @param optlen Length of the option value.
philware 1:8ea78dce6b36 562 * @return 0 on success, negative error code on failure.
philware 1:8ea78dce6b36 563 */
philware 1:8ea78dce6b36 564 virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
philware 1:8ea78dce6b36 565 int optname, void *optval,
philware 1:8ea78dce6b36 566 unsigned *optlen);
philware 1:8ea78dce6b36 567
philware 1:8ea78dce6b36 568 private:
philware 1:8ea78dce6b36 569
philware 1:8ea78dce6b36 570 // u_ added to namespace us somewhat as this darned macro
philware 1:8ea78dce6b36 571 // is defined by everyone and their dog
philware 1:8ea78dce6b36 572 #define u_stringify(a) str(a)
philware 1:8ea78dce6b36 573 #define str(a) #a
philware 1:8ea78dce6b36 574
philware 1:8ea78dce6b36 575 int _localListenPort;
philware 1:8ea78dce6b36 576
philware 1:8ea78dce6b36 577 bool _sim_pin_check_change_pending;
philware 1:8ea78dce6b36 578 bool _sim_pin_check_change_pending_enabled_value;
philware 1:8ea78dce6b36 579 bool _sim_pin_change_pending;
philware 1:8ea78dce6b36 580 const char *_sim_pin_change_pending_new_pin_value;
philware 1:8ea78dce6b36 581 Thread event_thread;
philware 1:8ea78dce6b36 582 void handle_event();
philware 1:8ea78dce6b36 583 SockCtrl * find_socket(int modem_handle = SOCKET_UNUSED);
philware 1:8ea78dce6b36 584 void clear_socket(SockCtrl * socket);
philware 1:8ea78dce6b36 585 bool check_socket(SockCtrl * socket);
philware 1:8ea78dce6b36 586
philware 1:8ea78dce6b36 587 nsapi_size_or_error_t receivefrom(int socketId, SocketAddress *address, int length, char *buf);
philware 1:8ea78dce6b36 588 nsapi_size_or_error_t sendto(SockCtrl *socket, const SocketAddress &address, const char *buf, int size);
philware 4:2bf3875a13f1 589 bool sendATChopped(const char *);
philware 1:8ea78dce6b36 590
philware 1:8ea78dce6b36 591 char hex_char(char c);
philware 1:8ea78dce6b36 592 int hex_to_bin(const char* s, char * buff, int length);
philware 1:8ea78dce6b36 593 void bin_to_hex(const char *buff, unsigned int length, char *output);
philware 1:8ea78dce6b36 594
philware 1:8ea78dce6b36 595 Callback<void(nsapi_error_t)> _connection_status_cb;
philware 1:8ea78dce6b36 596 void NSONMI_URC();
philware 1:8ea78dce6b36 597 };
philware 1:8ea78dce6b36 598
philware 1:8ea78dce6b36 599 #endif // _UBLOX_AT_CELLULAR_INTERFACE_
philware 1:8ea78dce6b36 600