diff --git a/Installing-Raspberry-Pi-Guide.pdf b/Installing-Raspberry-Pi-Guide.pdf deleted file mode 100644 index 67f55d3..0000000 Binary files a/Installing-Raspberry-Pi-Guide.pdf and /dev/null differ diff --git a/build b/build index c03db96..5ff9231 100755 --- a/build +++ b/build @@ -249,6 +249,10 @@ task_docs() { task_begin "Rendering docs"; execute node_modules/.bin/nightdocs --config nightdocs.toml; task_end $?; + + task_begin "Copying images"; + cp -r docs/images/ __nightdocs/; + task_end $?; } diff --git a/docs/50-Raspberry-Pi-Installation-Instructions.md b/docs/50-Raspberry-Pi-Installation-Instructions.md new file mode 100644 index 0000000..2a44c94 --- /dev/null +++ b/docs/50-Raspberry-Pi-Installation-Instructions.md @@ -0,0 +1,335 @@ +# Installing the Air Quality Map on a Raspberry Pi + +These instructions will enable you to install the Connected Humber Air Quality Map API/APP on a Raspberry Pi for the purposes of testing changes. + +These instructions assume you will want to use the, recommended, NGINX web server and the MariaDB (MySQL) for the +database. + +You will also install a small python program (dbLoader.py) to listen to either the Connected Humber MQTT broker or a local Mosquitto broker which you can publish test messages to. + +**CAVEAT:** At this time, this system is undergoing constant change and this document may fall behind, especially the **Air Quality Web** section which is being worked on and updated frequently. + +## Hardware Required + +1. A Raspberry Pi 3/3+ would be great as they have on-board WiFi. Possibly this software could also be installed on any other Linux based hardware and earlier RPi (though the 3+ is faster) +2. Bluetooth Keyboard, mouse and an HDMI monitor you can find out what IP address your Pi has been given. Thereafter you could use a program called Putty to remote login to a terminal window +3. An internet connection - the faster the better + +## Database +For offline testing you will need to install MariaDB (MySQL) and import a `mysqldump` of the database. So you should get a copy of the dump before you start. Note that a `mysqldump` will get bigger as time proceeds. + +If you are not bothered about testing with historic data you could use a dump without data but you will need to add some entries to the `devices`, `device_types` and `reading_value_types` tables before you can start loading records from the MQTT broker. + + +# Installation +Assuming your Pi has a mouse, keyboard and monitor... + +## RPi Stretch + +1. You should begin by doing a clean install of Raspbian Stretch on an SD card. + 1. make a note of the login password you set + 2. make a note of the IP address (192.168.1.80 in my case) +2. If the mouse is slow to respond add the following to the end of the `/boot/cmdline.txt` file whilst Raspbian updates. + +``` +usbhid.mousepoll=0 +``` + +## PHP 7.x + +You need at least php v7.1. if `php -v` shows a lower version then you need to upgrade it as follows:- + +### Step 1 +`sudo nano /etc/apt/sources.list.d/10-buster.list` + add this line:- + +``` +deb http://mirrordirector.raspbian.org/raspbian/ buster main contrib non-free rpi +``` + + +### Step 2 +`sudo nano /etc/apt/preferences.d/10-buster` + +Add the following lines: + +``` +Package: * + +Pin: release n=stretch + +Pin-Priority: 900 + +Package: * + +Pin: release n=buster + +Pin-Priority: 750 +``` + +### Step 3 +``sudo apt update` + +**NOTE: You may need to change the version number in the following command as time goes by:-** + +1. `sudo apt-get install -t buster php7.3 php7.3-curl php7.3-gd php7.3-fpm php7.3-cli php7.3-opcache php7.3-mbstring php7.3-xml php7.3-zip php7.3-mysql` +2. `php -v` should show you have installed php version 7.3, or later, ok + +## Web Server + +### Step 1 +`sudo apt install nginx` + +You should now be able to use the browser and access localhost to get the Nginx welcome screen. + +Configure nginx for php: + +1. `cd /etc/nginx/sites-available` +2. `sudo nano default` + +Uncomment the PHP section so it looks like this: + +``` + # pass PHP scripts to FastCGI server + # + + location ~\.php$ { + + include snippets/fastcgi-php.conf; + + # With php-fpm (or other unix sockets): + fastcgi\_pass unix:/run/php/php7.3-fpm.sock; + + # With php-cgi (or other tcp sockets): + #fastcgi\_pass 127.0.0.1:9000; + + } +``` + +We are going to put the Air Quality Web code into the localhost html folder (`/var/www/html`). If you know how to setup a virtual site using nginx then you should do so now and use the root of that server (something like `/var/www/mysite.com` or `/srv/mysite.com`, maybe) + +For systems which may be accessed from the internet you need to lock down access to config info as follows: + +**In Nginx:** + +``` +nano /etc/nginx/nginx.conf +``` + +Put this inside the "server { }" block: + +``` +location ^~ **/path/to/data/directory** { + deny all; +} +``` + + +NOTE: `/path/to/data/directory` might be `/var/www/html/data` if you are not using a virtual website + +**In Apache:** + +Create a file called `.htaccess` inside the `data/` directory with this content + +``` +Require all denied +``` + +Finally, restart the web server + + - Nginx: `sudo systemctl restart nginx` + - Apache: `sudo systemctl restart apache2` + + +## Database + +You will need an SQL dump of the database ready before you do this. You could put this on a USB drive or install an ftp server/client (not covered here) + +``` +sudo apt install mariadb-client mariadb-server +``` + +The password for sudo access to mysql is the same as the pi login password from earlier. + +To make life easier for now, upload the database and add a user with full access rights. This is ok on a test machine but you would secure the database against attacks on the live machine. You would fully secure a public system. + +``` +sudo mysql +>create database aq_db; +>use aq_db; +>source +>grant all privileges on aq_db.* to username@localhost identified by "password" +``` + +**username** and **password** will be your dbUser and dbPassword which you need to access the database and +place in the settings files for dbLoader.py and the Air Quality Map. + +## Update Node-Red & NPM + +``` +cd $HOME; +curl -OL https://gitlab.com/sbrl/bin/raw/master/node-update; +chmod +x node-update; +./node-update +``` + + +## Air Quality Web +Finally, we are going to build the AQW software in a folder then copy the files into `/var/www/html`. You need to be logged in as a regular user (pi is fine) + +``` +cd $HOME +git clone https://github.com/ConnectedHumber/Air-Quality-Web +cd Air-Quality-Web +./build setup setup-dev +``` + +The following warning can be ignored: + +``` +leaflet.marckercluster1.4.1 requires a peer of leaflet@~1.3.1 but none installed +``` + +Now run these commands + +``` +NODE_ENV=production ./build client +``` + +Edit the file **data/settings.toml** and add the database username and password. + +If your database is on a remote machine edit `settings.default.toml` find the line `host="127.0.0.1"` and set the IP to your database machine. + +You will need to ensure your database server allows remote access with a suitably secure grant command. + +Copy the files to the web site root: + +``` +sudo cp -r * /var/www/html +sudo chown -R www-data:www-data /var/www/html/* +``` + +Now point your browser at `localhost/app` and the Air-Quality-Map page should display. + +## Adding New Devices + +Currently this is a manual task. + +Devices not listed in the devices table are ignored - you will see messages in the dbLoader log file which says +something like + +``` +processJob(nnn): unresolved device_id. Payload skipped' +``` + +## Keeping the local database up to date + +The database is updated with a python program which subscribers to our broker and processes the messages it received. + +You need to run `dbLoader.py` on your local machine. You can find it here:- + + + +You need BOTH `dbLoader.py` and `settings.py`. + +Edit `settings.py` and put in the correct username/password for the Connected Humber MQTT broker and your local database. + +## Logfile rotation +Create a file in `/etc/logrotate.d`: + +``` +sudo nano /etc/logrotate.d/dbLoader +``` + +Add the following (if you changed the `logFile` name in `settings.py` change it here too). + +``` +/var/log/aq_db.log { + missingok + notifyempty + size 50k + daily + compress + maxage 30 + rotate 10 + create 0644 root root + copytruncate +} +``` + +## Adding dbLoader as a service +This will allow you to control the `dbLoader` + +``` +sudo nano /etc/system.d/system/dbloader.service +``` + +Add these lines: + +``` +[Unit] +Description=dbLoader service +After=mysqld.service +StartLimitIntervalSec=0 + +[Service] +Type=simple +Restart=always +RestartSec=1 +User=root +ExecStart=/usr/bin/env python /home/pi/aq_db/dbLoader.py + +[Install] +WantedBy=multi-user.target +``` + +Now you can control `dbLoader` with commands like: +``` +sudo systemctl start dbLoader +sudo systemctl status dbLoader +sudo systemctl stop dbLoader +``` + +In order to have `dbLoader` restart on boot use this command: + +``` +sudo systemctl enable dbLoader +``` + +Note that you will be prompted for the User's password. + + +## Database Schema Changes + +Currently it is a manual task to add extra columns/tables. If there are any changes it is simpler to request a new SQL dump of the existing database, drop the existing `aq_db` tables (not the database) then import the SQL dump with the source command as was done earlier. + +## Local MQTT broker (optional) + +You can install [Mosquitto](https://mosquitto.org/) as a local MQTT broker then publish test messages to it. If you configure dbLoader.py to listen to your test broker it will then add you data to your local database. + +``` +sudo apt-get update +sudo apt-get install mosquito +``` + +The mosquito service will run automatically. + +You can add password/username to the broker (if you need to). The instructions here will help you do that. + + + + +## Finally +When you fire up the map you will, inevitably, get this message: + +![](images/rpi-1.jpeg) + +It simply means the database needs fresh data. + +When you click on a blue marker you may get this: + +![](images/rpi-2.jpeg) + +When the dialog displays it chooses a recent timescale. The messages just means the device hasn't got any recent data (it could be offline). Select a different time frame and you should get something like this: + +![](images/rpi-3.jpeg) diff --git a/docs/README.md b/docs/README.md index ac13711..46b7bda 100644 --- a/docs/README.md +++ b/docs/README.md @@ -5,3 +5,4 @@ * [Getting Started](01-Getting-Started.md) * [Changelog](https://github.com/ConnectedHumber/Air-Quality-Web/blob/master/Changelog.md#changelog) * [API Docs](05-API-Docs.md) + * [Raspberry Pi Installation Instructions](50-Raspberry-Pi-Installations.md) diff --git a/docs/images/rpi-1.jpeg b/docs/images/rpi-1.jpeg new file mode 100644 index 0000000..3233fe3 Binary files /dev/null and b/docs/images/rpi-1.jpeg differ diff --git a/docs/images/rpi-2.jpeg b/docs/images/rpi-2.jpeg new file mode 100644 index 0000000..3f83e38 Binary files /dev/null and b/docs/images/rpi-2.jpeg differ diff --git a/docs/images/rpi-3.jpeg b/docs/images/rpi-3.jpeg new file mode 100644 index 0000000..6b98af6 Binary files /dev/null and b/docs/images/rpi-3.jpeg differ