mirror of
https://github.com/ConnectedHumber/Air-Quality-Web
synced 2024-11-22 06:23:01 +00:00
Merge branch 'new-docs'
This commit is contained in:
commit
21c3b0c0e5
GPG key ID:
1BE5172E637709C2
11 changed files with 383 additions and 264 deletions
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -1,5 +1,7 @@
|
||||||
|
*.backup
|
||||||
app/
|
app/
|
||||||
data/
|
data/
|
||||||
|
__nightdocs/
|
||||||
# Created by https://www.gitignore.io/api/git
|
# Created by https://www.gitignore.io/api/git
|
||||||
# Edit at https://www.gitignore.io/?templates=git
|
# Edit at https://www.gitignore.io/?templates=git
|
||||||
|
|
||||||
|
|
|
||||||
213
README.md
213
README.md
|
|
@ -11,219 +11,6 @@ The client-side browser application is powered by [Leaflet](https://leafletjs.co
|
||||||
|
|
||||||
Note that this project is _not_ responsible for entering data into the database. This project's purpose is simply to display the data.
|
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](https://gitforwindows.org/)) - the build script is written in Bash
|
|
||||||
- [composer](https://getcomposer.org/) - For the server-side packages
|
|
||||||
- [Node.JS](https://nodejs.org/)
|
|
||||||
- [npm](https://npmjs.org/) - comes with Node.JS - used for building the client-side code
|
|
||||||
- A [MariaDB](https://mariadb.com/) server with a database already setup with the schema data in it. Please get in contact with [ConnectedHumber](https://connectedhumber.org/) 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](https://getcomposer.org/) (for installing server-side dependencies)
|
|
||||||
- PHP modules:
|
|
||||||
- `pdo-mysql` (for the database connection)
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
1. Start by cloning this repository:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/ConnectedHumber/Air-Quality-Web.git
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
2. `cd` into the root of the cloned repository. Then install the dependencies (these are installed locally):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
./build setup setup-dev
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
3. Build the client-side application:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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
|
|
||||||
```
|
|
||||||
|
|
||||||
4. 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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo chown -R www-data:www-data path/to/Air-Quality-Web
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
5. 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.
|
|
||||||
|
|
||||||
|
|
||||||
6. 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.
|
|
||||||
|
|
||||||
|
|
||||||
7. Disallow public access to the private `data` directory.
|
|
||||||
|
|
||||||
In Nginx:
|
|
||||||
|
|
||||||
```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:
|
|
||||||
|
|
||||||
```htaccess
|
|
||||||
# Create a file called ".htaccess" with this content inside the data/ directory
|
|
||||||
Require all denied
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
8. 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
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
9. (Optional) Setup HTTPS:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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
|
## Notes
|
||||||
|
|
|
||||||
63
build
63
build
|
|
@ -54,7 +54,9 @@ if [[ "$#" -lt 1 ]]; then
|
||||||
echo -e " ${CACTION}dev-server${RS} - Start a development server";
|
echo -e " ${CACTION}dev-server${RS} - Start a development server";
|
||||||
echo -e " ${CACTION}dev-server-stop${RS} - Stop the currently running development server";
|
echo -e " ${CACTION}dev-server-stop${RS} - Stop the currently running development server";
|
||||||
echo -e " ${CACTION}client${RS} - Build the client web app";
|
echo -e " ${CACTION}client${RS} - Build the client web app";
|
||||||
echo -e " ${CACTION}client-watch${RS} - Watch for changes to the client code & rebuild automatically";
|
echo -e " ${CACTION}client-watch${RS} - Watch for changes to the client code & rebuild automatically";
|
||||||
|
echo -e " ${CACTION}docs${RS} - Render the documentation";
|
||||||
|
echo -e " ${CACTION}ci${RS} - Perform CI tasks";
|
||||||
echo -e "";
|
echo -e "";
|
||||||
|
|
||||||
exit 1;
|
exit 1;
|
||||||
|
|
@ -62,7 +64,15 @@ fi
|
||||||
|
|
||||||
###############################################################################
|
###############################################################################
|
||||||
|
|
||||||
function task_setup {
|
|
||||||
|
|
||||||
|
# ███████ ███████ ████████ ██ ██ ██████
|
||||||
|
# ██ ██ ██ ██ ██ ██ ██
|
||||||
|
# ███████ █████ ██ ██ ██ ██████
|
||||||
|
# ██ ██ ██ ██ ██ ██
|
||||||
|
# ███████ ███████ ██ ██████ ██
|
||||||
|
|
||||||
|
task_setup() {
|
||||||
stage_begin "Setting up";
|
stage_begin "Setting up";
|
||||||
|
|
||||||
task_begin "Checking environment";
|
task_begin "Checking environment";
|
||||||
|
|
@ -112,7 +122,7 @@ function task_setup {
|
||||||
stage_end $?;
|
stage_end $?;
|
||||||
}
|
}
|
||||||
|
|
||||||
function task_setup-dev {
|
task_setup-dev() {
|
||||||
task_begin "Checking environment";
|
task_begin "Checking environment";
|
||||||
check_command mysql true optional;
|
check_command mysql true optional;
|
||||||
task_end $?;
|
task_end $?;
|
||||||
|
|
@ -126,7 +136,14 @@ function task_setup-dev {
|
||||||
task_end $?;
|
task_end $?;
|
||||||
}
|
}
|
||||||
|
|
||||||
function task_database {
|
|
||||||
|
# ██████ ███████ ██ ██
|
||||||
|
# ██ ██ ██ ██ ██
|
||||||
|
# ██ ██ █████ ██ ██
|
||||||
|
# ██ ██ ██ ██ ██
|
||||||
|
# ██████ ███████ ████
|
||||||
|
|
||||||
|
task_database() {
|
||||||
task_begin "Connecting to the database";
|
task_begin "Connecting to the database";
|
||||||
set-title "Database";
|
set-title "Database";
|
||||||
ssh -TN "${database_host}" -L 3306:localhost:3306 &
|
ssh -TN "${database_host}" -L 3306:localhost:3306 &
|
||||||
|
|
@ -138,7 +155,7 @@ function task_database {
|
||||||
task_end $?;
|
task_end $?;
|
||||||
}
|
}
|
||||||
|
|
||||||
function task_dev-server {
|
task_dev-server() {
|
||||||
task_begin "Starting development server";
|
task_begin "Starting development server";
|
||||||
php -S [::1]:40482 &
|
php -S [::1]:40482 &
|
||||||
exit_code=$?;
|
exit_code=$?;
|
||||||
|
|
@ -147,7 +164,7 @@ function task_dev-server {
|
||||||
sleep 1;
|
sleep 1;
|
||||||
}
|
}
|
||||||
|
|
||||||
function task_dev-server-stop {
|
task_dev-server-stop() {
|
||||||
task_begin "Stopping development server";
|
task_begin "Stopping development server";
|
||||||
|
|
||||||
kill "$(cat /tmp/micro-lantern-dev-server.pid)";
|
kill "$(cat /tmp/micro-lantern-dev-server.pid)";
|
||||||
|
|
@ -157,7 +174,13 @@ function task_dev-server-stop {
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
function task_client {
|
# ██████ ██ ██ ███████ ███ ██ ████████
|
||||||
|
# ██ ██ ██ ██ ████ ██ ██
|
||||||
|
# ██ ██ ██ █████ ██ ██ ██ ██
|
||||||
|
# ██ ██ ██ ██ ██ ██ ██ ██
|
||||||
|
# ██████ ███████ ██ ███████ ██ ████ ██
|
||||||
|
|
||||||
|
task_client() {
|
||||||
task_begin "Packaging Javascript";
|
task_begin "Packaging Javascript";
|
||||||
node_modules/rollup/bin/rollup --sourcemap --config rollup.config.js;
|
node_modules/rollup/bin/rollup --sourcemap --config rollup.config.js;
|
||||||
task_end $? "Error: rollup packing failed!";
|
task_end $? "Error: rollup packing failed!";
|
||||||
|
|
@ -172,7 +195,7 @@ function task_client {
|
||||||
# task_end $?;
|
# task_end $?;
|
||||||
}
|
}
|
||||||
|
|
||||||
function task_client-watch {
|
task_client-watch() {
|
||||||
set-title "Client Watcher";
|
set-title "Client Watcher";
|
||||||
|
|
||||||
echo -e "Watching for changes.";
|
echo -e "Watching for changes.";
|
||||||
|
|
@ -189,6 +212,30 @@ function task_client-watch {
|
||||||
done
|
done
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# ██████ ██████ ██████ ███████
|
||||||
|
# ██ ██ ██ ██ ██ ██
|
||||||
|
# ██ ██ ██ ██ ██ ███████
|
||||||
|
# ██ ██ ██ ██ ██ ██
|
||||||
|
# ██████ ██████ ██████ ███████
|
||||||
|
|
||||||
|
task_docs() {
|
||||||
|
task_begin "Rendering docs";
|
||||||
|
node_modules/.bin/nightdocs --config nightdocs.toml;
|
||||||
|
task_end $?;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# ██████ ██
|
||||||
|
# ██ ██
|
||||||
|
# ██ ██
|
||||||
|
# ██ ██
|
||||||
|
# ██████ ██
|
||||||
|
task_ci() {
|
||||||
|
tasks_run setup setup-dev client docs;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
#########################################################################
|
#########################################################################
|
||||||
|
|
||||||
tasks_run $@;
|
tasks_run $@;
|
||||||
|
|
|
||||||
7
docs/00-Welcome.md
Normal file
7
docs/00-Welcome.md
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
# Welcome!
|
||||||
|
|
||||||
|
> The Web Interface for the _Monitair_ project.
|
||||||
|
|
||||||
|
This is the documentation for [Air Quality Web](https://github.com/ConnectedHumber/Air-Quality-Web/), the air quality web interface that displays data from sensors scattered about the globe.
|
||||||
|
|
||||||
|
Check out the sections in the sidebar for documentation on the installation process, configuring an installation, and the HTTP API provided.
|
||||||
102
docs/01-Getting-Started.md
Normal file
102
docs/01-Getting-Started.md
Normal file
|
|
@ -0,0 +1,102 @@
|
||||||
|
# Getting Started
|
||||||
|
To get started, there are 3 main steps:
|
||||||
|
|
||||||
|
1. Cloning & building the application
|
||||||
|
2. Configuring the application
|
||||||
|
3. Configuration a web server
|
||||||
|
|
||||||
|
The process is outlined in detail below.
|
||||||
|
|
||||||
|
|
||||||
|
## System Requirements
|
||||||
|
- Git
|
||||||
|
- Bash (if on Windows, try [Git Bash](https://gitforwindows.org/)) - the build script is written in Bash
|
||||||
|
- PHP 7+ enabled web server
|
||||||
|
- _Nginx_ + _PHP-FPM_ is recommended
|
||||||
|
- Apache works too
|
||||||
|
- MariaDB database with the appropriate table structure pre-loaded
|
||||||
|
- Node.JS (preferably 10+) + [npm](https://npmjs.org/) 6+ (for installing & building the client-side app code)
|
||||||
|
- [Node.JS](https://nodejs.org/)
|
||||||
|
- [Composer](https://getcomposer.org/) (for installing server-side dependencies)
|
||||||
|
- PHP modules:
|
||||||
|
- `pdo-mysql` (for the database connection)
|
||||||
|
- A [MariaDB](https://mariadb.com/) server with a database already setup with the schema data in it. Please get in contact with [ConnectedHumber](https://connectedhumber.org/) for information about the database schema and structure.
|
||||||
|
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
1. Start by cloning this repository:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/ConnectedHumber/Air-Quality-Web.git
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
2. `cd` into the root of the cloned repository. Then install the dependencies (these are installed locally):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./build setup setup-dev
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
3. Build the client-side application:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
```
|
||||||
|
|
||||||
|
4. 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo chown -R www-data:www-data path/to/Air-Quality-Web
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
5. 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.
|
||||||
|
|
||||||
|
|
||||||
|
6. 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.
|
||||||
|
|
||||||
|
|
||||||
|
7. Disallow public access to the private `data` directory.
|
||||||
|
|
||||||
|
In Nginx:
|
||||||
|
|
||||||
|
```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:
|
||||||
|
|
||||||
|
```htaccess
|
||||||
|
# Create a file called ".htaccess" with this content inside the data/ directory
|
||||||
|
Require all denied
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
8. 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
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
9. (Optional) Setup HTTPS:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
sudo apt install certbot
|
||||||
|
# On Nginx:
|
||||||
|
sudo certbot --nginx --domain example.com
|
||||||
|
# On Apache:
|
||||||
|
sudo certbot --apache --domain example.com
|
||||||
|
```
|
||||||
110
docs/05-API-Docs.md
Normal file
110
docs/05-API-Docs.md
Normal file
|
|
@ -0,0 +1,110 @@
|
||||||
|
# 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
|
||||||
|
```
|
||||||
7
docs/README.md
Normal file
7
docs/README.md
Normal file
|
|
@ -0,0 +1,7 @@
|
||||||
|
# Air Quality Web
|
||||||
|
|
||||||
|
* [Welcome!](./00-Welcome.md)
|
||||||
|
* [Production Instance](https://aq.connectedhumber.org/app/)
|
||||||
|
* [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)
|
||||||
0
docs/theme.css
Normal file
0
docs/theme.css
Normal file
2
nightdocs.toml
Normal file
2
nightdocs.toml
Normal file
|
|
@ -0,0 +1,2 @@
|
||||||
|
[template]
|
||||||
|
project_name = "Air Quality Web Docs"
|
||||||
45
package-lock.json
generated
45
package-lock.json
generated
|
|
@ -144,6 +144,12 @@
|
||||||
"integrity": "sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg==",
|
"integrity": "sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg==",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
|
"await-fs": {
|
||||||
|
"version": "1.0.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/await-fs/-/await-fs-1.0.0.tgz",
|
||||||
|
"integrity": "sha1-QAnTAIYz/WYlqgCfCm8aujY38wE=",
|
||||||
|
"dev": true
|
||||||
|
},
|
||||||
"base": {
|
"base": {
|
||||||
"version": "0.11.2",
|
"version": "0.11.2",
|
||||||
"resolved": "https://registry.npmjs.org/base/-/base-0.11.2.tgz",
|
"resolved": "https://registry.npmjs.org/base/-/base-0.11.2.tgz",
|
||||||
|
|
@ -1406,6 +1412,12 @@
|
||||||
"integrity": "sha512-P+M65QY2JQ5Y0G9KKdlDpo0zK+/OHptU5AaBwUfAIDJZk1MYf32Frm84EcOytfJE0t5JvkAnKlmjsXDnWzCJmQ==",
|
"integrity": "sha512-P+M65QY2JQ5Y0G9KKdlDpo0zK+/OHptU5AaBwUfAIDJZk1MYf32Frm84EcOytfJE0t5JvkAnKlmjsXDnWzCJmQ==",
|
||||||
"dev": true
|
"dev": true
|
||||||
},
|
},
|
||||||
|
"html-entities": {
|
||||||
|
"version": "1.2.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/html-entities/-/html-entities-1.2.1.tgz",
|
||||||
|
"integrity": "sha1-DfKTUfByEWNRXfueVUPl9u7VFi8=",
|
||||||
|
"dev": true
|
||||||
|
},
|
||||||
"icss-replace-symbols": {
|
"icss-replace-symbols": {
|
||||||
"version": "1.1.0",
|
"version": "1.1.0",
|
||||||
"resolved": "https://registry.npmjs.org/icss-replace-symbols/-/icss-replace-symbols-1.1.0.tgz",
|
"resolved": "https://registry.npmjs.org/icss-replace-symbols/-/icss-replace-symbols-1.1.0.tgz",
|
||||||
|
|
@ -1805,6 +1817,12 @@
|
||||||
"object-visit": "^1.0.0"
|
"object-visit": "^1.0.0"
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
"marked": {
|
||||||
|
"version": "0.6.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/marked/-/marked-0.6.1.tgz",
|
||||||
|
"integrity": "sha512-+H0L3ibcWhAZE02SKMqmvYsErLo4EAVJxu5h3bHBBDvvjeWXtl92rGUSBYHL2++5Y+RSNgl8dYOAXcYe7lp1fA==",
|
||||||
|
"dev": true
|
||||||
|
},
|
||||||
"mdn-data": {
|
"mdn-data": {
|
||||||
"version": "1.1.4",
|
"version": "1.1.4",
|
||||||
"resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-1.1.4.tgz",
|
"resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-1.1.4.tgz",
|
||||||
|
|
@ -1949,6 +1967,27 @@
|
||||||
"resolved": "https://registry.npmjs.org/nanomodal/-/nanomodal-5.1.1.tgz",
|
"resolved": "https://registry.npmjs.org/nanomodal/-/nanomodal-5.1.1.tgz",
|
||||||
"integrity": "sha1-qiEiUSr49vpr3G8y1nqm3whvfK0="
|
"integrity": "sha1-qiEiUSr49vpr3G8y1nqm3whvfK0="
|
||||||
},
|
},
|
||||||
|
"nightdocs": {
|
||||||
|
"version": "1.0.1",
|
||||||
|
"resolved": "https://registry.npmjs.org/nightdocs/-/nightdocs-1.0.1.tgz",
|
||||||
|
"integrity": "sha512-JRX8iOjvW0wbYFNWH16deb8KFAQq9lM74IBT1SdtEjAyqetDs3DmsAsJNc/HRqft8QRcRDQmWsWeLbV4nrW0QQ==",
|
||||||
|
"dev": true,
|
||||||
|
"requires": {
|
||||||
|
"marked": "^0.6.1",
|
||||||
|
"nightink": "^0.1.2",
|
||||||
|
"toml": "^3.0.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"nightink": {
|
||||||
|
"version": "0.1.2",
|
||||||
|
"resolved": "https://registry.npmjs.org/nightink/-/nightink-0.1.2.tgz",
|
||||||
|
"integrity": "sha512-nAyyf1EvghaFtmwD4ox2rFiY0eWqAsW6rulIPaPC5IMv3YaNKYdQ4F7zUZ6E7eONEVQGtiCGTv6YksY9wHHs1g==",
|
||||||
|
"dev": true,
|
||||||
|
"requires": {
|
||||||
|
"await-fs": "^1.0.0",
|
||||||
|
"html-entities": "^1.2.1"
|
||||||
|
}
|
||||||
|
},
|
||||||
"node-releases": {
|
"node-releases": {
|
||||||
"version": "1.1.10",
|
"version": "1.1.10",
|
||||||
"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.10.tgz",
|
"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-1.1.10.tgz",
|
||||||
|
|
@ -4210,6 +4249,12 @@
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
"toml": {
|
||||||
|
"version": "3.0.0",
|
||||||
|
"resolved": "https://registry.npmjs.org/toml/-/toml-3.0.0.tgz",
|
||||||
|
"integrity": "sha512-y/mWCZinnvxjTKYhJ+pYxwD0mRLVvOtdS2Awbgxln6iEnt4rk0yBxeSBHkGJcPucRiG0e55mwWp+g/05rsrd6w==",
|
||||||
|
"dev": true
|
||||||
|
},
|
||||||
"union-value": {
|
"union-value": {
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.0.tgz",
|
"resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.0.tgz",
|
||||||
|
|
|
||||||
96
package.json
96
package.json
|
|
@ -1,45 +1,55 @@
|
||||||
{
|
{
|
||||||
"name": "air-quality-mapper",
|
"name": "air-quality-mapper",
|
||||||
"version": "0.1.0",
|
"version": "0.1.0",
|
||||||
"description": "The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project.",
|
"description": "The web interface and JSON api for the ConnectedHumber Air Quality Monitoring Project.",
|
||||||
"main": "index.mjs",
|
"main": "index.mjs",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"test": "echo \"Error: no test specified\" && exit 1"
|
"test": "echo \"Error: no test specified\" && exit 1"
|
||||||
},
|
},
|
||||||
"repository": {
|
"repository": {
|
||||||
"type": "git",
|
"type": "git",
|
||||||
"url": "git+https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface.git"
|
"url": "git+https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface.git"
|
||||||
},
|
},
|
||||||
"author": "Starbeamrainbowlabs",
|
"author": "Starbeamrainbowlabs",
|
||||||
"license": "MPL-2.0",
|
"license": "MPL-2.0",
|
||||||
"bugs": {
|
"bugs": {
|
||||||
"url": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface/issues"
|
"url": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface/issues"
|
||||||
},
|
},
|
||||||
"homepage": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface#readme",
|
"homepage": "https://github.com/sbrl/ConnectedHumber-Air-Quality-Interface#readme",
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"chart.js": "^2.7.3",
|
"chart.js": "^2.7.3",
|
||||||
"dom-create-element-query-selector": "github:hekigan/dom-create-element-query-selector",
|
"dom-create-element-query-selector": "github:hekigan/dom-create-element-query-selector",
|
||||||
"leaflet": "^1.4.0",
|
"leaflet": "^1.4.0",
|
||||||
"leaflet-fullscreen": "^1.0.2",
|
"leaflet-fullscreen": "^1.0.2",
|
||||||
"leaflet-timedimension": "^1.1.0",
|
"leaflet-timedimension": "^1.1.0",
|
||||||
"leaflet.markercluster": "^1.4.1",
|
"leaflet.markercluster": "^1.4.1",
|
||||||
"moment": "^2.24.0",
|
"moment": "^2.24.0",
|
||||||
"nanomodal": "^5.1.1",
|
"nanomodal": "^5.1.1",
|
||||||
"smartsettings": "^1.2.3",
|
"smartsettings": "^1.2.3",
|
||||||
"tabs": "^0.2.0"
|
"tabs": "^0.2.0"
|
||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@types/chart.js": "^2.7.48",
|
"@types/chart.js": "^2.7.48",
|
||||||
"@types/leaflet": "^1.4.3",
|
"@types/leaflet": "^1.4.3",
|
||||||
"@types/leaflet-fullscreen": "^1.0.4",
|
"@types/leaflet-fullscreen": "^1.0.4",
|
||||||
"leaflet-heatmap": "^1.0.0",
|
"leaflet-heatmap": "^1.0.0",
|
||||||
"postcss-copy": "^7.1.0",
|
"nightdocs": "^1.0.1",
|
||||||
"postcss-import": "^12.0.1",
|
"postcss-copy": "^7.1.0",
|
||||||
"rollup": "^1.6.0",
|
"postcss-import": "^12.0.1",
|
||||||
"rollup-plugin-commonjs": "^9.2.1",
|
"rollup": "^1.6.0",
|
||||||
"rollup-plugin-node-resolve": "^4.0.1",
|
"rollup-plugin-commonjs": "^9.2.1",
|
||||||
"rollup-plugin-postcss": "^2.0.3",
|
"rollup-plugin-node-resolve": "^4.0.1",
|
||||||
"rollup-plugin-replace": "^2.1.0",
|
"rollup-plugin-postcss": "^2.0.3",
|
||||||
"rollup-plugin-terser": "^4.0.4"
|
"rollup-plugin-replace": "^2.1.0",
|
||||||
}
|
"rollup-plugin-terser": "^4.0.4"
|
||||||
|
},
|
||||||
|
"docpress": {
|
||||||
|
"github": "ConnectedHumber/Air-Quality-Web",
|
||||||
|
"markdown": {
|
||||||
|
"xhtmlOut": true
|
||||||
|
},
|
||||||
|
"css": [
|
||||||
|
"docs/theme.css"
|
||||||
|
]
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue