Skip to content

Progress Log: WiFi Manager Module（v1.8.0）

Task Description

Implemented a comprehensive WiFi management module for OSECHI that provides:

  1. AP Mode（Access Point） - ESP32 acts as a WiFi router
  2. Default behavior: Automatically starts in AP mode on boot
  3. SSID: OSECHI-DETECTOR, Password: osechi2025
  4. IP address: 192.168.4.1（ESP32標準）

  5. Allows direct device connection without external network

  6. STA Mode（Station/Client） - ESP32 connects to existing WiFi network

  7. Non-blocking connection with timeout handling
  8. Auto-reconnection logic with 5-second retry interval

  9. Credential storage and state management

  10. State Machine - Polling-based（non-blocking）

  11. DISCONNECTED → CONNECTING → CONNECTED
  12. Timeout handling and failure recovery
  13. Independent from cosmic ray detection loop

Outcome

✅ Successfully completed

Created Files

  1. include/wifi_manager.h - Public API
  2. Mode control: wifi_start_ap(), wifi_start_sta()
  3. Connection management: wifi_connect(), wifi_disconnect()
  4. State queries: wifi_get_state(), wifi_is_connected()

  5. AP info: wifi_get_ap_ssid(), wifi_get_ap_ip()

  6. src/wifi_manager.cpp - Full implementation

  7. Non-blocking state machine（<10ms per update）
  8. 10-second connection timeout
  9. 5-second retry interval
  10. Memory-safe credential handling
  11. Safe to call even if WiFi hardware unavailable

Architecture

State Machine Flow:

[DISCONNECTED]
    ↓ (credentials stored)
[CONNECTING] → timeout → [FAILED]
    ↓ (success)         ↓ (wait retry)
[CONNECTED]        [RETRY_INTERVAL]
    ↓ (loss)           ↓
[DISCONNECTED]  [DISCONNECTED]

Integration Points:

  • setup(): wifi_init() after 3-second stability delay
  • loop(): wifi_update() for state machine polling
  • Non-blocking: <10ms execution time, doesn't block detection

Key Features

  • Polling-based non-blocking - No FreeRTOS threading complexity
  • AP mode default - Immediate device connectivity without external network
  • Graceful degradation - Safely handles missing WiFi hardware
  • Credential storage - Stores SSID/password for auto-reconnection
  • State visibility - Multiple query functions for debugging

Configuration

  • AP SSID: "OSECHI-DETECTOR"（wifi_manager.cpp L44で変更可能）
  • AP Password: "osechi2025"（wifi_manager.cpp L45で変更可能）
  • Connection timeout: 10秒
  • Retry interval: 5秒
  • Compile-time control: -DENABLE_WIFI=1 で有効化

Status Reporting

WiFi状態はテキストコマンド経由でクエリ可能:

STATUS           → WiFi接続状態を表示
GET_VERSION      → ファームウェアバージョン（WiFi情報含む）

Learnings

  1. Polling vs Events - FreeRTOSのイベント駆動は複雑。シンプルなポーリングが効果的
  2. AP mode benefits - 外部ネットワーク不要で即座にデバイス接続可能
  3. Non-blocking design - detect.detected()の検出ロジックとの独立性が重要
  4. WiFi.h API - ESP32標準ライブラリで十分な機能を提供
  5. Default IP - 192.168.4.1はESP32標準のAP IPで変更不要

Design Decision: Custom wifi_state_t vs WiFi.h's wl_status_t

Why Custom wifi_state_t?

The implementation uses a custom wifi_state_t enumeration instead of directly using WiFi.h's wl_status_t:

// Custom high-level state (4 states)
typedef enum {
  WIFI_STATE_DISCONNECTED = 0,
  WIFI_STATE_CONNECTING = 1,
  WIFI_STATE_CONNECTED = 2,
  WIFI_STATE_FAILED = 3
} wifi_state_t;

// vs WiFi.h's low-level hardware state (11 states)
// WL_CONNECTED (3), WL_IDLE_STATUS (0), WL_NO_SSID_AVAIL (1),
// WL_SCAN_COMPLETED (2), WL_CONNECT_FAILED (4), WL_CONNECTION_LOST (5),
// WL_DISCONNECTED (6), WL_NO_SHIELD (255), etc.

Rationale

  1. Application Layer Abstraction
  2. Hardware states (wl_status_t) are low-level and numerous (11+ values)
  3. Application code needs simple, high-level states

  4. wifi_state_t maps multiple hardware states to meaningful application states

  5. Timeout Management

  6. Hardware alone cannot track connection timeouts (10 seconds max)
  7. Application layer maintains g_connect_start_time for timeout detection

  8. Impossible to implement with wl_status_t alone

  9. Auto-Retry Logic

  10. Custom 5-second retry interval after failed connection
  11. Requires application-level state tracking

  12. g_last_retry_time enables non-blocking retry behavior

  13. State Machine Design

  14. DISCONNECTED → CONNECTING → {CONNECTED, FAILED}
  15. FAILED → (wait 5s) → DISCONNECTED → (auto-reconnect)
  16. This high-level flow cannot be directly represented in wl_status_t

Implementation Details

Internally, wifi_update() still uses hardware states:

void wifi_update(void) {
  wl_status_t hw_status = WiFi.status();  // Hardware state (low-level)

  switch (g_wifi_state) {  // Application state (high-level)
    case WIFI_STATE_CONNECTING:
      if (hw_status == WL_CONNECTED) {
        g_wifi_state = WIFI_STATE_CONNECTED;  // Transition to app state
      }
      else if ((now - g_connect_start_time) > CONNECT_TIMEOUT_MS) {
        g_wifi_state = WIFI_STATE_FAILED;  // Timeout (impossible with hw_status alone)
      }
      break;
    // ... other cases
  }
}

Summary

  • Hardware layer: wl_status_t from WiFi.h (used internally in wifi_update())
  • Application layer: wifi_state_t (exposed in public API)
  • Mapping: Multiple hardware states → single application state
  • Benefits: Simplified API, timeout handling, auto-retry logic, debuggability

This is a standard abstraction pattern in embedded systems (hardware abstraction layer above low-level drivers).

Current Issues

STA Mode接続トラブル（調査中）

症状: WPA2/WPA3セキュリティが有効なルーターへのSTA接続がタイムアウト

  • エラー: [WiFi] Connection timeout (hw_status=1) (WL_NO_SSID_AVAIL)
  • 発生条件: WIFI_ENABLE <SSID> <PASSWORD> コマンド実行時
  • 状態: 接続状態遷移は正常、ただし認証段階で失敗

推定原因:

  1. WPA2/WPA3セキュリティプロトコルの互換性問題
  2. SSIDまたはパスワードの入力エラー
  3. ESP32WiFi.hライブラリのセキュリティプロトコル対応範囲

回避策（テスト済み）:

  • ルーターをWPA2のみに設定（WPA3を無効化）
  • シンプルなSSID（英数字のみ）とパスワード（英数字+特殊文字）でテスト
  • 2.4GHz帯域を使用（5GHzでなく）

次の調査ステップ:

  • WiFi接続詳細ログの追加実装
  • セキュリティプロトコル明示指定の検討（WiFi.begin()への引数追加）
  • タイムアウト値の調整（現在10秒）
  • 複数のテストWiFiネットワークでの検証

Next Steps

Optional enhancements for future versions:

  • STA mode接続トラブル解決（WPA2/WPA3互換性確認）
  • WiFi詳細ログ出力機能（デバッグ用）
  • STA mode接続画面（Web UI経由でWiFi設定変更）
  • Web設定ポータル（SSID/パスワード入力フォーム）
  • WPA3セキュリティ対応
  • WiFi信号強度（RSSI）のダッシュボード表示
  • OTA（Over-The-Air）ファームウェア更新対応
  • mDNS対応（osechi.localでの接続）