BEEP - Open source bee monitoring (v3.0.1)

BEEP is open source combination of a bee monitoring app + automatic bee hive measurement device. It's key feature is to integrate a user friendly responsive web app for manual inspections with automatically measured sensor data. Check the website https://beep.nl/index.php/home-english for more information.

BEEP System overview

You are free to use our BEEP app and API.

BEEP App

The BEEP app is a VUE app, communicating with a (Laravel PHP) BEEP API (this repository).

NB: The BEEP VUE (v3) app replaced the BEEP Angular JS (v2) app in 2021.

The BEEP app is publicly available at: https://app.beep.nl. It has about 5000+ users worldwide and is available in 9 languages (Jan 2022).

BEEP API / Backend

This repository. Serving both app v3 as app v2. Publicly available at https://api.beep.nl

BEEP base

The BEEP base v3 is an open source ultra low power automatic hive monitoring system. Design of the device and PCB (with accompanying firmware) be found at [this repository]](https://github.com/beepnl/measurement-system-v3). It measures weight, temperature and sound. We produce a yearly batch of BEEP bases for the European (868MHz LoRaWAN) market, that are sold via the BEEP webshop. The BEEP base sends it's data through The Things Network LoRaWAN to the BEEP API.

You can also use your own measurement device with the BEEP app by POSTing your measurement data to the BEEP API.

The BEEP base can be configured by Bluetooth using our native BEEP base apps for Android and iOS.

BEEP API Installation

If you would like to install this BEEP API (the code in this) repo on your own server, or contribute; please read on below.

0. Server specs

• Linux Debian (8+)
• Software installed
  • PHP 7.4+
  • MariaDB/MySQL
  • Apache 2 (or Nginx, creating Nginx 'server blocks' in step 4)
  • InfluxDB (https://docs.influxdata.com/influxdb/v1.7/introduction/installation/)
  • Composer - Installation tool for PHP/Laravel dependencies for API
• Optional: Letsencrypt SSL certificate generation

NB: We recommend to use Laravel Forge to easily install all the software you need on any Linux based server

1. Clone this repo

git clone https://github.com/beepnl/BEEP.git
cd BEEP

2. Database

Create a MySQL database (type: InnoDB, encoding: UTF_8, collation: utf8mb4_unicode_ci) called:

bee_data

NB: Make sure to pass the user and credentials to the newly made .env file after step 3.

3. Install dependencies

if [ ! -f '.env' ]; then cp .env.example .env && php artisan key:generate; fi
composer install && sudo chmod -R 777 storage && sudo chmod -R 777 bootstrap/cache && php artisan storage:link && php artisan migrate --force

NB: To stick to a certain PHP version (on the server e.g. 7.4.33), use composer install --ignore-platform-reqs or composer update --ignore-platform-reqs

4. Set up your end-points

Laravel Forge

Simply use the default Nginx template and install Let's Encrypt SSL certificate via the interface.

Apache

Install the desired config files from /apache to your apache/sites-available folder and enable them with a2ensite [config file name]

Install SSL certificates to your endpoints with Let's Encrypt

5. Add Influx database

Installation

Install InfluxDB or set up an account at InfluxCloud

Optional: migrate from local Influx v1.7.3 db to managed InfluxDB Cloud

• https://docs.influxdata.com/influxdb/cloud/upgrade/v1-to-cloud/
• NB: If you have influx already installed, use ./influx for the commands from inside the installation folder

wget https://dl.influxdata.com/influxdb/releases/influxdb2-client-2.0.6-linux-amd64.tar.gz
tar xvfz influxdb2-client-2.0.6-linux-amd64.tar.gz
cd influxdb2-client-2.0.6-linux-amd64
./influx config create --config-name beep-cloud-test --host-url https://eu-central-1-1.aws.cloud2.influxdata.com --org [your-email] --token [copy-from-influx-cloud] --active
./influx v1 dbrp create --db [influx-v1-db-name] --rp autogen --bucket-id [copy-from-influx-cloud] --default
sudo influx_inspect export -datadir /var/lib/influxdb/data -waldir /var/lib/influxdb/wal -database test_beep_nl -retention autogen -start 2021-01-01T00:00:00Z -end 2022-01-01T00:00:00Z -out test_beep_nl_temp.lp
sudo tail -n +4 test_beep_nl_temp.lp > test_beep_nl.lp
./influx write --bucket-id [copy-from-influx-cloud] --file test_beep_nl.lp --rate-limit "300 MB / 5 min" --skipRowOnError

Setup

Create a databse and user

influx
> CREATE USER user_influx WITH PASSWORD 'pass_influx' WITH ALL PRIVILEGES
> CREATE DATABASE bee_data
> exit

NB: Make sure to pass the user and credentials to the .env file that has been created in step 3. NB: If your Influx version was < 1.1.x (no TSI support), when using backups to transfer data: first install the old version that you are currently using on a new server, import the backups, then update to the newest Influx version!

Configuring your own back-end system

1. Set up valid credentials

a. Set up e-mail credentials in the .env config file

b. (Angular JS webapp v2) For the webapp to reach the API, rename the file 'public/webapp/js/constants.js.example' to 'public/webapp/js/constants.js' and edit it to change the 'api_url' to your own back-end API end-point

c. To enable schedules (e.g. for loading weather data), install a crontab with sudo crontab -e and add: * * * * * cd /home/bitnami/apps/appdir && /opt/bitnami/php/bin/php artisan schedule:run >> /dev/null 2>&1

2. Register new user

a. Go to api.[your_domain]/webapp#!/login/create

b. Create a new user

c. Promote the user to 'superadmin'

Open your database (with a database viewer like PhpMyadmin, Sequel Pro, MySQL Workbench, etc.), or just do a command line query: Define a relation in table role_user with (1,1) (linking user_id 1 to role_id 1).

Your user has just been promoted to the super administrator of the system, so you can use the back-end management interface to configure the complete system.

d. Go to api.[your_domain]/admin to log in with the same credentials that you created your app user with in step 3b.

e. You should see the back-end dashboard, looking like this:

Management interface

Installation using docker compose

A simple setup for small installations can be achived with docker-compose. The tool will spin up a webserver and initialize the beep mysql and influxdb database.

1. Install docker-compose
2. Checkout BEEP and switch into the code repository
3. Make your own .env file: run cp .env.example .env
4. Create a free mailtrap.io account
5. Fill in your mailtrap username & password in your .env file for MAIL_USERNAME and MAIL_PASSWORD (find it in your mailtrap account via Email Testing -> My inbox -> Integration)
6. Run

`php artisan key:generate`
`composer install && sudo chmod -R 777 storage && sudo chmod -R 777 bootstrap/cache`
`docker-compose up -d --build`
`docker-compose run --rm artisan migrate --seed`

7. Optional: verify whether the docker containers are running: run docker ps
8. Check whether backend login page is working
9. If everything is running smoothly, create a login via the frontend webapp BEEP VUE (v3) app. To connect the BEEP VUE app with the BEEP backend, make sure to specify the following .env variables in your local BEEP VUE app installation: VUE_APP_API_URL = http://localhost:8087/api/ VUE_APP_BASE_API_URL = http://localhost:8087/ (Psssst there is a shortcut for creating a login: just use the old BEEP Angular JS (v2) app app directly, via http://localhost:8087/webapp#!/login/create but beware to only use it to create your login, as the rest of the app is deprecated! (The v3 app replaced the v2 app in 2021))
10. With your newly created login, login to the backend. N.B. verification email from the previous step will be send to your mailtrap inbox
11. Give your newly created user the superadmin role, via phpmyadmin (server: mysql, user: root, password: secret): Go to bee_data db, users table, check your user id. Then in the role_user table, edit the role_id for that user_id to '1 - superadmin' and save.
12. Now setup Influxdb for the measurements data. Create a login via the Influxdb onboarding UI (choose your username and password, organization: beep, database: bee_data). Then copy and store the API token.
13. Add your Influxdb credentials to your .env file for INFLUXDB_USER and INFLUXDB_PASSWORD and the influx-configs file at storage/influxdb2/config like so: [yourusername] url = "http://localhost:8086" token = "your API