IoT・ハードウェア連携¶

SmoothBox とは¶

SmoothBox は、駐車場の各スポットに設置する Raspberry Pi ベースの IoT デバイスです。IPカメラ（RTSP接続）の映像を取得し、エッジ側（ラズパイ上）で YOLOv11 によるナンバープレート検出を行い、検出結果をバックエンドに送信します。入出庫の最終判定はバックエンドの OCR（EyeTech）が担います。

物理構成¶

┌─────────────────────────────────┐
│         SmoothBox               │
│  （Raspberry Pi）               │
│                                 │
│  ┌───────────┐                  │
│  │ IPカメラ  │ ←── RTSP接続    │
│  │（1台以上）│                  │
│  └─────┬─────┘                  │
│        │ フレーム取得            │
│  ┌─────▼─────────────────────┐  │
│  │ YOLOv11                   │  │
│  │ license_plate_detector.pt │  │
│  │ プレート領域を検出・crop   │  │
│  └─────┬─────────────────────┘  │
│        │ WebP crop画像           │
└────────┼────────────────────────┘
         │ HTTPS（X-API-Key）
         ▼
   バックエンド API
   POST /api/v1/hardware/detect-plate
         │
         ▼
   EyeTech OCR でテキスト認識
         │
         ▼
   4ケース分岐でセッション管理

通信フロー¶

同じ /api/v1/hardware/detect-plate エンドポイントを使いますが、Content-Type によって処理が分岐します。

プレート検出時（画像あり）¶

sequenceDiagram
    participant YOLO as YOLOv11（ラズパイ）
    participant Device as SmoothBox
    participant API as バックエンド
    participant OCR as EyeTech OCR

    YOLO->>Device: プレート領域を検出・crop
    Device->>API: WebP crop画像を送信（multipart/form-data）
    Note over Device,API: POST /api/v1/hardware/detect-plate
    API->>OCR: crop画像でOCR実行
    OCR-->>API: プレート番号・信頼スコア
    API->>API: 4ケース分岐でセッション管理
    API-->>Device: 結果（detected_plate_number, session, polling.action）

プレート未検出時（画像なし）¶

プレートが検出されない場合でも、必ずステータスチェックリクエストを送信します。これが CASE C（出庫確認フロー）のトリガーになります。

sequenceDiagram
    participant Device as SmoothBox
    participant API as バックエンド

    Device->>API: JSON のみ送信（画像なし）
    Note over Device,API: POST /api/v1/hardware/detect-plate
    Note over Device,API: Content-Type: application/json
    API->>API: consecutive_miss_count をインクリメント
    API-->>Device: 結果（polling.action）

セキュリティ¶

SmoothBox からの API リクエストは以下で保護されています：

APIキー: 駐車場ごとにユニークなAPIキーを発行（X-API-Key ヘッダー）
HMAC-SHA256 署名: 各リクエストに署名を付与し、改ざんを検知
nonce: リプレイアタックを防止（Redis で管理）

ナンバープレート認識（ANPR）¶

処理ステップ	実行場所	詳細
プレート領域の検出	ラズパイ（エッジ）	YOLOv11（`license_plate_detector.pt`）でバウンディングボックスを取得
crop・WebP 変換	ラズパイ（エッジ）	プレート領域を切り出し、WebP 品質50でエンコード
テキスト認識（OCR）	バックエンド	EyeTech OCR でプレート番号を読み取り

YOLO の推論はラズパイ側で完結するため、API には crop 済みの軽量な画像のみ送信されます。

ポーリング動作¶

SmoothBox は一定間隔でカメラを撮影し、検出結果を問わず毎回 API にリクエストを送ります。

設定	既定値	説明
ポーリング間隔	240秒（4分）	`--interval` 引数で変更可能
WebP 品質	50	`--quality` 引数で変更可能
YOLO 信頼度閾値	0.5	`--yolo-conf` 引数で変更可能
最小プレート幅	100px	遠い車・隣スポットの誤検知をフィルタ

複数カメラ対応¶

1台のラズパイで複数の駐車スポットを管理できます。カメラとスポット番号は 1:1 で対応します。

# 例: 2スポットを1台のラズパイで管理
python simple_plate_poller.py \
  --multi-rtsp "rtsp://192.168.1.10, rtsp://192.168.1.11" \
  --spot-numbers "1,2"

駐車場APIキー管理（Admin）¶

エンドポイント	説明
`GET /admin/parking-lots/{lotId}/api-key`	APIキーを取得
`POST /admin/parking-lots/{lotId}/api-key`	APIキーを作成
`POST /admin/parking-lots/{lotId}/api-key/regenerate`	APIキーを再生成
`POST /admin/parking-lots/{lotId}/api-key/regenerate-secret`	署名シークレットを再生成

レガシーコードについて¶

POST /api/v1/hardware/detection（status コード方式: 0=入庫/1=駐車中/2=出庫）は本番環境で使用されていません（過去30日間でリクエストゼロ）。コードは残存していますが実質的にデッドコードです。