esp32_NPM_only/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

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

Build and Development Commands

Build the project:

pio run

Upload to ESP32:

pio run --target upload

Monitor serial output (115200 baud):

pio device monitor

Build and upload in one command:

pio run --target upload && pio device monitor

Clean build files:

pio run --target clean

Hardware Configuration

• Board: ESP32 dev board
• Serial Configuration:
  • Debug serial: Serial (USB, 115200 baud)
  • NPM serial: Serial1 (UART1, 115200 baud, 8E1 parity)
  • RX Pin: GPIO 39
  • TX Pin: GPIO 32

Architecture

Serial Communication Protocol

The NextPM sensor uses a binary protocol with checksums. Communication follows a request-response pattern with specific message formats:

Message Structure:

• Header (2 bytes): Command identifier (e.g., 0x81 0x16)
• State (1 byte): Device state bits
• Data (variable): Response payload
• 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

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

Loop Behavior:

• Reads sensor every 60 seconds (configurable via interval constant)
• Non-blocking timing using millis()

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
• platformio.ini: PlatformIO configuration for ESP32

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