Skip to content

v1.6.7 - Semantic Naming: Poll Count Refactor (2025-11-20)

What Changed?

This release improves code clarity by renaming the sample_count parameter to poll_count throughout the codebase. The old name was misleading—the detector performs GPIO register polling, not statistical sampling. This refactoring aligns our terminology with embedded systems standards and makes the code more intuitive for developers.

⚠️ PROTOCOL BREAKING CHANGE: Client code must update serial commands. See "Backward Compatibility" section below.

What's New

Main Feature: Semantic Naming Clarity

What it does: Renames all references to sample_count → poll_count across the firmware, including:

  • Configuration macro: DETECT_POLL_COUNT (was DETECT_SAMPLE_COUNT)
  • Runtime config: RuntimeConfig.poll_count field
  • API functions: config_get_poll_count(), config_set_poll_count()
  • Serial command: SET_POLL_COUNT (was SET_SAMPLE_COUNT)

How to use it: Use the new command name in serial communication:

SET_POLL_COUNT 200       # ✅ NEW (polling cycles per detection)
SET_SAMPLE_COUNT 200     # ❌ OLD - will fail

Code example (for client integration):

// OLD (v1.6.6 and earlier)
serialPort.println("SET_SAMPLE_COUNT 100");

// NEW (v1.6.7+)
serialPort.println("SET_POLL_COUNT 100");

Installation

Quick Start

# Get the release
git checkout v1.6.7

# Build
task build

# Upload to device
task upload

# Test the new command
task monitor
# Try: SET_POLL_COUNT 200 → should respond OK

What's Different from the Last Version?

✅ Added

  • Improved semantic clarity: "polling" terminology replaces confusing "sampling" language

🔧 Changed

  • Serial Protocol: SET_SAMPLE_COUNT command renamed to SET_POLL_COUNT
  • Configuration API: Function names updated (config_get_sample_count() → config_get_poll_count())
  • Internal Naming: All sample_count references renamed to poll_count in code and documentation
  • Error Messages: References to "SAMPLE_COUNT" renamed to "POLL_COUNT"
  • Documentation: CLAUDE.md and inline comments updated

🐛 No Bug Fixes

This is a pure refactoring—no behavioral changes to detection algorithm.

Is It Safe to Upgrade?

Backward Compatible: ❌ NO - Protocol Breaking Change

Impact on Existing Users

  • ✅ Firmware functionality unchanged (pure refactoring)
  • ✅ Build profiles unchanged (dev, prod, debug)
  • ❌ Serial protocol clients MUST be updated
  • Old command SET_SAMPLE_COUNT will no longer be recognized
  • Clients must update to use SET_POLL_COUNT
  • All error messages now reference "POLL_COUNT"

Migration Path

  1. Update any client scripts/applications that use SET_SAMPLE_COUNT
  2. Replace all occurrences with SET_POLL_COUNT (parameter format unchanged)
  3. Rebuild and redeploy client code
  4. Test with task monitor before deploying to production

Tests Passed

  • ✅ Development build succeeds (task dev:build)
  • ✅ Production build succeeds (task prod:build)
  • ✅ No compilation errors or warnings
  • ✅ RAM usage stable: 6.9-7.3% (unchanged)
  • ✅ Flash usage stable: 22.7-23.0% (unchanged)
  • ✅ New serial command SET_POLL_COUNT works correctly
  • ✅ Old command SET_SAMPLE_COUNT properly rejected as unknown

Release Details

  • Date: 2025-11-20
  • Version: v1.6.7
  • Files Changed: 7 (config.h, runtime_config.h, runtime_config.cpp, cosmic_detector.cpp, text_command_handler.cpp, CLAUDE.md, progress entry)
  • Total Changes: 42 insertions, 42 deletions (mechanical refactoring)
  • Commits:
  • e152f58: Phase 1 - Core implementation (36 insertions, 36 deletions)
  • 40af970: Phase 2 - Documentation (6 insertions, 6 deletions)
  • 8b13b9e: Phase 4 - Progress entry (83 insertions)

Next Steps

  • Phase 2 Planning (v1.7.0): Text Command Parsing Optimization
  • Add backward compatibility alias (optional): SET_SAMPLE_COUNT → SET_POLL_COUNT
  • Improve error message formatting
  • Consider command validation tables

Summary

This release prioritizes code clarity and developer experience. The terminology change from "sample_count" to "poll_count" makes the firmware more intuitive and aligns with embedded systems conventions. Users upgrading to v1.6.7 must update their serial protocol clients, but the underlying detection algorithm and hardware behavior remain unchanged.