letteka
cdaaaad6af
Reviewed-on: #25 Co-authored-by: Andrew Kettel <andrew.kettel@gmail.com> Co-committed-by: Andrew Kettel <andrew.kettel@gmail.com>
106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
# BirdCam: A Flask-Based Camera Monitoring System
|
||
|
||
A lightweight, Python-based system for monitoring and managing Raspberry Pi cameras using Flask, SQLAlchemy, and modern Python best practices.
|
||
|
||
## 🚀 Overview
|
||
|
||
BirdCam is a simple yet robust application designed to monitor camera status and log events in real time. Built with Flask and SQLAlchemy, it provides:
|
||
- Real-time camera status tracking (`running` state).
|
||
- Event logging for camera actions (`start`, `stop`) with IP addresses and timestamps.
|
||
- A clean, maintainable architecture using modern Python 3.12 features and type hints.
|
||
|
||
It's ideal for hobbyists, developers, or IoT projects where you need to track camera activity from a central dashboard or script.
|
||
|
||
## 🔧 Key Features
|
||
|
||
- ✅ Real-time camera status (e.g., whether a camera is running or not).
|
||
- ✅ Event logging with full metadata (action, IP address, timestamp).
|
||
- ✅ Automatic creation of status records if missing.
|
||
- ✅ Type-safe, well-documented code with full type hints.
|
||
- ✅ Modern Python practices:
|
||
- Uses Python 3.12 with `__future__.annotations`.
|
||
- Leverages `dataclasses`-like patterns with `Mapped` and `mapped_column`.
|
||
- Includes comprehensive linting via **Black**, **Ruff**, and **Mypy**.
|
||
- ✅ Automated test coverage with `pytest` and `pytest-cov`.
|
||
|
||
## 📦 Dependencies
|
||
|
||
| Package | Version | Purpose |
|
||
|----------------------|---------------|------------------------------------------|
|
||
| `Flask` | `^3.0` | Web framework for serving the app |
|
||
| `Flask-SQLAlchemy` | `^3.1.1` | ORM for database interactions |
|
||
| `Pillow` | `^12.1.1` | Image processing (for camera previews) |
|
||
| `Gunicorn` | `^25.1.0` | Production WSGI server |
|
||
| `Pytest` | `^9.0.3` | Testing framework |
|
||
| `Pytest-Cov` | `^7.1.0` | Test coverage reporting |
|
||
| `Black` / `Ruff` | `^26.0` / `^0.4` | Code formatting and linting |
|
||
| `Mypy` | `^1.10` | Static type checking |
|
||
|
||
> ✅ All dependencies are pinned for stability and compatibility.
|
||
|
||
## 🛠️ Setup & Installation
|
||
|
||
1. Clone the repository:
|
||
```bash
|
||
git clone https://gitea.letteka.com/letteka/birdcam.git
|
||
cd birdcam
|
||
```
|
||
|
||
2. Install dependencies:
|
||
```bash
|
||
pip install -e .
|
||
```
|
||
|
||
3. Run the app:
|
||
```bash
|
||
gunicorn -w 1 -b 0.0.0.0:5000 app:app
|
||
```
|
||
|
||
Or use Flask’s built-in dev server:
|
||
```bash
|
||
flask run
|
||
```
|
||
|
||
## 📝 How It Works
|
||
|
||
### Camera Status
|
||
- The `CameraStatus` model tracks a single camera’s running state.
|
||
- On startup, it ensures a status record exists (ID = 1).
|
||
- The `get()` and `set_running()` methods allow safe access and updates.
|
||
|
||
### Camera Events
|
||
- Every time a camera action occurs (`start` or `stop`), an event is logged.
|
||
- Events include:
|
||
- Action type (`start` / `stop`)
|
||
- Client IP address
|
||
- Timestamp with timezone support
|
||
- The `recent()` method allows retrieval of the latest events (e.g., for logging or dashboard display).
|
||
|
||
## 🧪 Testing
|
||
|
||
The project includes full test coverage using `pytest` with coverage reporting:
|
||
|
||
```bash
|
||
pytest --cov=src --cov-report=term-missing
|
||
```
|
||
|
||
Tests are located in the tests/ directory and cover:
|
||
- Status retrieval and updates.
|
||
- Event logging and retrieval.
|
||
- Edge cases (e.g., missing status records).
|
||
## 📝 Development Workflow
|
||
✅ Code is formatted with Black and linted with Ruff.
|
||
✅ Static type checking is enforced using Mypy.
|
||
✅ All code uses consistent naming and formatting.
|
||
✅ All public APIs are documented with docstrings.
|
||
## ⚙️ Future Improvements
|
||
- Add support for multiple cameras.
|
||
- Integrate with a web dashboard (e.g., using Vue.js or Streamlit).
|
||
- Add camera preview functionality via HTTP endpoints.
|
||
- Support for MQTT or other event-driven systems.
|
||
- Add user authentication or role-based access.
|
||
## 📚 License
|
||
This project is open-source and available under the MIT License.
|
||
## 🙌 Contributing
|
||
Contributions are welcome! Please open an issue or submit a pull request with clear descriptions and tests.
|
||
📬 Contact: Andrew Kettel andrew.kettel@gmail.com |