UDP on the ESP01 (ESP8266 Development Board)
Monday, June 1st, 2015ESP8266 boards offer an amazing opportunity to explore the IoT world at a low cost. The boards start for as little as £5 here in the UK and come in a variety of form factors from one with only two GPIO pins to larger boards containing more GPIOs, PWM, I2C, SPI and analog capability. The boards started to become noticed around the middle of 2014 and have become more popular as the tools and documentation have matured.
Support for the boards is mainly through the online community forum. The latest documentation and SDKs can be found through the same forums.
The boards make low cost networks of sensors a possibility with the ESP8266 modules acting as either small servers or clients on your WiFi network.
The ESP8266 module is often supplied with one of two firmware version burned into the module:
- nodeMCU – Lua interpreter
- AT command interpreter
For the purposes of this exercise we will look at replacing the default firmware supplied with a custom application.
The SDK available from Expressif allows the developer to program the module using C. First thing to do is to install the tool chain for the module. The ESP8266 Wiki contains a host of information including instructions on setting up the tools on a variety of platforms. This whole process took about 2-3 hours on my Windows PC with another few hours to put together a template for a makefile application for Visual Studio.
Now that the development tools are in place we can start to think about the sensor network. Security is a major concern for Internet of Things (IoT) projects but this proof of concept will ignore this for the moment and rely on the WiFi encryption as the only mean of securing the data. This is a proof of concept afterall.
The applications developed here will allow data to be transmitted using UDL over the local area network.
UDP Receiver
Before starting on the ESP8266 application we should put together a simple application to receive the data from the local network. A simple .NET application on a Windows PC should do the trick:
using System;
using System.Collections.Generic;
using System.Text;
using System.Threading.Tasks;
using System.Net;
using System.Net.Sockets;
namespace UDPConsoleClient
{
class Program
{
static UdpClient _udpClient = new UdpClient(11000);
static void Main(string[] args)
{
Console.WriteLine("UDP Client listening on port 11000");
IPEndPoint _remoteEndPoint = new IPEndPoint(IPAddress.Any, 0);
while (true)
{
byte[] data = _udpClient.Receive(ref _remoteEndPoint);
string message = Encoding.ASCII.GetString(data);
Console.WriteLine("Message ({0}): {1}", _remoteEndPoint.Address.ToString(), message);
}
}
}
}
Create a new Windows console application on the PC and add the above code to the program.cs file. When run, this application will listen to the local network and display any UDP packets as a string to the console. Nothing special but good enough for the purposes of this experiment.
Basic ESP8266 Application
The basic ESP8266 application works in a similar way to an Arduino application, there is an initialisation method user_init and a loop method. The loop method is slightly different from the Arduino loop in that it is added to a task queue and the developer is free to select the name of the method. A basic application looks something like this:
#include "at_custom.h"
#include "ets_sys.h"
#include "osapi.h"
#include "gpio.h"
#include "os_type.h"
#include "mem.h"
#include "user_config.h"
#include "ip_addr.h"
#include "espconn.h"
#include "user_interface.h"
#define USER_TASK_PRIORITY 0
#define USER_TASK_QUEUE_LENGTH 1
//
// Callbacks for the OS task queue.
//
os_event_t userTaskQueue[USER_TASK_QUEUE_LENGTH];
//
// User function which will be added to the task queue.
//
static void ICACHE_FLASH_ATTR UserTask(os_event_t *events)
{
os_delay_us(10);
}
//
// Initialise the application and add the user task to the task queue.
//
void ICACHE_FLASH_ATTR user_init()
{
//
// Start OS tasks.
//
system_os_task(UserTask, USER_TASK_PRIORITY, userTaskQueue, USER_TASK_QUEUE_LENGTH);
}
Compiling and deploying this application will result in a module which does nothing much other than wait.
Debugging
Unlike some of the other modules and boards discussed on this blog, the ESP8266 does not have much available in the way of debugging. Code will need to be added to the application to output debug information on GPIO pins in order to get feedback on what is going on inside the application.
The ESP01 module being used has two GPIO pins available, GPIO0 and GPIO2. We can use these to output serial data akin to SPI and then use a logic analyser to examine the application state. Adding the code below will allow us to do this.
#define BB_DATA BIT0
#define BB_CLOCK BIT2
//
// Initialise the GPIO pins.
//
void InitialiseGPIO()
{
gpio_init();
//
// Set GPIO2 and GPIO0 to output mode.
//
PIN_FUNC_SELECT(PERIPHS_IO_MUX_GPIO2_U, FUNC_GPIO2);
PIN_FUNC_SELECT(PERIPHS_IO_MUX_GPIO0_U, FUNC_GPIO0);
}
//
// Bit bang the data out as serial (SPI) data.
//
void BitBang(uint8 byte)
{
//
// Set the clock and data bits to be low.
//
gpio_output_set(0, BB_DATA, BB_DATA, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
//
// Output the data.
//
short bit;
for (bit = 7; bit >= 0; bit--)
{
if (byte & (1 << bit))
{
gpio_output_set(BB_DATA, 0, BB_DATA, 0);
}
else
{
gpio_output_set(0, BB_DATA, BB_DATA, 0);
}
gpio_output_set(BB_CLOCK, 0, BB_CLOCK, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
}
//
// Set the clock and data bits to be low.
//
gpio_output_set(0, BB_DATA, BB_DATA, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
}
Timers
For the proof of concept the application can simply generate a regular packet of data emulating the presence of sensor data. The most cost effective (in terms of power) way of doing this will be to use a timer of some sort.
//
// OS Timer structure holding information about the timer.
//
static volatile os_timer_t timerInformation;
//
// Timer function called periodically - try communicating with the world.
//
void TimerCallback(void *arg)
{
BitBang(0x01);
}
//
// Initialise the application and add the user task to the task queue.
//
void ICACHE_FLASH_ATTR user_init()
{
InitialiseGPIO();
//
// Disarm timer.
//
os_timer_disarm(&timerInformation);
//
// Set up timer to call the timer function.
//
os_timer_setfn(&timerInformation, (os_timer_func_t *) TimerCallback, NULL);
//
// Arm the timer:
// - timerInformation is the pointer to the OS Timer data structure.
// - 1000 is the timer duration in milliseconds.
// - 0 fire once and 1 for repeating
//
os_timer_arm(&timerInformation, 1000, 1);
//
// Start OS tasks.
//
system_os_task(UserTask, USER_TASK_PRIORITY, userTaskQueue, USER_TASK_QUEUE_LENGTH);
}
Adding the above code to the basic application should generate data on GPIO0 and GPIO2 every second.
UDP Communication & WiFi Connectivity
The last part of the puzzle is to connect the board to the local WiFi network and to start to send data across the network.
WiFi Connection
For a basic WiFi connection where the router is providing a DHCP service then we need to let the firmware know the SSID of the network we wish to connect to and the password for the network:
const char ssid[32] = "--- Your SSID Here ---";
const char password[32] = "--- Your Password Here ---";
struct station_config stationConf;
wifi_set_opmode(STATION_MODE);
os_memcpy(&stationConf.ssid, ssid, 32);
os_memcpy(&stationConf.password, password, 32);
wifi_station_set_config(&stationConf);
Executing the above code will set the network parameters. The network connection is not established immediately but can take some time to become active. Network connectivity can be detected by the following code snippet:
struct ip_info info;
wifi_get_ip_info(STATION_IF, &info);
if (wifi_station_get_connect_status() != STATION_GOT_IP || info.ip.addr == 0)
{
// Not connected yet !!!
}
UDP Communication
Network communication needs a connection structure to be set up. This holds information about the network connection type, IP addresses and ports. For this exercise we are using the UDP protocol and will broadcast the data to any UDP listener on the network. The UDP broadcast address is x.y.z.255, in this case 192.168.1.255. The code to set this up is as follows:
struct espconn *_ptrUDPServer;
uint8 udpServerIP[] = { 192, 168, 1, 255 };
//
// Allocate an "espconn" for the UDP connection.
///
_ptrUDPServer = (struct espconn *) os_zalloc(sizeof(struct espconn));
_ptrUDPServer->type = ESPCONN_UDP;
_ptrUDPServer->state = ESPCONN_NONE;
_ptrUDPServer->proto.udp = (esp_udp *) os_zalloc(sizeof(esp_udp));
_ptrUDPServer->proto.udp->local_port = espconn_port();
_ptrUDPServer->proto.udp->remote_port = 11000;
os_memcpy(_ptrUDPServer->proto.udp->remote_ip, udpServerIP, 4);
The application can now start to send data over the network:
#define USER_DATA "ESP8266 - Data"
espconn_create(_ptrUDPServer);
espconn_sent(_ptrUDPServer, (uint8 *) USER_DATA, (uint16) strlen(USER_DATA));
espconn_delete(_ptrUDPServer);
The application should really perform some diagnostics in the above code in order to detect any errors and clean up where necessary.
Putting it all Together
A little rearrangement of the snippets above is necessary in order to put together a mode elegant solution, namely:
- Output the results of function calls to the network to the GPIO pins
- check for network connectivity before calling the network functions
Adding these modifications to the code gives the following final solution:
// ***************************************************************************
//
// Basic UDP broadcast application for the ESP8266.
//
#include "at_custom.h"
#include "ets_sys.h"
#include "osapi.h"
#include "gpio.h"
#include "os_type.h"
#include "mem.h"
#include "user_config.h"
#include "ip_addr.h"
#include "espconn.h"
#include "user_interface.h"
#define USER_TASK_PRIORITY 0
#define USER_TASK_QUEUE_LENGTH 1
#define USER_DATA "ESP8266 - Data"
#define BB_DATA BIT0
#define BB_CLOCK BIT2
//
// Callbacks for the OS task queue.
//
os_event_t userTaskQueue[USER_TASK_QUEUE_LENGTH];
struct espconn *_ptrUDPServer;
uint8 udpServerIP[] = { 192, 168, 1, 255 };
// ***************************************************************************
//
// Forward declarations.
//
static void UserTask(os_event_t *events);
//
// OS Timer structure holding information about the timer.
//
static volatile os_timer_t timerInformation;
//
// Initialise the GPIO subsystem.
//
void InitialiseGPIO()
{
gpio_init();
//
// Set GPIO2 and GPIO0 to output mode.
//
PIN_FUNC_SELECT(PERIPHS_IO_MUX_GPIO2_U, FUNC_GPIO2);
PIN_FUNC_SELECT(PERIPHS_IO_MUX_GPIO0_U, FUNC_GPIO0);
}
//
// Bit bang the data out as serial (SPI-like) data.
//
void BitBang(uint8 byte)
{
//
// Set the clock and data bits to be low.
//
gpio_output_set(0, BB_DATA, BB_DATA, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
//
// Output the data.
//
short bit;
for (bit = 7; bit >= 0; bit--)
{
if (byte & (1 << bit))
{
gpio_output_set(BB_DATA, 0, BB_DATA, 0);
}
else
{
gpio_output_set(0, BB_DATA, BB_DATA, 0);
}
gpio_output_set(BB_CLOCK, 0, BB_CLOCK, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
}
//
// Set the clock and data bits to be low.
//
gpio_output_set(0, BB_DATA, BB_DATA, 0);
gpio_output_set(0, BB_CLOCK, BB_CLOCK, 0);
}
//
// Timer function called periodically - try communicating with the world.
//
void TimerCallback(void *arg)
{
struct ip_info info;
wifi_get_ip_info(STATION_IF, &info);
if (wifi_station_get_connect_status() != STATION_GOT_IP || info.ip.addr == 0)
{
BitBang(0x01);
}
else
{
BitBang(0x02);
BitBang(espconn_create(_ptrUDPServer));
BitBang(0x03);
BitBang(espconn_sent(_ptrUDPServer, (uint8 *) USER_DATA, (uint16) strlen(USER_DATA)));
BitBang(0x04);
BitBang(espconn_delete(_ptrUDPServer));
BitBang(0x05);
}
}
//
// User function which will be added to the task queue.
//
static void ICACHE_FLASH_ATTR UserTask(os_event_t *events)
{
os_delay_us(10);
}
//
// Initialise the application and add the user task to the task queue.
//
void ICACHE_FLASH_ATTR user_init()
{
at_init();
InitialiseGPIO();
//
// Disarm timer.
//
os_timer_disarm(&timerInformation);
//
// Start the network connection.
//
const char ssid[32] = "--- Your SSID Here ---";
const char password[32] = "--- Your Password Here ---";
struct station_config stationConf;
wifi_set_opmode(STATION_MODE);
os_memcpy(&stationConf.ssid, ssid, 32);
os_memcpy(&stationConf.password, password, 32);
wifi_station_set_config(&stationConf);
//
// Allocate an "espconn" for the UDP connection.
///
_ptrUDPServer = (struct espconn *) os_zalloc(sizeof(struct espconn));
_ptrUDPServer->type = ESPCONN_UDP;
_ptrUDPServer->state = ESPCONN_NONE;
_ptrUDPServer->proto.udp = (esp_udp *) os_zalloc(sizeof(esp_udp));
_ptrUDPServer->proto.udp->local_port = espconn_port();
_ptrUDPServer->proto.udp->remote_port = 11000;
os_memcpy(_ptrUDPServer->proto.udp->remote_ip, udpServerIP, 4);
//
// Setup timer to call the timer function.
//
os_timer_setfn(&timerInformation, (os_timer_func_t *) TimerCallback, NULL);
//
// Arm the timer:
// - timerInformation is the pointer to the OS Timer data structure.
// - 1000 is the timer duration in milliseconds.
// - 0 fire once and 1 for repeating
//
os_timer_arm(&timerInformation, 1000, 1);
//
// Start OS tasks.
//
system_os_task(UserTask, USER_TASK_PRIORITY, userTaskQueue, USER_TASK_QUEUE_LENGTH);
}
Compiling and deploying this application to the ESP01 generates regular (1 second intervals) messages on the console application at the start of this post.
Conclusion
The journey with the ESP8266 has just started but it looks promising. The initial set up was not a simple as I would have liked as there are a number of parts all of which need to be brought together in order for the development cycle to start. Once these are all in place then coding is relatively easy even though there is little documentation. The community which is developing is certainly helping in this process.
On the whole this chipset offers an interesting opportunity especially with the like of Adafruit developing the Huzzah DIP friendly ESP12 board which has now received the appropriate certification for commercial WiFi use.
