3  イベントキュー

3.1 イベントの型

まず、「何が起きたか」を表す型を決めます。

#ifndef APP_EVENT_H
#define APP_EVENT_H

#include <Arduino.h>

#define EVENT_PAYLOAD_SIZE 16  // ペイロードの最大長(BLE コマンドの引数が収まる大きさ)
#define EVENT_QUEUE_LENGTH 32  // キューに溜められるイベント数

// イベント ID。状態遷移テーブルの「列」になる
enum EventId : uint8_t
{
  EVT_NOP,
  EVT_BUTTON_SHORT,       // ボタン短押し
  EVT_BUTTON_LONG,        // ボタン長押し(1 秒以上)
  EVT_TIMER_100MS,        // 100 ms 周期タイマー
  EVT_TIMER_1S,           // 1 s 周期タイマー
  EVT_BLE_CONNECTED,      // BLE 接続
  EVT_BLE_DISCONNECTED,   // BLE 切断
  EVT_BLE_CMD_GET_INFO,   // コマンド: 機器情報取得
  EVT_BLE_CMD_MEAS_START, // コマンド: 測定開始
  EVT_BLE_CMD_MEAS_STOP,  // コマンド: 測定停止
  EVT_BLE_CMD_GET_LATEST, // コマンド: 最新値取得
  EVT_MAX,
};

// キューに入れるイベント。キューには値のコピーが入るので、ポインタは持たせない
struct Event
{
  EventId id;
  uint8_t length;                      // payload の有効長
  uint8_t payload[EVENT_PAYLOAD_SIZE]; // 引数(BLE コマンドのパラメータなど)
  uint32_t timestamp;                  // 発生時刻 [ms]
};

void event_init();
// どのコンテキスト(通常タスク・割り込み)からでも呼べる。キューが満杯なら false
bool event_post(EventId id, const uint8_t *payload = nullptr, uint8_t length = 0);
// イベントが来るまでブロックする(その間 CPU はスリープできる)
Event event_wait();
uint32_t event_dropped_count();
const char *event_name(EventId id);

#endif // APP_EVENT_H

設計のポイント:

  • EventId は enum。末尾の EVT_MAX が「イベントの種類の数」になり、状態遷移テーブルの列数に使える
  • ペイロード(引数)は配列で持つ。キューには構造体の 値がコピーされる ので、ポインタを入れると、取り出したときには指す先が書き換わっている・消えている危険がある
  • ペイロードの大きさは 必要最小限 に。キューのメモリ = sizeof(Event) × キューの長さ になる(このサンプルでは約 24 バイト × 32 = 約 0.8 KB)

3.2 FreeRTOS のキュー

FreeRTOS の キュー (Queue) は、タスク間・割り込みとタスク間で安全にデータを受け渡すための仕組みです。

関数 用途
xQueueCreate(長さ, 要素サイズ) キューを作る
xQueueSendToBack(q, &item, 待ち時間) 末尾に追加(タスクから)
xQueueSendToBackFromISR(q, &item, &woken) 末尾に追加(割り込みハンドラから)
xQueueReceive(q, &item, 待ち時間) 先頭から取り出す
  • キューへの追加・取り出しは 排他制御されている ので、複数のタスクや割り込みから同時に呼んでも壊れない
  • 要素は コピー で受け渡される

3.3 実装

#include "app_event.h"
#include <FreeRTOS.h>
#include <queue.h>

static QueueHandle_t s_queue = nullptr;
static volatile uint32_t s_dropped = 0; // 満杯で捨てたイベント数(割り込みからも更新する)

void event_init()
{
  if (s_queue == nullptr)
  {
    s_queue = xQueueCreate(EVENT_QUEUE_LENGTH, sizeof(Event));
  }
}

static inline bool in_isr()
{
  // IPSR が 0 以外なら割り込みハンドラの中
  return __get_IPSR() != 0;
}

bool event_post(EventId id, const uint8_t *payload, uint8_t length)
{
  if (s_queue == nullptr)
    return false;

  Event ev = {};
  ev.id = id;
  ev.length = min<uint8_t>(length, EVENT_PAYLOAD_SIZE);
  if (payload != nullptr && ev.length > 0)
  {
    memcpy(ev.payload, payload, ev.length);
  }
  ev.timestamp = millis();

  BaseType_t ok;
  if (in_isr())
  {
    BaseType_t woken = pdFALSE;
    ok = xQueueSendToBackFromISR(s_queue, &ev, &woken);
    portYIELD_FROM_ISR(woken);
  }
  else
  {
    // 待たない: BLE やタイマーのタスクを止めないため。満杯なら捨てて数える
    ok = xQueueSendToBack(s_queue, &ev, 0);
  }
  if (ok != pdTRUE)
  {
    s_dropped++;
    return false;
  }
  return true;
}

Event event_wait()
{
  Event ev;
  if (xQueueReceive(s_queue, &ev, portMAX_DELAY) == pdTRUE)
  {
    return ev;
  }
  Event nop = {};
  nop.id = EVT_NOP;
  return nop;
}

uint32_t event_dropped_count()
{
  return s_dropped;
}

const char *event_name(EventId id)
{
  switch (id)
  {
  case EVT_NOP: return "NOP";
  case EVT_BUTTON_SHORT: return "BUTTON_SHORT";
  case EVT_BUTTON_LONG: return "BUTTON_LONG";
  case EVT_TIMER_100MS: return "TIMER_100MS";
  case EVT_TIMER_1S: return "TIMER_1S";
  case EVT_BLE_CONNECTED: return "BLE_CONNECTED";
  case EVT_BLE_DISCONNECTED: return "BLE_DISCONNECTED";
  case EVT_BLE_CMD_GET_INFO: return "BLE_CMD_GET_INFO";
  case EVT_BLE_CMD_MEAS_START: return "BLE_CMD_MEAS_START";
  case EVT_BLE_CMD_MEAS_STOP: return "BLE_CMD_MEAS_STOP";
  case EVT_BLE_CMD_GET_LATEST: return "BLE_CMD_GET_LATEST";
  default: return "UNKNOWN";
  }
}

3.3.1 割り込みの中か、タスクの中か

FreeRTOS の API には、割り込みハンドラ (ISR) から呼んでよい ...FromISR 版 と、タスクから呼ぶ通常版があります。ISR から通常版を呼ぶと、ISR の中で「待つ」ことになり、システムが壊れます。

event_post() は、Cortex-M の IPSR レジスタ(現在実行中の例外番号)を見て、

  • 0 なら 通常のタスク → xQueueSendToBack
  • 0 以外なら 割り込みハンドラ → xQueueSendToBackFromISR

を使い分けています。これで、呼び出し側(ボタン・タイマー・BLE)は自分がどのコンテキストで動いているかを気にせず event_post() を呼べます。

ノートportYIELD_FROM_ISR

ISR の中でキューに積んだ結果、より優先度の高いタスク(イベントを待っていたタスク)が動けるようになった場合、woken が pdTRUE になります。portYIELD_FROM_ISR(woken) は、ISR を抜けた直後にそのタスクへ切り替えるよう要求します。

3.3.2 待たない投入と、破棄の記録

タスクから積むとき、待ち時間を 0(待たない)にしています。

  • portMAX_DELAY(無期限に待つ)にすると、キューが満杯のとき 呼び出し元のタスクが止まる。BLE のコールバックは BLE スタックのタスク、タイマーのコールバックはタイマータスクで動いているので、それらが止まると BLE 通信やほかのタイマーまで止まる
  • 代わりに、満杯で積めなかったイベントは 破棄して数を記録 する(event_dropped_count())。測定中のログに表示しているので、破棄が起きていないか確認できる

キューが満杯になるのは、ハンドラの処理が遅すぎる(イベントの発生ペースに消費が追いつかない)ときです。キューを長くするのは対症療法で、根本的にはハンドラを短くします(第 10 章)。

3.3.3 待つ取り出しと省電力

xQueueReceive(s_queue, &ev, portMAX_DELAY);

取り出し側は 無期限に待ちます。キューが空の間、loop タスクは ブロック状態 になり、FreeRTOS はほかに動くタスクがなければ アイドル に入ります。Adafruit nRF52 コアの FreeRTOS は tickless idle(configUSE_TICKLESS_IDLE = 1)が有効なので、次のイベント(タイマー満了や割り込み)まで CPU は スリープ します。

loop() が空回りしないので、イベント駆動にするだけで消費電力が下がります。

3.4 メインループ

#include <Arduino.h>
#include "app_event.h"
#include "app_handler.h"
#include "app_meas.h"
#include "app_state.h"
#include "drv_ble.h"
#include "drv_button.h"
#include "drv_imu.h"
#include "drv_led.h"
#include "drv_timer.h"

static State s_state = STATE_WAIT;

// 状態に応じた LED 表示。イベントを 1 つ処理するたびに呼ばれる
// (100 ms タイマーがあるので、少なくとも 10 Hz で更新される)
static void ui_update(State state)
{
  switch (state)
  {
  case STATE_WAIT:
    if (ble_is_connected())
      led_blink(LED_COLOR_BLUE, 100, 1000);
    else
      led_blink(LED_COLOR_GREEN, 100, 2000);
    break;
  case STATE_MEAS:
    led_blink(LED_COLOR_RED, 100, 500);
    break;
  default:
    led_set(LED_COLOR_OFF);
    break;
  }
}

void setup()
{
  Serial.begin(115200);
  event_init(); // 他のモジュールがイベントを積む前に作っておく
  led_init();
  imu_init();
  button_init();
  ble_init();
  timer_init();
  Serial.println("boot: state=WAIT");
}

void loop()
{
  // 1. イベントを待つ(来るまでこのタスクは眠り、CPU はスリープできる)
  Event ev = event_wait();

  // 2. 状態遷移テーブルでハンドラを選んで実行し、次の状態を受け取る
  State next = dispatch(s_state, ev);

  // 3. 状態が変わったらログを出す(タイマーイベントは多いので出さない)
  if (next != s_state)
  {
    Serial.printf("%s --[%s]--> %s\n", state_name(s_state), event_name(ev.id), state_name(next));
  }
  s_state = next;

  // 4. 表示の更新
  ui_update(s_state);
}

loop() は、FreeRTOS の loop タスクの中で 何度も呼ばれる関数 です。1 回の呼び出しで、

  1. イベントを 1 つ待って取り出す
  2. 状態遷移テーブルで処理する(第 4 章)
  3. 状態が変わったらログを出す
  4. LED を更新する

を行います。

重要キーポイント
  • イベントは 値でコピー してキューに入れる。ポインタは入れない
  • ISR からは FromISR 版、タスクからは 待たない 投入
  • 取り出しは 無期限に待つ → 空のときは CPU がスリープ
  • 消費が生産に追いつかないとキューがあふれる → ハンドラは短く