Components / ESP8266Interface

Socket interface for ESP8266. Implements the NetworkSocketAPI. Requires device to use the Espressif Firmware.

Dependencies:   ESP8266

Dependents:   ESP8266InterfaceTests HelloESP8266Interface

Fork of ESP8266Interface by NetworkSocketAPI

Note

This library assumes your ESP8266 is running the Espressif Firmware. For instructions on how to update your ESP8266 to use the correct firmware see the Firmware Update Wiki Page.

Currently the ESP8266Interface LIbrary has the following Abilities:

Working

  • TCP Client
  • UDP Client
  • Transparent mode (single connection of 1 type at a time)
  • Station Mode (connects to AP)

To be implimented

  • TCP Server
  • UDP Server
  • Multi Connection Mode (able to have up to 5 sockets at a time)
  • AP Mode (Make ESP Chip act like access point)
  • DNS Support (currently websites must be looked up by IP)
  • Error Recovery

Nice but not necessary

  • colorized text for ESP AT Commands in Command line (easier to differentiate from other text)

ESP8266Interface.h@57:2ad35ade7a83, 2016-05-10 (annotated)

Committer:
Christopher Haster
Date:
Tue May 10 14:31:58 2016 -0500
Revision:
57:2ad35ade7a83
Parent:
56:34829ec3a3da 
Minor documentation changes

Who changed what in which revision?

UserRevisionLine numberNew contents of line
geky 49:750ed1b67483 1 /* ESP8266 implementation of NetworkInterfaceAPI
sarahmarshy 18:9fc7976c7b27 2 * Copyright (c) 2015 ARM Limited
sarahmarshy 18:9fc7976c7b27 3 *
sarahmarshy 18:9fc7976c7b27 4 * Licensed under the Apache License, Version 2.0 (the "License");
sarahmarshy 18:9fc7976c7b27 5 * you may not use this file except in compliance with the License.
sarahmarshy 18:9fc7976c7b27 6 * You may obtain a copy of the License at
sarahmarshy 18:9fc7976c7b27 7 *
sarahmarshy 18:9fc7976c7b27 8 * http://www.apache.org/licenses/LICENSE-2.0
sarahmarshy 18:9fc7976c7b27 9 *
sarahmarshy 18:9fc7976c7b27 10 * Unless required by applicable law or agreed to in writing, software
sarahmarshy 18:9fc7976c7b27 11 * distributed under the License is distributed on an "AS IS" BASIS,
sarahmarshy 18:9fc7976c7b27 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
sarahmarshy 18:9fc7976c7b27 13 * See the License for the specific language governing permissions and
sarahmarshy 18:9fc7976c7b27 14 * limitations under the License.
sarahmarshy 18:9fc7976c7b27 15 */
sarahmarshy 18:9fc7976c7b27 16
Christopher Haster 34:9c26a3dcdc1f 17 #ifndef ESP8266_INTERFACE_H
Christopher Haster 34:9c26a3dcdc1f 18 #define ESP8266_INTERFACE_H
sarahmarshy 18:9fc7976c7b27 19
sarahmarshy 18:9fc7976c7b27 20 #include "WiFiInterface.h"
sarahmarshy 23:fd0f3197c30b 21 #include "ESP8266.h"
Christopher Haster 34:9c26a3dcdc1f 22
Christopher Haster 34:9c26a3dcdc1f 23 #define ESP8266_SOCKET_COUNT 5
sarahmarshy 18:9fc7976c7b27 24
Christopher Haster 34:9c26a3dcdc1f 25 /** ESP8266Interface class
Christopher Haster 57:2ad35ade7a83 26 * Implementation of the NetworkStack for the ESP8266
sarahmarshy 18:9fc7976c7b27 27 */
Christopher Haster 56:34829ec3a3da 28 class ESP8266Interface : public NetworkStack, public WiFiInterface
sarahmarshy 18:9fc7976c7b27 29 {
sarahmarshy 18:9fc7976c7b27 30 public:
Christopher Haster 56:34829ec3a3da 31 /** ESP8266Interface lifetime
Christopher Haster 57:2ad35ade7a83 32 * @param tx TX pin
Christopher Haster 57:2ad35ade7a83 33 * @param rx RX pin
Christopher Haster 57:2ad35ade7a83 34 * @param debug Enable debugging
Christopher Haster 56:34829ec3a3da 35 */
Christopher Haster 34:9c26a3dcdc1f 36 ESP8266Interface(PinName tx, PinName rx, bool debug = false);
Christopher Haster 34:9c26a3dcdc1f 37
Christopher Haster 56:34829ec3a3da 38 /** Start the interface
Christopher Haster 56:34829ec3a3da 39 *
Christopher Haster 56:34829ec3a3da 40 * Attempts to connect to a WiFi network. If passphrase is invalid,
Christopher Haster 56:34829ec3a3da 41 * NSAPI_ERROR_AUTH_ERROR is returned.
Christopher Haster 56:34829ec3a3da 42 *
Christopher Haster 56:34829ec3a3da 43 * @param ssid Name of the network to connect to
Christopher Haster 56:34829ec3a3da 44 * @param pass Security passphrase to connect to the network
Christopher Haster 56:34829ec3a3da 45 * @param security Type of encryption for connection
Christopher Haster 56:34829ec3a3da 46 * @return 0 on success, negative error code on failure
Christopher Haster 56:34829ec3a3da 47 */
Christopher Haster 56:34829ec3a3da 48 virtual int connect(
Christopher Haster 34:9c26a3dcdc1f 49 const char *ssid,
Christopher Haster 34:9c26a3dcdc1f 50 const char *pass,
Christopher Haster 56:34829ec3a3da 51 nsapi_security_t security = NSAPI_SECURITY_NONE);
Christopher Haster 56:34829ec3a3da 52
Christopher Haster 56:34829ec3a3da 53 /** Stop the interface
Christopher Haster 56:34829ec3a3da 54 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 55 */
Christopher Haster 56:34829ec3a3da 56 virtual int disconnect();
Christopher Haster 56:34829ec3a3da 57
Christopher Haster 56:34829ec3a3da 58 /** Get the internally stored IP address
Christopher Haster 56:34829ec3a3da 59 * @return IP address of the interface or null if not yet connected
Christopher Haster 56:34829ec3a3da 60 */
Christopher Haster 56:34829ec3a3da 61 virtual const char *get_ip_address();
Christopher Haster 56:34829ec3a3da 62
Christopher Haster 56:34829ec3a3da 63 /** Get the internally stored MAC address
Christopher Haster 56:34829ec3a3da 64 * @return MAC address of the interface
Christopher Haster 56:34829ec3a3da 65 */
Christopher Haster 56:34829ec3a3da 66 virtual const char *get_mac_address();
Christopher Haster 56:34829ec3a3da 67
Christopher Haster 56:34829ec3a3da 68 protected:
Christopher Haster 56:34829ec3a3da 69 /** Open a socket
Christopher Haster 56:34829ec3a3da 70 * @param handle Handle in which to store new socket
Christopher Haster 56:34829ec3a3da 71 * @param proto Type of socket to open, NSAPI_TCP or NSAPI_UDP
Christopher Haster 56:34829ec3a3da 72 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 73 */
Christopher Haster 56:34829ec3a3da 74 virtual int socket_open(void **handle, nsapi_protocol_t proto);
Christopher Haster 34:9c26a3dcdc1f 75
Christopher Haster 56:34829ec3a3da 76 /** Close the socket
Christopher Haster 56:34829ec3a3da 77 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 78 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 79 * @note On failure, any memory associated with the socket must still
Christopher Haster 56:34829ec3a3da 80 * be cleaned up
Christopher Haster 56:34829ec3a3da 81 */
Christopher Haster 56:34829ec3a3da 82 virtual int socket_close(void *handle);
Christopher Haster 56:34829ec3a3da 83
Christopher Haster 56:34829ec3a3da 84 /** Bind a server socket to a specific port
Christopher Haster 56:34829ec3a3da 85 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 86 * @param address Local address to listen for incoming connections on
Christopher Haster 56:34829ec3a3da 87 * @return 0 on success, negative on failure.
Christopher Haster 56:34829ec3a3da 88 */
Christopher Haster 56:34829ec3a3da 89 virtual int socket_bind(void *handle, const SocketAddress &address);
Christopher Haster 56:34829ec3a3da 90
Christopher Haster 56:34829ec3a3da 91 /** Start listening for incoming connections
Christopher Haster 56:34829ec3a3da 92 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 93 * @param backlog Number of pending connections that can be queued up at any
Christopher Haster 56:34829ec3a3da 94 * one time [Default: 1]
Christopher Haster 56:34829ec3a3da 95 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 96 */
Christopher Haster 56:34829ec3a3da 97 virtual int socket_listen(void *handle, int backlog);
Christopher Haster 56:34829ec3a3da 98
Christopher Haster 56:34829ec3a3da 99 /** Connects this TCP socket to the server
Christopher Haster 56:34829ec3a3da 100 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 101 * @param address SocketAddress to connect to
Christopher Haster 56:34829ec3a3da 102 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 103 */
Christopher Haster 56:34829ec3a3da 104 virtual int socket_connect(void *handle, const SocketAddress &address);
Christopher Haster 34:9c26a3dcdc1f 105
Christopher Haster 56:34829ec3a3da 106 /** Accept a new connection.
Christopher Haster 56:34829ec3a3da 107 * @param handle Handle in which to store new socket
Christopher Haster 56:34829ec3a3da 108 * @param server Socket handle to server to accept from
Christopher Haster 56:34829ec3a3da 109 * @return 0 on success, negative on failure
Christopher Haster 56:34829ec3a3da 110 * @note This call is not-blocking, if this call would block, must
Christopher Haster 56:34829ec3a3da 111 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 56:34829ec3a3da 112 */
Christopher Haster 56:34829ec3a3da 113 virtual int socket_accept(void **handle, void *server);
Christopher Haster 56:34829ec3a3da 114
Christopher Haster 56:34829ec3a3da 115 /** Send data to the remote host
Christopher Haster 56:34829ec3a3da 116 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 117 * @param data The buffer to send to the host
Christopher Haster 56:34829ec3a3da 118 * @param size The length of the buffer to send
Christopher Haster 56:34829ec3a3da 119 * @return Number of written bytes on success, negative on failure
Christopher Haster 56:34829ec3a3da 120 * @note This call is not-blocking, if this call would block, must
Christopher Haster 56:34829ec3a3da 121 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 56:34829ec3a3da 122 */
Christopher Haster 56:34829ec3a3da 123 virtual int socket_send(void *handle, const void *data, unsigned size);
Christopher Haster 56:34829ec3a3da 124
Christopher Haster 56:34829ec3a3da 125 /** Receive data from the remote host
Christopher Haster 56:34829ec3a3da 126 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 127 * @param data The buffer in which to store the data received from the host
Christopher Haster 56:34829ec3a3da 128 * @param size The maximum length of the buffer
Christopher Haster 56:34829ec3a3da 129 * @return Number of received bytes on success, negative on failure
Christopher Haster 56:34829ec3a3da 130 * @note This call is not-blocking, if this call would block, must
Christopher Haster 56:34829ec3a3da 131 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 56:34829ec3a3da 132 */
Christopher Haster 56:34829ec3a3da 133 virtual int socket_recv(void *handle, void *data, unsigned size);
Christopher Haster 34:9c26a3dcdc1f 134
Christopher Haster 56:34829ec3a3da 135 /** Send a packet to a remote endpoint
Christopher Haster 56:34829ec3a3da 136 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 137 * @param address The remote SocketAddress
Christopher Haster 56:34829ec3a3da 138 * @param data The packet to be sent
Christopher Haster 56:34829ec3a3da 139 * @param size The length of the packet to be sent
Christopher Haster 57:2ad35ade7a83 140 * @return The number of written bytes on success, negative on failure
Christopher Haster 56:34829ec3a3da 141 * @note This call is not-blocking, if this call would block, must
Christopher Haster 56:34829ec3a3da 142 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 56:34829ec3a3da 143 */
Christopher Haster 56:34829ec3a3da 144 virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size);
Christopher Haster 56:34829ec3a3da 145
Christopher Haster 56:34829ec3a3da 146 /** Receive a packet from a remote endpoint
Christopher Haster 56:34829ec3a3da 147 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 148 * @param address Destination for the remote SocketAddress or null
Christopher Haster 56:34829ec3a3da 149 * @param buffer The buffer for storing the incoming packet data
Christopher Haster 56:34829ec3a3da 150 * If a packet is too long to fit in the supplied buffer,
Christopher Haster 56:34829ec3a3da 151 * excess bytes are discarded
Christopher Haster 56:34829ec3a3da 152 * @param size The length of the buffer
Christopher Haster 57:2ad35ade7a83 153 * @return The number of received bytes on success, negative on failure
Christopher Haster 56:34829ec3a3da 154 * @note This call is not-blocking, if this call would block, must
Christopher Haster 56:34829ec3a3da 155 * immediately return NSAPI_ERROR_WOULD_WAIT
Christopher Haster 56:34829ec3a3da 156 */
Christopher Haster 56:34829ec3a3da 157 virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size);
Christopher Haster 56:34829ec3a3da 158
Christopher Haster 56:34829ec3a3da 159 /** Register a callback on state change of the socket
Christopher Haster 56:34829ec3a3da 160 * @param handle Socket handle
Christopher Haster 56:34829ec3a3da 161 * @param callback Function to call on state change
Christopher Haster 56:34829ec3a3da 162 * @param data Argument to pass to callback
Christopher Haster 56:34829ec3a3da 163 * @note Callback may be called in an interrupt context.
Christopher Haster 56:34829ec3a3da 164 */
Christopher Haster 56:34829ec3a3da 165 virtual void socket_attach(void *handle, void (*callback)(void *), void *data);
Christopher Haster 57:2ad35ade7a83 166
Christopher Haster 34:9c26a3dcdc1f 167 private:
Christopher Haster 34:9c26a3dcdc1f 168 ESP8266 _esp;
Christopher Haster 34:9c26a3dcdc1f 169 bool _ids[ESP8266_SOCKET_COUNT];
sarahmarshy 18:9fc7976c7b27 170 };
sarahmarshy 18:9fc7976c7b27 171
sarahmarshy 18:9fc7976c7b27 172 #endif