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 values
    • 'oldest': will return the oldest values
    • 'avg' : 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