Skip to content

v1.1.0 - Module Refactoring & Cosmic Detector (2025-11-04)

Overview

A significant refactoring release that introduces comprehensive modularization of the codebase and adds the cosmic_detector module for independent cosmic ray detection. This release improves code maintainability, testability, and flexibility for future enhancements.

What's New

✨ Major Features

🔬 Cosmic Detector Module

  • New Module: Dedicated cosmic ray detection system
  • Features:
  • Independent detection signal processing for three channels
  • Optimized GPIO register sampling (10 samples per cycle)
  • LED feedback control for visual event notification
  • Clean structured return type (cosmic_detection_t)
  • Pin configuration:
    • Detection pins: GPIO12, GPIO19, GPIO27
    • LED pins: GPIO14, GPIO26, GPIO33

🏗️ Complete Modularization

The codebase has been split into five focused modules:

  1. serial_communication module
  2. Serial command reception and parsing
  3. Response transmission
  4. Input buffer management with timeout

  5. Reduces coupling between communication and logic

  6. bme280_sensor module

  7. Independent BME280 temperature/humidity/pressure sensor handling
  8. I2C address configuration (default: 0x76)
  9. Safe initialization state tracking

  10. Returns 0.0f on uninitialized access

  11. adc_sensor module

  12. ADC analog input management
  13. Configurable pin mapping (default: GPIO32)

  14. Simple, testable API

  15. spi_control module

  16. SPI-based DAC control for three channels
  17. Chip select pin management (GPIO5, GPIO13, GPIO15)
  18. Configurable SPI clock speed (default: 100kHz)

  19. Clean channel-specific functions

  20. cosmic_detector module

  21. Cosmic ray signal detection (new)
  22. LED feedback management
  23. Signal accumulation and detection logic

🔄 Refactoring Improvements

Code Organization

  • Before: All logic in single main.cpp file (~270 lines with comments)
  • After: Five specialized modules with clear responsibilities
  • Benefits:
  • Easier to test individual components
  • Reduced code duplication
  • Better code reusability
  • Improved maintainability

Main.cpp Simplification

// Before: 40+ lines of raw GPIO sampling code
for (int ii = 0; ii < 10; ii++) {
  uint32_t gpio_in_reg = *((uint32_t*)0x3FF4403C);
  signal1 += ((gpio_in_reg & GPIO_IN_REG_MASK) >> 12) & 1;
  // ... more manual bit manipulation
}

// After: Clean function call
cosmic_detection_t detection = cosmic_detector_read();
if (detection.detected) {
  cosmic_detector_led_feedback(detection.signal1, detection.signal2, detection.signal3);
}

Deprecated Code Cleanup

  • All deprecated global variables commented out with migration notes
  • Old function implementations kept for reference (to be removed in v1.2)
  • Clear documentation showing where functionality moved

📊 Code Metrics

Metric Value
Module Files 5 (serial, bme280, adc, spi, cosmic)
Header Files 5 corresponding .h files
Implementation Files 5 corresponding .cpp files
RAM Usage 6.9% (22,592 bytes / 327,680 bytes)
Flash Usage 22.6% (296,241 bytes / 1,310,720 bytes)
Build Time ~9-10 seconds

🛠️ Development Tooling

Version Management

  • Automatic changelog generation via commitizen
  • Semantic versioning with tag support
  • Safe version bump workflow (dry-run + apply)

📚 Documentation

API Documentation

Added comprehensive docstrings for:

  • cosmic_detection_t structure
  • cosmic_detector_init() initialization
  • cosmic_detector_read() signal sampling
  • cosmic_detector_led_feedback() LED control
  • All module functions with parameter and return documentation

Migration Documentation

Inline comments showing:

  • Where functionality moved to
  • How to use new module APIs
  • Deprecated code marked with [DEPRECATED] sections

Breaking Changes

⚠️ Important: While the API remains backward compatible at the binary level, internal code organization has changed:

  • Global variable changes: signal1, signal2, signal3 are now internal to cosmic_detector module
  • Function changes: Old vspiCommand() functions deprecated in favor of modular SPI API
  • Pin configuration: Now managed by individual modules rather than main.cpp

Migration Path: If you have custom code depending on main.cpp internals, please update to use the module APIs directly.

Performance Impact

✅ No Performance Degradation

  • Same memory footprint
  • Same execution speed
  • Identical binary size (within 150 bytes variance)

Commits in This Release

  1. ac4346d - feat: Add serial_communication module
  2. a323c9a - feat: Add bme280_sensor module
  3. dc496dd - feat: Add adc_sensor module
  4. 6faa88c - feat: Add spi_control module
  5. c3e61dc - refactor: Update main.cpp to use modularized components
  6. a5f9af9 - fix: Add forward declarations for vspiCommand functions
  7. 89bfd92 - chore: Comment out deprecated SPI DAC command functions
  8. 436dfc2 - feat: add cosmic_detector module
  9. eddcdbd - refactor: update main.cpp to use cosmic_detector module
  10. f229063 - bump: version 1.0.0 → 1.1.0
  11. 98305cf - docs: add changelog for version 1.1.0
  12. 295797d - refactor: enhance Taskfile.yml with useful development tasks

Installation & Upgrade

From v1.0.0 to v1.1.0

Simply pull the latest changes and rebuild:

git pull origin main
uv sync
task build
task upload

New Project Setup

git clone https://gitlab.com/osechi/kurikintons.git
cd kurikintons
git checkout v1.1.0
uv sync
uv run platformio run
uv run platformio run --target upload

Module API Reference

cosmic_detector

cosmic_detection_t cosmic_detector_read(void);
void cosmic_detector_led_feedback(int signal1, int signal2, int signal3);
void cosmic_detector_led_off(void);
void cosmic_detector_reset(void);

serial_communication

bool serial_command_available(void);
bool serial_read_command(int &ch, byte &val1, byte &val2);
void serial_send_response(const char* message);
void serial_flush_input(void);

bme280_sensor

bool bme280_init(uint8_t i2c_address);
float bme280_read_temperature(void);
float bme280_read_pressure(void);
float bme280_read_humidity(void);

adc_sensor

void adc_init(int pin);
int adc_read(void);
int adc_read_pin(int pin);

spi_control

void spi_init(uint32_t clockSpeed);
void spi_send_dac_command(int channel, byte data1, byte data2);
void spi_send_dac1(byte data1, byte data2);
void spi_send_dac2(byte data1, byte data2);
void spi_send_dac3(byte data1, byte data2);

Known Issues

None at this time. All deprecations are planned for v1.2.

Future Roadmap

v1.2.0 (Planned)

  • Remove deprecated code sections
  • Add comprehensive unit tests
  • Implement CI/CD pipeline

v1.3.0 (Planned)

  • Enhanced communication stability mechanisms
  • Advanced signal processing and filtering
  • Performance optimizations

v2.0.0 (Long-term)

  • Support for multiple detector boards
  • Real-time data visualization
  • Machine learning-based event classification

Contributors

  • Shota Takahashi (KMI, Nagoya University)

License

[To be determined]

Support

For issues, questions, or contributions:

Release Date: November 4, 2025 Tag: 1.1.0 Previous Release: v1.0.0