Testing a Custom IoT Framework by Controlling an LED: RIOT (RealTime Internet of Things)

February 08, 2017 by Robin Mitchell

Using a custom framework (RIOT) to control an LED with a networked computer.

RIOT, Realtime Internet of Things, is a custom framework designed to make using the ESP8266 with microcontrollers easy. In this project, we will demonstrate the simplicity of RIOT by controlling an LED with a networked computer.

Brief Introduction to RIOT

RIOT (Realtime Internet of Things) is a free software package (non-commercial) I created that makes using the ESP8266 with microcontrollers very simple.

The ESP8266 module is a very brilliant and underestimated Wi-Fi module that can turn any serial port (be it on a microcontroller or an old Z80 computer) into an internet-enabled device. However, the ESP8266 AT commands can be particularly tricky and, if not coded correctly, can result in lockups.

The RIOT framework provides several functions that make using the ESP8266 a breeze. Firstly, it contains an interpreter for data going in and out of the ESP8266. Secondly, it provides simple and easy-to-use functions to get a microcontroller Wi-Fi enabled in almost no time. Thirdly, the code utilizes ROM memory as much as possible so that very-small-RAM micros (256 bytes of RAM, for example) can still be internet-enabled. RIOT also has a server package that is written in (for simplicity reasons) which cannot be easier to use in a project.

In this project, we will look at how to use RIOT with any PIC18 device (this project will specifically use a PIC18F25K20) and use a computer to turn an LED on and off.

Note: RIOT is now called RIOTOUS and can be found at


For RIOT to function correctly on the client side, a specific AT and SDK version must be used. The AT version must be and the SDK version must be 1.5.4. Earlier versions have bugs when closing connections and later versions have either missing or buggy code.

To find the requirements of the RIOT client side framework, click here.

For compiling the project you will need

To find out how to re-program the firmware in an ESP8266:

The Schematic

Client schematic. Click to enlarge


See how simple RIOT is? Well, you won’t yet because this is just the hardware layer! However, it does demonstrate how amazingly simple the hardware requirements for the ESP8266 ESP01 module are!

Firstly, the whole circuit runs on 3.3V, which is very easy to do with the AMS1117 regulator. The SOT-223 package can be soldered on 2.54mm pitch stripboard with success so a simple power regulation circuit can be constructed on a separate board.

Secondly, three LEDs are used: D1 indicates if there is a Wi-Fi connection, D2 indicates if there is an active server connection, and D3 is the LED that we will control via the networked computer.

Thirdly, you may have noticed that we will be running off the internal oscillator, which is not highly accurate and therefore not an optimal choice for UART communication. However, the error percentage in the UART is very low and therefore can be ignored for our simple circuit (in practice, no problems have arisen yet due to a UART baud-rate mismatch).

Last is the PicKit3 programming connector. This part is up to you; you can use any PIC programmer that you see fit. Just remember to connect it up properly.

Creating the RIOT Server

With the circuit built and ready for programming, we will get a simple RIOT server ready. The RIOT server is specifically designed to make communicating between devices and computers as simple as possible. One feature that is slightly strange about a RIOT server is that it does not communicate using an IP address on one port. Instead, it assigns a port for a device to connect through.

For a RIOT device to connect to a RIOT server, it must first ask to connect on some global port (by default, 333). The RIOT server will immediately respond with a port number for the device to communicate on and close the connection. At this point, the RIOT device will then reconnect with the new port number and all communication is done through the port. Note that this only applies when connecting to a RIOT server. In other words, the RIOT device can still connect to other servers and websites but the RIOT server provides easy functions and a simple messaging protocol that is all handled by the RIOT framework.When you send messages to a RIOT server, the RIOT software will automatically add needed bits to that message for a complete transaction.

One other feature of RIOT frameworks is the keepalive probing. Every so often, the server will probe the device to see if the device is still connected and, if no response is made after a few seconds, the server will close the connection and free the port. Again, the software automatically handles this if using a RIOT framework. Any messages sent to the RIOT server will reset the watchdog probing timer.

To get this to work, you can either use the pre-made executable (which requires the .net framework) or compile the VB project, yourself. The executable is good for testing purposes, but otherwise it is better to make your own server (using the VB RIOT classes).

Before you can use the RIOT server, there is one piece of code that needs changing in the Server.vb file. Line 114 needs to be changed so that the IP address is your local IP address. The incorrect IP address will cause the program to crash (remember, RIOT is still in its early days so give it time to grow!).


Private serverAddress As IPAddress = IPAddress.Parse("")


With that changed, its time to look at the code for the server. There are three buttons, a text box, and a timer. The buttons turn the server on, turn the LED on, and turn the LED off. The text box is used to see how many current connections there are. The timer is a ticker that allows us to perform checks on the server every so often (here, 10 times a second).

One other thing to watch out for is the client ID. Remember to set the unique ID of the client device (in the client-side software) to 0 so that we can access the client by ID instead of by port.

The first task to do is create an instance of the server and start it. This is done using this section of code that is self-explanatory:



At this point, you can see how RIOT tries to use functions that are as descriptive as possible. Note that the timer is also started here! For a server that needs to be reliable, try and catches—so that exceptions don’t stop the program—may be a better approach.

The second task is to display how many active connections there are. This is not vital to the server’s operation—it just lets us know visually if the RIOT device connects properly to the server!



The third task is to turn the LED on and off. This is done by sending the string “LEDON” to the RIOT Client to turn the LED on or sending “LEDOFF” to turn the LED off. Note that the string needs to be converted to an array of bytes before being sent.



RIOT Client-Side Code

The code for the RIOT client side is written in C using MPLAB IDE 8.92. There are several reasons for using this older IDE and even older C18 compiler. The bottom line is that I was not impressed with the newer version (MPLAB X IDE version 3.40). I found the newer IDE to be slower, and I would repeatedly get disconnections and failed reads. I had much better experiences with the older MPLAB IDE 8.92.

To get RIOT to work on the PIC18 chip, there are a few requirements:

  • The UART must be configured to work with RIOT.
  • An interrupt for UART reception is needed so that, when a byte is received, RIOT will update itself.
  • Initialization code is needed. Please realize that all the code needed can be found in the project files but only the core code involved with RIOT will be discussed. Code such as oscillator configuration and port direction registers will not be shown or described.


Note: All resources for this project are available for free. You can use them instead of making the needed edits described below so long as you use the PIC18F25K20


Firstly, IoT_ClientFramework.c needs to have a few parts edited. The code below shows how the three functions uartSend(), uartInit(), and delay20ms() should look for this project to work correctly:



With the UART RIOT functions defined, the next step is to include an interrupt service routine that triggers upon a UART reception. When this happens, uartGet(uart byte) needs to be called before internet_update() so that RIOT takes in the byte and processes it.



Now that we have the interrupt routine coded (and interrupt-dependent registers configured correctly, as found in setup.h), it's time to start up RIOT!

The first function to call is internet_init(). This preps RIOT to flush variables and get it into a known state.

Once that is done, it's time to connect to a Wi-Fi network by calling the function internet_connectToWifi(“SSID”, “PASSWORD”). Obviously, you set the SSID and PASSWORD to your own network's credentials. This code (like many RIOT functions) will return either true (1) or false (0) to indicate if the request was successful. In the case of this code, the function call is placed inside a while loop so that the connection request is repeatedly made until RIOT successfully connects to the internet.



The next task is to connect to our server which is done by calling internet_connectToRIOTServer(“IP”, “PORT”). This function differs from internet_connectToServer(“IP”, “PORT”) because a RIOT server dynamically routes connections through unique ports and the RIOT server connection function will automatically reconnect to the server with the new port.

This function is placed in a while loop to ensure that RIOT keeps trying to connect until it finds the server and successfully connects. Once a server connection is made, we assign a unique ID to our device. While this is not important in our project, it is useful for sending data to and from clients by ID.

When devices connect to the RIOT server, they are placed in an array of objects at the lowest free slot. This means that a device could be placed anywhere in the array. The use of IDs means that if a device reconnects and is placed in a different location, the unchanged ID prevents messages going to the wrong client.

Remember, the server has two functions for sending data: one is to send data by position in the array (for example, send data to client 0, which is the first client that connected) and the second function is to send data by ID. Currently, the ID is an 8-bit number, giving 256 possibilities. In the future, however, this may change to be something akin to MAC addresses. The MAC address of the ESP8266 may even be implemented as the ID.

Since we use an ID number of 0 in the server, we must use the same ID number on our client. This is easily done with the function internet_setdeviceID(0).



The last piece of code is our while main loop that indefinitely loops. All that is needed to do is check for new data and, once new data is available, process it. In this case, new data is compared to const char buffers (strings) to see if the data stream is equal to “LEDON” and “LEDOFF”. Then, depending on the message, the LED (D3) is either turned off or on.




Schematic Reference





AMS1117 3.3V Regulator



ESP8266 ESP-01



1K Resistor

R2, R3, R4


5.6K Resistor




D1, D2, D3


100nF Capacitor

C1, C3, C4, C5


10uF Capacitor



22uF Capacitor C3 1


Breadboarding the circuit is fairly straightforward but the 3.3V regulator used here is not prototype-friendly. While there are 3.3V regulators available in through-hole packaging, the AMS1117 is dead cheap and the only 3.3V regulator available in my workshop (because I refuse to stock two types of components that do the same thing).

To convert the AMS1117 to a breadboard-friendly package, you can use a small piece of stripboard and a 3-pin header. Also remember to cut off the tab so that the copper strips do not make contact with the tab. 


Converting the AMS1117 for breadboard prototyping 


The finished project! 

Project in Action!

Here is a video showing the RIOT client connecting to the Wi-Fi network, connecting to the RIOT server, and then controlling the white LED using the server.


RIOT demonstrates how even low-end microcontrollers can be connected to the internet. While not demonstrated in this project, a test with RIOT on the PIC16F628 using the XC compiler was performed and was successful.

While RIOT is in its infancy, over time more features will be added and different implementations may become available so that more and more devices can run RIOT. The next project will involve the client sending data to the server in the form of a basic datalogger.


Give this project a try for yourself! Get the BOM.

  • liuqiblog February 15, 2017

    Could you let me know if this product ( the same as ESP8266 ? I also want to make one .

    Like. Reply
    • Robin Mitchell February 17, 2017
      It appears that this product is an ESP8266 module but you are better off getting a pre-programmed ESP8266 module with 1.5.4 SDK and AT
      Like. Reply
      • Shree Lakshmi August 15, 2017
        hi Robin, I wanted to know what motivated you to create this framework when there are so many exiting frameworks available. Any particular cause or source of reason why Riotous was built. Please let me know as I am studying to develop an application based on yours. Your response will help in greatly.Eagerly anticipating your response. Thanks
        Like. Reply