Skip to content

Progress Log: Detection Event Layering Strategy Investigation

Task Description

Investigated future architectural improvements to separate Detection, Event Handling, and Output layers in the detection buffer system. Current v1.9.2 design combines event dequeue and serial output into a single detection_buffer_send() function. This analysis explores when and how to separate these concerns for better extensibility and maintainability.

Current State (v1.9.2)

detection_buffer_queue()   // Detection Layer (Core 1)
detection_buffer_send()    // Event Handling + Output (Core 2, mixed)

Proposed Future State (v2.0.0中盤)

detection_event_dequeue()  // Event Handling Layer (Layer 2)
detection_event_send()     // Output Layer (Layer 3)

3-Layers

// ============================================
// Layer 1: Detection Layer (Core 1)
// ============================================
detection_buffer_queue(sensor_data_t *data)
  // 責任: 検出イベントをバッファーに追加のみ

// ============================================
// Layer 2: Event Handling Layer (Core 2)
// ============================================
detection_event_dequeue()  // ← 新規
  // 責任: キューからイベント取出し、統計更新、フィルタリング
  // 戻り値: detection_event_t*（またはNULL）

// ============================================
// Layer 3: Output/Sender Layer (Core 2)
// ============================================
detection_event_send(detection_event_t *event)  // ← 新規
  // 責任: イベントをシリアルに出力のみ
  // 複数の出力形式に対応可能（SSV, CSV, JSONL等）
実装例:
// v2.0.0: loop() in Core 2
void utility_loop_core2(void) {
  while (true) {
    // イベントハンドリング層
    detection_event_t *event = detection_event_dequeue();
    if (event) {
      // 出力層
      detection_event_send(event);
      free(event);  // または静的な再利用
    }

    // その他の処理
    process_protocol_commands();
    wifi_update();
    delay(10);
  }
}

具体的な拡張例（v2.0.0後半以降）

層分離のメリットが活きてくる場面：

// 同じイベント、複数の出力先に対応
detection_event_t *event = detection_event_dequeue();

if (event) {
  // 出力形式1: シリアル（JSONL）
  detection_event_send(event);  // 既存

  // 出力形式2: WiFi（JSON over HTTP）
  #if ENABLE_WIFI
  detection_event_send_wifi(event);  // 新規
  #endif

  // 出力形式3: ローカルストレージ（LittleFS）
  #if ENABLE_LITTLEFS
  detection_event_save_file(event);  // 新規
  #endif

  // 出力形式4: 複数デバイス同期（v2.0.0中盤以降）
  #if ENABLE_MULTIBOARD
  detection_event_broadcast(event);  // 新規
  #endif
}

推奨スケジュール

  • v1.9.2 現在の設計維持（基盤構築）
  • v2.0.0前半 マルチスレッド化完了
  • v2.0.0中盤 層分離（Event + Output分離）
  • v2.0.0後半 複数出力形式対応

Outcome

Analysis Complete ✅

3-Layer Architecture Designed:

  1. Layer 1: Detection Layer (Core 1, Real-time)
  2. cosmic_detector_read() - GPIO polling
  3. sensor_read() - BME280, ADC
  4. detection_buffer_queue() - Enqueue event to FIFO
  5. Responsibility: Fast detection + timestamp capture

  6. Timing: ~1-5ms total

  7. Layer 2: Event Handling Layer (Core 2, Utility)

  8. detection_event_dequeue() - NEW function
  9. Responsibility: Dequeue from FIFO, update statistics, apply filtering
  10. Returns: detection_event_t* (or NULL if queue empty)

  11. Allows: Independent testing, statistics tracking, future filtering rules

  12. Layer 3: Output/Sender Layer (Core 2, Utility)

  13. detection_event_send() - NEW function (replaces current detection_buffer_send())
  14. Responsibility: Serialize and output event to destination
  15. Supports: Multiple output formats (Serial, WiFi, LittleFS, Multiboard, etc.)

Architecture Benefits

Aspect Current (Mixed) Layered (Separated)
Testing Difficult (dequeue+send coupled) Easy (each layer independent)
Extensibility Limited (add new output = modify single function) High (new output = new function)
Debugging Hard (unclear where latency occurs) Easy (profile each layer separately)
Reusability Low (Layer 2 tied to serial output) High (Layer 2 usable for WiFi, LittleFS, etc.)

Implementation Timeline

Version Phase Task
v1.9.2 Baseline Keep current detection_buffer_send() (mixed)
v2.0.0前半 Multithreading Complete dual-core implementation
v2.0.0中盤 Layering Separate into detection_event_dequeue() + detection_event_send()
v2.0.0後半 Extension Add alternate outputs (WiFi, LittleFS, Multiboard)

Code Structure (v2.0.0中盤以降)

detection_event.h (New)

// Layer 2: Event Handling
detection_event_t* detection_event_dequeue(void);

// Layer 3: Output (expandable)
bool detection_event_send(detection_event_t *event);
bool detection_event_send_wifi(detection_event_t *event);    // v2.0.0後半
bool detection_event_save_file(detection_event_t *event);   // v2.0.0後半
bool detection_event_broadcast(detection_event_t *event);   // v2.0.0後半+

Loop structure (v2.0.0中盤)

void utility_loop_core2(void) {
  while (true) {
    // Layer 2: Dequeue event
    detection_event_t *event = detection_event_dequeue();

    if (event) {
      // Layer 3: Multiple outputs supported
      detection_event_send(event);        // Serial

      #if ENABLE_WIFI
      detection_event_send_wifi(event);   // WiFi
      #endif

      #if ENABLE_LITTLEFS
      detection_event_save_file(event);   // Storage
      #endif

      // Cleanup
      free(event);  // or reuse in pool
    }

    // Other tasks
    process_protocol_commands();
    wifi_update();
    delay(10);
  }
}

Learnings

Design Principles Applied

  1. Single Responsibility Principle (SRP)
  2. Layer 2: Event handling (dequeue, stats, filtering)
  3. Layer 3: Output (serialization, transmission)

  4. Clear separation improves maintainability

  5. Open/Closed Principle

  6. Current design: Closed to new outputs (must modify detection_buffer_send())

  7. Proposed design: Open for extension (add new detection_event_send_*() functions)

  8. Timing Considerations

  9. Layer 1 (detection): Must stay on Core 1 (~1-5ms)
  10. Layer 2 (dequeue): Can move between cores
  11. Layer 3 (output): Intentionally blocks (Core 2 supports this)

Why Not v1.9.2?

Keep current design because:

  • ✅ Simpler for single-output scenario
  • ✅ Reduces code churn before multithreading stabilizes
  • ✅ Testing of current mixed function is adequate
  • ✅ No other output methods exist yet

Why Separate in v2.0.0中盤?

Separate because:

  • ✅ Multiboard support requires event dequeue without immediate output
  • ✅ WiFi output needs identical event-to-JSON serialization
  • ✅ LittleFS storage needs same event capture but different format
  • ✅ Future cloud integration (v2.1.0+) needs flexible event pipeline

API Design Notes

Function Naming:

  • Layer 2: detection_event_dequeue() - Clearly separates from buffer operations
  • Layer 3: detection_event_send() - Generic output (primary path)
  • Layer 3 variants: detection_event_send_wifi(), detection_event_save_file(), etc. - Clear destination

Backward Compatibility:

  • Current detection_buffer_send() can be deprecated in v2.0.0中盤
  • Provide wrapper: detection_buffer_send() → calls both Layer 2 + Layer 3
  • Allows phased migration

Next Steps

Immediate (v1.9.2)

  • ✅ Document 3-layer strategy in REFACTORING_ROADMAP.md
  • ✅ Add to v2.0.0中盤 planning section
  • ✅ Keep current detection_buffer_send() implementation unchanged

v2.0.0前半

  • Implement dual-core task separation
  • Verify FreeRTOS Queue performance
  • Prepare detection_event_t struct finalization

v2.0.0中盤 (Target)

  • Create detection_event.h with detection_event_dequeue()
  • Implement detection_event_send() (extract from current detection_buffer_send())
  • Add wrapper for backward compatibility
  • Update utility_loop_core2() to use new Layer 2+3
  • Comprehensive testing (each layer independently)
  • Update documentation

v2.0.0後半+ (Long-term)

  • Implement detection_event_send_wifi()
  • Implement detection_event_save_file() (LittleFS)
  • Implement detection_event_broadcast() (Multiboard)
  • Event filtering/transformation layer (if needed)