- Introduction
- How to follow this docs
- System Architecture
- Detailed flow
- How to Setup
- Troubleshooting
- Things Left to Do
- Thanks
Are you a beekeeper? Do you struggle to keep control of your beehives and would like insights on what's going on, and possible actions to take, from your smartphone or laptop? Then our system is designed for you!
HiveGuard aims to improve beekeeping by leveraging modern technology to give beekeepers an edge in managing and monitoring their hives. This includes real-time video streaming, environmental sensing, machine learning for bee behavior analysis, and instant alerts - all integrated into an easy-to-use platform.
You will find a general overview of the system here, and linked you will find the software and documentation for every component. We recommend you read this docs first, and then read the docs for the Master Server, then the docs for the Streamer, and finally the docs for the Frontend.
The system is composed of three major components:
- Streamer: An ESP32CAM along with a DHT11 module attached to a hive for recording video, temperature, and humidity. Attach the streamer to your hive. It records video, temperature, and humidity, and streams this data to the master server over a local network.
- Master Server: A central server that processes data from the streamer. The master server uses machine learning to detect and analyze bee behaviors such as entering/leaving the hive and identifying ill bees. This server is intended to be run in a computer on the field where the hives are in, or in a raspberry pi. Its results are sent to the frontend.
- Frontend: A user interface that displays processed data and insights. The frontend generates charts and summaries, helping you make informed decisions such as when to place a pollen trap or identify potential hive issues. Alerts are sent to your email and displayed on the frontend.
This sequence diagram describes the initial connection and configuration process of the system. It starts with the beekeeper initiating the master server and ends with the streamer transmitting data to the master server.
The streamer sends the following data from itself to the master server:
id: Unique identifier for the ESP32 camera.wsPort: WebSocket port.appPort: Application port.display: Display name for the camera.ip: IP address of the streamer.
The ws and app (HTTP server) ports are generated dynamically, checking via a HTTP request if they're occupied or not. The UDP port is 12345 always and that's why it isn't sent.
This sequence diagram details how the beekeeper enters the master server's public URL in the frontend and how the initial parameters are configured and verified.
The frontend sends the following threshold and email parameters configuration:
{
"TEMP_MIN_THRESHOLD": 20,
"TEMP_MAX_THRESHOLD": 60,
"HUM_THRESHOLD": 80,
"EMAIL_USER": "test",
"EMAIL_PASS": "test",
"EMAIL_RECIPIENT": "test"
}EMAIL_RECIPIENT: The beekeeper's email entered in the frontend, where emails will be sent.EMAIL_USER: The email address from which emails will be sent.EMAIL_PASS: The API key (e.g., Gmail) for that email address.
You can get a Gmail API key by following this documentation.
This sequence diagram shows how the beekeeper queries updated hive data and how the frontend generates charts with temperature and humidity data.
This sequence diagram details how the frontend polls for alerts and how the master server sends email alerts to the beekeeper.
The following alerts can be generated:
- Humidity exceeds the threshold.
- Temperature exceeds the threshold.
- Temperature falls below the threshold.
- Hardware: ESP32-CAM modules for streamers, DHT11 sensors for temperature and humidity, a computer or Raspberry Pi for the master server.
- Software: All software and detailed setup instructions are available as open source. You can find the Git projects as submodules of this repository.
You can try the system using the mocks available in the master server to showcase some functionalities before deploying it to your hives.
To try the system on your hives:
- Initialize Master Server: Start the master server first.
- Streamer Initialization: Power on the ESP32CAM. It will launch an AP for WiFi credentials, connect to the network, and send a UDP broadcast message. The master server listens and starts a WebSocket connection.
- Save master server public URL: The server's webpage (localhost:8000/client) displays bee images, temperature, humidity data, and both local and public IP addresses. Save the master server public URL.
- Frontend Connection: A live version is available at this link. If unavailable, follow the local setup instructions in the documentation. Enter the master server's public URL in the frontend. The frontend performs a health check and establishes a connection to display hive data. Then it will ask you for config params such as thresholds for the alerts.
You can also find a video on how to set up the sytem here.
Having trouble? Here are some troubleshooting tips:
- Firewall Issues: If you encounter connectivity problems, ensure any firewalls on the master server's device are disabled.
- Connectivity: Make sure all devices are on the same network and properly configured.
Here are our next steps:
We are not beekepers, and the beekeper who is helping us is not a programmer, so this system needs further testing under real life scenarios. If you're a beekeper and a programmer, any feedback and contributions would be invaluable!
We developed a version that allows battery-powered streamers and battery level monitoring from the streamers. The battery level is displayed by the master server on its webpage and also in the frontend. We even created alerts for when the battery level exceeds a threshold, similar to how we handle humidity and temperature alerts, both via email and live alerts in the frontend!
The problem is that we didn't have enough pins on the ESP32-CAM. We had to read a general-purpose pin on the ESP32-CAM only during startup. When the device starts, it reads from the pin; if there is voltage, it means battery level monitoring is enabled. We save the battery level, stream it, work normally for 10 minutes, and then reboot the device to read the battery level again.
This is problematic because the re-connection takes time, during which we might lose data.
So, we thought of adding an extra ESP8266 device to the ESP32-CAM to use its additional pins. We could also attach an infrared movement sensor to record actual bee movement and save battery.
You can find more information about this in the "Things Left to Do" section in the master server and streamer projects.
Batch data transmission from streamers to optimize bandwidth usage and avoid congestion.
We would like to express our deep gratitude to:
- Jorge Seniw and his family: For letting us try the system, and helping us out with beekeeping related questions and issues. You can find him in this instagram account: La miel de papá
- Fabian Hickert: For his outstanding work on the machine learning neural network, which we used for detecting bees and identifying illnesses.
- Nomadic Geek: For his foundational surveillance system that inspired our project.
- Prof. Alexis Tcach: For his guidance and support throughout the development of HiveGuard.
Thank you for choosing HiveGuard! Whether you are a beekeeper, a programmer, or both, your contributions and feedback are invaluable. Feel free to fork, contribute, or contact us. Happy beekeeping!