135 lines
5.7 KiB
Markdown
135 lines
5.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
ModuleAir Pro 4G is an IoT air quality monitoring system built on Raspberry Pi CM4 with 4G cellular connectivity. It collects real-time environmental data through multiple sensors, stores data locally in SQLite, transmits to remote servers via cellular modem, and displays live data on a 128x64 RGB LED matrix.
|
|
|
|
## System Architecture
|
|
|
|
### Hardware Components
|
|
- **NPM Sensor**: Particulate matter (PM1/PM2.5/PM10) via Modbus RTU
|
|
- **MH-Z19**: CO2 sensor via UART serial
|
|
- **BME280**: Temperature/humidity/pressure via I2C
|
|
- **SARA R4**: 4G cellular modem for data transmission
|
|
- **Matrix LED**: 128x64 RGB display for real-time visualization
|
|
- **Push Button**: GPIO6 (GND) for screen mode cycling
|
|
- **RTC Module (DS3231)**: Real-time clock via I2C
|
|
- **Optional**: Sensirion SFA30 formaldehyde sensor
|
|
|
|
### Software Stack
|
|
- **Python 3**: Core data collection and processing
|
|
- **SQLite Database**: Local storage at `/var/www/moduleair_pro_4g/sqlite/`
|
|
- **Apache/PHP**: Web interface for configuration and monitoring
|
|
- **Systemd Services**: Automated data collection and transmission
|
|
- **C++ Matrix Library**: RGB LED matrix control (rpi-rgb-led-matrix)
|
|
|
|
### Data Flow
|
|
Sensors → Python Scripts → SQLite → {SARA R4 → Remote Servers, Matrix Display, Web Interface}
|
|
|
|
## Key Commands
|
|
|
|
### Installation & Setup
|
|
```bash
|
|
# Full system installation (run once)
|
|
sudo /var/www/moduleair_pro_4g/services/setup_services.sh
|
|
|
|
# Matrix LED library compilation
|
|
cd /var/www/moduleair_pro_4g/matrix/lib && make
|
|
|
|
# Apache configuration
|
|
sudo sed -i 's|DocumentRoot /var/www/html|DocumentRoot /var/www/moduleair_pro_4g|' /etc/apache2/sites-available/000-default.conf
|
|
sudo systemctl reload apache2
|
|
```
|
|
|
|
### Service Management
|
|
```bash
|
|
# Check all moduleair services status
|
|
systemctl list-timers | grep moduleair
|
|
systemctl status moduleair-npm-data.service
|
|
|
|
# Manual data collection
|
|
python3 /var/www/moduleair_pro_4g/NPM/get_data_modbus_v3.py
|
|
python3 /var/www/moduleair_pro_4g/MH-Z19/write_data.py
|
|
|
|
# Manual data transmission
|
|
python3 /var/www/moduleair_pro_4g/loop/SARA_send_data_v2.py
|
|
|
|
# Restart services
|
|
sudo systemctl restart moduleair-sara-data.timer
|
|
sudo systemctl restart moduleair-npm-data.timer
|
|
```
|
|
|
|
### Matrix LED Display & Button Control
|
|
```bash
|
|
# Compile matrix programs
|
|
cd /var/www/moduleair_pro_4g/matrix/lib && make
|
|
|
|
# Compile all display programs
|
|
g++ -I/var/www/moduleair_pro_4g/matrix/include -L/var/www/moduleair_pro_4g/matrix/lib /var/www/moduleair_pro_4g/matrix/screenNetwork/network_status.cc -o /var/www/moduleair_pro_4g/matrix/screenNetwork/network_status -lrgbmatrix -lsqlite3
|
|
g++ -I/var/www/moduleair_pro_4g/matrix/include -L/var/www/moduleair_pro_4g/matrix/lib /var/www/moduleair_pro_4g/matrix/screenSensors/displayAll4_v2.cc -o /var/www/moduleair_pro_4g/matrix/screenSensors/displayAll4_v2 -lrgbmatrix -lsqlite3
|
|
g++ -I/var/www/moduleair_pro_4g/matrix/include -L/var/www/moduleair_pro_4g/matrix/lib /var/www/moduleair_pro_4g/matrix/screenSensors/displayCO2_PM_Network.cc -o /var/www/moduleair_pro_4g/matrix/screenSensors/displayCO2_PM_Network -lrgbmatrix -lsqlite3
|
|
g++ -I/var/www/moduleair_pro_4g/matrix/include -L/var/www/moduleair_pro_4g/matrix/lib /var/www/moduleair_pro_4g/matrix/screenSensors/blank_screen.cc -o /var/www/moduleair_pro_4g/matrix/screenSensors/blank_screen -lrgbmatrix
|
|
|
|
# Start button-controlled display system
|
|
sudo systemctl restart moduleair-boot.service
|
|
|
|
# Manual button controller start
|
|
sudo python3 /var/www/moduleair_pro_4g/matrix/button_screen_controller.py
|
|
|
|
# Test button functionality only
|
|
sudo python3 /var/www/moduleair_pro_4g/test_button_controller.py
|
|
```
|
|
|
|
### Hardware Configuration Required
|
|
- Enable all UART ports in `/boot/firmware/config.txt`
|
|
- Enable I2C interface
|
|
- Set device permissions: `sudo chmod 777 /dev/ttyAMA* /dev/i2c-1`
|
|
- Configure sudo permissions for www-data user
|
|
|
|
## Automated Services (Systemd)
|
|
|
|
- **NPM Data**: Every 10 seconds (particulate matter)
|
|
- **CO2 Data**: Every 10 seconds
|
|
- **BME280 Data**: Every 120 seconds (temperature/humidity/pressure)
|
|
- **SARA Data Transmission**: Every 60 seconds (4G upload)
|
|
- **Database Cleanup**: Daily
|
|
- **Matrix Boot Display**: Once at startup (shows logo then starts button controller)
|
|
- **Matrix Button Controller**: Continuous (managed by boot service)
|
|
|
|
## Matrix Display Modes
|
|
|
|
The system features 4 button-controlled display modes accessible via GPIO6 push button:
|
|
|
|
1. **Network Status**: 4G and WiFi connectivity status with signal strength
|
|
2. **All 4 Sensors**: PM1, PM2.5, PM10, and CO2 measurements with quality indicators
|
|
3. **CO2 + PM + Network**: CO2, PM2.5, PM10 readings plus network status summary
|
|
4. **Blank Screen**: All pixels off (black screen)
|
|
|
|
Press the button connected to GPIO6 (GND when pressed) to cycle through modes. The system includes:
|
|
- 500ms debounce to prevent accidental double-presses
|
|
- Automatic program restart if display crashes
|
|
- Clean shutdown handling with proper GPIO cleanup
|
|
|
|
## Database Schema
|
|
|
|
SQLite database stores sensor readings with timestamps. Key tables include sensor data with datetime stamps for time-series analysis.
|
|
|
|
## Communication Protocols
|
|
|
|
- **Modbus RTU**: NPM particulate matter sensor
|
|
- **UART Serial**: CO2 sensor, 4G modem
|
|
- **I2C**: Environmental sensors, RTC
|
|
- **HTTP/HTTPS**: Data transmission to remote servers
|
|
- **MQTT**: Optional publishing via SARA module
|
|
|
|
## Configuration
|
|
|
|
- Main config: `/var/www/moduleair_pro_4g/config.json`
|
|
- Service logs: `/var/www/moduleair_pro_4g/logs/`
|
|
- Matrix input files: `/var/www/moduleair_pro_4g/matrix/input_*.txt`
|
|
|
|
## Web Interface
|
|
|
|
Local Apache server serves management interface at device IP address with real-time data visualization and system configuration. |