blueweather/README.md

128 lines
3.4 KiB
Markdown
Raw Normal View History

2019-07-11 13:24:13 +02:00
# BlueWeather
2019-07-11 14:08:50 +02:00
A (hopefully soon) fully featured selft-hosted web interface and server-backend to store weather data (comparable to opensensemap.org)
2019-07-11 13:52:01 +02:00
# State of development
2019-07-11 14:08:50 +02:00
- interface and backend planned
2019-07-15 20:29:19 +02:00
- readonly dashboard is working
2019-07-14 16:36:59 +02:00
2019-07-27 13:41:48 +02:00
# 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
2019-07-14 16:36:59 +02:00
# API docs
2019-07-15 18:56:51 +02:00
## get locations
triggered by setting no GET parameter at all
### Parameters
2019-07-15 20:29:19 +02:00
no parameters
2019-07-15 18:56:51 +02:00
### 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
2019-07-30 13:08:00 +02:00
- 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
2019-07-15 18:56:51 +02:00
### Tags
2019-07-14 16:36:59 +02:00
- id
- locationname
- latitude
- longitude
- countryname
- measvalues
- measvalue
- sensorid
- timestamp
- sensors
- id
- added
- userid
- sensorname
- property ('indoor' || 'sunny' || 'shadow')
2019-07-14 16:36:59 +02:00
- valuetypeid
- valuetypes
- id
- valuetype ('temperature' || 'humidity' || 'pressure' || 'fine dust')
2019-07-14 21:38:50 +02:00
- valueunit (html coding)
2019-07-14 16:36:59 +02:00
- displayproperty
- widget (properties for small widget)
2019-07-14 17:51:25 +02:00
- type ('doughnut' || 'text')
2019-07-14 16:36:59 +02:00
- 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
2019-07-15 20:29:19 +02:00
## 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)
2019-07-30 13:08:00 +02:00
- signature: hash_hmac with SHA256 of 'data' string with an API-key as key
2019-07-29 13:51:36 +02:00
- 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
2019-07-15 20:29:19 +02:00
2019-07-30 13:08:00 +02:00
##