このドキュメンテーションは、MicroPython の最新開発ブランチのためのものです。 リリースバージョンでは利用できない機能に言及することがあります。

特定のリリースのドキュメントをお探しの場合は、左側のドロップダウンメニューを使って、 望みのバージョンを選択します。

クラス WLAN -- 組込み WiFi インタフェースの制御

このクラスは WiFi ネットワークプロセッサー用のドライバーを提供します。たとえば次のように使います:

import network
# ステーションインタフェースを有効にし、WiFi アクセスポイントに接続
nic = network.WLAN(network.WLAN.IF_STA)
nic.active(True)
nic.connect('your-ssid', 'your-key')
# これで通常どおりソケットを使えるようになる

コンストラクタ

class network.WLAN(interface_id)

WLAN ネットワークインタフェースオブジェクトを作成します。サポートされているインタフェースは network.WLAN.IF_STA (ステーション、別名クライアント、上流のWiFiアクセスポイントに接続します)と network.WLAN.IF_AP (アクセスポイント、他の WiFi クライアントが接続できるようにする)です。以下のメソッドを利用できるかどうかは、インターフェイスの種類によって異なります。たとえば、STA インタフェースのみが WLAN.connect() でアクセスポイントに接続できます。

メソッド

WLAN.active([is_active])

ブール型の引数が渡された場合、ネットワークインタフェースを有効化("up")または無効化("down")します。引数が与えられていなければ現在の状態を問い合わせます。他のほとんどのメソッドは有効化したインターフェースを必要とします。

WLAN.connect(ssid=None, key=None, *, bssid=None)

指定のワイヤレスネットワークに、指定のキーを使って接続します。 bssid が与えられると、接続はそのMACアドレスのアクセスポイントに制限されます(この場合でも ssid は指定する必要があります)。

WLAN.disconnect()

現在接続している無線ネットワークから切断します。

WLAN.scan()

利用可能な無線ネットワークをスキャンします。隠れたネットワーク(SSID がブロードキャストされていないネットワーク)も、WLAN インターフェイスで許可されていればスキャンされます。

スキャンは STA インターフェイスでのみ可能です。戻り値は WiFi アクセスポイントに関する情報を含むタプルのリストです。

(ssid, bssid, channel, RSSI, security, hidden)

bssid はアクセスポイントのハードウェアアドレスで、バイナリ形式です。これは bytes 型オブジェクトとして返されます。 binascii.hexlify() を使えば ASCII 形式に変換できます。

security には5つの値があります:

  • 0 -- オープン

  • 1 -- WEP

  • 2 -- WPA-PSK

  • 3 -- WPA2-PSK

  • 4 -- WPA/WPA2-PSK

hidden には２つの値があります:

  • 0 -- 可視"

  • 1 -- 不可視

WLAN.status([param])

無線接続の現在のステータスを返します。

引数なしで呼び出された場合、戻り値はネットワークリンクステータスを表します。戻されるステータスは network モジュール中の定数として定義されています:

  • STAT_IDLE -- 無接続、無アクティビティ

  • STAT_CONNECTING -- 接続中

  • STAT_WRONG_PASSWORD -- パスワード不正により失敗

  • STAT_NO_AP_FOUND -- アクセスポイントが応答しないため失敗

  • STAT_CONNECT_FAIL -- その他の問題により失敗

  • STAT_GOT_IP -- 接続成功

１つの引数 param を指定して呼び出された場合、 param は取得するステータスパラメータの名前を表す文字列にする必要があります。WiFi の動作モードによって、サポートされるパラメータは異なります。

STA モードでは 'rssi' を指定すると、受信信号強度の値が返されます。この値の形式はポートによって異なります(WiFi ネットワークインタフェースをサポートするすべてのポートで利用可能ですが、CC3200 は除きます)。

AP モードでは 'stations' を指定すると、接続されている WiFi ステーションのリストが返されます(WiFi ネットワークインタフェースをサポートするすべてのポートで利用可能ですが、CC3200 は除きます)。ステーション情報のエントリの形式はポートによって異なり、接続されたステーションの BSSID、IPアドレス、またはその両方が提供されます。

WLAN.isconnected()

STA モードの場合、WiFi アクセスポイントに接続されていて有効なIPアドレスを持っていれば True を返します。AP モードの場合、ステーションが接続されていれば True を返します。これら以外では False を返します。

WLAN.ifconfig([(ip, subnet, gateway, dns)])

IP レベルのネットワークインターフェースパラメータ(IPアドレス、サブネットマスク、ゲートウェイ、DNSサーバー)を取得/設定します。引数なしで呼び出されると、このメソッドは上記の情報を含む4タプルを返します。上記の値を設定するには、必要な情報を含む4項目のタプルを渡します。たとえば次のように設定します:

nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
WLAN.config('param')
WLAN.config(param=value, ...)

一般的なネットワークインターフェースパラメータを取得または設定します。これらのメソッドは、(AbstractNIC.ipconfig() で扱われるように)標準の IP 設定以外の追加パラメータの扱いを可能にします。これらには、ネットワーク固有およびハードウェア固有のパラメータが含まれています。パラメータを設定するには、キーワード引数の構文を使用する必要があり、複数のパラメータを一度に設定できます。問合せを実行する場合、パラメータ名は文字列として引用符で囲みます。一度に問合せできるパラメータは1つだけです。

# WiFi アクセスポイント名(正式には SSID と呼ばれている)と WiFi チャンネルを設定
ap.config(ssid='My AP', channel=11)
# 一つずつパラメータを問合せ
print(ap.config('ssid'))
print(ap.config('channel'))

以下は一般的にサポートされているパラメータです(特定のパラメータが使用可能かどうかは、ネットワーク技術の種類、ドライバー、 MicroPython ポート によって異なります)。

パラメータ

説明

mac

MAC アドレス(bytes 型オブジェクト)

ssid

WiFi アクセスポイント名(文字列)

channel

WiFi チャンネル(整数)。ポートによっては、AP インタフェースでのみサポートとなっている。

hidden

SSID が隠されているかどうか(ブール型)

security

サポートされているセキュリティプロトコル(列挙値、モジュールの定数を参照)

key

アクセスキー(文字列)

hostname

DHCP (STA インターフェース)および mDNS (サポートされていれば STA と AP の両方)に送信されるホスト名。(非推奨、代わりに network.hostname() を使ってください)

reconnects

再接続を試みる回数(整数値、0=再接続なし、-1=無制限)

txpower

最大信号強度(dBm 単位で整数または浮動小数点数で指定)

pm

WiFi 電力管理設定(指定できる値は後述)

protocol

(ESP32 のみ) WiFi 低レベル 802.11 プロトコル。 WLAN.PROTOCOL_DEFAULT を参照。

bandwidth

(ESP32 のみ) WiFiチャネル帯域幅。 WLAN.BANDWIDTH_20 などを参照してください。

CSI メソッド (ESP32 のみ)

注釈

これらのメソッドは、CSI サポートが有効になっている ESP32 ビルドでのみ利用可能です。標準の汎用 ESP32、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-S3 ボード定義では、デフォルト設定でこの機能が有効になっています。その他のビルドでは、ESP-IDF 設定で CONFIG_ESP_WIFI_CSI_ENABLED=y を設定する必要があります。

チャンネル状態情報(CSI: Channel State Information)は、受信した Wi-Fi フレームから得られるパケットごとの物理層チャンネルデータを提供します。CSI の取得には、アクティブな Wi-Fi 接続とデバイスへの受信トラフィックが必要です。トラフィックがない場合、CSI フレームは取得されません。

Espressif のその他のCSIオプションは、接続されたステーションのキャプチャを目的としたデフォルト値にハードコーディングされています。

WLAN.csi_enable(buffer_size=16)

CSI キャプチャを有効にし、受信フレーム用の循環バッファを割り当てます。

オプションの buffer_size 引数は、新しい受信フレームが破棄される前に格納されるフレーム数を指定します。値が大きいほど、RAMを消費しますが、破棄されるフレーム数は減少します。正確な最大値はビルドによって異なりますが、基盤となるリングバッファの実装によって約100フレームに制限されます。

CSI を有効にできない場合(たとえば Wi-Fi がアクティブでない場合や、ESP-IDF が構成を拒否した場合など)は OSError が発生します。

サンプルコード:

import network
import time

wlan = network.WLAN(network.WLAN.IF_STA)
wlan.active(True)
wlan.config(protocol=network.MODE_11B | network.MODE_11G | network.MODE_11N)
wlan.config(pm=wlan.PM_NONE)
wlan.connect("SSID", "password")

while not wlan.isconnected():
    time.sleep_ms(100)

wlan.csi_enable(buffer_size=32)
WLAN.csi_disable()

CSI キャプチャを無効にしてリソースをクリーンアップします。

WLAN.csi_read([result])

バッファから CSI フレームを読み取ります。

戻り値: CSI フレーム データを含むリスト。フレームが利用できない場合は None になります。

オプションの result 引数が指定されている場合、それは WLAN.csi_read() によって、以前に返されたリストである必要があります。リストはインプレースで更新され、再度返されます。これにより、既存のリスト オブジェクトと、キャプチャされたフレームが収まる場合は既存の CSI データ bytearray を再利用することで、ビジーな読み取りループでのヒープの変動が軽減されます。

フレームリストフィールド(順不同):

  • 0 - rssi (int): 受信信号強度(dBm)

  • 1 - channel (int): Wi-Fi チャンネル番号

  • 2 - mac (bytes): 送信元MACアドレス(6バイト)

  • 3 - timestamp (int): タイムスタンプ(マイクロ秒単位)

  • 4 - local_timestamp (int): Wi-Fi ハードウェアからのローカルタイムスタンプ

  • 5 - data (bytearray): CSI 生データ(int8_t 値としての I/Q コンポーネント）

  • 6 - rate (int): データレート

  • 7 - sig_mode (int): 信号モード(レガシー, HT, VHT)

  • 8 - mcs (int): 変調および符号化方式インデックス

  • 9 - cwb (int): チャンネル帯域幅

  • 10 - smoothing (int): 平滑化処理を適用

  • 11 - not_sounding (int): Not sounding フレーム

  • 12 - aggregation (int): 集約

  • 13 - stbc (int): STBC

  • 14 - fec_coding (int): FEC コーディング

  • 15 - sgi (int): ショート GI

  • 16 - noise_floor (int): 背景雑音レベル(dBm)

  • 17 - ampdu_cnt (int): AMPDU カウント

  • 18 - secondary_channel (int): セカンダリーチャンネル

  • 19 - ant (int): アンテナ

  • 20 - sig_len (int): 信号長

  • 21 - rx_state (int): RX 状態

ESP-IDF がパブリック CSI 受信構造で対応する値を提供しないターゲットでは、一部のメタデータフィールドが 0 になる場合があります。

WLAN.csi_available()

バッファ内で使用可能な CSI フレーム数を取得します。

WLAN.csi_dropped()

バッファオーバーフローによりドロップされた CSI フレームの数を取得します。バッファがいっぱいになり、新しいフレームが読み取り速度よりも速く到着すると、フレームがドロップされます。ドロップを減らすには csi_enable() の buffer_size を増やしてください。

定数

WLAN.PM_PERFORMANCE
WLAN.PM_POWERSAVE
WLAN.PM_NONE

WLAN.config(pm=...) ネットワークインタフェースパラメータに指定できる値:

  • PM_PERFORMANCE: WiFi の電力管理を有効にし、電力の節約と WiFi のパフォーマンスをバランスさせます。

  • PM_POWERSAVE: WiFi の電力管理を有効にし、電力節約を優先して、WiFi のパフォーマンス低下させます。

  • PM_NONE: WiFi の電力管理を無効にします。

ESP32 プロトコル定数

次の ESP32 専用の定数は WLAN.config(protocol=...) ネットワークインタフェースのパラメータに関連します:

WLAN.PROTOCOL_DEFAULT

チップがサポートするすべてのデフォルト 802.11 Wi-Fi モードを表すビットマップです。詳細は ESP-IDF Wi-Fi Protocols ドキュメントを参照してください。

WLAN.PROTOCOL_LR

この値は Espressif proprietary "long-range" mode モードに対応します。これは標準的な Wi-Fi デバイスとは互換性がありません。このプロトコルを設定することで、長距離モードの ESP32 STA が長距離モードの ESP32 AP に接続したり、 ESP-NOW の長距離モード を使用したりできます。

このモードは、一部の標準 802.11 プロトコルビット(WLAN.PROTOCOL_DEFAULT を含む)とビットORで組み合わせることが可能で、標準 Wi-Fi モードと LR モードを混在させることができます。詳細は Espressif long-range documentation を参照してください。

長距離モードは ESP32-C2 ではサポートされていません。

WLAN.BANDWIDTH_20
WLAN.BANDWIDTH_40
WLAN.BANDWIDTH_80
WLAN.BANDWIDTH_160
WLAN.BANDWIDTH_80_80

WLAN.config(bandwidth=...) ネットワークインターフェイスパラメータに指定可能な値:

  • BANDWIDTH_20: STA および AP モード時に 20MHz 幅の WiFi チャンネルを指定します。

  • BANDWIDTH_40: STA および AP モード時に 40MHz 幅の WiFi チャンネルを指定します。

  • BANDWIDTH_80: AP モード時に 80MHz 幅の WiFi チャンネルを指定します。すべての ESP32 モデルで使えるとは限りません。

  • BANDWIDTH_160: AP モード時に 160MHz 幅の WiFi チャネルを指定します。すべての ESP32 モデルで使えるとは限りません。

  • BANDWIDTH_80_80: AP モード時にマルチアンテナ 80MHz + 80MHz 幅の WiFi チャネル設定を指定します。すべての ESP32 モデルで使えるとは限りません。

STA モードでは、アダプタがネットワークに接続されていない場合にのみ帯域幅を変更できます。AP モードでは、いつでも変更できます。