Skip to content

v1.5.0 - Runtime Configuration & Text Commands (2025-11-18)

Overview

A minor release introducing runtime configuration management and text-based command interface. This release enables dynamic firmware configuration without recompilation, allowing users to adjust detection sensitivity, sample rates, and thresholds at runtime through a simple serial command protocol.

Implementation: Feature 002-add-runtime-config | Branch: 002-add-runtime-config | Commit: 062f610

What's New

✨ Major Features

🔧 Runtime Configuration System

Introduces in-memory configuration management with persistent interface:

Key Features:

  • Sample Count Configuration: Adjust detection sample count (1-1000) at runtime
  • Threshold Management: Set per-channel detection thresholds (0-4095 12-bit range)
  • DAC Integration: Automatically update SPI DAC values when thresholds change
  • Version Tracking: Firmware version accessible via configuration interface
  • RAM-only Storage: Configuration resets on power cycle (no EEPROM wear)

Configuration Structure:

typedef struct {
  uint16_t sample_count;      // Detection samples per cycle (1-1000)
  uint16_t threshold_ch1;     // Channel 1 threshold (0-4095)
  uint16_t threshold_ch2;     // Channel 2 threshold (0-4095)
  uint16_t threshold_ch3;     // Channel 3 threshold (0-4095)
  const char* firmware_version; // Current firmware version
} RuntimeConfig;

📝 Text Command Interface

New serial protocol for runtime configuration using simple text commands:

Command Format:

<command> <ch> <param1> [param2]

Supported Commands:

  1. Sample Count Configuration (S command)
S <count>              # Set sample count (1-1000)
Example: S 100         # Set to 100 samples per cycle
  • Returns: ok on success or err if out of range

  • Error code: Invalid if count < 1 or count > 1000

  • Threshold Configuration (T command)

T <ch> <value>         # Set threshold for channel (0-4095)
Example: T 1 2048      # Set ch1 threshold to 2048 (mid-scale)
  • Channels: 1, 2, 3
  • Value range: 0-4095 (12-bit ADC range)
  • Returns: ok on success or err if invalid

  • Automatically updates SPI DAC control

  • Version Query (V command)

V                      # Get firmware version
Response: 1.5.0
  • Returns current firmware version

  • Synced with pyproject.toml via commitizen

  • Status Query (I command)

I                      # Get current configuration
Response: S:100 T1:0 T2:0 T3:0 V:1.5.0
  • Returns all configuration values in compact format

Serial Protocol Details:

  • Baud rate: 115200 bps
  • Terminator: newline character (\n)
  • Response format: Single-line text
  • Error indicator: err prefix
  • Maximum command length: 32 bytes

Usage Examples:

# Set detection sample count
echo "S 150" > /dev/ttyUSB0

# Configure channel 1 threshold
echo "T 1 2048" > /dev/ttyUSB0

# Query all configuration
echo "I" > /dev/ttyUSB0

# Check firmware version
echo "V" > /dev/ttyUSB0

📚 Protocol Documentation

Comprehensive communication protocol documentation added:

Protocols Documented:

  • UART Protocol (docs/protocols/uart.md) - Serial command interface detailed spec
  • SPI Protocol (docs/protocols/spi.md) - DAC communication and control signals
  • I2C Protocol (docs/protocols/i2c.md) - BME280 sensor communication
  • High/Low Protocol (docs/protocols/high-low.md) - GPIO detection signal formats

Key Sections:

  • Command syntax and examples
  • Response formats and error handling
  • Timing requirements and signal definitions
  • Usage scenarios and common patterns

🛠️ Monitoring & Debugging Tools

New documentation for development tools:

Device Monitor (docs/develop/platformio-device-monitor.md):

  • PlatformIO serial monitor setup and usage
  • Filter configuration for different log levels
  • Troubleshooting connection issues

📋 Development Documentation

Specification Documents (specs/002-add-runtime-config/): - plan.md - Implementation roadmap and architecture - quickstart.md - Developer quick start guide - checklists/requirements.md - Feature requirements checklist

Progress Tracking (docs/progress/entries/2025-11-18-runtime-config-implementation.md):

  • Implementation progress log
  • Design decisions and rationale
  • Testing and validation notes

🔄 Version Management Improvements

Automatic Version Synchronization:

Configuration added to pyproject.toml:

[tool.commitizen]
version_files = [
    "pyproject.toml:version",
    "src/runtime_config.cpp:FIRMWARE_VERSION",
]
update_changelog_on_bump = true
changelog_file = "CHANGELOG.md"

Benefits:

  • Version automatically synced across pyproject.toml and src/runtime_config.cpp
  • Changelog automatically generated from commit messages
  • Prevents version mismatch errors
  • Simplified release workflow

Usage:

task version:bump:apply  # Updates version and changelog automatically

🐛 Code Quality

Enhancements:

  • Separated configuration logic into dedicated module (src/runtime_config.cpp)
  • Text command parsing in new src/text_command_handler.cpp (336 lines)
  • Full input validation and error handling
  • Consistent response format for all commands

📊 Code Metrics

Metric Value Change
RAM Usage 7.2% (23,648 bytes) +1.1%
Flash Usage 26.8% (350,832 bytes) +4.2%
Build Time ~2.8 seconds +0.3s
New Functions 8 -
New Modules 2 runtime_config, text_command_handler
Lines Changed +680 (firmware), +1500 (docs) -
Warnings 0 -
Errors 0 -

🔧 Technical Details

New Modules

runtime_config.cpp/h (100 lines):

  • Configuration getter/setter functions
  • Validation logic for all parameters
  • DAC integration on threshold update
  • Version access interface

text_command_handler.cpp/h (336 lines):

  • Command parsing and dispatch
  • Parameter validation
  • Error handling and reporting
  • Response formatting

Module Integration

Modified Files: - src/serial_communication.cpp - Enhanced for command handling

Installation

Via Git Tag

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

Build from Source

# Build firmware
task build

# Upload to ESP32
task upload

# Monitor serial output
task monitor

Using New Features

# Connect serial monitor
task monitor

# Set sample count to 150
# Type: S 150

# Configure threshold
# Type: T 1 2048

# Check version
# Type: V

# Query all settings
# Type: I

Changelog

Added

  • Runtime configuration management system (src/runtime_config.cpp/h)
  • Text command interface for configuration (src/text_command_handler.cpp/h)
  • Sample count configuration (1-1000 range)
  • Per-channel threshold configuration (0-4095 range)
  • Configuration status query command (I)
  • Version query command (V)
  • Complete protocol documentation (UART, SPI, I2C, High/Low)
  • Monitoring tool guides (PlatformIO Device Monitor, GNU Screen)
  • Development specification documents for feature 002-add-runtime-config
  • Progress tracking documentation
  • Automatic version synchronization via commitizen

Changed

  • Updated src/main.cpp to integrate runtime configuration
  • Enhanced src/serial_communication.cpp for text command handling
  • Project version updated to 1.5.0 (synced with firmware)
  • Improved documentation structure with protocol section

Removed

  • None

Fixed

  • None

Documentation

  • Added 1500+ lines of documentation
  • Created protocol specification suite
  • Added monitoring tool guides
  • Comprehensive development specifications
  • Version management automation

Known Issues

None. This is a stable minor release.

Breaking Changes

None. This release is fully backward compatible with v1.4.2. Existing firmware behavior is unchanged; text command interface is additive.

Testing

All changes have been verified:

  • ✅ Code compiles without warnings or errors
  • ✅ RAM usage acceptable (7.2%)
  • ✅ Flash usage acceptable (26.8%)
  • ✅ Configuration functions validated with boundary values
  • ✅ Serial command parsing tested with various inputs
  • ✅ DAC integration verified
  • ✅ All new modules documented

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

This release adds new configuration capabilities without changing core detection:

  1. Firmware Update (recommended):
git pull origin main
git checkout v1.5.0
task build && task upload
  1. Testing New Features:
task monitor
# Type: V    (check version)
# Type: S 100 (set samples)
# Type: T 1 2048 (set threshold)
  1. Backward Compatibility: Existing detection behavior unchanged when using default configuration
  • SPI Protocol - DAC control details
  • PlatformIO Monitor - Serial monitoring guide
  • Hardware Overview - General hardware information

Contributors

  • Shota Takahashi (runtime configuration, text commands, documentation)

License

MIT License - See LICENSE file for details

Release Information

  • Date: November 18, 2025
  • Version: 1.5.0
  • Git Tag: v1.5.0
  • Commits: 6 (002-add-runtime-config branch + version bump)
  • Files Changed: 25 files added/modified