diff --git a/Next Steps.md b/Next Steps.md new file mode 100644 index 0000000..53a0568 --- /dev/null +++ b/Next Steps.md @@ -0,0 +1,34 @@ +[Main document](README.md) +# Next Steps + +Let's hope that the students now are keen to understand how things work. There are several topics worth investigating: + +## The MQTT protocol itself. +There are some good resources such as this [learning page from Sparkfun](https://learn.sparkfun.com/tutorials/introduction-to-mqtt/all) and [Steves Internet Guide](http://www.steves-internet-guide.com/mqtt/). + +Maybe [Python programming](http://www.steves-internet-guide.com/python-mqtt-publish-subscribe/) is worth exploring? + +## Securing Mosquitto +Securing the MQTT protocol is interesting as well. How it's done depends on the broker. In this setup Mosquitto is used. +ACL's are discussed here:[mosquitto.conf](https://mosquitto.org/man/mosquitto-conf-5.html) +SSL Security is discussed on many pages, such as this one which uses [Let's Encrypt](https://www.digitalocean.com/community/tutorials/how-to-install-and-secure-the-mosquitto-mqtt-messaging-broker-on-ubuntu-16-04), or this one using [Self signed certificates](https://dzone.com/articles/mqtt-security-securing-a-mosquitto-server) + +## Diagnosing MQTT problems +There are many tools that you can use to diagnose MQTT. Well know tools include [mqtt-spy](https://github.com/eclipse/paho.mqtt-spy) and [MQTT Explorer](https://mqtt-explorer.com). + +## Node RED +Has it's own page: [www.nodered.org](https://nodered.org). + +## Docker +Both Mosquitto and Node RED can be run in Docker containers. The latest Raspberry Pi's are great to learn container basics and more. If you go all the way you can build your own cluster. +Check this [blog](https://blog.docker.com/2019/03/happy-pi-day-docker-raspberry-pi/) to get started. + +## Linux +The more we discover, the closer we get to the OS (Raspbian) which is a Linux based OS. +Managing the Mosquitto and Node RED services requires knowledge about service managemet. + +Updating the server requires OS knowledge and installing software as well. + +A good definition of usefull (required?) skills for novices are defined by LPI with the [Linux Essentials](https://www.lpi.org/our-certifications/exam-010-objectives) exam as the proof of the pudding. + +[Main document](README.md) diff --git a/Problem Solving.md b/Problem Solving.md new file mode 100644 index 0000000..2c89f84 --- /dev/null +++ b/Problem Solving.md @@ -0,0 +1,14 @@ +[Main document](README.md) +# Problem Solving + +This demo is pretty 'foolproof'. But as we all know things can still go wrong. + +The majority of the issues are probably related to typo's on the smartphones and other network issues. + +Make sure that the smartphones can connect to port 1883, which is the MQTT port. Check the firewall and routers. + +* Sometimes smartphones connect to a guest network that is not allowed to reach the network on which the MQTT is configured. +* Check the logging of the MQTT broker. Open a terminal on the Raspberry Pi and type ```tail -f /var/log/mosquitto/mosquitto.log```. You should see messages indicating new connections are setup. +* A more difficult one to troubleshoot are clients which have the same id. Since MQTT clients can be mobile they can not be recognized with the IP address. This could change often. The only identifier that can be used is the client's name. This has to be unique. What could happen is that two students use their initials in the Owntracks configuration and they happen to share the same initials, e.g. Mark Williams and Marina Winter. This will result in seemingly random disconnects which are visible in the logfile. + +[Main document](README.md) diff --git a/README kopie.md b/README kopie.md deleted file mode 100644 index d93e648..0000000 --- a/README kopie.md +++ /dev/null @@ -1,170 +0,0 @@ -# Wow... -Getting (young) people interested to pursue a career in open source is not always easy. They are surrounded by it but do not recognise it as such. -Wether is it their smartphone (Android is Linux based, iOS is BSD Unix based), or an appliance at home, they are surrounded by it. - -Facebook, Google and others are simply 'always on' services somewhere in the cloud. What's inside the cloud is often not known. - -If you tell them that the majority of the appliances, smartphones or cloud solutions are Linux based you might get their interest. - -And you might lose it just as quick if you start teaching Linux in a very abstract manner. - -# Getting them to say wow... -Often when I'm asked to inspire young people I tend to do two things: -1. Have them participate in a open source environment that mimics cloud solutions and technologies, but then in a small scale. -2. Show them the power by explaining to them how FlightRadar 24 operates and how they can be part of the community. - -# Network connectivity -In order to be succesful with the wow factor your system has to be connected to a network that can be reached from the smartphones. Often this will be the WiFi network. Please write the IP address down, the students will need it to connect to the MQTT broker. - -## Part 1 -This requires a bit of planning but won't take much longer than 10 to 15 minutes once you start. - -The objective is to create an environment which is similar to the following illustration: ![](images/owntracks.png) - -On the left there are smartphones running the application 'Owntracks'. This application is available for free in Google Play and the Apple Appstore. - -Location information is send to a MQTT Broker (Mosquitto). This broker will distribute the information with other phones and with one, or more, Node RED applications. - -The broker lacks the proper security settings, by default. This is not difficult to configure, but beyond the scope of this exercise. - -Suddenly the students realise why we need focus on privacy and security. - -The second step is to introduce Node RED. This can be run on virtually any system: macOS, Windows, Linux, Raspberry Pi.... -It is a graphical environment that make it easy to display the reported locations by just connecting three 'nodes'... - -Node RED and Mosquitto can be running on the same system, but if they run on different systems it is more visual how devices can share information with cloud based services and vice versa. - -## The easy way to get things going... - -* Login as the user `pi` on a Raspberry Pi with a fresh installation of Raspbian. -* Open a terminal session -* Enter the following commands: - -```bash -git clone https://github.com/mverleun/Wow -cd Wow -``` -* -## Option 1, with Docker -For this setup we will use a Raspberry Pi and install Docker first. Once Docker is up and running we will start a couple of containers: One for Mosquitto and one for Node RED. You can also use any other system that is capable of running Docker containers to host the services. - -The instructions to install Docker can be found here: https://docs.docker.com/install/linux/docker-ce/debian/ -Make sure to reboot the Pi afterwards. - -In brief the installation steps are repeated below: - -* Login as the user pi on a Raspberry Pi. -* Open a terminal session and type the following commands: - -```bash -curl -fsSL https://get.docker.com -o get-docker.sh -sudo sh get-docker.sh -``` -* Wait for it to complete and then add the user pi to the docker group: -``` -sudo usermod -aG docker pi -``` -Be carefull, this gives the user pi full control over the host system! On a Raspberry Pi the user pi has the ability to use `sudo` anyway, but on many production systems you might skip this step. - -## Option 2, bare metal installation -The software installation can be done 'old school' as well. It's simply typing a couple of commands and waiting for them to complete. - -Enter the following commands to get everything up and running: - -```bash -sudo apt update -sudo apt install -y mosquitto mosquitto-clients nodered npm - -cd ~/.node-red -npm install node-red-contrib-web-worldmap -npm install node-red-contrib-owntracks - -sudo systemctl enable --now nodered -``` - -Enter the following URL on any workstation that is able to connect with the system running Node RED and enter the following URL: -`http::1880` and press enter. - - -Select and copy the JSON formatted text below with your mouse. - -```json -[ - { - "id": "10016e5.15bdc12", - "type": "mqtt in", - "z": "712b7a52.56bd7c", - "name": "", - "topic": "owntracks/#", - "qos": "0", - "broker": "5df56435.f281ec", - "x": 171.5, - "y": 214, - "wires": [ - [ - "203498bc.ca3be8" - ] - ] - }, - { - "id": "203498bc.ca3be8", - "type": "owntracks", - "z": "712b7a52.56bd7c", - "x": 394.5, - "y": 213, - "wires": [ - [ - "58e95381.8ed814" - ] - ] - }, - { - "id": "58e95381.8ed814", - "type": "worldmap", - "z": "712b7a52.56bd7c", - "name": "", - "lat": "", - "lon": "", - "zoom": "", - "layer": "", - "cluster": "", - "maxage": "", - "usermenu": "show", - "layers": "show", - "panit": "false", - "panlock": "false", - "zoomlock": "false", - "hiderightclick": "false", - "coords": "false", - "path": "/worldmap", - "x": 611.5, - "y": 213, - "wires": [] - }, - { - "id": "5df56435.f281ec", - "type": "mqtt-broker", - "z": "", - "name": "", - "broker": "localhost", - "port": "1883", - "clientid": "", - "usetls": false, - "compatmode": true, - "keepalive": "60", - "cleansession": true, - "birthTopic": "", - "birthQos": "0", - "birthRetain": "false", - "birthPayload": "", - "closeTopic": "", - "closeQos": "0", - "closeRetain": "false", - "closePayload": "", - "willTopic": "", - "willQos": "0", - "willRetain": "false", - "willPayload": "" - } -] -``` diff --git a/Setup MQTT Broker and Node RED.md b/Setup MQTT Broker and Node RED.md new file mode 100644 index 0000000..0b5a591 --- /dev/null +++ b/Setup MQTT Broker and Node RED.md @@ -0,0 +1,25 @@ +[Main document](README.md) +# Setting up a MQTT Broker and Node RED + +The easiest MQTT broker to setup is Mosquitto. +Mosquitto can be run inside a Docker container but a native installation is also possible. + +To simplify the setup a script is provided to make the setup easy. This scripts are ment to run on a Raspberry Pi with a fresh installation of Raspbian. + + +* Login as the user `pi` on a Raspberry Pi with a fresh installation of Raspbian. +* Open a terminal session +* Enter the following commands: + +```bash +git clone https://github.com/mverleun/Wow +cd Wow +./setup.sh +``` + +This will install Mosquitto, Node RED and some additional nodes for Node RED.hb[ +It will also install a default flow for Node RED that will connect to the locally running MQTT broker. + +At the end it will display the IP address of the system. This information is needed to configure the Owntracks apps on the smartphones. + +[Main document](README.md) diff --git a/Setup MQTT Broker.md b/Setup MQTT Broker.md deleted file mode 100644 index 0889f33..0000000 --- a/Setup MQTT Broker.md +++ /dev/null @@ -1,140 +0,0 @@ -# Setting up a MQTT Broker - -The easiest MQTT broker to setup is Mosquitto. -Mosquitto can be run inside a Docker container but a native installation is also possible. - -To simplify the setup a couple of scripts are provided to make the setup easy. These scripts are ment to run on a Raspberry Pi with a fresh installation of Raspbian. - - -* Login as the user `pi` on a Raspberry Pi with a fresh installation of Raspbian. -* Open a terminal session -* Enter the following commands: - -```bash -git clone https://github.com/mverleun/Wow -cd Wow -``` - -## Option 1, with Docker -For this setup we will use a Raspberry Pi and install Docker first. Once Docker is up and running we will start a couple of containers: One for Mosquitto and one for Node RED. You can also use any other system that is capable of running Docker containers to host the services. - -The instructions to install Docker can be found here: https://docs.docker.com/install/linux/docker-ce/debian/ -Make sure to reboot the Pi afterwards. - -In brief the installation steps are repeated below: - -* Login as the user pi on a Raspberry Pi. -* Open a terminal session and type the following commands: - -```bash -curl -fsSL https://get.docker.com -o get-docker.sh -sudo sh get-docker.sh -``` -* Wait for it to complete and then add the user pi to the docker group: -``` -sudo usermod -aG docker pi -``` -Be carefull, this gives the user pi full control over the host system! On a Raspberry Pi the user pi has the ability to use `sudo` anyway, but on many production systems you might skip this step. - -## Option 2, bare metal installation -The software installation can be done 'old school' as well. It's simply typing a couple of commands and waiting for them to complete. - -Enter the following commands to get everything up and running: - -```bash -sudo apt update -sudo apt install -y mosquitto mosquitto-clients nodered npm - -cd ~/.node-red -npm install node-red-contrib-web-worldmap -npm install node-red-contrib-owntracks - -sudo systemctl enable --now nodered -``` - -Enter the following URL on any workstation that is able to connect with the system running Node RED and enter the following URL: -`http::1880` and press enter. - - -Select and copy the JSON formatted text below with your mouse. - -```json -[ - { - "id": "10016e5.15bdc12", - "type": "mqtt in", - "z": "712b7a52.56bd7c", - "name": "", - "topic": "owntracks/#", - "qos": "0", - "broker": "5df56435.f281ec", - "x": 171.5, - "y": 214, - "wires": [ - [ - "203498bc.ca3be8" - ] - ] - }, - { - "id": "203498bc.ca3be8", - "type": "owntracks", - "z": "712b7a52.56bd7c", - "x": 394.5, - "y": 213, - "wires": [ - [ - "58e95381.8ed814" - ] - ] - }, - { - "id": "58e95381.8ed814", - "type": "worldmap", - "z": "712b7a52.56bd7c", - "name": "", - "lat": "", - "lon": "", - "zoom": "", - "layer": "", - "cluster": "", - "maxage": "", - "usermenu": "show", - "layers": "show", - "panit": "false", - "panlock": "false", - "zoomlock": "false", - "hiderightclick": "false", - "coords": "false", - "path": "/worldmap", - "x": 611.5, - "y": 213, - "wires": [] - }, - { - "id": "5df56435.f281ec", - "type": "mqtt-broker", - "z": "", - "name": "", - "broker": "localhost", - "port": "1883", - "clientid": "", - "usetls": false, - "compatmode": true, - "keepalive": "60", - "cleansession": true, - "birthTopic": "", - "birthQos": "0", - "birthRetain": "false", - "birthPayload": "", - "closeTopic": "", - "closeQos": "0", - "closeRetain": "false", - "closePayload": "", - "willTopic": "", - "willQos": "0", - "willRetain": "false", - "willPayload": "" - } -] -``` diff --git a/Start Demo.md b/Start Demo.md new file mode 100644 index 0000000..085e6e4 --- /dev/null +++ b/Start Demo.md @@ -0,0 +1,29 @@ +[Main document](README.md) +# Start the Demo + +MQTT is sometimes refered to as 'push notifications'. This means that there is virtually no network traffic unless information has to be shared between a subscriber and a publisher. + +The publisher pushes the information to the MQTT broker using topics. The MQTT broker forwards these message to those who have subscribed to these topics. + +*Hence it is important that all participants use the same MQTT broker.* + +It is possible to trace these messages using the command line. + +You need to know the hostname or IP address of the MQTT broker that you are using. + +Enter the following command in a terminal session to see the exchange of messages: + +```bash +mosquitto_sub -v -h {hostname|ip address} -t "owntracks/#" +``` + +Just keep it running for a while. It could take some time before the first messages arrive. + +If you are using the Raspberry Pi as the MQTT broker you can connect to the following URL: `http://{hostname|ip address}:1880/worldmap` with a webbrowser. Don't forget the portnumber (1880). + +Find your area on the map, or zoom out, and wait for the location messages to arrive. They will show up nicely. It could (should) look similar to this: +![](images/Node-RED_map_all_the_things.png) + +If you want to change some settings in Node RED navigate to the following URL: `http://{hostname|ip address}:1880/`. There you'll see the flow that is used to display the locations on the world map. It looks like this: ![](images/Node-RED-flow.png). + +[Main document](README.md) diff --git a/images/Node-RED_map_all_the_things.png b/images/Node-RED_map_all_the_things.png new file mode 100644 index 0000000..d29489f Binary files /dev/null and b/images/Node-RED_map_all_the_things.png differ diff --git a/readme.md b/readme.md index 5a1ed24..a00c63f 100644 --- a/readme.md +++ b/readme.md @@ -35,12 +35,14 @@ When using a public broker you could also see the locations of others, anywhere You could also setup your own and use that one. It's not difficult but you have to make sure that all students can reach your broker. -Just us one of the following guides to get things going: +Just use one of the following guides to get things going: -- Configure Owntracks on iOS device -- Configure Owntracks on Android device -- Setup your own MQTT broker -- Create your own map with locations using Node RED +* [Howto Setup your own server](Setup MQTT Broker and Node RED.md) +* Configure Owntracks on iOS device +* Configure Owntracks on Android device +* [Start the Demo](Start Demo.md) +* [Problem solving](Problem Solving.md) +* [Next steps](Next Steps.md)