# 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.