moduleair_pro_4g/CLAUDE.md

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

# 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

# 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

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