Revision as of 18:28, 4 March 2015

This page is currently under construction and is daily updated with new information.

IC_ESP is the software library implementing the IC ESP8266EX interface.

Setup

Install the IC_ESP libary files into the Arduino libraries directory.

To use IC_ESP within your Arduino [[1]] 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 responds is sent.

In example below reg1001 and reg1001 are registers defined as unsigned 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

• 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

• unsigned char init()

Initialize the ESP.

• unsigned char ready()

Returns true if the ESP is ready to use.

Wi-Fi

• unsigned char AP_setSSID(String ssid)

Set the access point SSID.

• unsigned char AP_setPW(String pw)

Set the access point password.

• unsigned char ST_setSSID(String ssid)

Set the station mode Wi-Fi SSID.

• unsigned char ST_setPW(String pw)

Set the station mode password.

• unsigned char NET_mode(ESP_wifi_modes mode)

Set Wi-Fi mode. Possible values: ESP_WIFI_STATION, ESP_WIFI_AP, ESP_WIFI_DUAL.

• unsigned char NET_wifiStart()

Set the Wi-Fi network.

• unsigned long getIPAddress()

Returns the IP4 Address as an unsigned long.

HTTPD-Server

• unsigned char HTTPD_setServerPort(unsigned short port)

Sets the HTTP server port. Default: 80.

• unsigned char HTTPD_startServer()

Start the HTTP server.

• unsigned char HTTPD_updateWebsite(char *data)
• unsigned char HTTPD_updateWebsite(String *data)

Update the content of the website.

Events

• unsigned newEventAvailable()

Returns 1 if a new event is available.

• struct event getEvent()

Returns a struct holding information about the event.

struct event {
  ESP_event_types type;
  unsigned reg;
  unsigned value;
};

Type is either EVENT_HTTP_GET_REQUEST or EVENT_HTTP_SET_REQUEST. Reg is the register number. The value is only valid for set requests.

• void sendEventResponse(unsigned long val)
• void sendEventResponse(String str)

Sends to corresponding response to a request.

System

• unsigned getFirmwareVersion()

Returns the firmware version number.

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);