PaulVua/esp32_NPM_only
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation: Add README and revise CLAUDE.md

Browse Source 
- Created comprehensive README.md with:
  - Project overview and features
  - Hardware requirements and wiring diagram
  - Installation and usage instructions
  - Detailed troubleshooting guide
  - Learning objectives for students
  - NextPM protocol reference

- Updated CLAUDE.md to reflect:
  - Simplified educational implementation
  - Removal of particle counts
  - Current function structure
  - Educational focus and objectives

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
PaulVua
2025-11-06 11:50:27 +01:00
parent 31127ff783
commit da7fafabda
2 changed files with 412 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
CLAUDE.md
View File

@@ -4,7 +4,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
This is a PlatformIO-based ESP32 Arduino project for communicating with a NextPM (NPM) particulate matter sensor over serial connection. The project reads PM1, PM2.5, and PM10 measurements in both µg/m³ and particles per liter (pcs/L).
This is a **simplified, educational** PlatformIO-based ESP32 Arduino project for communicating with a NextPM (NPM) particulate matter sensor over serial connection. The project reads PM1, PM2.5, and PM10 mass concentration measurements in µg/m³.
**Educational Focus:**
- Extensively commented code to help students understand serial communication protocols
- Simplified implementation focusing only on PM concentration readings (particle counts removed)
- Clear step-by-step documentation of the sensor communication process
- Non-blocking timing pattern demonstration
## Build and Development Commands
@@ -46,46 +52,55 @@ pio run --target clean
### Serial Communication Protocol
The NextPM sensor uses a binary protocol with checksums. Communication follows a request-response pattern with specific message formats:
The NextPM sensor uses a binary protocol with checksums. Communication follows a request-response pattern:
**Message Structure:**
- Header (2 bytes): Command identifier (e.g., `0x81 0x16`)
**Message Structure (16 bytes total):**
- Header (2 bytes): `0x81 0x12` (concentration response identifier)
- State (1 byte): Device state bits
- Data (variable): Response payload
- Data (12 bytes): 6 values × 2 bytes each
- Bytes 0-5: N1, N2.5, N10 particle counts (not used in this simplified version)
- Bytes 6-11: PM1, PM2.5, PM10 mass concentrations
- Checksum (1 byte): Sum of all bytes mod 0x100 must equal 0
**State Machine Enums:**
The code uses multiple enums (`NPM_waiting_for_4`, `NPM_waiting_for_8`, `NPM_waiting_for_16`) to track parsing state for different response types (4, 8, or 16 bytes total).
### Key Functions
**Initialization (`powerOnTestNPM`):**
- Waits 15 seconds for sensor startup
- Queries sensor state
- Starts sensor if stopped
- Reads firmware version and temperature/humidity
**`checksum_valid()`**
- Validates 16-byte messages using checksum algorithm
- Returns true if sum of all bytes modulo 256 equals 0
**Measurement (`fetchSensorNPM_1min`):**
- Sends concentration command (1-minute averaged readings)
- Parses 16-byte response containing 6 values:
- N1, N2.5, N10 (particle counts as pcs/L)
- PM1, PM2.5, PM10 (mass concentrations as µg/m³ × 10)
- Validates checksum before accepting data
**`send_concentration_command()`**
- Sends 3-byte command sequence: `{0x81, 0x12, 0x6D}`
- Requests 1-minute averaged concentration readings
**Loop Behavior:**
- Reads sensor every 60 seconds (configurable via `interval` constant)
- Non-blocking timing using `millis()`
**`read_concentration()`**
- Main sensor reading function with 11 documented steps
- Sends command, waits for response (3-second timeout)
- Validates header and checksum
- Extracts PM1, PM2.5, PM10 values from data bytes
- Converts scaled values (÷10) to actual µg/m³
- Displays results on serial monitor
**`setup()`**
- Initializes USB serial (115200 baud) for debugging
- Initializes sensor serial (115200 baud, 8E1 parity)
- Waits 15 seconds for sensor power-up
**`loop()`**
- Non-blocking timing implementation using `millis()`
- Reads sensor every 10 seconds (configurable via `interval`)
- Demonstrates proper Arduino timing patterns
### File Organization
- `src/main.cpp`: Main application logic, NPM protocol implementation, sensor state machine
- `src/utils.h`: Protocol constants, enums, checksum validation prototypes
- `src/utils.cpp`: Utility functions for checksum validation and NPM command transmission
- `src/main.cpp`: Complete application in single file with extensive educational comments
- `platformio.ini`: PlatformIO configuration for ESP32
- `CLAUDE.md`: Developer guidance for AI assistance
- `README.md`: User documentation and getting started guide
## Important Notes
- The sensor requires a 3-second timeout for serial responses
- All particle concentration values from the sensor are scaled (PM values by 10, temperature/humidity by 100)
- The `nextpmconnected` flag prevents infinite loops if sensor disconnects
- Comments are in French in some sections of the code
- PM values from the sensor are scaled by 10 (e.g., 25.3 µg/m³ sent as 253)
- The 15-second startup delay is critical - sensor won't respond if queried too early
- All comments are in English for educational purposes
- Code emphasizes readability and learning over performance optimization