Communication protocols allow devices to send and receive data/commands to/from other services (like web apis).

Internet Protocol

The internet protocol (IP) is a whole suite of different protocols. The different layers are loosely based on the OSI model.

Internet Protocol Addresses

IP addresses are used to identify devices:

  • IPv4 (four octets separated by dots, e.g. 192.168.0.1)
  • IPv6
  • UDP
  • TCP
  • HTTP

Domain Name System

IP addresses are hard to remember for humans. We use domain names and the domain name system (DNS) to make it easier. A domain name will be resolved to an IP address.

User Datagram Protocol

UDP is unreliable communication. There is no way to check if a package made it to the remote.

Transmission Control Protocol

TCP is reliable. Packages are automatically sent again if they were lost or damaged on the way to the remote.

API

An API provides a web interface to control a device. A simple web api can be implemented by creating a server on the MCU which listens on port 80.

The following examples are different implementations of an “API” to control an LED via the network.

  curl -v http://<ip>/state/1 # Turn on
curl -v http://<ip>/state/0 # Turn off
  
  #include <ESP8266WiFi.h>

#define WIFI_SSID "MY_SSID"         // TODO: Update
#define WIFI_PASSWORD "MY_PASSWORD" // TODO: Update
#define LED 5

const int port = 80;
WiFiServer server(port);

void setup()
{
    Serial.begin(115200);
    WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
    while (WiFi.status() != WL_CONNECTED)
    {
        delay(500);
        Serial.print(".");
    }
    Serial.print("\nServer IP: ");
    Serial.println(WiFi.localIP());
    pinMode(LED, OUTPUT);
    server.begin();
}

void loop()
{
    WiFiClient client = server.available();
    if (client && client.connected())
    {
        Serial.print("Client IP address: ");
        Serial.println(client.remoteIP());

        if (client.find("state"))
        {
            int state = client.parseInt();
            Serial.print("State: ");
            Serial.println(state);
            client.find("\r\n\r\n");

            if (state)
            {
                Serial.println("Turning on");
                digitalWrite(LED, HIGH);
            }
            else
            {
                Serial.println("Turning off");
                digitalWrite(LED, LOW);
            }
        }

        int ch;
        while ((ch = client.read()) != -1)
        {
            Serial.print((char)ch);
        }
        Serial.println();

        client.print("HTTP/1.1 200 OK\r\n");
        client.print("Content-Length: 0\r\n");
        client.print("Connection: close\r\n\r\n");

        delay(100);
        client.stop();
    }
}
  
  curl --insecure -v --user janick:12345678 https://<ip>/light\?state\=1 # Turn on
curl --insecure -v --user janick:12345678 https://<ip>/light\?state\=0 # Turn off
  
  #include <ESP8266WiFi.h>
#include <ESP8266WebServerSecure.h>
#include "WiFiCredentials.h"

#define LED 5
const int port = 443;
const char *username = "janick";
const char *password = "12345678";

// TODO: create your own self signed certificate
// $ openssl req -x509 -nodes -newkey rsa:2048 -keyout key.pem -out cert.pem -days 4096
static const char serverCert[] PROGMEM = R"EOF(
-----BEGIN CERTIFICATE-----
...
)EOF";

static const char serverKey[] PROGMEM =  R"EOF(
-----BEGIN PRIVATE KEY-----
...
)EOF";

BearSSL::ESP8266WebServerSecure server(port);

void handleLight()
{
    // This seems to be very slow... :(
    if (server.authenticate(username, password))
    {
        int state = 0;
        if (server.hasArg("state"))
            state = server.arg("state").toInt();
        
        digitalWrite(LED, state ? HIGH : LOW);
        server.send(200, "text/plain", "OK");
    }
    else
    {
        server.requestAuthentication();
    }
}

void setup()
{
    Serial.begin(115200);
    Serial.print("Connecting to ");
    Serial.print(WIFI_SSID);
    WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
    while (WiFi.status() != WL_CONNECTED)
    {
        delay(500);
        Serial.print(".");
    }
    Serial.print("\nConnected, IP: ");
    Serial.println(WiFi.localIP());
    pinMode(LED, OUTPUT);
    server.getServer().setRSACert(
        new BearSSL::X509List(serverCert),
        new BearSSL::PrivateKey(serverKey)
    );
    server.on("/light", handleLight);
    server.begin();
    Serial.print("Listening on port ");
    Serial.println(port);
}

void loop()
{
    server.handleClient();
}

REST

Based on HTTP verbs (GET, POST, PUT, DELETE, …).

  • GET: retrieve information from the server
  • POST: send information to the server for processing/storage
  • PUT: update information on the server
  • DELETE: remove information

Example: Philips HUE

CoAP

Lightweight message protocol, where messages fit into exactly one UDP frame.

Example: IKEA Tradfri

Hands-On: Display API

The display API allows to control brightness, dots and digits of a 4-digit 7-segment display.

GET /

  • 200 Uptime: hh:mm:ss: Time since system start🛫

GET /display?state=<on/off>

  • 200 OK: Power state changed
  • 400 Bad Request: Empty or invalid state

GET /display?value=<value>[&brightness=<brightness>&show_dots=<true/false>&leading_zeros=<true/false>]

  • 200 OK: Display value changed
  • 400 Bad Request: Empty or invalid value
  #include <TM1637Display.h>
#include <ESP8266WiFi.h>
#include <ESP8266WebServerSecure.h>

#include "WiFiCredentials.h"

#define CLK 5
#define DIO 4

const int port = 80;
TM1637Display display(CLK, DIO);
ESP8266WebServer server(port);

void handleRoot()
{
    unsigned long seconds = millis() / 1000;
    unsigned long minutes = seconds / 60;
    unsigned long hours = minutes / 60;
    char response[9];
    snprintf(response, 17, "Uptime: %02lu:%02lu:%02lu", hours, minutes % 60, seconds % 60);
    server.send(200, "text/plain", response);
}

void handleDisplay()
{
    if (server.hasArg("value"))
    {
        String value = server.arg("value");
        int length = value.length();
        int digits = value.toInt();
        int brightness = server.hasArg("brightness") ? server.arg("brightness").toInt() : 7;
        int dots = server.hasArg("show_dots") ? 64 : 0;
        bool zeros = server.hasArg("leading_zeros");
        display.clear();
        display.setBrightness(brightness);
        display.showNumberDecEx(digits, dots, zeros, zeros ? 4 : length, zeros ? 0 : 4 - length);
        Serial.println("Set display value");
        server.send(200, "text/plain", "OK");
    }
    else if (server.hasArg("state"))
    {
        String state = server.arg("state");
        if (state == "on")
        {
            Serial.println("Turn display on");
            display.clear();
            display.setBrightness(7, true);
            display.showNumberDec(0, true);
            server.send(200, "text/plain", "OK");
        }
        else if (state == "off")
        {
            Serial.println("Turn display off");
            display.clear();
            display.setBrightness(0, false);
            display.showNumberDec(0, true);
            server.send(200, "text/plain", "OK");
        }
        else
        {
            Serial.println("Invalid state");
            server.send(400, "text/plain", "Bad request");
        }
    }
    else
    {
        server.send(400, "text/plain", "Bad request");
    }
}

void handleNotFound()
{
    server.send(404, "text/plain", "Not found");
}

void setup()
{
    Serial.begin(115200);
    display.clear();
    display.setBrightness(0, false);
    display.showNumberDec(0, true);
    Serial.print("Connecting to ");
    Serial.print(WIFI_SSID);
    WiFi.begin(WIFI_SSID, WIFI_PASSWORD);
    while (WiFi.status() != WL_CONNECTED)
    {
        delay(500);
        Serial.print(".");
    }
    Serial.println("\nConnected");
    server.on("/", handleRoot);
    server.on("/display", handleDisplay);
    server.onNotFound(handleNotFound);
    server.begin();
    Serial.print("Server started on http://");
    Serial.print(WiFi.localIP());
    Serial.println("/ in your browser");
}

void loop()
{
    server.handleClient();
}