v1.6.4 - BME280 Hardware Availability Detection (2025-11-19)

Overview

A patch release introducing BME280 hardware availability detection at firmware startup. The firmware now automatically detects whether the BME280 environmental sensor is physically connected and informs users via serial output when the sensor is not found. This enables the device to function with optional hardware while maintaining a consistent data output format.

Implementation: Hardware Feature Enhancement | Branch: 005-detect-bme280 | Commits: 9090a2b, 9da1313

What's New

✨ Major Features

🔍 BME280 Hardware Availability Detection

Automatic detection of BME280 sensor presence at startup with user feedback:

Detection Logic:

• Checks BME280 initialization return value during setup()
• Displays warning message if sensor not found
• Maintains consistent data output format regardless of sensor presence

Implementation:

// main.cpp (lines 67-70)
bool bme280_available = bme280_init(0x76);
if (!bme280_available) {
  serial_send_response("WARNING: BME280 not found, sensor values will be 0.0");
}

Warning Message (when sensor not detected):

WARNING: BME280 not found, sensor values will be 0.0

Data Output Format (unchanged, consistent):

signal1 signal2 signal3 adc_value temperature pressure humidity

With BME280 Connected:

100 85 92 2048 25.35 1013.25 45.67

Without BME280 Connected:

100 85 92 2048 0.0 0.0 0.0

📝 Hardware Documentation

Updated docs/hardware.md with comprehensive BME280 optional hardware section:

Specifications:

• Component: Adafruit BME280 (I2C interface)
• I2C Address: 0x76 (default)
• Measurements: Temperature (°C), Pressure (Pa), Humidity (%RH)
• Connection: I2C bus (SDA, SCL pins)

Hardware Availability Detection:

• Automatic detection at startup
• Clear warning message when not detected
• No configuration required

User Guide:

• Explains BME280 as optional hardware
• Documents data output format consistency
• Clarifies what 0.0 values mean
• Provides troubleshooting guidance

🔧 Implementation Details

Code Changes

Files Modified: 1

• src/main.cpp (lines 67-70)

Lines Added: 4

• Boolean check of bme280_init() return value
• Conditional warning message output

Backward Compatibility: 100%

• No existing features affected
• No breaking changes to hardware interface
• No changes to serial protocol format
• All existing commands work unchanged

Sensor Module Integration

Uses existing functions from bme280_sensor module: - bme280_is_initialized() - State tracking function

No new modules or dependencies required.

📊 Code Metrics

Metric	v1.6.3	v1.6.4	Change
RAM Usage	7.3%	7.3%	No change
Flash Usage	23.1%	23.1%	No change
Build Time	~2.5s	~1.5s	-1.0s (faster)
Source Lines	614	618	+4
Warnings	0	0	✓
Errors	0	0	✓

✅ Acceptance Criteria

User Story 1: Detect BME280 at Startup (P1)

• ✅ With BME280 connected → No warning message
• ✅ Without BME280 → Warning message displayed

User Story 2: Maintain Consistent Data Format (P1)

• ✅ 7-column format always maintained
• ✅ Format: signal1 signal2 signal3 adc_value temperature pressure humidity
• ✅ With sensor: Numeric temperature/pressure/humidity values
• ✅ Without sensor: 0.0 for temperature/pressure/humidity

User Story 3: Document Hardware Configuration (P2)

• ✅ BME280 documented as optional hardware in docs/hardware.md
• ✅ Data column meanings explained
• ✅ Startup warning message documented

Installation

Via Git Tag

git checkout v1.6.4
# or
git clone --branch v1.6.4 https://gitlab.com/osechi/kurikintons.git

Build from Source

# Set up environment
task env:setup

# Build development firmware (default)
task build

# OR build production release
task prod:build

# Upload to ESP32
task upload
# or
task dev:upload

# Monitor serial output
task monitor

Verifying Installation

With BME280 Sensor Connected:

task upload
task monitor
# Expected: No warning message during startup
# Detection output shows numeric sensor values

Without BME280 Sensor:

task upload
task monitor
# Expected: "WARNING: BME280 not found, sensor values will be 0.0"
# Detection output shows 0.0 for temperature/pressure/humidity

Changelog

Added

• BME280 Hardware Availability Detection: Automatic detection at startup with user notification
• Hardware Documentation: Comprehensive BME280 documentation in docs/hardware.md
• Specifications and pin configuration
• Hardware availability detection explanation
• Data output format consistency documentation
• Example outputs (with and without sensor)
• Progress Log: Detailed implementation and testing notes in docs/progress/entries/2025-11-19-bme280-detection.md

Changed

• Startup Sequence: BME280 initialization now includes presence detection
• Documentation: Updated REFACTORING_ROADMAP.md to mark feature complete

Fixed

• User Confusion: Clear notification when BME280 is not detected (vs. undiagnosed "zero values")
• Hardware Visibility: Users now immediately know sensor status at boot

Documentation

• Updated docs/hardware.md with optional hardware section
• Updated REFACTORING_ROADMAP.md to mark BME280 detection complete
• Added progress log with implementation details

Known Issues

None. This is a stable patch release.

Breaking Changes

None. All previous features and commands work unchanged:

• Firmware fully backward compatible with v1.6.3
• No serial protocol changes
• No command interface changes
• Data output format unchanged

Testing

All changes verified:

• ✅ Build succeeds without errors/warnings
• ✅ RAM usage unchanged (7.3%)
• ✅ Flash usage unchanged (23.1%)
• ✅ Hardware detection verified (with and without sensor)
• ✅ Warning message displays correctly
• ✅ Data output format remains 7 columns
• ✅ Sensor values correct (non-zero with sensor, 0.0 without)
• ✅ No regression in detection functionality
• ✅ No regression in other sensor modules
• ✅ Documentation accurate and complete

Hardware Compatibility

Supported Hardware

• Microcontroller: ESP32-WROOM-32E
• BME280 Sensor: Optional (I2C address 0x76)
• SPI DAC: 3-channel digital control
• ADC: 12-bit converter with configurable channel jumper
• I2C: Standard 100kHz I2C bus
• UART: 115200 baud serial communication

Optional Components

• BME280: Temperature/humidity/pressure sensor (optional)
• When connected: Full environmental data included in output
• When not connected: Gracefully outputs 0.0 values with startup warning

Software Compatibility

Component	Version	Status
PlatformIO	>=6.1.18	✅
Arduino ESP32	3.20017	✅
Adafruit BME280	2.3.0	✅
Adafruit BusIO	1.17.4	✅
go-task	>=3.34	✅
uv	>=0.4.0	✅

Upgrading from v1.6.3

This release improves hardware flexibility by adding BME280 availability detection:

1. Update Firmware:

git pull origin main
git checkout v1.6.4
task env:setup
task build && task upload

1. Verify Installation:

task monitor
# Check for absence of BME280 warning (with sensor)
# or presence of warning (without sensor)

1. No New Configuration Required:
2. Feature is automatic
3. No build flags or settings needed
4. Works seamlessly with existing setup

Use Cases

Development & Testing

• Verify hardware configuration without extra diagnostics
• Quickly identify missing sensor (check serial output)
• Test detection functionality across hardware variants

Production Deployment

• Clear user feedback for incomplete hardware installations
• Troubleshooting support (users know exactly what's missing)
• Flexible hardware support (same firmware, optional sensor)

Hardware Variants

• Minimal Setup: Detection-only without environmental sensor
• Full Setup: Detection with temperature/pressure/humidity monitoring
• Same Firmware: Single build supports both configurations

Related Documentation

• Progress Log - Implementation details
• CLAUDE.md - Developer guide and build instructions

Contributors

• Shota Takahashi (BME280 hardware detection, documentation, testing)

License

MIT License - See LICENSE file for details

Release Information

• Date: November 19, 2025
• Version: 1.6.4
• Git Tag: v1.6.4
• Commits: 6 (specification, planning, implementation, completion, version bump)
• Files Changed: 8 (main.cpp, hardware.md, REFACTORING_ROADMAP.md, progress log, specs, version bump)
• Build Size: 302,581 bytes Flash (maintained)
• Development Effort: Feature specification, planning, implementation, hardware testing

Acknowledgments

This release completes the BME280 hardware availability detection feature, improving user experience for deployments with optional hardware. The feature was developed following spec-driven development principles with comprehensive documentation and testing.