v1.6.3 - Build Profiles & UPTIME Command (2025-11-19)

Overview

A patch release introducing comprehensive build profile management for different use cases (release, debug, development) and adding the UPTIME text command for runtime diagnostics. This release significantly improves the developer experience by providing environment-specific builds through a unified configuration system.

Implementation: Infrastructure Enhancement + Feature Addition | Branch: main | Commit: 6548261

What's New

✨ Major Features

🏗️ Multiple PlatformIO Build Profiles

Restructured build system with three distinct environment profiles:

Environment Profiles:

1. esp32dev-release - Production release
2. Optimization: -O2 (full optimization)
3. Features: Normal detection (DEBUG_DETECTION_MODE=0)
4. Text Commands: Disabled (legacy 3-byte protocol only)

5. Use Case: Shipping/deployment builds

6. esp32dev-debug - Production debug

7. Optimization: -Og (debug-friendly optimization)
8. Debug Symbols: Included for GDB debugging
9. Features: Normal detection (DEBUG_DETECTION_MODE=0)
10. Text Commands: Disabled

11. Use Case: Troubleshooting production issues with debug symbols

12. esp32dev-dev - Development (default)

13. Optimization: -O2
14. Features: Periodic random debug signals (DEBUG_DETECTION_MODE=2)
15. Text Commands: Enabled (full command interface)
16. Use Case: Development, testing, experimentation

Base Configuration:

[env]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

build_flags =
    -DCORE_DEBUG_LEVEL=0
    -DADC_DEPEND_CHANNEL=1

Environment-Specific Override Pattern:

[env:esp32dev-release]
build_type = release
build_flags =
    ${env.build_flags}
    -O2
    -DDEBUG_DETECTION_MODE=0
    -DENABLE_TEXT_COMMANDS=0

🎯 Structured Task System

New task prefixes for clarity and discoverability:

Development Tasks:

task dev:build       # Build development firmware
task dev:upload      # Build and upload development firmware
task dev:clean       # Clean development build artifacts
task build           # Alias for dev:build
task upload          # Alias for dev:upload
task clean           # Alias for dev:clean

Production Release Tasks:

task prod:build      # Build production release firmware (-O2)
task prod:upload     # Build and upload release firmware
task prod:clean      # Clean release build artifacts

Production Debug Tasks:

task debug:build     # Build with debug symbols (-Og)
task debug:upload    # Build and upload debug firmware
task debug:clean     # Clean debug build artifacts

Benefits:

• Clear intent: prod:build for production vs. dev:build for development
• Consistent naming across all prefixes
• Convenient aliases (build, upload, clean) for common development workflow
• IDE discovery: All tasks visible in task --list

⏱️ UPTIME Text Command [U]

New command for runtime system diagnostics:

Format: UPTIME or U (alias)

Output:

UPTIME: 2 days 03:45:12.567 (245112567 ms)

Fields:

• Human-readable format: Days HH:MM:SS.mmm
• Raw milliseconds: For scripting and integration
• Precision: 1 millisecond

Use Cases:

• Device uptime monitoring
• Checking system stability/restart frequency
• Automated health checks
• Debugging power cycling issues

Implementation:

// Get uptime in milliseconds since power-on
unsigned long uptime_ms = millis();

// Convert to days/hours/minutes/seconds/ms
unsigned long days = uptime_ms / (24 * 60 * 60 * 1000UL);
// ... (time decomposition)

// Output: "UPTIME: X days HH:MM:SS.mmm (X ms)\n"

Notes:

• Uses Arduino millis() function (~49.7 day overflow cycle)
• Continues counting across brief interruptions
• Suitable for monitoring device health and uptime statistics

🔧 Implementation Details

Taskfile Enhancement

Structure:

vars:
  PLATFORMIO_ENV_RELEASE: "esp32dev-release"
  PLATFORMIO_ENV_DEBUG: "esp32dev-debug"
  PLATFORMIO_ENV_DEV: "esp32dev-dev"

tasks:
  dev:build:
    desc: "Build development firmware (default)"
    cmds:
      - uv run platformio run -e {{.PLATFORMIO_ENV_DEV}}

  build:
    desc: "Build development firmware (alias for dev:build)"
    cmds:
      - task dev:build

Alias Pattern:

• Explicit prefixed tasks (dev:, prod:, debug:) for clarity
• Short aliases (build, upload, clean) for convenience
• Both patterns point to the same implementation

Text Command Handler Integration

New Handler: handle_uptime()

• Validates zero arguments
• Retrieves millis() value
• Decomposes into days/hours/minutes/seconds
• Formats human-readable and raw output

Alias Registration:

{"U", "UPTIME"}  // In alias_table[]
{"UPTIME", handle_uptime}  // In command_table[]

HELP Output Update:

[U] UPTIME                     - Display uptime since power-on

📊 Code Metrics

Metric	v1.6.2	v1.6.3	Change
RAM Usage	7.3%	7.3%	No change
Flash Usage	23.1%	23.1%	No change
Build Time	~2.5s	~2.5s	No change
Text Commands	9	10	+1 (UPTIME)
Task Aliases	3	9	+6 (prod:, debug:)
Taskfile Lines	48	88	+40
Lines of Code	~576	~614	+38 (uptime handler)
Warnings	0	0	✓
Errors	0	0	✓

🔄 Developer Workflow Improvement

Before v1.6.3 (Command-line complexity):

# Build release: requires full environment name
pio run -e esp32dev -t upload

# Build with text commands: requires build flag override
PLATFORMIO_BUILD_FLAGS="-DENABLE_TEXT_COMMANDS=1" pio run -t upload

# Switching contexts: manual tracking of configuration

After v1.6.3 (Clear, memorable commands):

# Build release
task prod:build && task prod:upload

# Build development (with text commands, default)
task build && task upload

# Build for debugging
task debug:build && task debug:upload

# Clean specific build artifacts
task prod:clean
task dev:clean
task debug:clean

Benefits:

• No need to remember environment names or build flags
• Self-documenting: command intent is clear
• Easier for team collaboration
• IDE integration: All tasks discoverable in task --list

Installation

Via Git Tag

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

Build from Source

# Set up environment
task env:setup

# Build development firmware (default - includes UPTIME command)
task build

# OR build production release
task prod:build

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

# Monitor serial output
task monitor

Using New Features

Testing UPTIME Command:

# Connect serial monitor
task monitor

# Type: UPTIME
# Response: UPTIME: 0 days 00:00:15.234 (15234 ms)

# Alias also works
# Type: U
# Response: UPTIME: 0 days 00:00:20.567 (20567 ms)

Switching Build Profiles:

# For development with text commands
task dev:build && task dev:upload

# For production release
task prod:build && task prod:upload

# For production debugging
task debug:build && task debug:upload

Changelog

Added

• Build Profiles: Three distinct PlatformIO environments
• esp32dev-release: Production (-O2, no text commands)
• esp32dev-debug: Debug symbols (-Og, no text commands)
• esp32dev-dev: Development default (text commands enabled)
• Task System: Structured task prefixes (dev:, prod:, debug:) with convenient aliases
• UPTIME Command: New text command [U] to query system uptime since power-on
• Output: Days HH:MM:SS.mmm + raw milliseconds
• Useful for monitoring device stability and restart frequency
• Documentation: Updated CLAUDE.md and README.md with build profile and task usage
• Environment Variables: Taskfile.yml now uses PLATFORMIO_ENV_* variables for maintainability

Changed

• Build System: Refactored from single env to base + derived environments pattern
• Default Build: Development (esp32dev-dev) now default for dev workflow
• Task Naming: Explicit prefixes (dev:, prod:, debug:) for clarity
• Taskfile Structure: Cleaner organization with grouped task sections
• Documentation: Clarified user vs. developer build recommendations

Fixed

• Build flag duplication eliminated through variable inheritance
• Task discovery improved with consistent naming scheme

Documentation

• Updated CLAUDE.md with new build profile descriptions
• Updated README.md with developer vs. user guidance
• Added task examples for each build profile
• Documented UPTIME command with examples

Known Issues

None. This is a stable patch release.

Breaking Changes

None. All previous commands and build methods continue to work:

• Old: pio run (legacy, still works)
• New: task build (recommended)
• All firmware features backward compatible with v1.6.2

Testing

All changes verified:

• ✅ Build profiles compile without errors/warnings
• ✅ All three environments produce valid firmware
• ✅ Task system executes correctly
• ✅ Aliases properly delegate to main tasks
• ✅ UPTIME command correctly calculates uptime
• ✅ UPTIME alias [U] works as expected
• ✅ HELP output includes UPTIME
• ✅ Text commands enabled in dev environment
• ✅ Text commands disabled in release environment
• ✅ RAM/Flash usage unchanged
• ✅ No regression in detection or sensor functionality

Supported Hardware

• Microcontroller: ESP32-WROOM-32E
• SPI DAC: 3-channel digital 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

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

This release improves the build system and adds UPTIME diagnostics:

1. Update Firmware:

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

1. Use New Task System:

# Easier to remember and execute
task dev:build      # Instead of: pio run
task prod:build     # Instead of: pio run -e esp32dev-release
task debug:build    # Instead of: pio run -e esp32dev-debug

1. Test UPTIME Command:

task monitor
# Type: U
# Check: UPTIME response displays correctly

Related Documentation

• Text Command Interface - Complete command specification
• API Documentation - Module APIs and data structures
• CLAUDE.md - Developer guide with updated task examples

Contributors

• Shota Takahashi (Build profile redesign, UPTIME command, task system organization)

License

MIT License - See LICENSE file for details

Release Information

• Date: November 19, 2025
• Version: 1.6.3
• Git Tag: v1.6.3
• Commits: 8 (build profiles, task organization, UPTIME command, version bump)
• Files Changed: 6 (platformio.ini, Taskfile.yml, text_command_handler.cpp, CLAUDE.md, README.md, version bump)
• Build Size: 302,465 bytes Flash (maintained)
• Development Effort: Infrastructure improvements for long-term maintainability