Skip to content

M5Atom_HID_KeepAwake_Spec.md

Latest commit

 

History

History
252 lines (180 loc) · 9.75 KB

M5Atom_HID_KeepAwake_Spec.md

File metadata and controls

252 lines (180 loc) · 9.75 KB
Raw

M5 Atom HID スリープ回避デバイス 設計仕様書

1. 概要

M5 Atom (M5Atom Lite / M5Atom Matrix) を USB HID デバイスとして PC に接続し、定期的にマウス入力信号を送信することで、PC の自動スリープおよびスクリーンロックを回避する。OS のスリープ設定や企業 IT ポリシーを変更せずに、ハードウェアレベルで「アクティブな入力」を擬似する。

1.1 目的

  • OS 設定を変更せずに PC のスリープ・スクリーンセーバー起動を防ぐ
  • ハードウェアデバイスとして動作するため、ソフトウェア (Caffeine, Amphetamine 等) のインストールが禁止された環境でも利用可能
  • ON/OFF を物理スイッチで切り替え可能にし、必要な時だけ稼働させる

1.2 対象デバイス

  • M5Atom Lite (推奨) / M5Atom Matrix
  • SoC: ESP32-PICO-D4 (USB OTG 非搭載のため、USB HID は TinyUSB の Native USB ではなく BLE HID を使用)

重要: ESP32 (無印) は USB OTG を持たないため、有線 USB HID として動作させることは不可能。BLE HID として PC に Bluetooth 接続する方式を採用する。有線 HID が必要な場合は ESP32-S2/S3 系 (M5Stamp S3, M5AtomS3 等) を選定する必要がある。

2. 方式選定

2.1 採用方式: BLE HID Mouse

項目 BLE HID USB HID (要 ESP32-S3)
M5Atom Lite 対応 ◯ ✕
ペアリング設定 初回のみ必要 不要 (挿すだけ)
電源 USB 給電可 USB 給電
安定性 OS依存あり 高い
企業PC利用 BLE禁止環境では不可 ほぼ問題なし

M5AtomS3 (ESP32-S3 搭載) であれば USB HID も可能。本仕様は M5Atom Lite + BLE HID を基本構成とする。代替構成として M5AtomS3 + USB HID の派生案を §8 に記載。

2.2 入力信号の選定

スリープ回避には以下のいずれかを定期送信する:

  1. マウスの微小移動 (推奨): カーソルを 1px 右に動かし、直後に 1px 左に戻す。視覚的影響なし。
  2. キーボードの F15 キー: 一般的に未使用で、副作用が最小。ただし一部アプリで挙動あり。
  3. マウスのジッター (ランダム移動): 検知回避目的の場合に使用。

→ 採用: マウス微小移動 (+1, 0) → (-1, 0)

3. ハードウェア構成

3.1 構成図

┌─────────────┐  USB-C   ┌────────────┐  BLE   ┌────────┐
│ USB電源/PC  │ ───────► │ M5Atom Lite│ ─────► │  PC    │
└─────────────┘  給電のみ  │  (BLE HID) │        └────────┘
                          └────────────┘
                              │
                              ├── 内蔵ボタン (G39): ON/OFF トグル
                              └── 内蔵LED (G27): ステータス表示

3.2 使用ペリフェラル

機能 GPIO 用途
内蔵ボタン G39 動作 ON/OFF トグル、長押しでペアリング解除
内蔵RGB LED G27 ステータス表示 (色で状態を可視化)

3.3 LED ステータス定義

色 状態
青 (点滅) BLE 広告中 (未接続)
緑 (常灯) 接続中・動作中 (信号送信中)
黄 (常灯) 接続中・一時停止 (OFF)
赤 (点滅) エラー
消灯 起動直後・低電力時

4. ソフトウェア設計

4.1 開発環境

  • PlatformIO + Arduino framework for ESP32
  • 主要ライブラリ:
    • M5Atom (LED, ボタン制御)
    • ESP32 BLE Mouse (T-vK/ESP32-BLE-Mouse) または NimBLE-Arduino ベースの HID 実装
    • FastLED (M5Atom LED 制御の依存)

4.2 状態遷移

[起動]
   ↓
[BLE_ADVERTISING] ──接続成功──► [ACTIVE]
       ▲                            │
       │ペアリング解除               │ボタン押下
       │                            ▼
       └──────────────────── [PAUSED]
                                    │
                                    │ボタン押下
                                    ▼
                                [ACTIVE]

4.3 主要パラメータ (設定可能値)

パラメータ デフォルト 説明
JIGGLE_INTERVAL_SEC 50 マウス移動の送信間隔 (秒)
JIGGLE_DISTANCE_PX 1 移動量 (ピクセル)
JIGGLE_RETURN_DELAY_MS 100 往復の中間遅延
DEVICE_NAME "M5Atom KeepAwake" BLE デバイス名
BUTTON_LONGPRESS_MS 3000 長押し判定時間

Windows / macOS のデフォルトスリープが 5〜15 分のため、50 秒間隔で十分な余裕。短すぎる間隔 (1秒等) は OS の挙動を不安定化させる場合があるため避ける。

4.4 モジュール構成

src/
├── main.cpp              // setup/loop, 状態遷移
├── KeepAwakeConfig.h     // 設定値・定数の集約
├── HidMouseDriver.h/.cpp // BLE Mouse のラッパー (抽象化)
├── StatusIndicator.h/.cpp// LED 制御
└── ButtonHandler.h/.cpp  // ボタン入力 (短押し/長押し判定)

4.5 主要クラス設計

HidMouseDriver (抽象化レイヤ)

BLE 実装と USB 実装を差し替え可能にするため、インターフェースを切る。Swift で言う protocol。

class HidMouseDriver {
public:
    virtual ~HidMouseDriver() = default;
    virtual void begin(const char* deviceName) = 0;
    virtual bool isConnected() const = 0;
    virtual void jiggle(int deltaX, int deltaY) = 0;
};

// 実装: BleHidMouseDriver, UsbHidMouseDriver (S3用)

これにより、後に M5AtomS3 に移行した際もコア層の改修が不要になる。

KeepAwakeService

class KeepAwakeService {
public:
    KeepAwakeService(HidMouseDriver& driver, const KeepAwakeConfig& cfg);
    void start();
    void pause();
    void resume();
    void tick(uint32_t nowMs);  // loop から呼ぶ
private:
    enum class State { Advertising, Active, Paused };
    State state_;
    uint32_t lastJiggleAt_ = 0;
};

tick() ベースの設計とすることで、delay() を使わず、ボタン応答性を保つ。

5. 動作シーケンス

5.1 起動・初回ペアリング

  1. 電源投入 → LED: 青点滅
  2. PC 側の Bluetooth 設定で "M5Atom KeepAwake" を検出しペアリング
  3. 接続成功 → LED: 緑常灯
  4. 50 秒ごとにカーソルが +1px → -1px と動く (実質静止)

5.2 ON/OFF 切替

  • ボタン短押し: ACTIVE ⇄ PAUSED トグル (LED: 緑 ⇄ 黄)
  • ボタン長押し (3秒): ペアリング情報削除 + 再起動

5.3 再接続

  • PC のスリープや再起動でBLE接続が切れた場合、自動的に広告状態に戻り、PC側が再接続を試みる

6. テスト計画

ユニットテストはハードウェア依存箇所を HidMouseDriver の Mock 実装で差し替えて検証する。

6.1 ユニットテスト対象

クラス テスト項目
KeepAwakeService tick() で正しい間隔で jiggle() が呼ばれる / pause 中は呼ばれない / 状態遷移が仕様通り
ButtonHandler 短押し・長押し・チャタリング判定
StatusIndicator 各状態で正しい LED 色が指定される

6.2 結合テスト

項目 確認方法
BLE ペアリング Windows / macOS でペアリング成功
スリープ回避動作 OS のスリープを 1 分に設定し、5 分放置でスリープしないことを確認
接続復帰 PC スリープ → 復帰後に自動再接続
長時間安定性 24 時間連続稼働でハング・メモリリークなし

7. セキュリティ・運用上の留意

  • 企業ポリシー遵守: 本デバイスはスリープポリシーを意図的に回避する性質を持つ。所属組織の IT ポリシーで明示的に禁止されている場合は使用しないこと。
  • BLE セキュリティ: HID デバイスとしてペアリングするため、近隣からの不正接続を防ぐためボンディング (永続的ペアリング) を有効にする。
  • 無人放置の防止: 業務 PC で席を離れる際は、本デバイスでスクリーンロックを回避することなく、別途手動ロックすること。

8. 派生案: M5AtomS3 + USB HID

将来的に有線 HID 化したい場合の構成。

  • ハード: M5AtomS3 (ESP32-S3, USB OTG 搭載)
  • ライブラリ: TinyUSB (Arduino-ESP32 公式サポート)
  • 差分: HidMouseDriver を UsbHidMouseDriver に差し替えるのみ。KeepAwakeService 以上のレイヤは変更不要。
  • メリット: ペアリング不要、BLE 禁止環境でも動作、遅延が小さい
  • デメリット: USB ケーブルで PC に直結が必要

9. 開発マイルストーン

Phase 内容 完了条件
1 BLE Mouse PoC M5Atom から PC にマウス入力が届く
2 KeepAwakeService 実装 50秒ごとの jiggle が動作
3 ボタン・LED 統合 ON/OFF 切替、ステータス表示
4 ユニットテスト整備 Mock を用いたサービス層テスト
5 長時間安定性検証 24時間連続稼働クリア
6 (オプション) M5AtomS3 USB HID 版 USB 接続のみで動作

10. 参考