The Hardware

The WeMos D1 Mini is a board which is built around the ESP8266 chip. The board features:

• Small size.
• 11 digital input/output pins.
• 1 analog input.
• A Micro USB connection.
• Integrated WiFi network support.

Buying from AliExpress, or similar, these can be had from as little as €3, even in single quantities. I've bought seven, just so I don't run out!

Identification & Permission Setup

Once connected to your system you should find you have a new device appear, thanks to the wonders of hotplugging. The new device will be called /dev/ttyUSB0, or similar. The simplest way to find out what the new device is called is to use the lsusb utility which will show you your connected USB devices.

Run lsusb, then plug in the board, and finally run it again. In my case before I see this:

$ lsusb
Bus 006 Device 002: ID 8087:8000 Intel Corp.
Bus 006 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 005 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 004 Device 015: ID 045e:00db Microsoft Corp. Natural Ergonomic Keyboard 4000 V1.0
Bus 004 Device 013: ID 062a:4101 Creative Labs

After insertion I see this:

$ lsusb
Bus 006 Device 002: ID 8087:8000 Intel Corp.
Bus 006 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 005 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 004 Device 015: ID 045e:00db Microsoft Corp. Natural Ergonomic Keyboard 4000 V1.0
Bus 004 Device 013: ID 062a:4101 Creative Labs
Bus 001 Device 005: ID 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter

So I know the USB-device which appeared is the WeMos D1 device, which was described by this line:

Bus 001 Device 005: ID 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter

By default the permissions are configured such that I cannot read/write to the device, so we'll fix that, and create a handy symlink for ease of future identification. We'll do this by creating a local udev rule in the file /etc/udev/rules.d/99-wemos.rules - create that file, and give it the following contents:

SUBSYSTEM=="tty", GROUP="plugdev", MODE="0660"
ACTION=="add", SUBSYSTEMS=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", SYMLINK+="wemos"

NOTE: The numbers in bold come from the output of lsusb which we saw earlier. You'll want to use the numbers you see.

Now that the new udev rule is in place we need to reload the service, unplug the device, and plug it in again. That will allow the new rule to be recognized and applied. Reloading the rules can be achieved via:

# /etc/init.d/udev reload

Once that is complete we'll see we have the symlink, and better permissions.

$ ls -l /dev/wemos /dev/ttyUSB0
lrwxrwxrwx 1 root root         7 Jan  5 08:15 /dev/wemos -> ttyUSB0
crw-rw---- 1 root plugdev 166, 1 Jan  5 08:15 /dev/ttyUSB0

NOTE: My user is a member of the plugdev group, so I can now read/write to the device.

Software Installation

To write your code, and upload it to your board over the USB cable, you'll need to install the Arduino IDE, which is currently version 1.8.0.

You can find the project here:

• http://www.arduino.org/downloads

The project is written in Java, so you'll need to have a suitable runtime installed.

The current stable release of Debian GNU/Linux includes openjdk-7-jre, which is sadly too old to run the project. To run the IDE you'll need to install the openjdk-8-jre package, via the backports repository.

ESP8266 Setup

Now the 1.8.0 studio doesn't contain support for the WeMos D1 Mini - so we need to add it. Open the preferences display via the "File | Preferences" menu-item. In the section "Additional Board Manager URLS:" enter the following URL:

http://arduino.esp8266.com/stable/package_esp8266com_index.json

Once you've done that you can open the board-manager via the "Tools | Board: .." menu-item, and choose "Board Manager" from the top of the list. In the resulting dialog you can now enter "ESP8266" in the filter-section, and that will then let you install the appropriate supporting libraries, headers, and board-descriptions.

To complete the setup we'll now use the "Tools | Board .." menu-item to select the "WeMos D1 R2 & Mini" board we're using.

First Program

The single biggest difference between the D1 board and the other Arduino devices I've used so far is that it has on-board WiFi. We'll take advantage of that in this first sample program, by writing a program which will:

• Connect to my local WiFi network.
• Run a HTTP server which will allow an LED to be controlled.
• Also show the state of the LED.

The sample code needs to be updated to include your WiFi details. In my case my home network runs with SSID SCOTLAND, and password Highlander1 - if you're nearby feel free to connect!

#include <ESP8266WiFi.h>

const char* ssid = "SCOTLAND";
const char* password = "Highlander1";

int ledPin = 2; // GPIO2

WiFiServer server(80);

void setup() {
  // Setup serial-output
  Serial.begin(115200);
  delay(10);

  WiFi.mode(WIFI_STA);

  // Pin 2 has an integrated LED - configure it, and turn it off
  pinMode(ledPin, OUTPUT);
  digitalWrite(ledPin, LOW);

  // Connect to WiFi network
  Serial.println();
  Serial.println();
  Serial.print("Connecting to ");
  Serial.println(ssid);

  // Set the hostname
  WiFi.hostname("web-blink");
  WiFi.begin(ssid, password);

  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("");
  Serial.println("WiFi connected");

  // Start the server
  server.begin();
  Serial.println("Server started");

  // Print the IP address
  Serial.print("Use this URL to connect: ");
  Serial.print("http://");
  Serial.print(WiFi.localIP());
  Serial.println("/");
}

void loop() {
  // Check if a client has connected
  WiFiClient client = server.available();
  if (!client) {
    return;
  }

  // Wait until the client sends some data
  Serial.println("new client");


  while(client.connected() && !client.available())
  {
    delay(1);
  }

  // Read the first line of the request
  String request = client.readStringUntil('\r');
  Serial.println(request);
  client.flush();

  // Match the request
  int value = LOW;
  if (request.indexOf("/LED=ON") != -1) {
    digitalWrite(ledPin, HIGH);
    value = HIGH;
  }
  if (request.indexOf("/LED=OFF") != -1) {
    digitalWrite(ledPin, LOW);
    value = LOW;
  }

  // Return the response
  client.println("HTTP/1.1 200 OK");
  client.println("Content-Type: text/html");
  client.println(""); // do not forget this one
  client.println("<!DOCTYPE HTML>");
  client.println("<html>");

  client.print("Led pin is now: ");

  if(value == HIGH) {
    client.print("On");
  } else {
    client.print("Off");
  }
  client.println("<br><br>");
  client.println("Click <a href=\"/LED=ON\">here</a> turn the LED on pin 2 ON<br>");
  client.println("Click <a href=\"/LED=OFF\">here</a> turn the LED on pin 2 OFF<br>");
  client.println("</html>");

  delay(1);
  Serial.println("Client disonnected");
  Serial.println("");
}

Download the code.