Alex Leung / Mbed OS HealthTracker

Test version

ESP8266Interface.h@0:4be500de690c, 2018-03-20 (annotated)

Committer:
a2824256
Date:
Tue Mar 20 02:09:21 2018 +0000
Revision:
0:4be500de690c
test

Who changed what in which revision?

UserRevisionLine numberNew contents of line
a2824256 0:4be500de690c 1 /* ESP8266 implementation of NetworkInterfaceAPI
a2824256 0:4be500de690c 2 * Copyright (c) 2015 ARM Limited
a2824256 0:4be500de690c 3 *
a2824256 0:4be500de690c 4 * Licensed under the Apache License, Version 2.0 (the "License");
a2824256 0:4be500de690c 5 * you may not use this file except in compliance with the License.
a2824256 0:4be500de690c 6 * You may obtain a copy of the License at
a2824256 0:4be500de690c 7 *
a2824256 0:4be500de690c 8 * http://www.apache.org/licenses/LICENSE-2.0
a2824256 0:4be500de690c 9 *
a2824256 0:4be500de690c 10 * Unless required by applicable law or agreed to in writing, software
a2824256 0:4be500de690c 11 * distributed under the License is distributed on an "AS IS" BASIS,
a2824256 0:4be500de690c 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
a2824256 0:4be500de690c 13 * See the License for the specific language governing permissions and
a2824256 0:4be500de690c 14 * limitations under the License.
a2824256 0:4be500de690c 15 */
a2824256 0:4be500de690c 16
a2824256 0:4be500de690c 17 #ifndef ESP8266_INTERFACE_H
a2824256 0:4be500de690c 18 #define ESP8266_INTERFACE_H
a2824256 0:4be500de690c 19
a2824256 0:4be500de690c 20 #include "mbed.h"
a2824256 0:4be500de690c 21 #include "ESP8266.h"
a2824256 0:4be500de690c 22
a2824256 0:4be500de690c 23
a2824256 0:4be500de690c 24 #define ESP8266_SOCKET_COUNT 5
a2824256 0:4be500de690c 25
a2824256 0:4be500de690c 26 /** ESP8266Interface class
a2824256 0:4be500de690c 27 * Implementation of the NetworkStack for the ESP8266
a2824256 0:4be500de690c 28 */
a2824256 0:4be500de690c 29 class ESP8266Interface : public NetworkStack, public WiFiInterface
a2824256 0:4be500de690c 30 {
a2824256 0:4be500de690c 31 public:
a2824256 0:4be500de690c 32 /** ESP8266Interface lifetime
a2824256 0:4be500de690c 33 * @param tx TX pin
a2824256 0:4be500de690c 34 * @param rx RX pin
a2824256 0:4be500de690c 35 * @param debug Enable debugging
a2824256 0:4be500de690c 36 */
a2824256 0:4be500de690c 37 ESP8266Interface(PinName tx, PinName rx, bool debug = false);
a2824256 0:4be500de690c 38
a2824256 0:4be500de690c 39 /** Start the interface
a2824256 0:4be500de690c 40 *
a2824256 0:4be500de690c 41 * Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
a2824256 0:4be500de690c 42 * If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
a2824256 0:4be500de690c 43 *
a2824256 0:4be500de690c 44 * @return 0 on success, negative error code on failure
a2824256 0:4be500de690c 45 */
a2824256 0:4be500de690c 46 virtual int connect();
a2824256 0:4be500de690c 47
a2824256 0:4be500de690c 48 /** Start the interface
a2824256 0:4be500de690c 49 *
a2824256 0:4be500de690c 50 * Attempts to connect to a WiFi network.
a2824256 0:4be500de690c 51 *
a2824256 0:4be500de690c 52 * @param ssid Name of the network to connect to
a2824256 0:4be500de690c 53 * @param pass Security passphrase to connect to the network
a2824256 0:4be500de690c 54 * @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE)
a2824256 0:4be500de690c 55 * @param channel This parameter is not supported, setting it to anything else than 0 will result in NSAPI_ERROR_UNSUPPORTED
a2824256 0:4be500de690c 56 * @return 0 on success, or error code on failure
a2824256 0:4be500de690c 57 */
a2824256 0:4be500de690c 58 virtual int connect(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE,
a2824256 0:4be500de690c 59 uint8_t channel = 0);
a2824256 0:4be500de690c 60
a2824256 0:4be500de690c 61 /** Set the WiFi network credentials
a2824256 0:4be500de690c 62 *
a2824256 0:4be500de690c 63 * @param ssid Name of the network to connect to
a2824256 0:4be500de690c 64 * @param pass Security passphrase to connect to the network
a2824256 0:4be500de690c 65 * @param security Type of encryption for connection
a2824256 0:4be500de690c 66 * (defaults to NSAPI_SECURITY_NONE)
a2824256 0:4be500de690c 67 * @return 0 on success, or error code on failure
a2824256 0:4be500de690c 68 */
a2824256 0:4be500de690c 69 virtual int set_credentials(const char *ssid, const char *pass, nsapi_security_t security = NSAPI_SECURITY_NONE);
a2824256 0:4be500de690c 70
a2824256 0:4be500de690c 71 /** Set the WiFi network channel - NOT SUPPORTED
a2824256 0:4be500de690c 72 *
a2824256 0:4be500de690c 73 * This function is not supported and will return NSAPI_ERROR_UNSUPPORTED
a2824256 0:4be500de690c 74 *
a2824256 0:4be500de690c 75 * @param channel Channel on which the connection is to be made, or 0 for any (Default: 0)
a2824256 0:4be500de690c 76 * @return Not supported, returns NSAPI_ERROR_UNSUPPORTED
a2824256 0:4be500de690c 77 */
a2824256 0:4be500de690c 78 virtual int set_channel(uint8_t channel);
a2824256 0:4be500de690c 79
a2824256 0:4be500de690c 80 /** Stop the interface
a2824256 0:4be500de690c 81 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 82 */
a2824256 0:4be500de690c 83 virtual int disconnect();
a2824256 0:4be500de690c 84
a2824256 0:4be500de690c 85 /** Get the internally stored IP address
a2824256 0:4be500de690c 86 * @return IP address of the interface or null if not yet connected
a2824256 0:4be500de690c 87 */
a2824256 0:4be500de690c 88 virtual const char *get_ip_address();
a2824256 0:4be500de690c 89
a2824256 0:4be500de690c 90 /** Get the internally stored MAC address
a2824256 0:4be500de690c 91 * @return MAC address of the interface
a2824256 0:4be500de690c 92 */
a2824256 0:4be500de690c 93 virtual const char *get_mac_address();
a2824256 0:4be500de690c 94
a2824256 0:4be500de690c 95 /** Get the local gateway
a2824256 0:4be500de690c 96 *
a2824256 0:4be500de690c 97 * @return Null-terminated representation of the local gateway
a2824256 0:4be500de690c 98 * or null if no network mask has been recieved
a2824256 0:4be500de690c 99 */
a2824256 0:4be500de690c 100 virtual const char *get_gateway();
a2824256 0:4be500de690c 101
a2824256 0:4be500de690c 102 /** Get the local network mask
a2824256 0:4be500de690c 103 *
a2824256 0:4be500de690c 104 * @return Null-terminated representation of the local network mask
a2824256 0:4be500de690c 105 * or null if no network mask has been recieved
a2824256 0:4be500de690c 106 */
a2824256 0:4be500de690c 107 virtual const char *get_netmask();
a2824256 0:4be500de690c 108
a2824256 0:4be500de690c 109 /** Gets the current radio signal strength for active connection
a2824256 0:4be500de690c 110 *
a2824256 0:4be500de690c 111 * @return Connection strength in dBm (negative value)
a2824256 0:4be500de690c 112 */
a2824256 0:4be500de690c 113 virtual int8_t get_rssi();
a2824256 0:4be500de690c 114
a2824256 0:4be500de690c 115 /** Scan for available networks
a2824256 0:4be500de690c 116 *
a2824256 0:4be500de690c 117 * This function will block.
a2824256 0:4be500de690c 118 *
a2824256 0:4be500de690c 119 * @param ap Pointer to allocated array to store discovered AP
a2824256 0:4be500de690c 120 * @param count Size of allocated @a res array, or 0 to only count available AP
a2824256 0:4be500de690c 121 * @param timeout Timeout in milliseconds; 0 for no timeout (Default: 0)
a2824256 0:4be500de690c 122 * @return Number of entries in @a, or if @a count was 0 number of available networks, negative on error
a2824256 0:4be500de690c 123 * see @a nsapi_error
a2824256 0:4be500de690c 124 */
a2824256 0:4be500de690c 125 virtual int scan(WiFiAccessPoint *res, unsigned count);
a2824256 0:4be500de690c 126
a2824256 0:4be500de690c 127 /** Translates a hostname to an IP address with specific version
a2824256 0:4be500de690c 128 *
a2824256 0:4be500de690c 129 * The hostname may be either a domain name or an IP address. If the
a2824256 0:4be500de690c 130 * hostname is an IP address, no network transactions will be performed.
a2824256 0:4be500de690c 131 *
a2824256 0:4be500de690c 132 * If no stack-specific DNS resolution is provided, the hostname
a2824256 0:4be500de690c 133 * will be resolve using a UDP socket on the stack.
a2824256 0:4be500de690c 134 *
a2824256 0:4be500de690c 135 * @param address Destination for the host SocketAddress
a2824256 0:4be500de690c 136 * @param host Hostname to resolve
a2824256 0:4be500de690c 137 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
a2824256 0:4be500de690c 138 * version is chosen by the stack (defaults to NSAPI_UNSPEC)
a2824256 0:4be500de690c 139 * @return 0 on success, negative error code on failure
a2824256 0:4be500de690c 140 */
a2824256 0:4be500de690c 141 using NetworkInterface::gethostbyname;
a2824256 0:4be500de690c 142
a2824256 0:4be500de690c 143 /** Add a domain name server to list of servers to query
a2824256 0:4be500de690c 144 *
a2824256 0:4be500de690c 145 * @param addr Destination for the host address
a2824256 0:4be500de690c 146 * @return 0 on success, negative error code on failure
a2824256 0:4be500de690c 147 */
a2824256 0:4be500de690c 148 using NetworkInterface::add_dns_server;
a2824256 0:4be500de690c 149
a2824256 0:4be500de690c 150 /* Set socket options
a2824256 0:4be500de690c 151 *
a2824256 0:4be500de690c 152 * The setsockopt allow an application to pass stack-specific hints
a2824256 0:4be500de690c 153 * to the underlying stack. For unsupported options,
a2824256 0:4be500de690c 154 * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
a2824256 0:4be500de690c 155 *
a2824256 0:4be500de690c 156 * @param handle Socket handle
a2824256 0:4be500de690c 157 * @param level Stack-specific protocol level
a2824256 0:4be500de690c 158 * @param optname Stack-specific option identifier
a2824256 0:4be500de690c 159 * @param optval Option value
a2824256 0:4be500de690c 160 * @param optlen Length of the option value
a2824256 0:4be500de690c 161 * @return 0 on success, negative error code on failure
a2824256 0:4be500de690c 162 */
a2824256 0:4be500de690c 163 virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
a2824256 0:4be500de690c 164 int optname, const void *optval, unsigned optlen);
a2824256 0:4be500de690c 165
a2824256 0:4be500de690c 166 /* Get socket options
a2824256 0:4be500de690c 167 *
a2824256 0:4be500de690c 168 * getsockopt allows an application to retrieve stack-specific options
a2824256 0:4be500de690c 169 * from the underlying stack using stack-specific level and option names,
a2824256 0:4be500de690c 170 * or to request generic options using levels from nsapi_socket_level_t.
a2824256 0:4be500de690c 171 *
a2824256 0:4be500de690c 172 * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
a2824256 0:4be500de690c 173 * and the socket is unmodified.
a2824256 0:4be500de690c 174 *
a2824256 0:4be500de690c 175 * @param level Stack-specific protocol level or nsapi_socket_level_t
a2824256 0:4be500de690c 176 * @param optname Level-specific option name
a2824256 0:4be500de690c 177 * @param optval Destination for option value
a2824256 0:4be500de690c 178 * @param optlen Length of the option value
a2824256 0:4be500de690c 179 * @return 0 on success, negative error code on failure
a2824256 0:4be500de690c 180 */
a2824256 0:4be500de690c 181 virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname,
a2824256 0:4be500de690c 182 void *optval, unsigned *optlen);
a2824256 0:4be500de690c 183
a2824256 0:4be500de690c 184 protected:
a2824256 0:4be500de690c 185 /** Open a socket
a2824256 0:4be500de690c 186 * @param handle Handle in which to store new socket
a2824256 0:4be500de690c 187 * @param proto Type of socket to open, NSAPI_TCP or NSAPI_UDP
a2824256 0:4be500de690c 188 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 189 */
a2824256 0:4be500de690c 190 virtual int socket_open(void **handle, nsapi_protocol_t proto);
a2824256 0:4be500de690c 191
a2824256 0:4be500de690c 192 /** Close the socket
a2824256 0:4be500de690c 193 * @param handle Socket handle
a2824256 0:4be500de690c 194 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 195 * @note On failure, any memory associated with the socket must still
a2824256 0:4be500de690c 196 * be cleaned up
a2824256 0:4be500de690c 197 */
a2824256 0:4be500de690c 198 virtual int socket_close(void *handle);
a2824256 0:4be500de690c 199
a2824256 0:4be500de690c 200 /** Bind a server socket to a specific port
a2824256 0:4be500de690c 201 * @param handle Socket handle
a2824256 0:4be500de690c 202 * @param address Local address to listen for incoming connections on
a2824256 0:4be500de690c 203 * @return 0 on success, negative on failure.
a2824256 0:4be500de690c 204 */
a2824256 0:4be500de690c 205 virtual int socket_bind(void *handle, const SocketAddress &address);
a2824256 0:4be500de690c 206
a2824256 0:4be500de690c 207 /** Start listening for incoming connections
a2824256 0:4be500de690c 208 * @param handle Socket handle
a2824256 0:4be500de690c 209 * @param backlog Number of pending connections that can be queued up at any
a2824256 0:4be500de690c 210 * one time [Default: 1]
a2824256 0:4be500de690c 211 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 212 */
a2824256 0:4be500de690c 213 virtual int socket_listen(void *handle, int backlog);
a2824256 0:4be500de690c 214
a2824256 0:4be500de690c 215 /** Connects this TCP socket to the server
a2824256 0:4be500de690c 216 * @param handle Socket handle
a2824256 0:4be500de690c 217 * @param address SocketAddress to connect to
a2824256 0:4be500de690c 218 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 219 */
a2824256 0:4be500de690c 220 virtual int socket_connect(void *handle, const SocketAddress &address);
a2824256 0:4be500de690c 221
a2824256 0:4be500de690c 222 /** Accept a new connection.
a2824256 0:4be500de690c 223 * @param handle Handle in which to store new socket
a2824256 0:4be500de690c 224 * @param server Socket handle to server to accept from
a2824256 0:4be500de690c 225 * @return 0 on success, negative on failure
a2824256 0:4be500de690c 226 * @note This call is not-blocking, if this call would block, must
a2824256 0:4be500de690c 227 * immediately return NSAPI_ERROR_WOULD_WAIT
a2824256 0:4be500de690c 228 */
a2824256 0:4be500de690c 229 virtual int socket_accept(void *handle, void **socket, SocketAddress *address);
a2824256 0:4be500de690c 230
a2824256 0:4be500de690c 231 /** Send data to the remote host
a2824256 0:4be500de690c 232 * @param handle Socket handle
a2824256 0:4be500de690c 233 * @param data The buffer to send to the host
a2824256 0:4be500de690c 234 * @param size The length of the buffer to send
a2824256 0:4be500de690c 235 * @return Number of written bytes on success, negative on failure
a2824256 0:4be500de690c 236 * @note This call is not-blocking, if this call would block, must
a2824256 0:4be500de690c 237 * immediately return NSAPI_ERROR_WOULD_WAIT
a2824256 0:4be500de690c 238 */
a2824256 0:4be500de690c 239 virtual int socket_send(void *handle, const void *data, unsigned size);
a2824256 0:4be500de690c 240
a2824256 0:4be500de690c 241 /** Receive data from the remote host
a2824256 0:4be500de690c 242 * @param handle Socket handle
a2824256 0:4be500de690c 243 * @param data The buffer in which to store the data received from the host
a2824256 0:4be500de690c 244 * @param size The maximum length of the buffer
a2824256 0:4be500de690c 245 * @return Number of received bytes on success, negative on failure
a2824256 0:4be500de690c 246 * @note This call is not-blocking, if this call would block, must
a2824256 0:4be500de690c 247 * immediately return NSAPI_ERROR_WOULD_WAIT
a2824256 0:4be500de690c 248 */
a2824256 0:4be500de690c 249 virtual int socket_recv(void *handle, void *data, unsigned size);
a2824256 0:4be500de690c 250
a2824256 0:4be500de690c 251 /** Send a packet to a remote endpoint
a2824256 0:4be500de690c 252 * @param handle Socket handle
a2824256 0:4be500de690c 253 * @param address The remote SocketAddress
a2824256 0:4be500de690c 254 * @param data The packet to be sent
a2824256 0:4be500de690c 255 * @param size The length of the packet to be sent
a2824256 0:4be500de690c 256 * @return The number of written bytes on success, negative on failure
a2824256 0:4be500de690c 257 * @note This call is not-blocking, if this call would block, must
a2824256 0:4be500de690c 258 * immediately return NSAPI_ERROR_WOULD_WAIT
a2824256 0:4be500de690c 259 */
a2824256 0:4be500de690c 260 virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size);
a2824256 0:4be500de690c 261
a2824256 0:4be500de690c 262 /** Receive a packet from a remote endpoint
a2824256 0:4be500de690c 263 * @param handle Socket handle
a2824256 0:4be500de690c 264 * @param address Destination for the remote SocketAddress or null
a2824256 0:4be500de690c 265 * @param buffer The buffer for storing the incoming packet data
a2824256 0:4be500de690c 266 * If a packet is too long to fit in the supplied buffer,
a2824256 0:4be500de690c 267 * excess bytes are discarded
a2824256 0:4be500de690c 268 * @param size The length of the buffer
a2824256 0:4be500de690c 269 * @return The number of received bytes on success, negative on failure
a2824256 0:4be500de690c 270 * @note This call is not-blocking, if this call would block, must
a2824256 0:4be500de690c 271 * immediately return NSAPI_ERROR_WOULD_WAIT
a2824256 0:4be500de690c 272 */
a2824256 0:4be500de690c 273 virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size);
a2824256 0:4be500de690c 274
a2824256 0:4be500de690c 275 /** Register a callback on state change of the socket
a2824256 0:4be500de690c 276 * @param handle Socket handle
a2824256 0:4be500de690c 277 * @param callback Function to call on state change
a2824256 0:4be500de690c 278 * @param data Argument to pass to callback
a2824256 0:4be500de690c 279 * @note Callback may be called in an interrupt context.
a2824256 0:4be500de690c 280 */
a2824256 0:4be500de690c 281 virtual void socket_attach(void *handle, void (*callback)(void *), void *data);
a2824256 0:4be500de690c 282
a2824256 0:4be500de690c 283 /** Provide access to the NetworkStack object
a2824256 0:4be500de690c 284 *
a2824256 0:4be500de690c 285 * @return The underlying NetworkStack object
a2824256 0:4be500de690c 286 */
a2824256 0:4be500de690c 287 virtual NetworkStack *get_stack()
a2824256 0:4be500de690c 288 {
a2824256 0:4be500de690c 289 return this;
a2824256 0:4be500de690c 290 }
a2824256 0:4be500de690c 291
a2824256 0:4be500de690c 292 private:
a2824256 0:4be500de690c 293 static const int ESP8266_SSID_MAX_LENGTH = 32; /* 32 is what 802.11 defines as longest possible name */
a2824256 0:4be500de690c 294 static const int ESP8266_PASSPHRASE_MAX_LENGTH = 63; /* The longest allowed passphrase */
a2824256 0:4be500de690c 295 static const int ESP8266_PASSPHRASE_MIN_LENGTH = 8; /* The shortest allowed passphrase */
a2824256 0:4be500de690c 296
a2824256 0:4be500de690c 297 ESP8266 _esp;
a2824256 0:4be500de690c 298 bool _ids[ESP8266_SOCKET_COUNT];
a2824256 0:4be500de690c 299 int _initialized;
a2824256 0:4be500de690c 300 int _started;
a2824256 0:4be500de690c 301
a2824256 0:4be500de690c 302 char ap_ssid[ESP8266_SSID_MAX_LENGTH + 1]; /* 32 is what 802.11 defines as longest possible name; +1 for the \0 */
a2824256 0:4be500de690c 303 nsapi_security_t ap_sec;
a2824256 0:4be500de690c 304 uint8_t ap_ch;
a2824256 0:4be500de690c 305 char ap_pass[ESP8266_PASSPHRASE_MAX_LENGTH + 1];
a2824256 0:4be500de690c 306 uint16_t _local_ports[ESP8266_SOCKET_COUNT];
a2824256 0:4be500de690c 307
a2824256 0:4be500de690c 308 bool _disable_default_softap();
a2824256 0:4be500de690c 309 void event();
a2824256 0:4be500de690c 310 bool _get_firmware_ok();
a2824256 0:4be500de690c 311 nsapi_error_t _init(void);
a2824256 0:4be500de690c 312 nsapi_error_t _startup(const int8_t wifi_mode);
a2824256 0:4be500de690c 313
a2824256 0:4be500de690c 314 struct {
a2824256 0:4be500de690c 315 void (*callback)(void *);
a2824256 0:4be500de690c 316 void *data;
a2824256 0:4be500de690c 317 } _cbs[ESP8266_SOCKET_COUNT];
a2824256 0:4be500de690c 318 };
a2824256 0:4be500de690c 319
a2824256 0:4be500de690c 320 #endif