mdiaconescu's blog

Seeeduino XIAO - A Tiny Arduino Zero Variation

mdiaconescu — Mon, 17 Aug 2020 10:02:49 +0000

You may like to check our other WoT/IoT related articles.

Another Arduino Compatible Board?

You probably asked yourself a few times: what, another Arduino compatible board? Why shall I choose this one over the other one? Is this "the one" for my project?

If you are not familiar with Arduino, you shall have a look at the Arduino official website. You may also be interested in reading our WoT with Arduino for Beginners tutorials.

A simple answer for all or each of these questions does not really exist. A few other questions must be answered first: which features do I really need for my project? Is it battery powered? How much $$$ do I want to spend (or do I have available) for the project? Where do I buy the board? Does it have a "real" community? ... and so on.

The expectations: a new Arduino "compatible" board is also a progress step, so at least in theory it must have "something" that makes it "better" or at least "different". Many of these boards have just (some) minor hardware changes when comparing them with the equivalent Arduino brother, but their price is the one of a coffee cup, thus making them attractive for the very beginner or for low cost projects - this is also the case of many "Arduino clone" boards. Other boards have relevant hardware improvements, but usually (at least at the release time) have a higher price. Such boards have for example a better MCU (higher speed, amount of RAM and FLASH) and usually a larger features pack, like I2C, SPI, UART, CAN, touch sensor interface, ADC, DAC, etc. Finally, a few of them combine most of the goodies in a (very) tiny board and have the price of two beers or coffee cups. In the former category, we also find the Seeeduino XIAO board.

While XIAO is not necessarily "the perfect Arduino compatible board", it is among the few ones that for around five bucks, comes in a very low size, has a MCU capable of coping with demanding tasks, requires just a little amount of power, has 11 GPIOs that can be either used for digital or analog operations and supports a lot of the standard protocols. The compatibility with the Arduino IDE and many of the existing libraries is also very good, and in practice this means that it can be a replacement for the Arduino Zero (or its smaller brothers) board in many projects.

Technical Description and Features

A brief description of the most important features and technical characteristics of the XIAO board are provided in Table 1.

Table 1: XIAO Technical Specs.
Feature	Description
MCU	32 Bit ARM Cortex-M0+ @48MHz
RAM	32KB SRAM
FLASH	256KB
GPIOs	11 analog/digital pins A0-A10 analog (-0.3 - 3.3V) D0-D10 digital (max. 7mA / pin)
DAC	pin D0/A0 10 Bit, 350ksps
ADC	pin A0-A10 12 Bit, 350ksps
UART	TX: pin A6/D6 RX: pin A7/D7
I2C	SDA: pin A4/D4 SCL: pin A5/D5
SPI	MOSI: pin A10/D10 MISO: pin A9/D9 SCK/SCLK: pin A8/D8 CS/SS: any GPIO but D8, D9, D10
IRQ	all GPIOs support interrupts, but GPIO A5/D5 and GPIO A7/D7 cannot be used at the same time
PWM	available on pins D1-D10
SWD	Serial Wire Debug (SWD) is available as exposed pads on the back of the board
RTC	32-bit Real Time Counter (RTC) with clock/calendar function but requires the board to be powered
Builtin LEDs	one green power led one yellow user led two blue serial port LEDs
Power Supply	Option 1: 5V via USB-C port Option 2: 4-6V via power pads Note: The power pads are on the back of the board (see Figure 3).
Reset	exposed reset pads on the front (See Figure 2) and on the back (See Figure 3) of the board
Size	20x17.5x3.5mm (See Figure 1)

Figure 1: XIAO Board Size.

Figure 2: XIAO Board Pinout.

Figure 3: the Back of the XIAO Board.

Benchmark Test

We performed a benchmark test on the XIAO Board, by using the Paul Stoffregen's CoreMark GitHub project. The Table 2 shows a comparison with a few other Arduino or Arduino compatible boards which we have available on our toolbox. The results were rounded up to the closest integer value.

Table 2: CoreMark Benchmark
Board	Result
Teensy 4.0 (ARM Cortex-M7 @600MHz)	2309
Teensy 3.2 (ARM Cortex-M4 @72MHz)	167
Arduino Due (AT91SAM3X8E @84MHz)	91
Arduino Zero (ATSAMD21G18 @48MHz)	53
Seeeduino XIAO (ATSAMD21G18 @48MhZ)	52
Arduino Mega (ATmega2560 @16MHz)	8

As expected, in terms of the CoreMark benchmark, the little XIAO board behaves very similar with Arduino Zero, which also uses the ATSAMD21G18, 32-Bit ARM Cortex M0+ chip familly.

Note: A CoreMark test with an Arduino UNO Rev 3 was not possible, due to its low amount RAM that causes instability problems, and as a result the board keeps restarting itself every a few seonds.

The Power Consumption

Not necessarily each WoT/IoT project is battery powered, nor require a very low power consumption. However, we still need to think on our "little and still green planet" and use the limited resources responsible. Believe it or not, but a few extra mW does really matter - as of 2020 over 30 billion IoT devices are estimated as being used all over the world and connected to the Internet. In addition, there are many other such devices not (yet) connected to the internet. Elementary math show us that even 1mW (milli watts!) extra power consumption, actually means 30MW (mega watts!), and this just for the IoT devices connected to the Internet. So, yes, it does really matter to keep the power consumption reduced at the minimum, at least when that is possible.

In our opinion, this little XIAO guy, was well designed, and the power consumption is quite low for what this board can do. The MCU plays a key role, since it takes most of the power juice, but the hardware design is also an important factor. Many other Arduino compatible boards, use additional components or modules (sometimes justified, sometimes not really), thus increasing the power consumption of the board. For example, various sensors or wireless communication modules (WiFi, Bluetooth, RF, etc) are incorporated in some boards. While this is not every time the case, and by this we mean "having the board filled up with as many goodies as possible" in terms of hardware features, such features are in fact underused. As a result, they don't only take additional space on the board and increase the price but also produce a bit more CO₂ using additional power when the board is powered, and of course at the time of being produced by the factory.

While we are really fans of the ESP8266, ESP32 and alike boards, they do not represent the answer to all our problem. Sure, it makes a lot of sense to use the powerful MCU and the included WiFi or Bluetooth features when needed, but for example these are a very bad replacement for a simple IoT temperature monitoring node, where an ATMega 328 MCU (e.g., Arduino Nano), a temperature / humidity sensor (e.g., DHT11 / DHT22) and a nRF24-based transmitter/receiver (e.g., nRF24L01+) make much more sense. Using the Arduino Nano, a nRF24L01+ module and a DHT11 / DHT22 sensor the power consumption will go around 30mA@5V (so, about 150mW). This can be reduced even more by using 3.3V instead of 5V and an efficient LDO, thus going down to about 40mA@3.3V (so about 132mW). The Arduino Nano can be successfully replaced with the XIAO board, and the power requirements do not increase, actually it can go down if your project is well designed. An ESP32 or ESP8266 will be less efficient by a few factors of magnitude, even with the WiFi and/or BT deactivated.

The XIAO Board uses the XC6206. According to the datasheet of this voltage regulator, the maximum input voltage is 6V, so this will also be the maximum voltage that it can be supplied to the board either via the contact pads located on the back of the board (see Figure 3) or via the USB-C connector (which normally shall provide about 5V). It can output a maximum of 200mA of current, but we do not recommend more than 150mA to avoid overheating it. Moreover, keep in mind that up to about 25mA may be used by the MCU and the other components (LEDs, voltage regulator, etc), so the conservative current available for the user, to power sensors and any other devices is about 120mA. Moreover, keep in mind that the GPIO pins can only supply a little amount of current. According with the specs, this can go up to 7mA (source) or 10mA (sink) per pin, but for this a special bit/flag shall be enabled, and this also comes with some other disadvantages. The real "by default" current for each GPIO pin is 2.5mA (sink) or 2mA (source) per pin.

Keep this in mind: you can easily burn up a GPIO or even destroy the MCU completely if the source or sink current is larger than 2.5mA (sink) or 2mA (source) even if this happens for very short amount of time. Something like half of a second is more than enough to destroy your MCU or GPIO if the current is exceeded. By setting the Output Driver Strength bit (DRVSTR) to 1 for a specific pin, a maximum of 10mA (sink) and 7mA (source) can be obtained. More details about this are available on the section 37.9 I/O Pin Characteristics of the SAMD21D datasheet document.

Using our digital multimeter UNI-T model UT71C we made some measurements to see how this board performs in terms of power requirements. In Table 3 we provide the obtained results.

Table 3: Power Consumption Measurements
Conditions	Results	Details
Input voltage via USB-C port: 4.95V Sketch: LED Blink every second Sketch	12.4mA@4.95V (61.38mW)	Measured when the blinking LED is ON.
Input voltage via USB-C port: 4.95V Sketch: the CoreMark benchmark	13.5mA@4.95V (66.82mW)	Measured during the benchmark runtime.
Input voltage via USB-C port: 4.95V Sketch: Sleep Mode with RTCZero Library	2.2mA@4.95V (10.89mW)	The MCU itself uses less than 1mA (the RTC and some other services are active). The rest is used by the power LED and the voltage regulator.

Get Started with the XIAO board and the Arduino IDE

The XIAO board can be programmed by using the Arduino IDE and the "Arduino Programming Language". Well, to be clear here, there is no such thing as "Arduino Programming Language", it is really just C/C++, but there is a trend to use this metaphor whenever the Arduino core and custom libraries are used. There following steps will guide you to get started with your first Arduino sketch and having the XIAO user controlled LED blinking.

Download the official Arduino IDE software if you didn't already. We also recommend to use the latest version available to avoid various issues caused by old bugs and to get access to the newest features.
Add Seeeduino to your Arduino IDE. For this, use the "File > Preference" menu item and copy/paste the following URL https://files.seeedstudio.com/arduino/package_seeeduino_boards_index.json into the "Additional Boards Manager URLs" input field.
Use the "Tools > Board > Boards Manager..." menu item, and in the new open window, search and install the "Seeed SAMD Boards". After this step we recommend to restart your Arduino IDE.
Open the Blink sketch by using the "File > Examples > 01.Basics > Blink" menu item.
Select the "Tools > Board > Seeed SAMD (32-bits ARM Cortex-M0+ and Cortex-M4) Boards > Seeeduino XIAO" menu item. This will instruct Arduino IDE what to do when you like to compile and upload a sketch.
Select the "Tools > Port > COMxx (Seeeduino XIAO)" menu item. COMxx represents the COM port to which the XIAO board connects too.
Now use the "Sketch > Upload" menu item to have the sketch compiled and uploaded to your board. It may take a up to one minute to complete this task, in particular when the sketch was not yet compiled and your PC is not the fastest one in the world.

If all went well, when the upload is completed your XIAO shall have the yellow user LED blinking once every second.

Note: in our experience, most of the time this board can't be switched to programming mode automatically. What you shall do is to use some tweezers or a conductive tool (e.g., a small flat head screwdriver) and to touch the two reset pins from the front of the board - these are located near the A0/D and A1/D2 GPIO pins (see Figure 2). Notice that you have to repeat this twice, in a short time (i.e., twice in about one second). After that, the board enters boot-loading mode (the green and yellow LEDs must be on at this point) and the uploading of your sketch will work as expected. Notice that this will also switch the used COM port, thus you have to select the new one by using the "Tools > Port > COMxx (Seeeduino XIAO)" menu item.

Some Final toughts

We played with the little XIAO for a few months by now and we have used it in a few of our projects already. It is for sure not perfect, and there are a few issues with it, like the need to manually enter boot-loading mode every time when it needs to be reprogrammed, the low amount of current available to each GPIO or the incompatibility with a few Arduino libraries. The 11 GPIO pins are also not enough for projects that requires more than just one or two sensors, a switch and eventually an I2C or SPI display. In many of our projects however, the board filled up the requirements and being so tiny, it fitted with ease in almost any case of the IoT/WoT nodes. Therefore, whenever we do not need WiFi / BT, a faster MCU or more GPIO pins, we do consider using XIAO before jumping further with our searches. The low price is also a big plus, in particular when you need a lot of such boards and the total price can rise up very fast.

Do we recommend the XIAO board? Yes, it is a very good candidate for many low power projects. It is also very small and very cheap, so you don't need to break the bank when you need a few of them for your project.

Is is perfect candidate for any project? No, unfortunately it is not. Among the reasons, an important one is the reduced number of GPIO pins. In this case, you either have to look further for another board, but then expect a larger sized board and very likely a higher price too, or you think on using a "GPIO multiplier", such as the MCP23017 IC, which will give you 8 I/O pins with 25mA per pin at the expense of the I2C pins of your board.

What's next?

The the "Green Balcony" project is work in progress. Among others, it makes use of a few Seeeduino XIAO boards, used to control the watering of the plants as well to monitor various aspects, such as the water tank level, temperature and to keep an eye on the light intensity variation. Since the balcony is populated with very different species of plants (blackberry, raspberry, a small fig tree and various flowers), it is important and interessant as well to observe the light variation. This will help to decide the optimal position for the plants, to have them as "happy" as possible, and get their smile when drinking the morning coffee in the green seven square meter mini-garden. Since only solar power is used for this project, keeping an eye on the light intensity provides also indications about the optimal positioning of the 10W solar panel used to collect the "free" energy from the sun.

Note: yes, we know that there is no such thing as free energy. We use here the term of free energy only as a metaphor, with the meaning of energy that is not taken from the grid. In term of costs, this actually means, the costs of the equipment used to collect it (solar panel, charge controller, battery, wires, etc) - theoretically no other costs are involved, practically, we'll see...

Stay tuned, a set of tutorials providing step-by-step implementation instructions of the "Green Balcony" project will be published soon!

PRODINo: Home Automation with ESP8266 based WiFi Control

mdiaconescu — Sun, 27 Nov 2016 14:30:39 +0000

What is PRODINo WiFi-ESP?

PRODINo is an industrial grade, ESP8266 based WiFi module (uses the WROOM-2 official ESP8266 module) that is designed and produced by KMP Electronics LTD, based in Bulgaria. The module contains four high power relays, allowing to control all kind of appliances, including some that require mains power. It opens the door for DIY (but not only) projects that otherwise would have been required careful design and good electronics knowledge, normally possible only for specialists or requiring a lot of time for design and implementation. Moreover, using ESP8266 allows not only for WiFi network connection, but also provides space for hacking and tweaking, using custom firmware if Arduino is not what you want to use, and even giving you access to your project from the Internet, which however comes with security risks and requires additional care.

Disclaimer: working with electricity is very dangerous! The module we are going to discuss uses 3.3-5VDC, as well as mains voltage (110 - 250V). Working with electricity can cause bad injuries and even death if not used with care. We cannot be held responsible for any caused damage or any harm brought to yourself! Do it at your own risk and/or ask help from an electronics engineer.

Hardware Specifications

The used relay specification (15A@125VAC, 15A@24VDC, 10A@250VAC) allows for up to 2500W for each output. In addition, it provides four optically isolated inputs (using the Toshiba TLP185 opto-coupler), meaning that it does not only allow to read data, e.g., from sensors, but also makes this operation (relatively) safe, allowing to connect 3-30V sources without killing the ESP8266 module or its GPIOs, since they are only up 3.3V tolerant. In Table 1 we show the complete electrical specs for this module:

Name	Min	Max	Unit
Size	-	70 x 32 x 92	mm
Module power supply	5	30	V
Module power supply @5V	150	400	mA
DC Input (opto-couplers)	3	30	V
Output AC (relay)	-	2500 (10A@250VAC) 1800 (15A@120VAC)	W
Output DC (relay)	-	360 (15A@24VDC)	W

The relays are not driven directly by using the ESP8266 GPIOs but with the help of an MCP23S08 IC (see Figure 2), that is an 8-bit, general purpose, parallel bidirectional I/O expansion for SPI (an I2C version of it, i.e., MCP23008, is also available). The optically isolated inputs use the same MCP23S08 IC (see Figure 2), which means that most of the ESP8266 GPIOs remains practically unused, and most of those I/O pins (including the analog one) are brought out via connectors (which unfortunately are not standard 2.54 male or female headers). To drive the relay coils (requires ~5V@72mA for each), the MCP23S08 is connected to an ULN2003A IC (see Figure 2), which is a 7 port Darlington Transistor Array, allowing an output of up to 50V@300mA per port. This may be a bit of an overkill for this design, but allows for some error margins and also some higher powered relays on future module releases, or...to be replaced by the DIY project author (we love hacking!).

Figure 1: PRODINo WROOM-02 Module Specs.

As visible on the product label, shown in Figure 1, the specified output per relay is only 5A, which at the highest voltage (250VAC) means 1250W. We are not sure if this is just a very conservative specification, with respect to the usage of this module, thus allowing for a large safety margin or simply because of some other design considerations that we are not aware of. From our perspective, both the relays (specified for 10A@250V) and the ULN2003A IC that drives the relay coil can easily handle a much higher output (lets say about 2000W, keeping some safety margins).

Figure 2: PRODINo WROOM-02 Module Board (Front).

Programming the PRODINo

Programming the module requires to use the included FTDI module. However, it is also possible to use a cheap (under 2 EUR) USB-TTL converter module, as long as it supports 3.3V output on its TX (UART transmit) line. Make sure that the FTDI module, that comes on the packet, has the voltage selection jumper set to 3.3V position, as shown in Figure 3. Make sure that you connect the FTDI module in the correct position (see Figure 3), otherwise you may kill the PRODUINo module.

Note: the "Auto-Flash" jumper located just on the right site if the UART connector (see Figure 2), below the "Flash" button, can be set, thus allowing to program the ESP8266 module (the brain of the PRODINo module) without your direct intervention: there is no need to ground the GPIO 0 or to push some sort of "Set to Flash Mode" button. The alternative is to use the "Flash" button, located above the "Auto-Flash" jumper, (see Figure 2). This makes sense when using an USB-TTL module that does not allow to ground the GPIO 0 pin of the ESP8266 module, for all the other cases, just enable the "Auto-Flash" jumper.

Figure 3: FTDI Programmer Connected to PRODINo WROOM-02 Module Board.

Use Arduino IDE to Program a PRODINo Module

It is fairly easy to program the PRODINo module, by simply using the Arduino IDE and Arduino code. Thus, if you ever used the Arduino IDE and wrote some code for one or more of the Arduino boards, you are ready to go with the PRODINo module.

First, you'll need to download the Arduino IDE from the official download page. Make sure that you download the correct version corresponding to your operating system. Also, specially when using UNIX/Linux systems, make sure that your user has the rights to use "COM" ports, that are required by the FTDI module when programming the PRODINo board.

Next, start the Arduino IDE and navigate to File > Preferences menu. In the section "Additional Boards Manager URLs", copy and paste the following URL: https://raw.githubusercontent.com/kmpelectronics/Arduino/master/ProDinoEsp8266/package_prodino-esp8266_index.json, used to indicate the location of the JSON which describes the PRODINo module and the additional Arduino libraries that it requires. Further, use the Tools > Board Manager menu, and from the list of the additional (custom) boards, select the "PRODINo WiFi board by KMP Electronics LTD" one, then click "Install". In a short amount of time the installation process is completed and we are ready to go with the programming of the PRODINo WiFi-ESP module.

Later, when you'll like to write your custom program to the PRODINo module, use the small arrow icon from the left-top of the Arduino IDE user interface or use the Sketch > upload menu (its keyboard shortcut is CTRL + U). Remember, you'll need to use the Tools menu to select the corresponding board (use: PRODINo WiFi-ESP WROOM-2) and COM port (this can be different from case to case, but usually is something like COM4, COM5, etc).

Controlling the Relays

The first feature we like to test is the control of the four relays. We'll write the most basic Arduino program that allows to switch ON or OFF any of the four relays, by simply using a HTML form. At first, lets write the HTML form, which sends a POST request to the PRODINo module. The full content of the index.html HTML file is shown below:

<!DOCTYPE html>
<html>
  <head>
    <title>PRODINo Relay Controller</title>
  </head>
  <body>
   <form method="POST" action="http://192.168.4.1/relay">
    <label>Select relay:
      <select name="relayId">
        <option value="0">Relay 1</option>
        <option value="1">Relay 2</option>
        <option value="2">Relay 3</option>
        <option value="3">Relay 4</option>
      </select>
    </label>
    <label>Select relay state:
      <select name="relayState">
        <option value="1">On</option>
        <option value="0">Off</option>
      </select>
    </label>
    <input type="submit" value="Save relay state" />
   </form>
  </body>
</html>

Pushing the "Save relay state" form submit button, a standard HTML POST request is made to http://192.168.4.1/relay. The request URL consists of: 1) the IP address of our PRODINo module (defaults to 192.168.4.1, but it can be changed if needed or wanted); 2) a custom path that handles the requests (we chose to use /relay).

Two HTML select elements are used for our form. The first one uses the name relayId (this is the parameter name received on the POST request) and allows to select the relay we'll like to control. Allowed values are from 0 (first relay from left to right when watching the relay connectors on the module) to 3 (the most right relay). The second HTML select uses the name, relayState, and allows to specify the state of the selected relay. We'll use 1 for enable (turn ON) and 0 for disable (turn OFF).

Let's now write the Arduino code that intercepts the HTTP post request and turn the corresponding relay ON or OFF based on our selection in the HTML form:

#include <KMPDinoWiFiESP.h>
#include <KMPCommon.h>
#include <ESP8266WebServer.h>

const char WIFI_PSK[] = "1a2b3c4d";
const char SSID[] = "Charlie's Home";
const uint8_t PORT = 80;
ESP8266WebServer webServer(PORT);

void setup(void) {
  // initialize the PRODINo board
  KMPDinoWiFiESP.init();
  // setup the WiFi module as AccesPoint (AP Mode).
  WiFi.mode(WIFI_AP);
  // set the SSID and Password for the AP
  WiFi.softAP(SSID, WIFI_PSK);
  // set the HTTP route for the relay control
  webServer.on("/relay", handleRelayRoute);
  // start the web server
  webServer.begin();
}

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

void handleRelayRoute() {
  int8_t relayId = -1;
  bool relayState = 0;
  // incomming POST request (two expected params: relayId and relayState).
  if (webServer.method() == HTTP_POST && webServer.args() == 2) {
    for (uint8_t i = 0; i < webServer.args(); i++) {
      if (webServer.argName(i) == "relayId") {
        relayId = CharToInt(webServer.arg(i)[0]);
      } else if (webServer.argName(i) == "relayState") {
        relayState = CharToInt(webServer.arg(i)[0]);
      }
    }
    KMPDinoWiFiESP.SetRelayState(relayId, relayState);
    webServer.send(200, TEXT_HTML, "OK");
  } else {
    webServer.send(400, TEXT_HTML, "Bad request");
  }  
}

The set of #include directives allows to load the required libraries, which were automatically added when installing the new PRODINo board manager module. Further, for the WiFi name, the WiFi shared password and the server port, the corresponding SSID, WIFI_PSK and PORT constants are defined. Feel free to alter the SSID and WIFI_PSK values, but let the PORT value unchanged (port 80 is the HTTP port).

As part of the Arduino setup method, we initialize the module and set the WiFi in AP (access point) mode. Then, we register the /relay route (as used for the @action attribute of the HTML form element) and the corresponding handler method, i.e., handleRelayRoute. Last, we start the web server by calling its begin method.

The handleRelayRoute method, the handler for the /relay HTTP route, checks if the used HTTP request is of type POST and if there are exactly two parameters provided (recall, we expect the relayId and relayState parameters to be sent). If that is the case, then we extract the relay identifier and the desired relay state, then we change the relay to that state by using the KMPDinoWiFiESP.SetRelayState method and we respond with HTTP code 200, having the meaning "all went fine for the request". If the request type is not of type POST or there are more or less than two parameters, then a HTTP error code 400 is sent, which means "bad request - wrong parameters or request type!"

The Arduino loop method simply waits for requests, by using the ESP8266WebServer.handleClient method.

To test, upload the following code to the PRODINo board (as shown before in this tutorial), then connect to the WiFi network with the name set by the SSID variable. Open the index.html HTML page, and use the form to turn ON or OFF the relays you'll like to test.

Download the code

Reading the Inputs

The second important feature we like to test is the optically isolated inputs. For this, we'll write a simple Arduino program that is able to read the states of all four optically isolated inputs and return the result. A HTML GET request for the path /opto is used, i.e., http://192.168.4.1/opto. The response is plain text with the format I_x is HIGH | LOW;.

#include <KMPDinoWiFiESP.h>
#include <KMPCommon.h>
#include <ESP8266WebServer.h>

const char WIFI_PSK[] = "1a2b3c4d";
const char SSID[] = "Charlie's Home";
const uint8_t PORT = 80;
ESP8266WebServer webServer(PORT);

void setup(void) {
  // initialize the PRODINo board
  KMPDinoWiFiESP.init();
  // setup the WiFi module as AccesPoint (AP Mode).
  WiFi.mode(WIFI_AP);
  // set the SSID and Password for the AP
  WiFi.softAP(SSID, WIFI_PSK);
  // set the HTTP route for the DHT22 sensor readings
  webServer.on("/opto", handleOptoRoute);
  // start the web server
  webServer.begin();
}

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

void handleOptoRoute() {
  bool optoState;
  String result = "";
  // incomming GET request (get the state of all opto-inputs)
  if (webServer.method() == HTTP_GET) {
    for (uint8_t i = 0; i < 4; i++) {
      optoState = KMPDinoWiFiESP.GetOptoInState(i);
      result.concat("I_");
      result.concat(i);
      result.concat(" is ");
      result.concat(optoState == true ? "HIGH" : "LOW");
      result.concat("; ");
    }
    webServer.send(200, TEXT_HTML, result);
  } else {
    webServer.send(400, TEXT_HTML, "Bad request");
  }  
}

Compared with the relays example, we have a few relevant differences. The first one is in the setup method, for which we register the new route, /opto and the new handler, handleOptoRoute. The second change is in the handleOptoRoute method, as part of the request method detection, where now we expect a HTTP GET type instead of POST. The last one is the reading of the optically isolated inputs, made with the help of the KMPDinoWiFiESP.GetOptoInState(inputId) method, which as as parameter the input number (0 to 3). A less significant change regards the creation of the GET response body, which consists of chain of "I_x is HIGH | LOW;" strings, one for each of the four inputs (response example: I_0 is LOW; I_1 is HIGH; I_2 is HIGH; I_3 is LOW;).

To test this example, write the Arduino program to your PRODINo board (as shown above in this tutorial), then connect to the WiFi network with the name set by the SSID constant. Open a Web Browser and navigate to http://192.168.4.1/opto. For this case we don't need a HTML form, since GET is the default request type you get by simply using the URL in the URL bar of a web browser.

Note: normally, you'll only see only "LOW" states for all the input pins. Also, notice that those inputs are actually in pair of two for each input, since they are practically diodes. You'll need to provide HIGH (more than 0.5VDC) or LOW (less than 0.5VDC) voltages at the corresponding diode end to achieve the expected results. The product cover has labels clearly showing which pin represents which end of the corresponding diode (see also Figure 1).

Homework: modify the above Arduino program so that the number (0 to 3) of the optically isolated input is provided as part of the HTML GET request, and the response is either "HIGH" or "LOW" depending on the state.

Download the code

More Examples for PRODINo

It looks that the PRODINo team had a busy time, so an impressive number of usage scenarios and examples are available and ready to use. You'll certainly want to check the Arduino IDE File > Examples > Examples for PRODINo WiFi-ESP menu and chose the one you'll like to test. The example set includes the use of PRODINo as server, access point and client, with the help of the WiFi module and also shows how to provide a HTML interface that allows to control the relays or to show the state of the optically isolated inputs by simply using a web browser, available on any PC or smart device, such as a smartphone, smartwatch or table.

Conclusions

After having quite some fun with the PRODINo WiFi-ESP WROOM-2 v1.0 module and taking a closer look at its hardware components and design, we found it to be user friendly and easy to use for DIY IoT projects, even for beginners. The quality of the board, its electrical design (also check the schematics) and the selection of the electronic components, sets the PRODINo device into the semi-professional category. The price range makes possible its usage for most of the DIY or professional projects / products. Below are the most relevant pros and cons we have found for this module:

Pros:

low-to-medium price: 40-47 EUR, exclusive shipping costs, but including the FTDI programmer;
DIY ready and user friendly: if you ever played with Arduino IDE and some Arduino boards, you are ready to go with PRODINo;
(almost) ready to use out of the box: it comes together with the FTDI FTD232R based programmer/debugger module, but notice that you'll need a 5-30V@400mA+ power supply (or an USB breakup cable) and a mini USB cable (for programming only).
allows to control four appliances with up to 2500W each: unfortunately, with the current design, it is not possible to directly parallel the outputs for even higher power;
isolated inputs: four optically isolated inputs are available, thus the ESP8266 module is safe, even when inputs are misused;
uses the official WROOM-02 ESP8266 module: ensures a good WiFi experience and allows for lots of hacks and software tweaks, including the use of JavaScript as the programming language, when the appropriate firmware is uploaded;
(almost) open source: its electrical schematics are made public and a module (and corresponding libs) is available for the Arduino IDE board manager, but it is unclear if you are allowed to improve the schematics and release them for public usage;
lots of usage examples: after installing the corresponding Arduino IDE module (via the board manager), more than sufficient examples are available (check the File > Examples > Examples for PRODINo menu in Arduino IDE).

Cons:

(somehow) limited number of inputs: only four (optically isolated) inputs are available, keeping in account that the MCP23S08 (8-bit, general purpose, parallel I/O expansion for I2C bus or SPI) is used, and the WROOM-2 module provides itself 9 GPIOs (including SPI and I2C ones);
hazard safety, while in general we found this module safe to be used, a better electrical isolation of the (possible mains connected) outputs would have helped to avoid electrical shocks, that can possibly cause injuries or even death (!). This is even more relevant, when the module is used for DIY projects implemented by amateurs. The plastic cover could have been extended over the output connections, thus making the (accidental) touching less probable.

Project Ideas

automatic home/garage door locker (and un-locker), based on the the location of your smartphone, and home monitoring by reading various available sensors, such as temperature, humidity, light intensity or air quality;
control the watering of your home plants or your backyard garden, by reading soil moisture sensors and enabling/disabling water pumps or water pipe connected electro-valves;
an alarm system that detects intrusion into a home (or perimeter) when we are in holidays, using PIR and capacitive touch sensors, allowing to trigger a high level alarm bugler and sending an e-mail to you whenever something suspicious is detected.

In further tutorials we'll show how to use JavaScript (Mongoose-IoT based firmware) code to program the PRODINo module. We'll also discuss how to write an Android App to control common used appliances from your house, such as unlocking the door and turning on the light when dark and you just reached the house after a hard work day.

JavaScript-Based IoT/WoT Development with the ESP8266 and the Raspberry Pi

mdiaconescu — Wed, 21 Sep 2016 09:52:01 +0000

The ESP8266 micro-controller module gained huge popularity over the last few years, being a small module with a powerful MCU, SPI Flash, 2.4GHz 802.11 b/g/n WiFi capabilities and relatively small power consumption, all for just a few dollars. This article focuses on discussing how to use JavaScript to program an ESP8266. Currently, two firmware versions allow JavaScript code execution on an ESP8266: Mongoose-IoT (that we'll discuss about in this tutorial) and Espruino for ESP8266.

With a single small and cheap board, it is possible to have a JavaScript interpreter, WiFi client, WiFi router, HTTP client and server and GPIOs control, therefore allowing to read sensors, control actuators and use human interface devices, such as displays, buttons or joysticks.

Meet the ESP8266

Various modules built around the ESP8266 IC are available, and the most common 12 standard modules are shown in Figure 1.

Figure 1: Variants of the ESP8266 Module.

These modules use the 802.11b/g/n WiFi standard, operating at 2.4 GHz. It means they can connect to a standard WiFi network, such as the ones provided by an WiFi router, WiFi repeater or access point (AP). No need for special communication channels or frequencies, such as the 433MHz band required by some wireless modules.

Choosing the Appropriate ESP8266 Module for a Project

Having multiple variants of ESP8266 module, comes the question: "which one should I use ?". There is no perfect answer for this question, and it highly depends on what you are using the WiFi module for. These are not just "blind" WiFi communication modules, but small development boards, containing a programmable MCU and builtin GPIO pins, thus it can do tasks similar with the ones possible with the Arduino boards, but being much faster and in some sense more capable. We see three main points to be considered when choosing an ESP8266 module for a specific project:

usability on a breadboard: most of the times we prototype on a breadboard, therefore we should be able to easily connect (or plug) these modules to such a board. Some of the modules, such as ESP02, ESP03 and ESP05 (see Figure 1) are breadboard friendly, having a pitch of 2.54mm (the distance between two pins). Other modules, such as ESP07 or ESP08 have a pitch of 1.27mm, thus you'll only be able to use them with a breadboard when using an adapter. Last, other modules, such as ESP01 have a pitch of 2.54mm, but they have a two rows header, which makes it impossible to be used with a breadboard, because of the implied short-circuit between the pins. Notice that some of the breadboard friendly modules have only a "half-way" pin connections, e.g., ESP02 module. Such connections are somehow harder to solder, specially for a beginner. Our tip for the ESP02 module: plug the pin headers into a breadboard, align the module on top of them, then solder.
flash memory size: the ESP8266 modules come with permanent flash memory ranging from 4MBit (512KB) up to 16MBit (2MB), but some may even go up to 128MBit (16MB). In many cases, it is also possible to increase the flash capacity of such a module, but for this, one needs good soldering skills to remove the old flash IC and solder the new one, and usually the price of the flash IC bought in small quantities is about the same as for the price of the complete ESP8266 module (or even more!), thus defeating the purpose. Excepting the case of ESP06, ESP07, ESP08 and ESP12E/F modules, where a hard to remove metallic shield covers the CPU and flash ICs, one can simply check the flash size by reading the text on the 8 pin black IC soldered near the MCU (which is the square black IC with pins on all four sides). For example, if the number on the flash IC starts with 25Q80 then it is a 8MBit Flash, while if it starts with 25Q40 then it is a 4MBit one. For our purpose, a minimum of 1MB (8MBit) Flas is required, but we recommend 4MB+ (16MBit+).
MCU features: these modules are driven by a low power 32-bit RISC CPU (Tensilica Xtensa LX106) running at 80 MHz. It has 64 KB instructions RAM, 96 KB data RAM, it and supports external QSPI flash - 512 KB to 4 MB (but also up to 16MB is supported). Up to 16 GPIO pins are available, from which one has 10Bit ADC capabilities, and supports I2C, I2S, SPI and UART communication protocols. All these features are quite important if you are using the ESP8266 module as standalone controller board. However, if the ESP8266 module is used as an UART WiFi interface only, then you'll not really use the GPIO pins, so you may ignore this when selecting the board that suits your needs.

Note: for being able to write a new firmware or to communicate with an ESP module by using a computer, you'll need a USB-TTL module, such as the CP2102 IC based one, shown in Figure 4. You'll need to connect the TX pin of the USB-TTL module to the RX pin of the ESP module, and the RX pin of the USB-TTL module to the TX pin of the ESP module. For being able to flash a new firmware, but NOT when using the ESP module in normal mode, you'll also need to connect the GPIO0 pin of the ESP module to ground then perform a power cycle.

Figure 4: USB-TTP Module based on CP2102 IC.

Standalone User Friendly ESP8266 based Modules

Other ESP8266 based modules are designed with "make it simple, for anyone" in mind. Usually these provide a two rows breadboard friendly PCB, with USB (usually via a micro USB cable) connection, both for providing power (also by using a standard micro USB charger) and if needed, also for the communication with a PC. Figure 2 shows the NodeMCU V2 board, designed by Amica, providing an on-board CP2102 USB-TTL IC, allowing to communicate with the PC via the same micro USB cable that also used to power it. Figure 3 shows a WeMOS D1 Mini module, designed to use stackable expansions boards (similar with the Arduino Shields), thus being able to attach various sensors, actuators or even OLED LCDs.

Figure 2: Amica NodeMCU v2 Module.

Figure 3: WeMOS D1 Mini Module.

Some Words Before Getting Started...

Before going further with the reading and following the tutorial instructions, is good to know that:

we are going to use an ESP8266 NodeMCU V2 board, produced by Amica (see Figure 2), which means: a) there is no need to put it to "flashing mode", since this happens automatically, the bundled USB-TTL CP2102 IC takes care of this task; b) is powered via the micro USB cable directly from an USB port, the same port being also used for the communication with the module, if this is needed (e.g., for programming the module)
the further provided instructions presumes that a Raspberry Pi 2/3 board running Raspbian is used, but other Linux distribution, on either a RPi 2/3 board or a PC works too, however some differences may occur with respect to some commands and Linux repositories used to obtain the required components
the ESP8266 12E/F modules (see Figure 1) should work well, as an alternative to NodeMCU board, but its GPIO0 pin must be pulled LOW to set the module to "flashing mode", task required ONLY when the firmware needs an upgrade, and then a power cycle between the "flashing mode" and "normal operational mode" is also required - other ESP8266 modules may also work, but usually they either have less exposed GPIO pins or they are not breadboard friendly
the SPI Flash IC of the ESP8266 module must be 1MB+, otherwise the module will not work properly or may not work at all
a Windows PC can also be used, and this makes the process of writing the firmware to ESP8266 module easier, but various other changes are needed for being able to build the Mongoose-IoT firmware from source code, when you need custom functionality which requires firmware code changes - unfortunatelly, compiling the Mongoose-IoT firmware on a Windows machine is a real pain
further on, we'll use MFT as a short name for the "Mongoose-IoT Flashing Tool" software, ESP as a short name for the ESP8266 module (full name is used if needed to make distinction in some cases, when just ESP is confusing) and RPi as a short name for "Raspberry Pi 3 Model B".

Flashing the Standard Mongoose-IoT Firmware by Using an Raspberry Pi

For being able to execute JavaScript code on your ESP module requires to upload the Mongoose-IoT firmware. It uses the V7 JavaScript engine and allows to execute standard JavaScript code. Notice that only a subset of the standard JavaScript is supported, and some of the features are stripped down, so the V7 engine "fits" on the ESP module. For example, some String related check/manipulation methods (e.g., startsWith and endsWith) and the new ECMA5 features may not be (at all or fully) supported. However, it comes with additional features, which are not available as part of the standard JavaScript core, but a being available on NodeJS (i.e., stripped down modules or core functionality), such as the HTTP client (allowing for HTTP requests) and HTTP server capabilities.

Build the Mongoose Flashing Tool Application

The latest standard Mongoose-IoT firmware version can be obtained by using the MFT software. Compiling and building it from source code requires quite some time (about 2+ hours) to complete, and lots of space on your RPi storage (3GB+, but most of it can be recovered at the end), because it needs to download and compile the Qt Framework. The following steps guides you through the process of installing MFT on your RPi:

make sure that your RPi has internet connection (either WiFi or wired connection)
install dependencies required further in the build and compile processes:
# sudo apt-get install build-essential git python-git wget libglib2.0-dev libudev-dev libftdi-dev libfontconfig1-dev libjpeg-dev libssl-dev libicu-dev libjpeg-dev libxcb-xinerama0-dev libxcb-icccm4-dev libxcb-image0-dev libxcb-keysyms1-dev libxcb-render-util0-dev libxcb-shm0-dev libxi-dev libxrender-dev x11proto-render-dev qt5-qmake libqt5serialport5-dev libxcb-util0 libffi-dev
configure, build and install the Qt static libraries by executing: # wget -c http://download.qt.io/official_releases/qt/5.7/5.7.0/single/qt-everywhere-opensource-src-5.7.0.tar.gz # tar xzf qt-everywhere-opensource-src-5.7.0.tar.gz # cd qt-everywhere-opensource-src-5.7.0 # ./configure -make 'libs tools' -static -prefix /opt/qt5 -opensource -confirm-license -skip qt3d -skip qtcanvas3d -skip qtdoc -skip qtlocation -skip qtscript -skip qtmultimedia -skip qtsensors -skip qtwebengine # sudo nice make -j4 # sudo nice make -j4 install # sudo /opt/qt5/bin/qmake && nice make -j 4
...now take a cafe and watch some YouTube videos, this task takes quite some time to complete (approx. 80 minutes on our RPi 3B board). Some Qt5 extensions were excluded since we don't really need them for our purpose and thus the compilation time is cut down.
Note: each line starting with a dash (#) is a new command, and you should not write the # when executing this. You can execute the commands one by one or as a batch, on your RPi console of via SSH.
ensure that your beloved RPi does not overheat during the above tasks (specially when building Qt), so from time to time check the CPU temperature by using
sudo /opt/vc/bin/vcgencmd measure_temp
and make sure that the temperature stays below 80°C / 176°F. Blow some air by using a cooler or place your RPi somewhere in a good ventilated area. In our case the temperature did not exceeded 60°C, on a room with temperature of about 24°C, but a cooler was used to move the air around, because our RPi is a bare board with no heatsinks or any other cooling method.
Note: for single core RPi boards (RPi 1 Model B), do not use the "-j" parameter, e.g., sudo nice make -j 4 (or any other task), since this parameter is being used to specify the number of CPU cores to be used during that task, so it fails with a value of "4" (or any other) when used with single core CPUs (e.g., Raspberry Pi Zero or Raspberry Pi 1 Model B).
clone the Mongoose Flashing Tool Repository - thus getting the latest available source code:
# git clone https://github.com/cesanta/mongoose-flashing-tool.git
in a folder at your choice
enter the newly source code folder, by using:
# cd mongoose-flashing-tool
execute:
# QT_SELECT=5 /opt/qt5/bin/qmake && make -j 3
to build MFT from source. This step may take some time to complete (about 2 minutes on our RPi 3B)
in case that the above step results in one or all of the build errors:
/usr/bin/ld: cannot find -lEGL /usr/bin/ld: cannot find -lGLESv2
then your OpenGL static libraries cannot be linked, probably because are not found, because normally their shared versions are available on Raspbian. To solve this you need to edit the mongoose-flashing-tool/src/Makefile file, by using whatever editor you like. Notice that this file DO NOT existst before trying to compile MFT, you can only find it afterwards (even if you get the error, the file must be there). In this file, find the following -lEGL and -lGLESv2 and delete them. Then at the end of the line where you found these two, add the following: -Wl,-Ddynamic -L/opt/vc/lib -l:libEGL.so -l:libGLESv2.so, then save the file and execute the QT_SELECT=5 /opt/qt5/bin/qmake && make -j 3 command again (make sure that you are in the mongoose-flashing-tool folder and NOT in its src sub-folder when doing this).
at this point you must connect the ESP module (e.g., NodeMCU, WeMOS or a standard one with an attached USB-TTL bridge) to an USB port of your RPi board,by using a corresponding USB cable and any of the USB ports of your RPi board
start the MFT application by executing:
# cd src # ./MFT
and the application must start in GUI mode and should detect the module type (ESP8266). Make sure that you select the correct port (e.g., ttyUSB0 in our case), then follow the instructions, as also shown in Figure 5, Figure 6, Figure 7, and Figure 8.
if your ESP module refuses connection for firmware update (it happens normally only with the basic ESP modules, see Figure 1, but should not be the case for NodeMCU and WeMOS D1 Mini boards), it usually means that the module did not entered "flashing mode", so you may want to check if the GPIO0 pin is pulled LOW (do this task without supplying power to the board!), i.e., connected to GND rail, and make sure to power cycle the module after pulling LOW the GPIO0 pin
now you can remove the source folders for the Qt5 library, this freeing up 3GB+ on the RPi SD/MicroSD card, by executing:
# rm -rf qt-everywhere-opensource-src-5.7.0
from the parent folder of qt-everywhere-opensource-src-5.7.0 folder. If permission denied errors occurs, then execute the command with sudo.

If you find the build process too complicated, but still want to try the ESP8266 firmware, then download the compiled MFT application for Raspbian (tested on 20 October 2016) from the link below. Unzip the archive by executing unzip mongoose-flashing-tool.zip, and give execution rights to the src/MFT application, by using sudo u+x src/MFT from the mongoose-flashing-tool folder. Finally, install the libxcb dependency library, by using sudo apt-get install libxcb-util0. Now you can run the application by using src/MFT from the mongoose-flashing-tool folder or simply ./MFT from the mongoose-flashing-tool/src folder.

Download Mongoose Flashing Tool (MFT) Build for Raspbian

Figure 5: Mongoose-IoT Flashing Tool - Select Module and Communication Port.

Figure 6: Mongoose-IoT Flashing Tool - Select Firmware.

Figure 7: Mongoose-IoT Flashing Tool - Flashing the Firmware.

Figure 8: Mongoose-IoT Flashing Tool - Connect to WiFi Network.

Connecting the ESP8266 module to a WiFi network (see Figure 8), is optional, and you can do this later when the module needs access to Internet or Intranet. Therefore, after the step shown in Figure 7 you can already close the MFT application.

First JavaScript Tests on ESP8266

Lets test now our new JavaScript toy! For this, from the folder mongoose-flashing-tool/src, execute:
./MFT --advanced
which opens the same MFT application, this time in an advanced mode where you can interact with the ESP module, using some kind of console like style (see Figure 9). Then, select the communication port (should be the same as the one used when writing the firmware), and click the Connect button. If all went fine, you must be connected to your ESP module.

As a simple test, lets check the current configuration of your ESP module, currently running on the Mongoose-IoT firmware. For this, in the MFT Console, write Sys.conf then press Enter. As result, the serialized JavaScript configuration object is shown (see Figure 10).

Figure 9: Mongoose-IoT Flashing Tool - Connect to ESP8266 Module.

Figure 10: Mongoose-IoT Flashing Tool - A First JavaScript Test Code on ESP8266.

One more test we like to do, is to upload a JavaScript file, containing some code that we like to execute on ESP8266. For this, create a file named app.js on a folder at your choice, then using a text editor, open it and copy/paste the following simple test code:

function sum(a, b) {return a+b;};
console.log( "The sum of 123 and 456 is: " + sum( 123, 456));

Use the Upload File button, and and select the app.js JavaScript file to be uploaded to your ESP8266 module. Reboot the module, using the Reboot button, then in a few seconds, after some initialization messages, you should see:
The sum of 123 and 456 is: 579
as the result of executing the JavaScript code from app.js file.

Note: the JavaScript code MUST be in a file named app.js, and you can't just use any filename you like, because after booting, the firmware runtime looks for this specific file, and if is found, the JavaScript code is executed. Note that if you have JavaScript errors in your code, the module may behave strange, like continuously resetting itself, and in some cases, the only way to have it back working is to upload the firmware again!

You may also want to check this YouTube video showing the basics steps in using the Mongoose-IoT Cloud Service.

Build and Flash Mongoose-IoT ESP8266 Firmware by Using a Raspberry Pi Board

Since we like to add more functionality into the existing Mongoose-IoT firmware, discussed later in this article, we need to compile the firmware and flash it to the ESP module. For this, we need to prepare our system by following the steps below:

install docker, if not already existing in your system:
# sudo curl -sSL https://get.docker.com | sh
allow user to use docker (add user to docker group):
sudo usermod -aG docker pi
Notice that we have used the user with name pi in the example above, if is the case, replace this accordingl
start the docker service:
# sudo systemctl daemon-reload # sudo service docker start
clone the git repository of the Mongoose-IoT Firmware project:
# git clone https://github.com/cesanta/mongoose-iot
enter the ESP8266 firmware project folder:
# cd mongoose-iot/fw/platforms/esp8266

edit the Makefile.build and make sure that the following parameters are set:

APP_FS_PATH ?= $(REPO_PATH)/fw/platforms/esp8266/fs
MG_ENABLE_JS ?= 0
CREATE_RAW_FS ?= 1

build the firmware:
# sudo make
Notice that this task may take some time to complete, for the first time, since various docker image packages needs to be downloaded and extracted on your machine
when the build process is complete, the resulting firmware zip archive file is: mongoose-iot/fw/platforms/esp8266/firmware/mongoose-iot-esp8266-last.zip
open the MFT application in advanced mode, by executing:
./MFT --advanced
from the mongoose-flashing-tool/src folder
connect to the ESP module by using the connect button, after selecting the correct communication port (e.g., ttyUSB0), then use the Firmwware section to select the firmware zip file created above, and press the Flash button
in a few seconds, the flash process must be completed, now reboot the ESP module by clicking the Reboot button
test if the module works as expected: execute Sys.conf in the MFT console, and you should see current configuration settings.

You can also download the "ready to flash" Mongoose-IoT Firmware for ESP8266 with DHT11/21/22 JavaScript support by using the download button below:

Download Mongoose-IoT Firmware for ESP8266 with DHT11/21/22 JavaScript Support

Expose Custom JavaScript Global Methods and Objects

Note: the complete source code for all the examples discussed in this section is available on our GitHub project page. You can also download the code using the links from this article, however, it may be outdated after some time, so we strongly recommend our GitHub project page instead.

Some components, such as DHT22 / AM2302, temperature and humidity sensor, but not only, are harder to be read directly from the JavaScript code with the Mongoose-IoT firmware. This happens because the MCU is simply not fast enough for the JavaScript interpreter, so we can't deal with the very small pulses (under 20μs) we need to measure on the code, for being able to communicate with such components. The alternative and better approach is to write custom C/C++ code as part of the Mongoose-IoT firmware, and expose some objects and methods to JavaScript, thus being executed by the native firmware code, which is so much faster.

First we define a flag which allows to enable of disable the DHTxx library, so in case that for a project you don't need such a sensor, is possible to exclude this code from the firmware simply by using a flag. Notice that the firmware needs to be compiled/rebuild after adding or dropping the parameter. The following C/C++ code is part of the fw/platforms/esp8266/user/v7_esp_features.h file:

#ifndef CS_FW_PLATFORMS_ESP8266_USER_V7_ESP_FEATURES_H_
  #define CS_FW_PLATFORMS_ESP8266_USER_V7_ESP_FEATURES_H_
  #define V7_ESP_ENABLE__DHT
#endif

Note: only the marked code line is new (added by us), the rest of the code already exists as part of the fw/platforms/esp8266/user/v7_esp_features.h file.

The next step is to modify the file fw/platforms/esp8266/user/v7_esp.c by considering the code shown below:

#include "fw/platforms/esp8266/user/dht.h"

#ifdef V7_ESP_ENABLE__DHT
  static enum v7_err DHT_read(struct v7 *v7, v7_val_t *result) {
    v7_val_t sensorTypeArg = v7_arg(v7, 0);
    v7_val_t pinArg = v7_arg(v7, 1);
  
    // validate the first parameter - the DHT sensor type (11, 21, or 22)
    if (!v7_is_number(sensorTypeArg) || 
        (v7_get_double(v7, sensorTypeArg) != 1 
        && v7_get_double(v7, sensorTypeArg) != 2 
        && v7_get_double(v7, sensorTypeArg) != 3)) 
      return v7_throwf(v7, "Error", "Parameter 1, must be one of Dht.TypeEL.DHTxx.");

    // validate the second parameter - the GPIO pin number
    if (!v7_is_number(pinArg)) 
      return v7_throwf(v7, "Error", "Parameter 2, must be a GPIO pin number.");

    uint8_t pin = v7_get_int(v7, pinArg);
    uint8_t sType = v7_get_int(v7, sensorTypeArg);
    double temperature = 0.0;
    double humidity = 0.0;
    const char* sTypeName = (sType == 1 ? "DHT11" : (sType == 2 ? "DHT21" : "DHT22"));

    // read the DHT sensor and check if the read was a successful
    if (!dhtRead(sType, pin, &temperature, &humidity)) {
      // error reading DHT sensor...normally this is a check sum error
      return v7_throwf(v7, "Error", "Failed to read the DHT sensor!");
    }
    
    // create the result JavaScript object and append the 
    // "type", "temperature" and "humidity" properties, as well as their values
    *result = v7_mk_object(v7);
    v7_set(v7, *result, "type", 4, v7_mk_string(v7, sTypeName, 5, 1));
    v7_set(v7, *result, "temperature", 11, v7_mk_number(v7, temperature));
    v7_set(v7, *result, "humidity", 8, v7_mk_number(v7, humidity));
    return V7_OK;
  };
#endif /* V7_ESP_ENABLE__DHT */

The DHT_read method is responsible to check the parameters provided to the JavaScript Dht.read method. Internally, the dhtRead method will be called - it is responsible for the communication with the sensor, as discussed further in this section. Finally, a JavaScript anonymous object representing the JavaScript Dht.read method response is created. It is stored in a pointer, the last parameter of the DHT_read method. Notice that the DHT_read method returns V7_OK or throws exceptions, depending on the case. Also notice that DHT_read is a name that we choose, so you are free to change it with whatever you find appropriate, but remember to change every reference in the code.

Further, in the same fw/platforms/esp8266/user/v7_esp.c file, we modify the init_v7 method code as shown below:

void init_v7( void *stack_base) {
  // this code is compiled and becomes part of the firmware, only if the 
  // V7_ESP_ENABLE__DHT flag is used
  #ifdef V7_ESP_ENABLE__DHT
    v7_val_t dht = v7_mk_object(v7);
    v7_val_t typeEL = v7_mk_object(v7);
    // create the Dht global object, accessible in JS code
    v7_set(v7, v7_get_global(v7), "Dht", 3, dht);
    // add the read method to the DHT JS object
    v7_set_method(v7, dht, "read", DHT_read);
    // define the Dht.TypeEL enumeration property
    v7_def(v7, dht, "TypeEL", 6, 
      (V7_DESC_WRITABLE(0) | V7_DESC_ENUMERABLE(1)), typeEL);
    // create the Dht.TypeEL.DHT11 enumeration literal 
    // {enumerable: true, writable: false}
    v7_def(v7, typeEL, "DHT11", 5, 
      (V7_DESC_WRITABLE(0) | V7_DESC_ENUMERABLE(1)), v7_mk_number(v7, 1));
    // create the Dht.TypeEL.DHT21 enumeration literal 
    // {enumerable: true, writable: false}
    v7_def(v7, typeEL, "DHT21", 5, 
      (V7_DESC_WRITABLE(0) | V7_DESC_ENUMERABLE(1)), v7_mk_number(v7, 2));
    // create the Dht.TypeEL.DHT22 enumeration literal 
    // {enumerable: true, writable: false}
    v7_def(v7, typeEL, "DHT22", 5, 
      (V7_DESC_WRITABLE(0) | V7_DESC_ENUMERABLE(1)), v7_mk_number(v7, 3));
  #endif /* V7_ESP_ENABLE__DHT */
}

The purpose of this code is to create the Dht JavaScript object (accessible from the JavaScript code running on the ESP module), create the Dht.TypeEL JavaScript "enumeration" (well, emulating an enumeration) and to expose the Dht.read method, so we are able to read the DHT sensor from a JavaScript program.

Notice that we can create objects and object properties for the exposed JavaScript interface, in a similar manner as we do in standard JavaScript code with the help of Object.defineProperty and Object.defineProperties, thus we can make a property read-only, enumerable and provide an initial value to it if required. Datatypes values are obtained by calling the corresponding v7_mk_xxx method, where xxx can be null, object, number or string depending on the case.

It is also important to know that when we use the v7_def and v7_set methods, their 4th parameter is a positive integer, representing the number of characters of the name of the property or method that is created. Failing to set this value correctly, results in the property or method not being recognized in the JavaScript code!

Note: the init_v7 method contains additional code, which should be kept unchanged. In this tutorial only show the new code, required for our custom functionality, but the existing code must not be changed, otherwise the resulting firmware may not work as expected.

Now, we need to write the a C/C++ header file that exposes the method(s) meant to be used by the Mongoose-IoT firmware for the communication with the DHTxx sensor. We create the file fw/platforms/esp8266/user/dht.h that defines the signature of the dhtRead method:

#ifndef DHT_LIBRARY
  #define DHT_LIBRARY
  #include "v7_esp_features.h"

  #ifdef V7_ESP_ENABLE__DHT
   bool dhtRead(uint8_t sensorType, uint8_t pin, double* temperature, double* humidity);
  #endif
#endif

Notice that this header file was already used in the fw/platforms/esp8266/user/v7_esp.c code. Finally, we need to add the fw/platforms/esp8266/user/dht.c file, where we put the code that allows us to communicate with any of the the DHT11/21/22 sensors, for getting temperature and humidity readings:

#include <osapi.h>
#include "v7/v7.h"
#include "common/platforms/esp8266/esp_missing_includes.h"
#include "fw/platforms/esp8266/user/v7_esp_features.h"
#include "fw/platforms/esp8266/user/util.h"
#include "fw/platforms/esp8266/user/esp_gpio.h"

#ifdef V7_ESP_ENABLE__DHT
  static uint16_t waitLHCycle(uint8_t pin, uint32_t* maxCycles) {
    // wait until the pin goes from a digital LOW state 
    // to a digital HIGH state, or until the timeout occurs
    // NOTE: this is a helper method for dhtReadByte, to avoid repetitive code
  };
  static uint8_t dhtReadByte(uint8_t pin, uint32_t* maxCycles) {
    // read one byte (8 bits) of data from the DHTxx sensor
    // by using the sensor datasheet which explains what means a bit 1 and a bit 0
  };
  bool dhtRead(uint8_t sensorType, uint8_t pin, double* temperature, double* humidity) {
    // 1) read the 5 bytes of data from the DHTxx sensor;
    // 2) perform a check sum test for data integrity (the 5th byte is the check sum one);
    // 3) decode the 4 bytes of data and transform them to temperature and humidity values
  };
#endif

See the fw/platforms/esp8266/user/dht.c full source code on GitHub or download the full source code archive using the link at the top of this tutorial page.

Lets have a look at the interesting parts only, mainly how to control GPIO pins. Before being able to interact with a GPIO pin, we need to set the pin either for read of write mode, with the help of mg_gpio_set_mode method. It accepts three parameters: 1) the GPIO pin number; (e.g., 5 for GPIO5) 2) the mode, which is one of {GPIO_MODE_INOUT = 0, GPIO_MODE_INPUT = 1, GPIO_MODE_OUTPUT = 2}; 3) GPIO pull type, one of {GPIO_PULL_FLOAT = 0, GPIO_PULL_PULLUP = 1, GPIO_PULL_PULLDOWN = 2}, specifying if the GPIO pin is internally pulled up, down or let floating. The following example makes sets the GPIO5 pin as a digital output and GPIO4 as pulled down digital input:

mg_gpio_set_mode( 5, GPIO_MODE_OUTPUT, GPIO_PULL_FLOAT);
mg_gpio_set_mode( 4, GPIO_MODE_INPUT, GPIO_PULL_DOWN);

Reading the state of a digital pin that was set as digital input is made by using read_gpio_pin method, which returns GPIO_LEVEL_ERR (GPIO_LEVEL_ERR = -1) in case of error, GPIO_LEVEL_LOW (GPIO_LEVEL_LOW = 0) if a LOW status was read and GPIO_LEVEL_HIGH (GPIO_LEVEL_HIGH = 1) if a HIGH state was read. To set the status of a GPIO that was set as output implies to use the set_gpio method, which takes two parameters: 1) the GPIO pin number (e.g., 5 for GPIO5); 2) the state to set the pin to, one of {GPIO_LEVEL_LOW = 0, GPIO_LEVEL_HIGH = 1}. For example, if we like to wait for a HIGH signal on GPIO4 pin (set as digital input in the above example) and write a HIGH state on GPIO5 (set as digital output in the above example) afterwards, we'll use:


while( read_gpio_pin( 5) == GPIO_LEVEL_LOW);
set_gpio( 4, GPIO_LEVEL_HIGH);

Note: the following two header files are required for getting the above described GPIO operations: fw/platforms/esp8266/user/util.h and fw/platforms/esp8266/user/esp_gpio.h.

To make this new feature available on your ESP module, you'll need to compile and build the source code, then flash the firmware, as shown in Section: Build the Mongoose-IoT Firmware on a Raspberry Pi.

After uploading the new firmware, test the DHT functionality by using the following JavaScript code in the MFT Console, or as part of the app.js file:

Dht.read( Dht.TypeEL.DHT11, 5);

Note: if is the case, replace Dht.TypeEL.DHT11 with Dht.TypeEL.DHT21 or Dht.TypeEL.DHT22, depending on the used DHT sensor type, and also replace 5 (the second parameter) with the corresponding GPIO number, to which you have connected the data pin of the DHT sensor.

Download the code

The ESP8266's Big Brother: ESP32

The ESP8266 module got lately a big brother: the new ESP32 module. It is more powerful, but also comes with new features, such as builtin Bluetooth 4.2. In Figure 13 we can see the official ESP32 modules, also named WROOM-32. The following table provides the main differences of ESP32 by comparison with ESP8266.

Feature / Component	ESP8266	ESP32
MCU	Xtensa Single-Core 32-bit L106, 80MHz	>Xtensa Dual-Core 32-bit LX6, 160MHz
RAM	160KB	512KB
FLASH	up to 16MB SPI Flash	up to 16MB SPI Flash
GPIOs	17	36
SPI/I2C/I2S/UART/CAN	2/1/2/2/0	4/2/2/2/1
ADC	1 x 10bits	1 x 12bits
WiFi	b/g/n, HT20	b/g/n, HT40
Bluetooth	-	v4.2
Builtin sensors	-	temperature, touch
Working conditions	-40°C - 125°C	-40°C - 125°C
Approximate price	3-10 EUR, including shipping to EU	10-22 EUR, including shipping to EU

Figure 13: WROOM-32, the Official ESP32 Module.

Unfortunately, at the moment of writing this tutorial, it is not easy to buy the ESP32 module, since most of the online sources (the vast majority from Asia) report the module as "out of stock". However, we strongly believe that the situation will change soon, and the ESP32 may take the place of ESP8266 modules in new projects, or as improvements of the old projects that requires WiFi or Bluetooth connection and MCU on a single small and cheap module.

Some Points of Attention

The ESP8266 module represents the brain of your projects, but it requires that you take some precautions to keep it safe and be sure that it runs as supposed:

Most of the ESP8266 modules are powered by 3.3V, thus using 5V or anything more than 3.6V may and will damage your module! Some of the ESP8266 modules, such as the NodeMCU or WeMOS, discussed in this article, allows to power the module board (but not directly the ESP8266 MCU!) by using a USB connector (mini or micro USB ones), thus using 5V (or up to 10V for WeMOS D1 Mini), while a builtin voltage regulator is responsible for converting this down to 3.3V as required by the MCU.
No matter the input voltage accepted by an ESP8266 module (usually a direct 3.3V input or 5V via USB connector), in most cases the GPIOs pins are tolerant to ONL 3.3V or less positive voltage, meaning that you should never ever provide more than 3.3V nor a negative voltage to any of the GPIO pins.
The ESP8266 module exposes one ADC pin (expandable by using multiplexing or specialized ICs), allowing to measure analog voltages in the range 0-1V. Do NOT provide more than 1V or a negative voltage to this pin. If more than 1V must be measured, then use a voltage divider circuit or an external ADC IC or module (e.g., ADS1015 12-Bit ADC - 4 Channel) capable to communicate via I2C, SPI or UART. However, some modules, such as WeMOS D1 Mini allows 0-3.3V as input for the ADC pin, since it uses a builtin voltage divider circuit.

mdiaconescu's blog

Seeeduino XIAO - A Tiny Arduino Zero Variation

Another Arduino Compatible Board?

Technical Description and Features

Benchmark Test

The Power Consumption

Get Started with the XIAO board and the Arduino IDE

Some Final toughts

What's next?

Category:

PRODINo: Home Automation with ESP8266 based WiFi Control

What is PRODINo WiFi-ESP?

Hardware Specifications

Programming the PRODINo

Use Arduino IDE to Program a PRODINo Module

Controlling the Relays

Reading the Inputs

More Examples for PRODINo

Conclusions

Project Ideas

Category:

JavaScript-Based IoT/WoT Development with the ESP8266 and the Raspberry Pi

Meet the ESP8266

Choosing the Appropriate ESP8266 Module for a Project

Standalone User Friendly ESP8266 based Modules

Some Words Before Getting Started...

Flashing the Standard Mongoose-IoT Firmware by Using an Raspberry Pi

Build the Mongoose Flashing Tool Application

First JavaScript Tests on ESP8266

Build and Flash Mongoose-IoT ESP8266 Firmware by Using a Raspberry Pi Board

Expose Custom JavaScript Global Methods and Objects

The ESP8266's Big Brother: ESP32

Some Points of Attention

Category: