CommandQueue & EventQueue - ファイルマッピングドキュメント¶

Date: 2025-12-09

ファイル一覧¶

既存ファイル（CommandQueue関連）¶

Header Files¶

ファイル	内容	状態
`include/command_queue.h`	CommandQueue クラス定義、command_t、command_response_t、command_entry_t 型	✅ 既存
`include/device_response.h`	device_response_t、device_response_type_t、device_response_status_t、device_response_code_t 型、builder 関数	✅ 既存
`include/command.h`	Command シングルトン（設定管理）	✅ 既存
`include/event_response.h`	イベント出力関数（event_t対応）	✅ 既存
`include/stream_data.h`	event_t（legacy）	✅ 既存

Implementation Files¶

ファイル	内容	状態
`src/command_queue.cpp`	CommandQueue 実装（receive, execute, parse, dispatch）	✅ 既存
`src/device_response.cpp`	device_response_ok(), device_response_error(), device_get_timestamp()	✅ 既存
`src/command.cpp`	Command シングルトン実装	✅ 既存
`src/event_response.cpp`	send_event_as_device_response()（legacy event_t対応）	✅ 既存

Command Handlers（`src/command/` ディレクトリ）¶

ファイル	ハンドラー	内容
`version.cpp`	GET_VERSION	Firmware version
`status.cpp`	GET_STATUS	System status
`uptime.cpp`	GET_UPTIME	Board uptime
`help.cpp`	GET_HELP	Help text
`mac_address.cpp`	GET_MAC_ADDRESS	MAC address
`poll_count.cpp`	GET_POLL_COUNT, SET_POLL_COUNT	Detection poll count
`threshold.cpp`	GET_THRESHOLD, SET_THRESHOLD	DAC threshold
`deadtime.cpp`	SET_DEADTIME	Detector deadtime
`stream.cpp`	SET_STREAM, GET_STREAM	Stream enable flag
`test_led.cpp`	TEST_LED	LED test
`rtc.cpp`	SET_RTC_TIME, GET_RTC_TIME	RTC time control
`gnss.cpp`	GNSS関連	GNSS commands
`wifi.cpp`	WiFi関連	WiFi commands
`bme280.cpp`	BME280関連	Sensor commands
`reset.cpp`	RESET	Device reset

新規ファイル（EventQueue関連、v1.14.0計画）¶

Header Files¶

ファイル	内容	役割
`include/event_queue.h`	新規 event_t 型定義 + EventQueue クラス定義	イベントデータ構造体、キューイング API、FreeRTOS静的キュー管理

Implementation Files¶

ファイル	内容	役割
`src/event_queue.cpp`	新規 EventQueue 実装	enqueue(), flush(), has_pending(), clear(), get_queued_count()
`src/event_response.cpp`	更新	event_to_device_response() 追加

CommandQueue の詳細メッピング¶

Header: `include/command_queue.h`¶

// ============================================================================
// CONFIGURATION MACROS
// ============================================================================
#define COMMAND_QUEUE_SIZE 10                    // L50
#define COMMAND_RECEPTION_TIMEOUT_MS 500         // L58
#define MAX_COMMAND_LENGTH 64                    // L66
#define MAX_COMMAND_ARGS 2                       // L74
#define MAX_ARG_LENGTH 16                        // L82

// ============================================================================
// TYPE DEFINITIONS
// ============================================================================
typedef struct {                                 // L106-132: command_t
  char name[32];
  uint8_t arg_count;
  char args[MAX_COMMAND_ARGS][MAX_ARG_LENGTH];
} command_t;

typedef struct {                                 // L140-161: command_response_t
  bool is_ok;
  char message[512];
} command_response_t;

typedef command_response_t (*command_handler_t)  // L177
  (const command_t& cmd);

typedef struct {                                 // L191-235: command_entry_t
  const char* name;
  const char* aliases[4];
  command_handler_t handler;
  const char* category;
  const char* description;
} command_entry_t;

// ============================================================================
// PUBLIC API - Static Class
// ============================================================================
class CommandQueue {                             // L265-433
  static void init(void);                        // L282
  static bool receive(void);                     // L313
  static bool has_pending(void);                 // L328
  static bool execute(void);                     // L356

  // Private helpers
  static bool receive_line(char*, size_t);       // L378
  static command_t parse(const char*);           // L400
  static void discard_input(void);               // L412
  static command_response_t dispatch(
    const command_t&);                           // L432
};

Implementation: `src/command_queue.cpp`¶

// FreeRTOS Queue Management
static StaticQueue_t g_queue_static;             // Static queue structure
static uint8_t g_queue_buffer[...];              // Queue buffer array
static QueueHandle_t g_queue_handle;             // Queue handle

// Implementation Details
void CommandQueue::init()                        // Initialize FreeRTOS queue
void CommandQueue::receive()                     // Read from serial, parse, queue
void CommandQueue::execute()                     // Dequeue, dispatch, send response
bool CommandQueue::receive_line(...)             // Serial reading with timeout
command_t CommandQueue::parse(...)               // Parse text line to command_t
void CommandQueue::discard_input()               // Clear serial buffer
command_response_t CommandQueue::dispatch(...)   // Lookup handler, execute

EventQueue の詳細メッピング（新規、v1.14.0）¶

Header: `include/event_queue.h` (新規作成予定)¶

#if ENABLE_DEVICE_RESPONSE

// ============================================================================
// EVENT DATA STRUCTURE - EventQueue Optimized
// ============================================================================
/**
 * @brief Detection event data optimized for EventQueue buffering
 *
 * Core fields (always present, 8 bytes):
 * - hit1, hit2, hit3: Detection counts (0-100) per channel
 * - adc: ADC reading (12-bit, 0-4095)
 *
 * Optional fields (ENABLE_* flags):
 * - hit_type: Detection pattern bitmask (ENABLE_HITTYPE)
 * - adc_mv: ADC millivolt conversion (ENABLE_ADCMV)
 * - temperature, pressure, humidity: Environmental (ENABLE_BME280)
 * - uptime_ms, timedelta_us: Timing (ENABLE_TIMESTAMP)
 * - unix_timestamp: Absolute time (ENABLE_RTC)
 * - gnss_*: GNSS positioning (ENABLE_GNSS)
 */
typedef struct {                                 // Optimized for FreeRTOS queue
  // Core fields (always present)
  uint16_t hit1;                                 // Detection channel 1 (0-100)
  uint16_t hit2;                                 // Detection channel 2 (0-100)
  uint16_t hit3;                                 // Detection channel 3 (0-100)
  int16_t adc;                                   // ADC reading (0-4095)

  // Optional fields (ENABLE_* flags)
#if ENABLE_HITTYPE
  uint8_t hit_type;                              // Detection pattern bitmask
#endif

#if ENABLE_ADCMV
  uint16_t adc_mv;                               // Millivolt conversion
#endif

#if ENABLE_BME280
  float temperature;                             // Temperature (°C)
  float pressure;                                // Pressure (Pa)
  float humidity;                                // Humidity (%)
#endif

#if ENABLE_TIMESTAMP
  uint32_t uptime_ms;                            // Board uptime (ms)
  uint64_t timedelta_us;                         // Event interval (us)
#endif

#if ENABLE_RTC
  uint32_t unix_timestamp;                       // Absolute time (unix seconds)
#endif

#if ENABLE_GNSS
  double gnss_latitude;                          // Latitude (decimal degrees)
  double gnss_longitude;                         // Longitude (decimal degrees)
  float gnss_altitude;                           // Altitude (meters)
  uint8_t gnss_satellites;                       // Satellite count
  uint8_t gnss_fix_quality;                      // NMEA fix quality
  float gnss_hdop;                               // Horizontal DOP
  bool gnss_fix_valid;                           // Fix validity flag
#endif
} event_t;

// ============================================================================
// CONFIGURATION
// ============================================================================
#define EVENT_QUEUE_SIZE 200                     // High-frequency buffering

// ============================================================================
// PUBLIC API - Static Class
// ============================================================================
class EventQueue {
  // Initialization
  static void init(void);                        // Initialize FreeRTOS queue

  // Main operations
  static bool enqueue(const event_t*);           // Buffer event for deferred output
  static bool has_pending(void);                 // Check if events pending
  static bool flush(void);                       // Send all pending events

  // Statistics & control
  static size_t get_queued_count(void);          // Current queue depth
  static size_t get_capacity(void);              // Maximum queue size
  static bool is_full(void);                     // Queue at capacity?
  static size_t clear(void);                     // Emergency clear (returns count)

  // Private helpers
  static void send_response(const device_response_t*);  // Serialize & output one event
};

#endif  // ENABLE_DEVICE_RESPONSE

Implementation: `src/event_queue.cpp` (新規作成予定)¶

#if ENABLE_DEVICE_RESPONSE

// FreeRTOS Queue Management
static StaticQueue_t g_event_queue_static;      // Static queue structure
static uint8_t g_event_queue_buffer[...];       // Queue buffer array
static QueueHandle_t g_event_queue_handle;      // Queue handle

// Statistics
static size_t g_enqueue_total = 0;               // Total enqueued events
static size_t g_dequeue_total = 0;               // Total dequeued events
static size_t g_overflow_count = 0;              // Overflow drop count

// Implementation Details
void EventQueue::init()                          // Initialize FreeRTOS queue
bool EventQueue::enqueue(const event_t*)         // Enqueue event
bool EventQueue::has_pending()                   // Check queue status
bool EventQueue::flush()                         // Drain queue & send
size_t EventQueue::get_queued_count()            // Current depth
bool EventQueue::is_full()                       // Capacity check
size_t EventQueue::clear()                       // Emergency reset
void EventQueue::send_response(...)              // Serialize & output event

#endif  // ENABLE_DEVICE_RESPONSE

Updated: `src/event_response.cpp`¶

#if ENABLE_DEVICE_RESPONSE

// New conversion function
device_response_t event_to_device_response(
  const event_t *data);                          // Convert to device_response_t

// Serialization helper (used by EventQueue::flush)
void send_device_response(
  const device_response_t *response);            // Serialize to JSON & send

#endif  // ENABLE_DEVICE_RESPONSE

ファイル間の依存関係図¶

CommandQueue パス¶

command_queue.h
  ├── Defines: command_t, command_response_t, command_entry_t, CommandQueue
  └── Depends on: config.h

command_queue.cpp
  ├── Implements: CommandQueue (receive, parse, dispatch, execute)
  ├── Calls: CommandQueue::dispatch() (table-driven lookup)
  ├── Depends on: command_queue.h, command_manager.h, device_response.h
  └── External: Serial I/O, FreeRTOS queue API

command/version.cpp, status.cpp, ... (handler implementations)
  ├── Implements: Specific command handlers
  ├── Signature: command_response_t handler(const command_t& cmd)
  ├── Depends on: command.h, device_response.h
  └── Called by: CommandQueue::dispatch() via command_entry_t table

device_response.h
  ├── Defines: device_response_t, device_response_type_t, builder functions
  └── Depends on: config.h

device_response.cpp
  ├── Implements: device_response_ok(), device_response_error(), device_get_timestamp()
  └── Depends on: device_response.h, command.h, config.h

command.h
  ├── Defines: Command class (singleton, configuration management)
  └── Depends on: device_response.h, config.h

command.cpp
  ├── Implements: Command::get_stream(), set_stream(), get_threshold(), set_threshold(), etc.
  ├── Inline getters (zero-cost)
  └── Depends on: command.h, device_response.h, dac_manager.h

EventQueue パス（新規、v1.14.0）¶

event.h (NEW)
  ├── Defines: event_t structure
  ├── Depends on: config.h, stdint.h
  └── Used by: main.cpp (detection loop), event_queue.h

event_queue.h (NEW)
  ├── Defines: EventQueue class
  ├── Depends on: config.h, device_response.h, event.h
  └── Used by: main.cpp

event_queue.cpp (NEW)
  ├── Implements: EventQueue (enqueue, flush, has_pending, clear, etc.)
  ├── FreeRTOS queue management (xQueueCreateStatic, xQueueSend, xQueueReceive)
  ├── Calls: send_device_response()
  ├── Depends on: event_queue.h, event_response.h, command.h, config.h
  └── External: FreeRTOS queue API, Serial I/O

event_response.h (UPDATED)
  ├── Adds: event_to_device_response() inline function
  ├── Existing: stream_data.h event_t functions (legacy)
  └── Depends on: device_response.h, event.h, stream_data.h

event_response.cpp (UPDATED)
  ├── Adds: send_device_response() (unified serializer)
  ├── Existing: send_event_as_device_response() (legacy event_t)
  ├── Depends on: event_response.h, ArduinoJson, config.h
  └── External: Serial I/O, ArduinoJson JSON serialization

main.cpp (UPDATED)
  ├── Calls: EventQueue::init() in setup()
  ├── Calls: EventQueue::enqueue() in detection loop
  ├── Calls: EventQueue::flush() in loop()
  ├── Depends on: event_queue.h, event.h, cosmic_detector.h, sensors
  └── No longer calls: send_event() directly (replaced by EventQueue)

メソッド・変数配置表（完全な対称性）¶

Layer 1: データ構造定義¶

要素	CommandQueue	EventQueue
データ型	`command_t`	`event_t`
定義ファイル	command_queue.h (L106-132)	event_queue.h (L50-200予定)
キュー容量	10項目	200項目
メモリ/item	~32 bytes	~100-150 bytes

Layer 2: キューイング管理クラス¶

要素	CommandQueue	EventQueue
クラス名	`CommandQueue`	`EventQueue`
定義ファイル	command_queue.h	event_queue.h
実装ファイル	command_queue.cpp	event_queue.cpp
マクロ	COMMAND_QUEUE_SIZE=10	EVENT_QUEUE_SIZE=200
FreeRTOS Handle	`g_queue_handle`	`g_event_queue_handle`
キュー構造体	`StaticQueue_t g_queue_static`	`StaticQueue_t g_event_queue_static`

Layer 2: Public API メソッド（共通インターフェイス）¶

メソッド	CommandQueue	EventQueue
初期化	`init()`	`init()`
入力受け取り	`receive()`	`enqueue(event_t*)`
キュー確認	`has_pending()`	`has_pending()`
処理実行	`execute()`	`flush()`
キュー深さ	(なし)	`get_queued_count()`
キュー容量	(なし)	`get_capacity()`
容量確認	(なし)	`is_full()`
緊急リセット	(なし)	`clear()`

Layer 2: Private Helper メソッド¶

メソッド	CommandQueue	EventQueue
受け取り補助	`receive_line()`	(enqueue内)
パース	`parse()`	(なし)
ディスパッチ	`dispatch()`	(なし)
出力補助	(execute内)	`send_response()`
入力破棄	`discard_input()`	(なし)

Layer 3: プロトコル変換と出力¶

要素	CommandQueue	EventQueue
入力型	`command_t`	`event_t`
変換関数	(execute内でJSON生成)	`event_to_device_response()`
出力関数	(execute内でSerial)	`send_device_response()`
出力型	`device_response_t` (暗黙)	`device_response_t`
ファイル	command_queue.cpp	event_response.cpp
フォーマット	JSON (可変)	JSONL (固定形式)

Layer 4: 統合ポイント（main.cpp内）¶

操作	CommandQueue	EventQueue
setup()での初期化	`CommandQueue::init()`	`EventQueue::init()`
loop()での入力	`CommandQueue::receive()`	`EventQueue::enqueue()` (検出器トリガー)
loop()での処理	`CommandQueue::execute()`	`EventQueue::flush()`
制御フラグ	SET_STREAM コマンド	Command::getInstance().get_stream()

Layer 4: 統計・監視（オプション、v1.14.0+で検討）¶

メトリクス	CommandQueue	EventQueue
受け取り総数	(なし)	`g_enqueue_total`
処理総数	(なし)	`g_dequeue_total`
オーバーフロー数	(なし)	`g_overflow_count`
最大深さ	(なし)	(動的取得可)

ファイル依存関係（グラフ表示）¶

┌─ ENABLE_DEVICE_RESPONSE フラグ
│
├─ CommandQueue Path (既存)
│  ├─ command_queue.h
│  │  ├─ command_t
│  │  ├─ CommandQueue class
│  │  └─ depends: config.h
│  │
│  ├─ command_queue.cpp
│  │  ├─ FreeRTOS queue buffer
│  │  ├─ receive(), parse(), dispatch(), execute()
│  │  └─ depends: command_queue.h, command_manager.h, device_response.h
│  │
│  ├─ device_response.h/cpp
│  │  ├─ device_response_t
│  │  ├─ device_response_ok/error()
│  │  └─ device_get_timestamp()
│  │
│  ├─ command.h/cpp
│  │  ├─ Command singleton
│  │  ├─ get_stream(), set_threshold(), etc.
│  │  └─ depends: device_response.h, config.h
│  │
│  └─ command/[*.cpp]
│     ├─ Handler implementations
│     ├─ Signature: command_response_t handler(const command_t&)
│     └─ depends: command.h, device_response.h
│
└─ EventQueue Path (新規, v1.14.0)
   ├─ event.h (NEW)
   │  ├─ event_t structure
   │  └─ depends: config.h
   │
   ├─ event_queue.h (NEW)
   │  ├─ EventQueue class
   │  ├─ enqueue(), flush(), has_pending(), clear()
   │  └─ depends: device_response.h, event.h
   │
   ├─ event_queue.cpp (NEW)
   │  ├─ EventQueue implementation
   │  ├─ FreeRTOS queue buffer
   │  ├─ send_response() helper
   │  └─ depends: event_queue.h, event_response.h, command.h
   │
   ├─ event_response.h (UPDATED)
   │  ├─ Adds: event_to_device_response()
   │  ├─ Existing: legacy event_t functions
   │  └─ depends: device_response.h, event.h
   │
   └─ event_response.cpp (UPDATED)
      ├─ Adds: send_device_response()
      ├─ Existing: send_event_as_device_response()
      └─ depends: event_response.h, ArduinoJson

処理フロー（ファイル横断）¶

CommandQueue フロー¶

main.cpp::loop()
  └─> CommandQueue::receive()                   [command_queue.cpp]
      └─> Serial.available() & readBytesUntil()
      └─> CommandQueue::parse()                 [command_queue.cpp]
          └─> Parse line → command_t
      └─> xQueueSend() to FreeRTOS queue        [command_queue.cpp]

  └─> CommandQueue::execute()                   [command_queue.cpp]
      └─> xQueueReceive() from FreeRTOS queue   [command_queue.cpp]
      └─> CommandQueue::dispatch()              [command_queue.cpp]
          └─> command_table[] lookup
          └─> handler(cmd)                      [command/*.cpp]
              └─> Calls Command::getInstance()  [command.h/cpp]
              └─> Generate JSON response
              └─> return command_response_t
      └─> Serial.println(response)              [command_queue.cpp]

EventQueue フロー（新規、v1.14.0）¶

main.cpp::loop()
  └─> cosmic_read().detected
      └─> Collect sensors
      └─> Create event_t                       [main.cpp local]
      └─> EventQueue::enqueue(event)           [event_queue.cpp]
          └─> xQueueSend() to FreeRTOS queue   [event_queue.cpp]

  └─> EventQueue::flush()                      [event_queue.cpp]
      └─> Check stream_enabled()               [command.h or config]
      └─> xQueueReceive() loop                 [event_queue.cpp]
          └─> get event_t
          └─> send_device_response()           [event_response.cpp]
              └─> ArduinoJson serialization    [ArduinoJson library]
              └─> Serial.println(JSON)         [event_response.cpp]

実装チェックリスト（参照用）¶

Phase 4, v1.14.0 Implementation¶

[ ] event.h (NEW)
    [ ] struct event_t definition
    [ ] ENABLE_* flag support
    [ ] JSDoc documentation

[ ] event_queue.h (NEW)
    [ ] class EventQueue definition
    [ ] static methods: init, enqueue, flush, has_pending, clear, get_queued_count, is_full
    [ ] Configuration: EVENT_QUEUE_SIZE = 200
    [ ] JSDoc for public API

[ ] event_queue.cpp (NEW)
    [ ] FreeRTOS static queue initialization
    [ ] xQueueCreateStatic() setup
    [ ] EventQueue::init() implementation
    [ ] EventQueue::enqueue() implementation
    [ ] EventQueue::flush() implementation
    [ ] EventQueue::has_pending() implementation
    [ ] EventQueue::get_queued_count() implementation
    [ ] EventQueue::is_full() implementation
    [ ] EventQueue::clear() implementation
    [ ] EventQueue::send_response() helper
    [ ] Stream flag check (Command::getInstance().get_stream())

[ ] event_response.h (UPDATED)
    [ ] Add: inline event_to_device_response()
    [ ] Keep existing: legacy event_t functions

[ ] event_response.cpp (UPDATED)
    [ ] Add: send_device_response(const device_response_t*)
    [ ] JSON serialization using ArduinoJson
    [ ] Keep existing: legacy event_t handling

[ ] main.cpp (UPDATED)
    [ ] Add: #include "event_queue.h"
    [ ] Add: EventQueue::init() in setup()
    [ ] Update detection loop:
        [ ] Create event_t
        [ ] Call EventQueue::enqueue()
    [ ] Update loop: Replace send_event() with EventQueue::flush()
    [ ] Remove: Direct send_event() calls

[ ] Build & Testing
    [ ] Compile with ENABLE_DEVICE_RESPONSE=1
    [ ] No linker errors
    [ ] No circular dependencies
    [ ] Test enqueue/flush cycle
    [ ] Verify JSON output format

CommandQueue & EventQueue - ファイルマッピングドキュメント¶

ファイル一覧¶

既存ファイル（CommandQueue関連）¶

Header Files¶

Implementation Files¶

Command Handlers（src/command/ ディレクトリ）¶

新規ファイル（EventQueue関連、v1.14.0計画）¶

Header Files¶

Implementation Files¶

CommandQueue の詳細メッピング¶

Header: include/command_queue.h¶

Implementation: src/command_queue.cpp¶

EventQueue の詳細メッピング（新規、v1.14.0）¶

Header: include/event_queue.h (新規作成予定)¶

Implementation: src/event_queue.cpp (新規作成予定)¶

Updated: src/event_response.cpp¶

ファイル間の依存関係図¶

CommandQueue パス¶

EventQueue パス（新規、v1.14.0）¶

メソッド・変数配置表（完全な対称性）¶

Layer 1: データ構造定義¶

Layer 2: キューイング管理クラス¶

Layer 2: Public API メソッド（共通インターフェイス）¶

Layer 2: Private Helper メソッド¶

Layer 3: プロトコル変換と出力¶

Layer 4: 統合ポイント（main.cpp内）¶

Layer 4: 統計・監視（オプション、v1.14.0+で検討）¶

ファイル依存関係（グラフ表示）¶

処理フロー（ファイル横断）¶

CommandQueue フロー¶

EventQueue フロー（新規、v1.14.0）¶

実装チェックリスト（参照用）¶

Phase 4, v1.14.0 Implementation¶

Command Handlers（`src/command/` ディレクトリ）¶

Header: `include/command_queue.h`¶

Implementation: `src/command_queue.cpp`¶

Header: `include/event_queue.h` (新規作成予定)¶

Implementation: `src/event_queue.cpp` (新規作成予定)¶

Updated: `src/event_response.cpp`¶