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.
You are free to use our BEEP app and API.
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).
This repository. Serving both app v3 as app v2. Publicly available at https://api.beep.nl
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.
If you would like to install this BEEP API (the code in this) repo on your own server, or contribute; please read on below.
NB: We recommend to use Laravel Forge to easily install all the software you need on any Linux based server
git clone https://github.com/beepnl/BEEP.git
cd BEEP
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.
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
Simply use the default Nginx template and install Let's Encrypt SSL certificate via the interface.
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
Install InfluxDB or set up an account at InfluxCloud
./influx
for the commands from inside the installation folderwget 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
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!
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
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:
A simple setup for small installations can be achived with docker-compose. The tool will spinn up a mysqldb, influx, a webserver and initialize the beep database.
docker-compose.yaml
(set suitable environment variables).docker-compose up
. During the first start, you might see some database connectivity issues. Docker compose will restart the BEEP Server component untill a database connection is available. So don't worry.docker-compose exec mysql mysql -h localhost -P 3306 -ppass -u user -D bee_data -Bse "INSERT INTO role_user (user_id,role_id) VALUES(1,1);"
To upgrade beep to the latest version, simply stop and start docker-compose.
As the setup is based on docker containers, code changes inside the repository will not have an effeact till the underlying docker image is updated.
Thank you for considering contributing to the BEEP framework! If you would like to contribute, please fork this repository, edit on your Github account, and finally send Pull Requests to this repository to include new features.
Please request access to our slack community at https://beep-global.slack.com if you would like to know more, or cooperate.
Upcoming:
History:
Documentation and manual of the app can be found at https://beep.nl/beep-app.
API documentation of the BEEP API can be found at https://api.beep.nl/docs/.
Here we describe the first steps to setup a programming environment, in case you want to contribute to the app but are not yet a professional laravel developer.
If you setup your own BEEP instance, you might still want to have a local version running, so that you can test changes immedieatly.
Clone the repository to your Laptop or Computer.
We recomend using php version 8.0
We recommend to install and use Laravel Valet.
For Mac: https://laravel.com/docs/10.x/valet#installation (you might want to browse to the newest version)
For Linux: https://cpriego.github.io/valet-linux/
For Linux, make sure that you meet the requirements: https://cpriego.github.io/valet-linux/requirements
Install following additional php extensions: fpm, intl, gd, mysql
Make sure valet uses the correct php version
For Mac: valet use php@8.0
For Linux: valet use 8.0
fill out the .env file
Set APP_URL=beep.test
or choose an other url
Set the information for the mysql, influx and redis connections. If you connect to your remote server, make sure the ports are open on your server. You might also need to set a password for redis in this case.
Use php artisan key:generate
to generate a key and add it to your env file.
navigate to /public and run valet link
run valet secure
to add an ssl certificate
run composer install
and valet start
You should be able to access the app, e.g. on https://beep.test
Tips and Troubleshooting:
If you get an error like "Composer detected issues in your platform: Your Composer dependencies require a PHP version ">= 8.1.0"." you might need to run composer global update
You can also link your local vue app to this url in the .env file. If you do this and you get cors errors, this might be because of one of the following reasons:
The url you set is wrong. You have to open beep.test first (or your url) and add a security exception for your browser.
If you want to test your new api functions, we recommend to use Postman: https://www.postman.com/downloads/
In some cases, e.g. in case you made changes to the measurements database, you need to run php artisan cache:clear
to make the changes effective in your api calls.
If you discover a security vulnerability within BEEP, please send an e-mail to support@beep.nl.
The BEEP framework is open-sourced software licensed under the GNU AGPLv3 license.