OpenWRT router + Ubidots = Real-time data monitoring

In my projects I needed a tool to monitor data in real time, the data is captured by a microcontroller and uploaded to the web using a wireless router. Initially I was trying to use yeelink since it is in chinese langguage and yet I'm a Malaysian Chinese.

One month ago, I have tried with Ubidots, there were a few things that caught my eye.

Ubidots is a cloud service to store and analyze sensor data in real-time, it is free with 30,000 dots/month data-points usage, features as follow:

1. Push Data from Internet-Enabled Device
2. Display sensor data through widgets without any coding required.
3. Data are updated in real-time and no need to refresh the browser
4. Trigger alerts when a sensor value hits a threshold.
5. Powerful and flexible API

There are number of well-documented tutorials and sample projects provided by Ubidots, however there is no simple way to upload data by using an OpenWRT wireless router. After spend some time studying on the TP-Link TL-Wr103ND V2 project, this "Ubidots-Lua" is developed.

Ubidots-Lua is written in Lua, it allows you to post data to or get data from Ubidots with minimum coding required. Ubidots-Lua should run on any OpenWRT wireless router, and it is able to execute from console, Shell script or as a Lua function call.

Prerequisite

• Router flashed with OpenWRT firmware. I'm tested with TP-Link TL-Wr103ND V2 & TL-WR3020 V1 wireless router, the routers is flashed with OpenWRT Barrier Breaker 14.07
• An Ubidots account

Installing curl

An easy way to access Ubidots is to use curl commands. curl is a tool to transfer data from or to a server, it offers proxy support, user authentication, FTP uploading, HTTP posting and more.

• The router need to have internet connection in order to perform the package installation.
• SSH to router via PuTTY.
• Enter the following commands via its console.

opkg updateopkg install curl

Installing Ubidots-lua

There is no need to run a specific installation program, just put the file to your wireless router, giving execution permission and run it.

• Download Ubidots-lua to your computer, it is available on github, alternatively it can download from my personal website.
• Extract the zip file and transfer the file (ubidots.lua) to wireless router (it must reside in the \usr\lib\lua direcotry). I'm using WinSCP for tranferring, see below:
  
• SSH to router via PuTTY, set the execute permissions to allow script execution
  chmod 755 \usr\lib\lua\ubidots
• Alternatively you can set the permissions using WinSCP, right click the ubidots.lua filename and click on properties to popup the properties windows, change the permission as shown in figure below
  

Getting your Ubidots API key

You must know your API key, the API key grant access to your Ubidots resources.

• Log in to Ubidots
• On the screen top right corner, click on your user name and select My Profile
• Click on API keys to view your API key
  
• Write down your API key, which are then used in every API request.

Create Ubidots data source and variable

You must setup the Ubidots data source and variable before you can upload data to your Ubidots. A data source represents a device or a virtual source, while a variable is a series of data containing values that change over time.

• Log in to Ubidots
• Click on Sources tab
• Click on Add Data Source. 
• Select Type of Data Source, I'm select Generic as shown in figure below
  
• Give a name to the data source and click on Create button
  
• Now we need to add Variable to the newly created Data source. 
• Click on the data source you have just created
• Click on Add Variable
• Give a name to the new variable and click on Create button. 
  
• Follow picture below to retrieve your Variable ID (Device ID)
  

Create a Widget

Widgets are custom visualizations of your data that help you extract the value of it. Example, you can display your sensor data through widgets like line charts, gauges, multi-line charts, scatter plots or maps.

• Click on Add Widget icon from Dashboard as shown in figure below
  

• Select a desired widget as shown in figure below. I'm select Metric Widget in order to displays the last value of a variable
  

•  Now choose a Data source and  Variable
• Click Finish to complete and return to Dashboard
  
•  Follow picture below to get the URL for the variable

• You Use this URL to share a public version of your widget
  

When you post a value to this variable, you should able to read its value from this URL. It is so simple and yet no coding required.

Execute ubidots-Lua from command-line interpreter

It is time to post your data to Ubidots. With only a single line command, you should able to post data to your Ubidots.

• SSH to OpenWRT via PuTTY and running the following commands in the terminal. This will post a value of 100 to your Ubidots Variable

root@OpenWrt:~# /usr/lib/lua/ubidots.lua -post api_key deviceID 100

You must replace api_key and deviceID with your API key and Ubidots Variable ID respectively. Upon posting this data to your Ubidots, its data is available in the widget URL immediately.

You may want to retrieve your data from a Ubidots Variable ID, but this is not often necessary since using a Ubidots widget is much more simple and flexible.

• Retrieve last value from Ubidots Variable

root@OpenWrt:~# /usr/lib/lua/ubidots.lua -get api_key deviceID

• Retrieve all data from Ubidots Variable

root@OpenWrt:~# /usr/lib/lua/ubidots.lua -get api_key deviceID all

• Retrieve last value from Ubidots Variable and save it to router /tmp/data.txt directory

root@OpenWrt:~# /usr/lib/lua/ubidots.lua -get api_key deviceID last data.txt

Calling Ubidots-Lua function from lua

Here is a lua script demonstrate how to use the Ubidots-Lua as a function call. You need only call get_token() once.#!/usr/bin/lua

#!/usr/bin/lua

require "ubidots" -- do not put extension (.lua) after the filename

local api_key= "your api key here"
local deviceID="your deviceID here"
local value = 100 -- post this value

--obtain a token based on a given api_key
get_token(api_key)
print("Token: " .. my_token)

--post data to Ubidots
post_value(deviceID, value)

--retrieve last value from Ubidots
get_value(deviceID)
print(my_data)

--retrieve all data from Ubidots
get_value(deviceID, "all")
print(my_data)

--retrieve last value from Ubidots & save to a file
get_value(deviceID, "", "data.txt")

--data is saved in router /tmp/data.txt

Ruuning Ubidots-Lua from Ash

OpenWrt comes with Ash shell.

#!/bin/sh 

api_key="your api key here"
deviceID="your deviceID here"
value=10 #post this value

#obtain a token
my_token=`/usr/lib/lua/ubidots.lua -token $api_key)`
echo "Token: "$my_token

#post data to Ubidots
/usr/lib/lua/ubidots.lua "-post" $api_key $deviceID $value

#retrive last value from Ubidots
my_data=`/usr/lib/lua/ubidots.lua "-get" $api_key $deviceID`
echo $my_data

#retrieve all value from Ubidots
my_data=`/usr/lib/lua/ubidots.lua "-get" $api_key $deviceID "all"`
echo $my_data

#retrieve last value from Ubidots & save to router \tmp\data1.txt 
/usr/lib/lua/ubidots.lua "-get" $api_key $deviceID "" "data1.txt"

#retrieve all data from Ubidots & save to router \tmp\data2.txt 
/usr/lib/lua/ubidots.lua "-get" $api_key $deviceID "all" "data2.txt"

Running Ubidots-Lua from Bash shell

I'm not able to install Bash onto my TL-MR3020 wireless router, the limited 4MB flash router have not enough space to installing Bash. You should get a wireless router with at least 8MB flash memory, for example: Nexx WT3020, GL.iNet, TL-WR1043ND.

Enter the following command to installing Bash shell to your router.

opkg updateopkg install bash

Here is a Bash example:

#!/bin/bash

api_key="your api key here"
deviceID="your deviceID here"
value=10 #post this value

#obtain a token
my_token=$(bash -c "/usr/lib/lua/ubidots.lua -token "$api_key)
echo "Token: "$my_token

#post data to Ubidots
bash -c "/usr/lib/lua/ubidots.lua -post "$api_key" "$deviceID" "$value

#retrieve last value from Ubidots
my_data=$(bash -c "/usr/lib/lua/ubidots.lua -get "$api_key" "$deviceID)
echo $my_data

#retrieve all data from Ubidots
my_data=$(bash -c "/usr/lib/lua/ubidots.lua -get "$api_key" "$deviceID" all")
echo $my_data

#retrieve last value from Ubidots & save to router /tmp/data.txt
my_data=$(bash -c "/usr/lib/lua/ubidots.lua -get "$api_key" "$deviceID" all data.txt")