Requirements
Goal
clouddata.dustcloud.org allows a customer to publish sensor data to the Internet less than 5 min after having opened a SmartMesh IP starter kit
This translates into the following requirements:
- clouddata.dustcloud.org must be able to receive sensor data, and store data as timelines for 12 hours.
- clouddata.dustcloud.org must offer a web interface to visualize the data.
Architecture
The solution consists of the PublishToWeb
SmartMesh SDK program and the clouddata.dustcloud.org server.
PublishToWeb
Smartmesh SDK application
This application is part of the default SmartMesh SDK, and runs on the user's computer. It:
- connects to the SmartMesh IP Manager
- subscribes to data notifications
- forwards all the OAP temperature data readings produced by the SmartMesh IP motes to clouddata.dustcloud.org.
clouddata.dusctloud.org server
The clouddata.dusctloud.org server is built on Ubuntu Server. It has the following internal architecture:
- the iptables firewall filters out all external traffic not going to TCP port 80
- the NGINX load balancer redirects:
- HTTP requests to http://clouddata.dustcloud.org/api/v1 to the
clouddata_server
script running on TCP port 8080 - HTTP requests to http://clouddata.dustcloud.org/ to the grafana frontend running on TCP port 3000
- HTTP requests to http://clouddata.dustcloud.org/api/v1 to the
- the
clouddata_server
script is part of the SmartMesh SDK. It receives data from the PublishToWeb.py application and inserts it into the database. - the influxdb database efficiently stores time series data. In this example, the database is configured to automatically drop data after 12 hours.
- the grafana data visualization tools offer a clean dashboard for visualizing the data
Installation Steps
Vagrant setup files for the step-by-step guide below are maintained at https://github.com/dustcloud/clouddata-server.
Ubuntu
At the time of writing, we have installed Ubuntu Server 16.04 LTS.
If you are installing the server on a virtual machine using VirtualBox for testing purposes:
- configure two network adapters:
- Adapter 1 as "NAT" (this allows your VM to access the web)
- Adaptor 2 as "Host-only Adapter" (this allows your host OS to access the web server running your VM)
after booting your VM, edit
/etc/network/interfaces
to add the last lines corresponding to the second network interfacerestart the networking services:
Once installed, log into the server.
Update
The commands above update your entire OS. This can take 10-15min.
SSH
Install the OpenSSH server:
Add your public key to the server:
Edit /etc/ssh/sshd_config
so it contains the following (un-commented) lines:
Restart the SSH server:
influxdb
install database
Install and start InfluxDB automatically:
You should see the InfluxDB admin panel at http://192.168.56.101:8083/.
By default, the HTTP API of InfluxDB runs on TCP port 8086.
create database
Use the influx
client to create a database "grafana" and associate a retention policy so datapoints are automatically deleted after 12 hours:
Recent versions of the influxdb
package include the command-line client. If your distribution has an older package, you may need to install the client separately.
grafana
install
The following commands install grafana, start it, and ensure it also starts on the next boot:
You should now be able to see the Grafana front end running at http://192.168.56.101:3000/.
We are not using authentication between Grafana and InfluxDB, but you still have to provide a username/password in the "InfluxDB Details" section below.
change admin username and password
Connect to the Grafana front end with username "admin" and password "admin". Though the profile page, change both the username and password associated with the Grafana administrator.
connect to database
Through the admin interface, add InfluxDB as a data source. From the drop down menu in the upper left, choose Data Sources and click on Add data source.
create dashboard
Through the admin interface, create a new dashboard named Temperature. From the drop down menu in the upper left, select Dashboards → New. The first row is already created, indicated by the vertical line on the left edge. Hovering over that indicator will reveal a menu for editing. Select Add Panel → Graph to create a graph of the temperature data. Under Metrics, select Toggle edit mode under the drop down menu (on the right next to the eye icon) to change the input mode so you can paste in the following query:
To verify everything works, on the Admin interface of InfluxDB (http://192.168.56.101:8083/), select the "grafana" database, click "Write Data" and enter:
enable anonymous access
Change the /etc/grafana/grafana.ini
file so it contains the following lines:
set as default dashboard
- log into Grafana as admin
- star the dashboard you create
- in the dropdown menu, edit the setting for the default organization, and set the dashboard as default home dashboard
clouddata_server
script
install Python
install clouddata_server
script
You can download the cloudata_server.py
script as part of the SmartMesh SDK. You will find it in the app/PublishToWeb/
directory.
Install the Python dependencies of the SmartMesh SDK:
run at startup
Install supervisor:
Create a new file for supervisor to manage the clouddata_server
process:
Include the following contents, where _USER_ is replaced with the current username:
Start the supervisor daemon and configure the daemon to start when the system is booted:
NGINX
installation
nginx
starts automatically. Pointing your browser at http://192.168.56.101/ shows you the default interface:
configuration
We will use nginx
in proxy mode. The role is that it redirects per the table below:
url | point to |
---|---|
http://<ip_address>/api/v1/oap | http://<ip_address>:8080/oap |
http://<ip_address>/ | http://<ip_address>:3000/ |
Create file /etc/nginx/sites-available/clouddata_server
with the following contents:
Install the script:
Restart the server:
iptables
It is important you step through the iptables
instructions in the order they are written!
configure
Type the following commands in this order to configure iptables
(the firewall):
There lines have the following actions (respectively):
- [line 1] all ports are open for communication internal to the server (needed for the communication between grafana, influxdb, and
clouddata_server
) - [line 2] accept incoming SSH traffic (needed for you to configure the server later on)
- [line 3] accept incoming HTTP traffic (needed for a client to push sensor data and see the grafana web interface)
- [lines 4,5,6,7] allow outgoing DNS queries
- [lines 8,9] allow outgoing HTTP traffic (needed for example to use
apt-get
) - [lines 10,11] allow incoming ping requests (needed so you can ping your server)
- [lines 12,13] allow outgoing ping requests (needed so from the server you can ping other hosts to verify connectivity)
- [line 14] drop all other incoming traffic
verify
Type the following command to verify all rules are active:
run at boot
By default, your iptables
rules will disappear at reboot. The iptables-persistent
packages allows them to be applied at each reboot.
Install the iptables-persistent
package:
At installation, make sure to click "yes" to save the current IPv4 and IPv6 rules
Testing
Once you have the server running, you can test it by using the following scripts:
PublishRandom.py
publishes a random temperature coming from a (fake) random MAC address
publishes a temperature published through OAP by a real nodePublishToWeb
.py
Make sure to reboot reboot the server and verify everything starts up as expected. You should be able to ping the server, but not access the grafana website on port 3000, or the influxdb admin interface on port 8083.