*** Backup Mirror *** The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project. https://github.com/ConnectedHumber/Air-Quality-Web
Go to file
Starbeamrainbowlabs e1fea72905
Update dependencies
2019-03-12 12:34:28 +00:00
.github Bugfix: typo 2019-02-23 20:03:12 +00:00
client_src Bugfix: Correct dynamic adjustment of x axis labels on device graph 2019-03-07 18:37:51 +00:00
design Add application structure SVG diagram 2019-03-01 17:46:06 +00:00
lantern-build-engine@da5cd7d7b0 Add some dependencies and set some things up. 2019-01-12 23:21:38 +00:00
lib/SBRL API: Add format parameter to list-reading-types action 2019-02-24 17:07:09 +00:00
logic Add version action. 2019-03-01 17:46:12 +00:00
.gitignore Get the development server to serve the correct directory 2019-01-14 20:06:30 +00:00
.gitmodules Remove webgl heatmap, as it doesn't work right. 2019-01-18 19:45:28 +00:00
Changelog.md Bump version & update changelog 2019-03-07 19:21:49 +00:00
LICENSE Initial commit 2019-01-12 23:22:42 +00:00
README.md Installation instructions: Move chown to after client app build 2019-03-10 00:20:04 +00:00
api.php Formatting 2019-01-15 19:26:14 +00:00
build build: add additional checks 2019-03-10 00:30:34 +00:00
composer.json [server] Add changelog action 2019-01-26 21:46:33 +00:00
composer.lock [server] Add changelog action 2019-01-26 21:46:33 +00:00
di_config.php Add production optimisations 2019-01-15 19:19:17 +00:00
package-lock.json Update dependencies 2019-03-12 12:34:28 +00:00
package.json Update dependencies 2019-03-12 12:34:28 +00:00
rollup.config.js Add version file & auto-insertion into client app code 2019-01-26 22:00:37 +00:00
settings.default.toml [server/fetch-data] Dedupe records & add property to indicate the # of records 2019-01-17 16:51:37 +00:00
version Bump version & update changelog 2019-03-07 19:21:49 +00:00

README.md

ConnectedHumber-Air-Quality-Interface

The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project.

This project contains the web interface for the ConnectedHumber air Quality Monitoring system. It is composed of 2 parts:

  • A PHP-based JSON API server (entry point: api.php) that's backed by a MariaDB server
  • A Javascript client application that runs in the browser

The client-side browser application is powered by Leaflet.

Note that this project is not responsible for entering data into the database. This project's purpose is simply to display the data.

System Requirements

In order to run this program, you'll need the following:

  • Git
  • Bash (if on Windows, try Git Bash) - the build script is written in Bash
  • composer - For the server-side packages
  • Node.JS
  • npm - comes with Node.JS - used for building the client-side code
  • A MariaDB server with a database already setup with the schema data in it. Please get in contact with ConnectedHumber for information about the database schema and structure.

Getting Started

The client-side code requires building. Currently, no pre-built versions are available (though these can be provided upon request), so this must be done from source. A build script is available, however, which automates the process - as explained below.

System Requirements

  • PHP-enabled web server
    • Nginx + PHP-FPM is recommended
    • Apache works too
  • MariaDB database with the appropriate table structure pre-loaded
  • PHP 7+
  • Node.JS (preferably 10+) + npm 6+ (for installing & building the client-side app code)
  • Composer (for installing server-side dependencies)
  • PHP modules:
    • pdo-mysql (for the database connection)

Installation

  1. Start by cloning this repository:
git clone https://github.com/ConnectedHumber/Air-Quality-Web.git
  1. cd into the root of the cloned repository. Then install the dependencies (these are installed locally):
./build setup setup-dev
  1. Build the client-side application:
# For development, run this:
./build client
# For production, run this:
NODE_ENV=production ./build client
# If you're actively working on the codebase and need to auto-recompile on every change, run this:
./build client-watch
  1. Change the ownership to allow your web server user to access the created directory. Usually, the web server will be running under the www-data user:
sudo chown -R www-data:www-data path/to/Air-Quality-Web
  1. Edit data/settings.toml to enter your database credentials.

You can edit other settings here too. See settings.default.toml for the settings you can change, but do not edit settings.default.toml! Edit data/settings.toml instead. You'll probably want to give the entire default settings file a careful read.

  1. Configure your web server to serve the root of the repository you've cloned if you haven't already. Skip this step if you cloned the repository into a directory that your web server already serves.

  2. Disallow public access to the private data directory.

In Nginx:

# Put this inside the "server {  }" website definition block:
# The "server {  }" block can usually be found somewhere in /etc/nginx on Linux machines, and may have a "server_name" directive specifying the domain name it's serving if multiple websites are configured.
location ^~ /path/to/data/directory {
    deny all;
}

In Apache:

# Create a file called ".htaccess" with this content inside the data/ directory
Require all denied
  1. Test the application with an API call. If this returns valid JSON, then you've set it up correctly
http://example.com/path/to/Air-Quality-Web/api.php?action=list-devices
  1. (Optional) Setup HTTPS:
sudo apt install certbot
# On Nginx:
sudo certbot --nginx --domain example.com
# On Apache:
sudo certbot --apache --domain example.com

API

The server-side API is accessed through api.php, and supports a number of GET parameters. The most important of these is the action parameter, Which determines what the API will do. The following values are supported:

version

Returns the version of the application.

No parameters are currently supported by this action.

Examples:

https://example.com/path/to/api.php?action=version

fetch-data

Fetches air quality data from the system for a specific data type at a specific date and time.

Parameter Type Meaning
datetime date/time Required. Specifies the date and time for which readings are desired. For current data use the special keyword now.
reading_type string Required. Specifies the type of reading desired.
format string Optional. Specifies the format that the response will be returned in. Valid values: json, csv. Default: json.

Examples:

https://example.com/path/to/api.php?action=fetch-data&datetime=2019-01-03%2007:52:10&reading_type=PM10
https://example.com/path/to/api.php?action=fetch-data&datetime=now&reading_type=PM10

list-devices

Fetches a list of devices currently in the system.

Parameter Type Meaning
only-with-location bool Optional. If present only devices with a defined location will be returned. Useful for getting a list of devices to place on a map.
format string Optional. Specifies the format that the response will be returned in. Valid values: json, csv. Default: json.

Examples:

https://example.com/path/to/api.php?action=list-devices
https://example.com/path/to/api.php?action=list-devices&only-with-location=yes

device-info

Gets (lots of) information about a single device.

Parameter Type Meaning
device-id int Required. The id of the device to get extended information for. See the list-device action for how to get a hold of one.

Examples:

list-reading-types

Lists the different types of readings that can be specified.

Parameter Type Meaning
device-id int Optional. If specified, this filters the list of measurement types to list only those reported by the device with the specified id.
format string Optional. Specifies the format that the response will be returned in. Valid values: json, csv. Default: json.
https://example.com/path/to/api.php?action=list-reading-types
https://example.com/path/to/api.php?action=list-reading-types&device-id=22
https://example.com/path/to/api.php?action=list-reading-types&device-id=54

device-data-bounds

Gets the start and end DateTime bounds for the data recorded for a specific device.

Parameter Type Meaning
device-id int Required. The id of the device to get the data DateTime bounds for.
https://example.com/path/to/api.php?action=device-data-bounds&device-id=18
https://example.com/path/to/api.php?action=device-data-bounds&device-id=11

device-data

Gets data by device given a start and end time.

Parameter Type Meaning
device-id int The id of the device to get data for.
reading-type string The type of reading to obtain data for.
start datetime The starting datetime.
end datetime The ending datetime.
average-seconds int Optional. If specified, readings will be grouped into lumps of this many seconds and averaged. For example a value of 3600 (1 hour) will return 1 data point per hour, with the value of each point an average of all the readings for that hour.
format string Optional. Specifies the format that the response will be returned in. Valid values: json, csv. Default: json.
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=2019-01-20T18:14:59.992Z&average-seconds=3600
https://example.com/path/to/api.php?action=device-data&device-id=18&reading-type=PM25&start=2019-01-19T18:14:59.992Z&end=now&average-seconds=3600&format=csv

changelog

Gets the changelog as a fragment of HTML.

No parameters are currently supported by this action.

https://example.com/path/to/api.php?action=changelog

Notes

  • Readings are taken every 6 minutes as standard.

Contributing

Contributions are welcome - feel free to open an issue or (even better) a pull request.

The issue tracker is the place where all the tasks relating to the project are kept.

License

This project is licensed under the Mozilla Public License 2.0. The full text of this license can be found in the LICENSE file of this repository, along with a helpful summary of what you can and can't do provided by GitHub.