IC ESP

From InCircuit
Jump to: navigation, search

IC_ESP is the software library implementing the IC ESP8266EX interface.

Contents

Setup

Install the IC_ESP libary files into the Arduino libraries directory.

To use IC_ESP within your Arduino Sketch you have to include the following headers:

#include <SPI.h>
#include <SPI_UART.h>
#include <IC_ESP.h>

Now create an instance of the IC_ESP class:

IC_ESP esp = IC_ESP();

Initialization

To initialize the IC_ESP (within the setup() function of your sketch), you first need to set the mode of operation.

esp.setMode(ESP_IC_PROTOCOL_MODE);
esp.init();  // Init ESP8266EX

Then you have to wait, until the ESP is ready to use.

dbgSerial.begin(57600);
unsigned char cnt = 0;
// Wait for ESP
while(!esp.ready())
{
  if(!(++cnt%10)) esp.init(); // Re-Init ESP
  dbgSerial.println("ESP !ready...");
  delay(500);
 }

Wi-Fi-Setup

By default the ESP sets up an access point with SSID "RADINO-WiFi" and password "12345678" using IP address 192.168.2.1.

Access Point

You can setup an access point with a different configuration. For example set a different SSID and password.

dbgSerial.print("Set SSID:");
if(esp.AP_setSSID("TestRadino"))  dbgSerial.println("ok");
  else dbgSerial.println("er");
dbgSerial.print("Set PW:");
if(esp.AP_setPW("1234567890"))  dbgSerial.println("ok");
  else dbgSerial.println("er");

Set the mode to access point mode.

dbgSerial.print("Set Mode:");
if(esp.NET_mode(ESP_WIFI_AP))  dbgSerial.println("ok");
  else dbgSerial.println("er");

Start the network.

dbgSerial.print("starting Wi-Fi:");
if(esp.NET_wifiStart())  dbgSerial.println("ok");
  else dbgSerial.println("er");

Station Mode

If you do not want to start an access point, you can setup the ESP to join an existing Wi-Fi network.

Set SSID and password.

 dbgSerial.print("Set SSID:");
 if(esp.ST_setSSID("TestRadino"))  dbgSerial.println("ok");
   else dbgSerial.println("er");
   dbgSerial.print("Set PW:");
 if(esp.ST_setPW("12345678"))  dbgSerial.println("ok");
   else dbgSerial.println("er");

Set station mode.

 dbgSerial.print("Set Mode:");
 if(esp.NET_mode(ESP_WIFI_STATION))  dbgSerial.println("ok");
   else dbgSerial.println("er");

Start the network.

 dbgSerial.print("starting Wi-Fi:");
 if(esp.NET_wifiStart())  dbgSerial.println("ok");
   else dbgSerial.println("er");

Usage

After the setup is complete you can start using the IC_ESP (in the loop() function of your Arduino sketch).

Status Information

Some status information can be queried. Only a few examples are presented here. For a full list see the function list below.

  • Reading firmware version
 dbgSerial.print("ESP library firmware version: ");
 dbgSerial.println(esp.getFirmwareVersion());
  • Read IP Address (IP4)
 unsigned long ip = esp.getIPAddress();

Events

If the website contains register names encoded inside '%', a get request for each register will be created by the ESP.

The following code will create a get request for register 1001 each time the website is visited.

 <span>%1001%</span>

To handle events in your sketch you should use a while loop like below. If events are available (newEventAvailable) use getEvent() to get details about the event. Depending on the type of request a response is sent.

In example below reg1001 and reg1002 are registers defined as unsigned long in our sketch.

while(esp.newEventAvailable())
{
   // new event arrived
   struct event e = esp.getEvent();
   switch (e.type) {
     case EVENT_HTTP_GET_REQUEST:
       switch(e.reg) {
         case 1001:
           esp.sendEventResponse(reg1001);
           break;
         case 1002:
           esp.sendEventResponse(reg1002);
           break;
         default:
           dbgSerial.print("unknown register: ");
           dbgSerial.println(e.reg);
       }
       break;
     case EVENT_HTTP_SET_REQUEST:
       switch(e.reg) {
         case 1001:
           reg1001 = e.value;
           esp.sendEventResponse(reg1001);
           break;
         case 1002:
           reg1002 = e.value;
           esp.sendEventResponse(reg1002);
           break;
         default:
           dbgSerial.print("unknown register: ");
           dbgSerial.println(e.reg);
       }
       break;
     default:
       dbgSerial.print("unknown event: ");
       dbgSerial.println(e.type);
   }
 }

Function List

Functions return 1 or other (higher) value on success. In case of error 0 is returned.

Initial Setup

Function Description Implemented since Version
unsigned char setMode(unsigned char mode) Used to set the mode of operation. Should be called before init().

Possible values: ESP_IC_PROTOCOL_MODE, ESP_RAW_MODE (default, not interrupt handling, e.g. no events), ESP_FIMWAREUPDATE_MODE

1
unsigned char init() Initialize the ESP. 1
unsigned char ready() Returns true if the ESP is ready to use. 1

Wi-Fi

This section contains the available Wi-Fi functions. Most functions only take effect if set before calling NET_wifiStart.

Setting the access point IP address only works during ESP boot. Therefore it needs to be written to ESP flash before resetting the ESP. The function AP_forceIPAddress() does this all at once. All other (non default) settings need to be stored to flash, too. Otherwise they are lost during reset.

Function Description Implemented since Version
unsigned char AP_setSSID(String ssid) Set the access point SSID. 1
unsigned char AP_setPW(String pw) Set the access point password. 1
unsigned char AP_setChannel(unsigned int channel) Set the WiFi channel to use. 2
unsigned long AP_getIPAddress() Returns the access point IP4 Address as an unsigned long. (Big endian, first number is in the highest byte) 2
unsigned char AP_setIPAddress(unsigned long ip) Set the access point IP4 Address. (Big endian, first number is in the highest byte)

Only effective after ESP restart.

2
unsigned char AP_forceIPAddress(unsigned long ip) Set the access point IP4 Address. (Big endian, first number is in the highest byte)

This will restart the ESP. All other settings are restored to the values stored in ESP flash or to their default values if not saved to ESP flash.

2
unsigned char ST_setSSID(String ssid) Set the station mode Wi-Fi SSID. 1
unsigned char ST_setPW(String pw) Set the station mode password. 1
unsigned long getIPAddress() Returns the currently used IP4 Address (regardless of the used mode) as an unsigned long. (Big endian, first number is in the highest byte). 1
unsigned long ST_getIPAddress() Returns the IP4 Address as an unsigned long used in Station Mode. (Big endian, first number is in the highest byte) 2
unsigned char NET_mode(ESP_wifi_modes mode) Set Wi-Fi mode. Possible values: ESP_WIFI_STATION, ESP_WIFI_AP, ESP_WIFI_DUAL. 1
unsigned char NET_wifiStart() (Re)Start the Wi-Fi network. 1
unsigned char NET_wifiReset() Reset the ESP Wi-Fi chip. 1

TCP

This section contains the available TCP functions. Up to 8 TCP sockets can be established in parallel. Which socket to use it declared implicitly by using function TCP_setClientSocket().

Function Description Implemented since Version
unsigned long TCP_status(unsigned long *status) Returns the complete ESP TCP status register. 2
TCP_SOCKET_STATUS TCP_status(unsigned long socket) Returns the TCP socket status for a specific socket. 2
unsigned char TCP_openClientSocket() Opens a TCP connection as configured with functions below. 2
unsigned char TCP_setClientTargetIP(unsigned long ip) Sets TCP client target IP address. 2
unsigned char TCP_clientTargetIP() Returns TCP client target IP address. 2
unsigned char TCP_setClientTargetPort(unsigned short port) Sets TCP client target port. 2
unsigned short TCP_clientTargetPort() Returns TCP client target port. 2
unsigned char TCP_setClientSocket(unsigned long clientSocket) Set the TCP socket to use. 2
unsigned char TCP_clientSocket(unsigned long *clientSocket) Returns the currently used socket. 2
unsigned char TCP_clientSend(unsigned char *data)

unsigned char TCP_clientSend(const char *data)

Send data over TCP. 2
unsigned char TCP_closeSocket() Close the currently used socket. 2
void TCP_push(unsigned long ip, unsigned short port, String data) Sends data to a remote host. It does not wait for a response. 1

The TCP_SOCKET_STATUS is defined in IC_ESP.h as follows:

enum TCP_SOCKET_STATUS {
  CLOSED = 0,
  CONNECTING = 1,
  LISTENING = 2,
  OPEN = 3,
  ERROR = 0xFF,
};

Telnet-Server

Function Description Implemented since Version
unsigned long Telnet_status(unsigned long *status) Returns Telnet Server status. 2
unsigned char Telnet_start() Start telnet server. 2
unsigned char Telnet_stop() Stop telnet server (not yet implemented in ESP). 2
unsigned long Telnet_TCPPort() Returns the telnet server TCP port. 2
unsigned char Telnet_setTCPPort(unsigned long port) Sets the telnet server TCP port. 2
unsigned long Telnet_UDPPort() Returns the telnet server UDP port. 2
unsigned char Telnet_setUDPPort(unsigned long port) Sets the telnet server UDP port. 2
unsigned long Telnet_UDPBroadcastPort() Returns the UDP boardcast port. 2
unsigned char Telnet_setUDPBroadcastPort(unsigned long port) Sets the UDP boardcast port. 2
unsigned char Telnet_targetSocket(unsigned long *socket) Returns TCP target socket. 2
unsigned char Telnet_setTargetSocket(unsigned long socket) Sets TCP target socket. 2
void Telnet_socketSend(String data) Send data via TCP. Uses the target socket set above. 2
void Telnet_UDPSend(String data) Broadcasts data to UDP boardcast port. 2
void Telnet_broadcastSend(String data) Sends data to all connected TCP sockets and the UDP boardcast port. 2

HTTPD-Server

Function Description Implemented since Version
unsigned char HTTPD_setServerPort(unsigned short port) Sets the HTTP server port. Default: 80. 1
unsigned char HTTPD_startServer() Start the HTTP server. 1
unsigned char HTTPD_updateWebsite(char *data)

unsigned char HTTPD_updateWebsite(String *data)

Update the content of the website. 1

Events

This section describes useful functions for handling events.

Function Description Implemented since Version
unsigned newEventAvailable() Returns 1 if a new event is available. 1
struct event getEvent() Returns a struct holding information about the event. See below. 1
void sendEventResponse(unsigned long val)

void sendEventResponse(String str)

Sends to corresponding response to a request. 1
struct event {
  // IE event type
  ESP_event_types type;
  unsigned char socket;
  // remote/client ip & port
  unsigned long ip;
  unsigned short port;
  // IE GET / SET register
  unsigned long reg;
  unsigned long value;
  // client data (tcp/telnet)
  unsigned char* data;
  unsigned char datalen;
};

Not all fields are always valid. The following table shows which fields are valid for which events. Field type is always valid.

Event Type Description Valid Values
EVENT_HTTP_GET_REQUEST Get request for website variable. socket, ip, reg
EVENT_HTTP_SET_REQUEST Set request for website variable. socket, ip, reg, value
EVENT_TCP_CLIENT_DATA_RECEIVED Called when TCP client receives data. socket, data, datalen
EVENT_TELNET_GOT_TCP_DATA Called when telnet TCP server receives data. socket, data, datalen
EVENT_TELNET_GOT_UDP_DATA Called when telnet UDP server receives data. data, datalen
EVENT_TELNET_TCP_CONNECTED Called when a client connects to the telnet TCP server. socket, ip, port
EVENT_TELNET_TCP_DISCONNECTED Called when a client disconnects from the telnet TCP server. socket

System

Function Description Implemented since Version
unsigned char StoreSettings_all() Saves all ESP chip settings to flash. 2
unsigned char StoreSettings_apIP() Saves access point IP address to flash. IP changes takes effect after ESP reset. 2
unsigned char StoreSettings_FactoryReset() Restores all ESP chip settings to factory defaults an saves them to flash. 2
unsigned char getUserData(unsigned long *data)

unsigned char setUserData(unsigned long data)

Can be used to store user defined data (e.g. configuration version, status variables). 2
unsigned long getVersion() Returns the IC_ESP library version number. 2
unsigned long getFirmwareVersion() Returns the ESP firmware version number. 1

Serial

This tutorial uses dbgSerial as the serial port to print intformation. It can be defined as Serial for USB-UART or Serial1 for Hardware-UART. For example:

#define dbgSerial Serial
#define DBG_SERIAL_BAUDRATE 57600

You have to start the serial to use it:

dbgSerial.begin(DBG_SERIAL_BAUDRATE);
Personal tools