blueweather/README.md

# 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