Skip to content

v1.4.1 - ADC Refactoring & Hardware Documentation (2025-11-17)

Overview

A patch release focused on firmware refactoring and comprehensive hardware documentation. This release improves code maintainability by moving ADC channel dependency logic into a dedicated module with configurable build flags, and provides detailed hardware design documentation for developers and users.

What's New

✨ Major Features

🔧 ADC Channel Dependency Refactoring

Move configurable ADC channel handling from main.cpp into the adc_sensor module:

Before (v1.4.0): Inline ADC logic in main.cpp

// main.cpp - lines 122-124, 150-153
int sensorValue = adc_read();
if (detection.signal1 == 0) {
  sensorValue = 0;  // Hardware constraint hardcoded
}
// ... later ...
pinMode(ADC_IN, OUTPUT);
digitalWrite(ADC_IN, LOW);
pinMode(ADC_IN, ANALOG);
delay(1);

After (v1.4.1): Modular, configurable implementation

// main.cpp - 2 lines only
int sensorValue = adc_read_with_channel_filter(
    detection.signal1, detection.signal2, detection.signal3
);
adc_reset_pin_mode();

Benefits:

  • Responsibility Separation: ADC filtering logic in adc_sensor module
  • Configurability: Change hardware jumper position via build flag only
  • Code Reduction: 8 lines → 2 lines in main.cpp
  • Flexibility: Support ch1, ch2, ch3 without code changes
ADC_DEPEND_CHANNEL Configuration

Hardware jumper determines which channel the ADC reads from:

; platformio.ini
[env:esp32dev]
build_flags =
    -DADC_DEPEND_CHANNEL=1  ; Default: ch1 (current hardware)

Override via command line for testing:

# Build for ch1 (default)
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=1" pio run -t upload

# Build for ch2 position
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=2" pio run -t upload

# Build for ch3 position
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=3" pio run -t upload

📚 Comprehensive Hardware Documentation

Two new documentation files provide complete hardware reference:

1. ADC Design Documentation (docs/hardware/adc_design.md - 7.7KB)

Contents:

  • Physical ADC configuration and specifications
  • Channel dependency explanation (why ADC is coupled to specific channel)
  • Three configuration methods (platformio.ini, command line, build task)
  • Filtering logic and functional behavior
  • Design rationale and benefits
  • Usage scenarios for different hardware configurations
  • Troubleshooting guide with common issues
  • Performance characteristics
  • Future enhancement roadmap

Key Sections:

  • Overview of ADC hardware architecture
  • Jumper positions: CH1, CH2, CH3
  • Firmware configuration options
  • Functional behavior during detection
  • Design rationale (signal correlation, noise reduction)
  • Typical usage scenarios
  • Serial output format reference
2. GPIO Pinout Documentation (docs/hardware/gpio_pinout.md - 10KB)

Contents:

  • Complete ESP32-WROOM-32E pin allocation reference
  • Detailed tables for all 17 used pins
  • Physical layout diagrams
  • Pin conflict analysis
  • Power consumption breakdown
  • Hardware configuration file consolidation plan
  • Modification guide for adding new pins

Pin Groups:

  • Detection Channels (GPIO12, 19, 27)
  • LED Feedback (GPIO14, 26, 33)
  • ADC Input (GPIO32)
  • SPI DAC Control (GPIO5, 13, 15, 23, 18)
  • I2C Sensor Bus (GPIO21, 22)
  • Serial Communication (GPIO1, 3)
  • Button/Interrupt (GPIO0)

📖 Updated Documentation Structure

mkdocs.yml now organizes hardware documentation hierarchically:

Hardware:
  - Overview: hardware.md
  - ADC Design: hardware/adc_design.md
  - GPIO Pinout: hardware/gpio_pinout.md

📊 Code Metrics

Metric Value Change
RAM Usage 6.9% (22,592 bytes) -
Flash Usage 22.6% (296,409 bytes) -
Build Time ~2.5 seconds -
Lines Changed +101 (code), +579 (docs) -
Warnings 0 -
Errors 0 -

🔧 Technical Details

ADC Module Enhancements

New Functions in adc_sensor.h:

  1. int adc_read_with_channel_filter(int signal1, int signal2, int signal3)
  2. Reads ADC value with configurable channel dependency
  3. Applies filtering based on ADC_DEPEND_CHANNEL macro
  4. Returns 0 if dependent channel has no detection

  5. Supports ch1, ch2, ch3 configurations

  6. void adc_reset_pin_mode()

  7. Safely resets ADC pin after detection
  8. Sequence: OUTPUT → LOW → ANALOG → delay(1)
  9. Centralizes GPIO management for ADC pin

Implementation Location: src/adc_sensor.cpp (35 new lines)

Build Flag Configuration

The ADC_DEPEND_CHANNEL macro provides compile-time configuration:

// include/adc_sensor.h
#ifndef ADC_DEPEND_CHANNEL
#define ADC_DEPEND_CHANNEL 1  // Default: ch1
#endif

Configuration Methods:

  1. platformio.ini (persistent):
build_flags = -DADC_DEPEND_CHANNEL=1
  1. Command Line (one-time):
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=2" pio run -t upload
  1. Task System (if configured):
ADC_DEPEND_CHANNEL=3 task build

🐛 Bug Fixes

  • Code Smell: Duplicate ADC filtering logic removed from main.cpp
  • Maintainability: Scattered ADC configuration consolidated into module

📝 Documentation Improvements

  • Hardware Design: 7.7KB of detailed ADC documentation
  • GPIO Reference: 10KB comprehensive pinout reference
  • Legacy Cleanup: Removed redundant docs/pinout.md in favor of unified structure
  • Navigation: Restructured mkdocs.yml Hardware section with subsections

Installation

Via Git Tag

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

Build from Source

# Build firmware
task build

# Upload to ESP32
task upload

# Monitor serial output
task monitor

Specific Channel Configuration

To build firmware for different ADC channel jumper positions:

# Default (ch1 position - recommended)
task build && task upload

# For ch2 position hardware
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=2" pio run -t upload

# For ch3 position hardware
PLATFORMIO_BUILD_FLAGS="-DADC_DEPEND_CHANNEL=3" pio run -t upload

Changelog

Added

  • adc_read_with_channel_filter() function for configurable ADC channel dependency
  • adc_reset_pin_mode() function for safe GPIO pin reset
  • ADC_DEPEND_CHANNEL macro for compile-time configuration
  • ADC_DEPEND_CHANNEL build flag in platformio.ini (default: 1)
  • Comprehensive ADC design documentation (docs/hardware/adc_design.md)
  • Complete GPIO pinout reference (docs/hardware/gpio_pinout.md)
  • Hardware submenu in mkdocs.yml navigation

Changed

  • Moved ADC filtering logic from main.cpp to adc_sensor module
  • Shortened main.cpp ADC processing from 8 lines to 2 lines
  • Centralized ADC pin reset operation into dedicated function
  • Updated mkdocs.yml Hardware section with subsections

Removed

  • Legacy docs/pinout.md (replaced by unified hardware documentation)

Fixed

  • Code smell: Duplicate ADC configuration logic
  • Maintainability: Scattered pin mode operations consolidated

Documentation

  • 17.7KB of new hardware documentation added
  • ADC design rationale and configurations documented
  • Complete GPIO pin allocation reference created
  • Hardware documentation structure reorganized

Known Issues

None. This is a stable patch release.

Breaking Changes

None. This release is fully backward compatible with v1.4.0.

Testing

All changes have been verified:

  • ✅ Code compiles without warnings or errors
  • ✅ RAM usage unchanged (6.9%)
  • ✅ Flash usage unchanged (22.6%)
  • ✅ ADC module functionality maintains original behavior
  • ✅ All new functions documented with examples

Supported Hardware

  • Microcontroller: ESP32-WROOM-32E
  • SPI DAC: 3-channel digital potentiometer control
  • Sensors: BME280 (temperature, humidity, pressure)
  • ADC: 12-bit converter with configurable channel jumper
  • I2C: Standard 100kHz I2C bus
  • UART: 115200 baud serial communication

Compatibility

Dependency Version Status
PlatformIO >=6.1.18 ✅
Arduino ESP32 3.20017 ✅
Adafruit BME280 2.3.0 ✅
Adafruit BusIO 1.17.4 ✅

Upgrading from v1.4.0

This is a patch release with minimal changes:

  1. Firmware Update:
git pull origin main
git checkout v1.4.1
task build && task upload

  1. No Configuration Changes Required: Default ADC behavior (ch1) is identical to v1.4.0

  2. Documentation: New hardware documentation is available but optional to read

  • ADC Design Guide: docs/hardware/adc_design.md
  • GPIO Pinout Reference: docs/hardware/gpio_pinout.md
  • Hardware Overview: docs/hardware.md
  • API Documentation: docs/api/v1.md, docs/api/v2.md
  • Debugging Guide: docs/debug-mode.md

Contributors

  • Shota Takahashi (firmware, documentation)

License

MIT License - See LICENSE file for details

Release Information

  • Date: November 17, 2025
  • Version: 1.4.1
  • Git Tag: v1.4.1
  • Commits: 4 (66e13d0, 0ca795d, d76a6ec, 4cd9bc4)
  • Files Changed: 7 added, 1 deleted, 5 modified