95-733 Internet of Things Tuesday, September 11, 2018
MQTT, Google Charts, Particle Photon Due Date : 11:59 PM, Tuesday, September 25, 2018
Project 2
=========
The internet of things (IoT) often collects real time data from sensors and
transmits these data to a service offering publish and subscribe capabilities. The service
is usually called a broker. The sensor acts as a publisher. The sensor has no idea who
its subscribers are. It simply transmits data to the broker. The subscriber subscribes
to messages from the broker and, in this way, is able to read data from the sensors.
The publish subscribe approach exemplifies loose coupling and provides for scalability.
Objectives
==========
One objective of this project is to learn to use an MQTT publish subscribe broker
named Mosquitto. MQTT is targeted at low power constrained devices. It will likely play an
important role in a mature IoT.
The second objective is to learn Google Charts. The internet of things will rely
heavily on real time visualization in the browser. Google Charts may play a significant
role in this area.
The third objective is to continue our work with the Particle Photon microcontroller.
Overview and setup
==================
This is a three part assignment. The first part asks that you develop a small
system using Javascript and an MQTT broker. The second part asks that you
build a small system using a Java program as a publisher to MQTT and a
Javascript program as a subscriber to messages coming from MQTT. The third
part asks that you create a simple application that will be deployed (flashed)
to a Particle Photon. This application will make good use of MQTT.
In Project 1, we used a whiteboard application from Oracle to build an
application that allowed us to collaborate in real time without polling. We leveraged
HTML WebSockets and wrote our own server side code that sent a message to all listeners.
In Parts 1 and 2 of this project, we will not write our own server side code. Instead,
we will use an open source MQTT broker called Mosquitto. Mosquitto can be downloaded
from here: http://mosquitto.org/download/.
Note: In the past, some students had trouble with Mosquito but had an easy time
downloading Hive MQ's MQTT broker. The instructions below
refer to my success in using Mosquito. Feel free to use whatever MQTT broker that
you are comfortable with. You may use the local Hive MQ (downloaded to your machine
or the remote version on the cloud.) Hive MQ's MQTT (both local and cloud) are
available from here: https://www.hivemq.com/try-out/
You can install Mosquitto on your MAC using brew. See http://brew.sh and then
use "brew install mosquitto". There are directions on the mosquitto web site for
Windows users.
When you run mosquitto, it will run with its default configuration. We need to change
its configuration to allow for WebSocket connections (we want to visit the server from
Javascript). To change the configuration of Mosquitto, we can modify the configuration
file found at /usr/local/etc/mosquitto/mosquitto.conf (on a MAC). My configuration file
contains these lines:
listener 1883
protocol mqtt
listener 9002
protocol websockets
My copy of mosquitto is located at /usr/local/sbin. If I change to that
directory, I can run mosquitto (picking up the configuration file) with the command
mosquitto -c /usr/local/etc/mosquitto/mosquitto.conf -v
Once you have Mosquitto running, we want to connect to the server from Javascript running
in a browser. We do not want to write the client side MQTT code ourselves. Even though we have
easy access to WebSockets, it would be far better to use an existing Javascript library
that provides a convenient API to MQTT. The implementation of the API will, of course,
use Websockets below the scenes.
In our web pages, we will include the Javascript library from Paho. It is called mqttws31.js.
There is a very nice getting started section at the following link. It has a simple example of a
Javascript client that will run in a web page:
https://eclipse.org/paho/clients/js/
The mqttws31.js Javascript library can be included in your HTML with this script:
There is a nice discussion here on MQTT.
https://www.ibm.com/support/knowledgecenter/SSFKSJ_9.0.0/com.ibm.mq.pro.doc/q002870_.htm
Part 1.
=======
Your task in Project 2 Part 1 is to:
1) 5 Points. Build a Netbeans project named Project2Basic with the code found here:
http://www.w3schools.com/jsref/tryit.asp?filename=tryjsref_onmousemove
Note that every time the mouse moves (within the box) an event is generated
and the x and y coordinates are displayed. It is required that you add your
own detailed comments to this code - explaining clearly how it works. The grader
will grade based on the quality of these comments.
2) 15 Points. Here we want to sense the mouse movements and pass them along to Mosquitto(MQTT).
Copy Project2Basic (along with your comments) to a new Netbeans project called
MouseTrackerPublisher. This will need to be modified so that every mouse movement
publishes the coordinates to Mosquitto. It must make good use of the Javascript library
mqttws31.js.
3) 15 Points. Create a new Netbeans project called MouseTrackerSubscriber. It too will make use of
mqttws31.js. MouseTrackerSubscriber will subscribe to events published to Mosquitto.
It will simply display the coordinates being received (there will be no box as is
shown in MouseTrackerPublisher).
Part 2.
=======
In Part 2, we will be communicating with Mosquitto in two ways. We will use Websockets from within
our Javascript code - running within a browser. And we will also use standard TCP sockets (and a client
library) from within a stand-alone Java program. In order to make this happen, we need to
ensure that the Mosquitto configuration includes the following four lines. You will need to
carefully use the appropriate ports within your code.
listener 1883
protocol mqtt
listener 9002
protocol websockets
For the Java client, we will be using the Eclipse Paho Java Client libraries.
This is very easy to do using Maven and Netbeans. In short, Maven is an opinionated build tool.
That is, it is based around the idea of "convention over configuration". There is a nice 15 minute
video here on using Maven on the Netbeans IDE: https://www.youtube.com/watch?v=mGmUH-SxFHA
The following URL has the repository definition and the dependency definition needed for your pom.xml.
It also has a very nice sample Java client that you may work from.
https://eclipse.org/paho/clients/java/
1) 5 Points. Build a Netbeans project named TemperatureSensorProject. This project will hold a stand alone
Java program named TemperatureSensor.java. Every 5 seconds, TemperatureSensor.java will generate a
random temperature (uniformly distributed) between the values of 0 and 100 degrees fahrenheit. If the
random temperature is between 0 and 45 degrees inclusive, TemperatureSensor.java sends the temperature
and a timestamp to the topic called "pittsburgh/temperature/coldTemps" on Mosquitto. If the temperature is
greater than 45 degrees but less than or equal to 80 degrees, TemperatureSensor.java sends the temperature
and a timestamp to the topic called "pittsburgh/temperature/niceTemps" on Mosquitto. If the temperature is greater
than 80 degrees then TemperatureSensor.java sends the temperature and a timestamp to
the topic called "pittsburgh/temperature/hotTemps" on Mosquitto.
2) 5 Points. Build a Netbeans web application that allows the user to subscribe to a particular topic
from Mosquitto. The user might be interested in "pittsburgh/temperature/coldTemps", "pittsburgh/temperature/niceTemps",
"pittsburgh/temperature/hotTemps", or all temperatures in Pittsburgh. Name the web application project TemperatureSubscriberProject.
This project will require the Javascript library mqttws31.js. To get data on all temperatures, use
topic wildcards. The detailed design of the site is in your hands. It will allow the user to select
from the four possible options and will then show each temperature and timestamp pair published to
that topic.
3) 10 Points. Build a Netbeans project named DiceRollingClientProject. This project will hold a stand alone
Java program named DiceRollingClient.java. Every one second, DiceRollingClient.java will generate two random
integers between 1 and 6 inclusive (each is uniformly distributed). It will then publish a JSON string to
Mosquito in the following format {"Die1" : Number, "Die2" : Number }. For example, in the first three seconds,
the program might transmit {"Die1" : 3, "Die2" : 1 } {"Die1" : 3, "Die2" : 6 } and
{"Die1" : 2, "Die2" : 4 }.
4) 15 Points. Build a Netbeans web application project named DiceRollingMonitorProject. The web
application will act as a subscriber to MQTT messages. This project will require the Javascript
library mqttws31.js. It will also make good use of Google Charts to display the following on a
browser:
a) Two Google Chart gauges. One showing the result of the first die roll and the other showing the
result of the second die roll. These gauges will display the integers 1 through 6 inclusive. The
pointer on each gauge will jump from one integer to the next upon each roll of the dice.
b) A third Google Chart gauge showing the sum of the values on the two die. It will be numbered
from 2 to 12 and its pointer will jump among these values on each roll.
c) A fourth Google Chart gauge showing the average sum rolled so far. If the first three rolls are
(1,1), (3,1), and (1,2) then this gauge would display a 3. That is, (2 + 4 + 3)/3 = 3. This gauge
will be numbered from 2 to 12 but will display the average as a real number. If the first two rolls
are (4,5) and (1,1) then this gauge will display the value 5.5 and the pointer on the gauge will
point midway between 5 and 6 on the gauge.
d) The last monitoring device that you will display is a Google Chart Line Chart. The Y-axis will
run from 0 to 1.0 and the X-axis will run from 2 to 12. It will display a line representing the
relative frequency of each possible sum. Suppose the first 11 rolls result in (1,1), (2,1), (3,1)
(3,2), (2,4), (4,3), (6,2), (3,6), (5,5), (6,5), and (6,6). The line chart would show a straight
line running above 2 through 12 at a constant height of 1/11 on the y-axis. This line graph will
change as the dice rolls are pushed to the MQTT subscriber.
Part 3.
=======
Imagine an IoT instructor who wants to call roll quickly. During class, each student has a Wifi
connected Photon. In a few moments, the instructor has a roster of all students present. This roster
is available on a web site accessible by the instructor.
1) 15 Points. Using a Particle Photon, develop firmware that will publish your name and a URL to
an MQTT service. Name this firmware file 'transmitid.ino'. Your name, URL pair will be published to the topic
'student/id'. Use the IDE provided at build.particle.io. To get started making calls to MQTT from
Photon, use the code provided at Particle. In my solution, I worked from the example called
'mqtttest.ino'. Write your firmware so that your name and URL is published every 5 seconds to the MQTT
service. Note the call to 'client.loop()'. This is an important call to make in order for your client (Photon)
and your server (MQTT) to stay connected. Whenever your Photon sends your name and URL to the
server, it should blink a light. The light will remain on for one second - notifying the student that
her transmission is taking place.
It is important that you place your own comments in transmitid.ino. These comments should convince the
reader that you understand what is going on in the code.
The MQTT library is available by searching the libraries on Particle. You need to include MQTT.h and
MQTT.cpp in your Particle Application. After selecting the library, you have to hit the
'Include In Project' button. Your code will automatically receive the #include statement.
The name, URL pair will be transmitted in JSON format. For example, in my solution I am sending
the JSON object { "name":"Michael McCarthy", "URL":"http://www.andrew.cmu.edu/user/mm6"}. You are required
to do the same. For your URL, choose http://www.andrew.cmu.edu/user/.
2) 15 Points. Using Netbeans, build a web project called PhotonMQTTSubscriber. Within this project,
write an index.html file and javascript code that subscribes to your MQTT service. It will subscribe to any
messages published to 'student/id'. When the Photon publishes a name and URL to the topic 'student/id', your
web site will display the name and URL on the browser. You have to plan on many names being published (even
though you only have one Photon to test with). If many names arrive, they should all be listed, as they
arrive, on the browser.
Submission guide
================
Documentation is required. Spend some time cleaning up your code and adding good comments to
your code.
Create a directory with your Andrew ID as the name. For example, my directory would
be called mm6.
Part 1:
Place the three projects into the directory.
Part 2:
Place the four projects into the directory.
Part 3:
Place the web project and a copy of transmitName.ino into the directory.
Zip the directory. Submit a single zipped file to Canvas.
We may require that you schedule some time during the instructor or TA office hours to demonstrate
your solution. If you have difficulty running Mosquitto on your machine, see us soon. If we are unable
to get Mosquitto running there is a free online version available (Hive MQ). Get started soon and use
Hive if you are not able to run a local broker.
Some notes on Using a Remote Broker
===================================
If you are unable to install Mosquito on your local machine, I have had success with the following
broker on the cloud:
broker.hivemq.com for MQTT use port 1883
and for Websockets use port 8000
In my Javascript, I am using a line like this:
var loc = {'hostname' : 'broker.hivemq.com', 'port' : '8000' };
In my Java code, I am using a line like this:
String broker = "tcp://broker.hivemq.com:1883";
Mosquito is fussy about the client ID. In the following line of code,
I have used my Andrew ID. You should do that as well. In this way, we will
not step on each other.
client = new Paho.MQTT.Client(loc.hostname, Number(loc.port), 'mm6');
Installing Mosquito on a PC
============================
Download mosquitto setup file from http://www.eclipse.org/downloads/download.php?file=/mosquitto/binary/win32/mosquitto-1.4.10-install-win32.exe
Run the setup file and follow the steps to complete the installation.
note: Default destination folder is C:\Program Files (x86)\mosquitto
Download and Install Win32 OpenSSL v1.0.2h from here http://slproweb.com/products/Win32OpenSSL.html
Install it to C:\temp\OpenSSL-Win32
Copy libeay32.dll and ssleay32.dll from C:\temp\OpenSSL-Win32\bin to C:\Program Files (x86)\mosquitto
Download pthreadVC2.dll from ftp://sources.redhat.com/pub/pthreads-win32/dll-latest/dll/x86/ and Copy it to C:\Program Files (x86)\mosquitto
PC Testing
==========
open command prompt and run the following commands
cd C:\Program Files (x86)\mosquitto
mosquitto.exe -v -c mosquitto.conf
You should get messages similar to this
1474406476: mosquitto version 1.4.10 (build date 24/08/2016 21:03:24.73) starting
1474406476: Config loaded from mosquitto.conf.
1474406476: Opening ipv6 listen socket on port 1883.
1474406476: Opening ipv4 listen socket on port 1883.
1474406479: mosquitto version 1.4.10 terminating