While using RIOTOUS itself is incredibly easy and simple some users may still find configuring RIOTOUS a tad tricky. Despite trying to keep the framework as simple as possible the user manual is still a fair number of pages so if you find reading the manual daunting then this Quick Start Guide is just for you!


Step 1 – Pick a device

Firstly, pick a device that will be the centre of your IoT project. For inexpereienced users we recommend that you pick up a RIOTOUS development board which is based around the PIC16F1516 as well as a PicKit3 programmer (a clone will suffice here). If you are insistent on making your own circuit from scratch then pick one of the following micro-controllers (this list will grow with time).

  • RIOTOUS Development Board
  • PIC16F1516 (Recommended for its low price and high functionality)
  • PIC16F1825 (Dead cheap and sits in a tiny DIP 14 package)
  • PIC18F25K22 (More advanced that the PIC16F1516)
  • PIC18F45K22 (Large DIP 40 packaging offering a lot of power and I/O)

Also make sure to get the appropriate programmer


Step 2 – Get an ESP-01 Module

RIOTOUS relies on the ESP8266 UART to Wi-Fi controller so getting one of these is imperative. The most user friendly module is the ESp-01 but chances are it wont have the correct firmware version. This means that you will either need to get a pre-programmed ESP-01 or flash the firmware yourself.


Step 3 – Make your circuit

If you get a RIOTOUS development board then there is no need to build anything to learn how to use RIOTOUS. If instead you wish to build a custom IoT project then you will need to make it at this point. The ESP-01 connects to the micro-controllers UART port and both the micro-controller and the ESP-01 need a 3.3V power source (see the schematic below).



Step 4 – Download an empty project

With your circuit made download one of the empty projects below. These empty projects contain all the code and configuration bits to get your device to run RIOTOUS correctly.

  • RIOTOUS Development Board – MPLABX
  • PIC16F1516 – MPLABX
  • PIC16F1825 – MPLABX
  • PIC18F25K22 – MPLABX
  • PIC18F45K22 – MPLABX


Step 5 – Download the basic server and run it

RIOTOUS servers are available in two main languages; VB.net and Python. The VB.net version allows for user friendly GUI applications using windows forms but will only be executable on Windows machines. The Python version will run on any device that can run Python 3 but coding GUI applications is somewhat more tricky. For beginners it is recommended to use the pre-made Windows VB.net server and should run out of the box! This server will simply display information on a log window and can be used to send data to connected clients.

  • Basic VB.net powered RIOTOUS server (run Server.exe)
  • Basic Python 3 RIOTOUS server (execute Main.py)


Step 6 – Program and Run!

Open the IDE associated with the empty project (for example, MPLAB X for the development board), and then open main.c. In this file you will need to make several changes:

  • while(riotous_connectToWiFi(“SSID”,”PASS”) != 1);
    • Change SSID to your Wi-Fi SSID and PASS to your Wi-Fi password
  • while(!riotous_connectToRiotServer(“IP”, “333”);
    • Change IP to the IP address of your server (your computers local IP address)

With the project configured compile and execute the project. If all goes to plan your RIOTOUS project should now automatically connect to the Wi-Fi network, connect to your server, and be ready for IoT applications! The default code in the while loop will send the text “Hello World!” to the server and you should see this in the servers log window.


What’s Next?

At this point you should learn how to create a custom server so you can display graphs, store readings, and send commands to RIOTOUS clients. Here are some simple project ideas that you can try out!

  • IoT controlled LED
  • Temperature and humidity logger
  • IoT controlled security system
  • IoT controlled RC car / plane