179 lines
5.1 KiB
Markdown
Executable file
179 lines
5.1 KiB
Markdown
Executable file
# BlueWeather
|
|
|
|
A (hopefully soon) fully featured selft-hosted web interface and server-backend to store weather data (comparable to opensensemap.org)
|
|
|
|
# State of development
|
|
- readonly frontend is working
|
|
- login is working
|
|
|
|
# Installation
|
|
1. Install the required packages
|
|
```
|
|
sudo apt install git apache2 mysql-server mysql-client php libapache2-mod-php php-mysql php-cli php-common -y
|
|
```
|
|
2. Prepare the working directory and download SafeMail
|
|
```
|
|
cd /var/www/html/
|
|
|
|
git clone https://git.itsblue.de/dorian/blueweather.git
|
|
```
|
|
3. Create the database
|
|
```
|
|
sudo mysql -u root
|
|
|
|
CREATE DATABASE blueweather;
|
|
```
|
|
4. now create the database user, if you change the username, password or database name, don't forget to change that data in the config.php file!
|
|
|
|
```
|
|
GRANT ALL ON blueweather.* TO 'blueweather'@'localhost' IDENTIFIED BY 'root';
|
|
|
|
FLUSH PRIVILEGES;
|
|
|
|
exit;
|
|
```
|
|
5. Prepare database for usage (create Tables and Keys)
|
|
```
|
|
cd /var/www/html/blueweather/api
|
|
|
|
sudo mysql -u root blueweather < blueweather.sql
|
|
```
|
|
Your BlueWeather instance can now be reached under: <your_ip>/blueweather
|
|
|
|
|
|
# API docs
|
|
|
|
## get locations
|
|
triggered by setting no GET parameter at all
|
|
### Parameters
|
|
no parameters
|
|
|
|
### Tags
|
|
- id
|
|
- locationname
|
|
- latitude
|
|
- longitude
|
|
- countryname
|
|
|
|
## get location data
|
|
triggered by setting GET parameter 'locId' to a vaild location id
|
|
### Parameters
|
|
- locId: id of the location to display
|
|
- range: range of the data to display in unix time
|
|
- from
|
|
- to
|
|
- max vals:
|
|
- count: maximum measvals to be transmitted
|
|
- mode: can be:
|
|
- 'newest': will return the newest <maxVals> values
|
|
- 'oldest': will return the oldest <maxVals> values
|
|
- 'avg' : <maxVals> sub avarages will be calculated
|
|
|
|
### Tags
|
|
- id
|
|
- locationname
|
|
- latitude
|
|
- longitude
|
|
- countryname
|
|
- measvalues
|
|
- measvalue
|
|
- sensorid
|
|
- timestamp
|
|
- sensors
|
|
- id
|
|
- added
|
|
- userid
|
|
- sensorname
|
|
- property ('indoor' || 'sunny' || 'shadow')
|
|
- valuetypeid
|
|
- valuetypes
|
|
- id
|
|
- valuetype ('temperature' || 'humidity' || 'pressure' || 'fine dust')
|
|
- valueunit (html coding)
|
|
- displayproperty
|
|
- widget (properties for small widget)
|
|
- type ('doughnut' || 'text')
|
|
- properties (chartjs dataset properties if type is a chartjs type)
|
|
- chart (properties for large chart)
|
|
- type ('scatter')
|
|
- properties (chartjs dataset properties)
|
|
- range (actual range of present measvalues)
|
|
- from
|
|
- to
|
|
|
|
## submit sensor data
|
|
triggered by setting POST parameter 'submitSensorData' to a JSON encoded string containing the request
|
|
### Request
|
|
- identity: identity of the api token (given by webinterface)
|
|
- signature: hash_hmac with SHA256 of 'data' string with an API-key as key
|
|
- data: JSON array[array[
|
|
sensorId,
|
|
measvalue,
|
|
timestamp
|
|
]]
|
|
CAUTION!! This MUST be a string and NOT direct JSON!!
|
|
### Reply
|
|
- status:
|
|
- 200: was inserted
|
|
- 400: format of request was wrong
|
|
- 401: signture verify failed
|
|
- 404: key identity was not found
|
|
- 500: internal error
|
|
- 900: format of data JSON string was invalid
|
|
- 901: signature was fine but one or more sensors have been ignored due to some error (see 'data') all other sensors were processes successfully
|
|
- data: Array[Array[sensorId, errorCode]] sensors which were ignored due to some error (401: user doesn't own sensor; 404: senso wasn't found)
|
|
only set if status is 901
|
|
|
|
## edit user data
|
|
- requests to change user specific data (like adding/removing sensors/api-keys, etc.)
|
|
- this type of request is triggered by setting GET parameter 'command' to a JSON encoded string containing the request
|
|
- request structure: (JSON object)
|
|
- header: (int) containing the desired command
|
|
- body: (mixed)(optional) containing the individual request
|
|
- reply structure: (JSON object)
|
|
- header: (int) indicating if the request was successfull (mostly like HTTP status codes)
|
|
- body: (mixed)(optional) containing further data depending on the request
|
|
---
|
|
### login
|
|
submit username and password to get a session token which can be used to authenticate any further commands
|
|
#### Request
|
|
- header: 1000
|
|
- body: (object)
|
|
- username: (string)
|
|
- password: (string)
|
|
#### Reply
|
|
- header: (int)
|
|
- 200: OK
|
|
- 400: invalid request
|
|
- 401: invalid username or password
|
|
- body: (string) (only set when header is 200) session-token
|
|
---
|
|
### logout
|
|
submit session token to destroy the session
|
|
#### Request
|
|
- header: 1002
|
|
- body: (string) session-token
|
|
#### Reply
|
|
- header: (int)
|
|
- 200: OK
|
|
- 400: invalid request
|
|
- 401: invalid session-token
|
|
|
|
#### Reply
|
|
- header: (int)
|
|
---
|
|
### get user information
|
|
submit a sesion token to check if it s valid and get some information about the user if it is
|
|
#### Request
|
|
- header: 1001
|
|
- body: (string) the session token to be checked
|
|
#### Reply
|
|
- header: (int)
|
|
- 200: OK
|
|
- 400: invalid request
|
|
- 401: the token is invalid
|
|
- body: (object) (only set when header is 200)
|
|
- username: (string) username of the user the session belongs to
|
|
- realname: (string) full name of the user the session belongs to
|
|
|
|
|