Wi-Fi ライブラリ

重要

このライブラリは、非推奨の Amazon-FreeRTOS リポジトリでホストされています。新しいプロジェクトを作成するときは、ここから始めることをお勧めします。現在非推奨の Amazon-FreeRTOS リポジトリをベースにした既存の FreeRTOS プロジェクトが既にある場合は、「Amazon FreeRTOS Github リポジトリ移行ガイド」を参照してください。

概要

FreeRTOS Wi-Fi ライブラリは、ポート別の Wi-Fi 実装を、Wi-Fi 機能を持つすべての FreeRTOS 認定ボードでのアプリケーション開発および移植を簡素化する共通の API に抽象化します。この共通の API を使用して、アプリケーションは、共通のインターフェイスを通じて低いレベルのワイヤレスのスタックと通信できます。

依存関係と要件

FreeRTOS Wi-Fi ライブラリには、FreeRTOS+TCP コアが必要です。

機能

Wi-Fi ライブラリには以下の機能があります。

WEP、WPA、WPA2、WPA3 認証のサポート
アクセスポイントのスキャン
電源管理
ネットワークプロファイリング

Wi-Fi ライブラリの機能の詳細については、以下を参照してください。

Wi-Fi モード

Wi-Fi デバイスは、ステーションモード、アクセスポイントモード、P2P モードの 3 つのうちのいずれかのモードになります。Wi-Fi デバイスの現在のモードは、WIFI_GetMode を呼び出すことで取得できます。デバイスの Wi-Fi モードは、WIFI_SetMode を呼び出すことで設定できます。デバイスが既にネットワークに接続されている状態で WIFI_SetMode を呼び出してモードを切り替えると、接続は切断されます。

ステーションモード: デバイスをステーションモードに設定すると、ボードを既存のアクセスポイントに接続できます。
アクセスポイント (AP) モード: デバイスを AP モードに設定すると、そのデバイスを他のデバイスが接続できるアクセスポイントにすることができます。デバイスが AP モードになっている場合、FreeRTOS デバイスに別のデバイスを接続し、新しい Wi-Fi 認証情報を設定することができます。AP モードを設定するには、WIFI_ConfigureAP を呼び出します。デバイスを AP モードにするには、WIFI_StartAP を呼び出します。AP モードをオフにするには、WIFI_StopAP を呼び出します。

注記
FreeRTOS ライブラリは、AP モードでは Wi-Fi プロビジョニングを提供しません。AP モードを完全にサポートするには、DHCP および HTTP サーバー機能を含む追加の機能を提供する必要があります。
P2P モード: デバイスを P2P モードに設定すると、アクセスポイントなしで、複数のデバイスを直接相互に接続できるようにすることができます。

セキュリティ

Wi-Fi API は、WEP、WPA、WPA2、WPA3 セキュリティタイプをサポートしています。デバイスがステーションモードの場合は、WIFI_ConnectAP 関数を呼び出すときにネットワークセキュリティタイプを指定する必要があります。デバイスが AP モードの場合は、以下のサポートされているセキュリティタイプのいずれかを使用するようにデバイスを設定できます。

eWiFiSecurityOpen
eWiFiSecurityWEP
eWiFiSecurityWPA
eWiFiSecurityWPA2
eWiFiSecurityWPA3

スキャンと接続

近くにあるアクセスポイントをスキャンするには、デバイスをステーションモードに設定し、WIFI_Scan 関数を呼び出します。スキャンで目的のネットワークが見つかった場合は、WIFI_ConnectAP を呼び出してそのネットワークの認証情報を指定することで、ネットワークに接続できます。ネットワークからの Wi-Fi デバイスの切断は、WIFI_Disconnect を呼び出すことで行えます。スキャンと接続の詳細については、「使用例」および「API リファレンス」を参照してください。

電源管理

さまざまな Wi-Fi デバイスやアプリケーションに応じて、要件が異なる電源を使用できます。Wi-Fi が不要な場合は、レイテンシーを短くするためにデバイスの電源をオンにするか、断続的に接続して低電力モードに切り替えることがあります。インターフェイス API は、常時オン、低電力、通常モードなどのさまざまな電力管理モードをサポートしています。WIFI_SetPMMode 関数を使用して、デバイスの電源モードを設定します。デバイスの現在の電源モードは、WIFI_GetPMMode 関数を呼び出すことで取得できます。

ネットワークプロファイル

Wi-Fi ライブラリを使用すると、ネットワークプロファイルをデバイスの不揮発性メモリに保存できます。これによりネットワーク設定が保存され、デバイスが Wi-Fi ネットワークに再接続したときにその設定が取得されるので、ネットワークに接続した後にデバイスを再プロビジョニングする必要がなくなります。WIFI_NetworkAdd はネットワークプロファイルを追加します。WIFI_NetworkGet は、ネットワークプロファイルを取得します。WIFI_NetworkDel はネットワークプロファイルを削除します。保存できるプロファイルの数は、プラットフォームによって異なります。

構成

Wi-Fi ライブラリを使用するには、設定ファイルで複数の ID を定義する必要があります。これらの ID の詳細については、API リファレンスを参照してください。

注記

ライブラリには、必要な設定ファイルは含まれていません。設定ファイルは作成する必要があります。設定ファイルを作成するときは、必ず、ボードに必要なボード固有の設定 ID を含める必要があります。

初期化

Wi-Fi ライブラリを使用する前には、FreeRTOS コンポーネントに加えて、一部のオンボード固有のコンポーネントを初期化する必要があります。初期化のテンプレートとして vendors/vendor/boards/board/aws_demos/application_code/main.c ファイルを使用し、以下の操作を行います。

ご自分のアプリケーションで Wi-Fi 接続を処理する場合は、main.c のサンプル Wi-Fi 接続ロジックを削除してください。以下の DEMO_RUNNER_RunDemos() 関数呼び出しを


if( SYSTEM_Init() == pdPASS )
    {
    ...
        DEMO_RUNNER_RunDemos();
    ...
        }

ご自分のアプリケーションの呼び出しに置き換えます。


if( SYSTEM_Init() == pdPASS )
    {
    ...
        // This function should create any tasks
        // that your application requires to run.
        YOUR_APP_FUNCTION();
    ...
        }

WIFI_On() を呼び出して、Wi-Fi チップを初期化して電源を入れます。

注記
一部のボードでは、追加のハードウェア初期化処理が必要になる場合があります。
設定済みの WIFINetworkParams_t 構造を WIFI_ConnectAP() に渡して、利用可能な Wi-Fi ネットワークにボードを接続します。WIFINetworkParams_t 構造の詳細については、「使用例」および「API リファレンス」を参照してください。

API リファレンス

完全な API リファレンスについては、Wi-Fi API リファレンスを参照してください。

使用例

既知の AP への接続


#define clientcredentialWIFI_SSID    "MyNetwork"
#define clientcredentialWIFI_PASSWORD   "hunter2"

WIFINetworkParams_t xNetworkParams;
WIFIReturnCode_t xWifiStatus;

xWifiStatus = WIFI_On(); // Turn on Wi-Fi module

// Check that Wi-Fi initialization was successful
if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ( "WiFi library initialized.\n") );
}
else
{
    configPRINT( ( "WiFi library failed to initialize.\n" ) );
    // Handle module init failure
}

/* Setup parameters. */
xNetworkParams.pcSSID = clientcredentialWIFI_SSID;
xNetworkParams.ucSSIDLength = sizeof( clientcredentialWIFI_SSID );
xNetworkParams.pcPassword = clientcredentialWIFI_PASSWORD;
xNetworkParams.ucPasswordLength = sizeof( clientcredentialWIFI_PASSWORD );
xNetworkParams.xSecurity = eWiFiSecurityWPA2;

// Connect!
xWifiStatus = WIFI_ConnectAP( &( xNetworkParams ) );

if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ( "WiFi Connected to AP.\n" ) );
    // IP Stack will receive a network-up event on success
}
else
{
    configPRINT( ( "WiFi failed to connect to AP.\n" ) );
    // Handle connection failure
}

近くにある AP のスキャン


WIFINetworkParams_t xNetworkParams;
WIFIReturnCode_t xWifiStatus;

configPRINT( ("Turning on wifi...\n") );
xWifiStatus = WIFI_On();

configPRINT( ("Checking status...\n") );
if( xWifiStatus == eWiFiSuccess )
{
    configPRINT( ("WiFi module initialized.\n") );
}
else
{
    configPRINTF( ("WiFi module failed to initialize.\n" ) );
    // Handle module init failure
}

WIFI_SetMode(eWiFiModeStation);

/* Some boards might require additional initialization steps to use the Wi-Fi library. */

while (1)
{
    configPRINT( ("Starting scan\n") );
    const uint8_t ucNumNetworks = 12; //Get 12 scan results
    WIFIScanResult_t xScanResults[ ucNumNetworks ];
    xWifiStatus = WIFI_Scan( xScanResults, ucNumNetworks ); // Initiate scan

    configPRINT( ("Scan started\n") );

    // For each scan result, print out the SSID and RSSI
    if ( xWifiStatus == eWiFiSuccess )
    {
        configPRINT( ("Scan success\n") );
        for ( uint8_t i=0; i<ucNumNetworks; i++ ) 
        {
            configPRINTF( ("%s : %d \n", xScanResults[i].cSSID, xScanResults[i].cRSSI) );
        }
    } else {
        configPRINTF( ("Scan failed, status code: %d\n", (int)xWifiStatus) );
    }
    
    vTaskDelay(200);
}

移植

iot_wifi.c 実装は、iot_wifi.h で定義された関数を実装する必要があります。少なくとも、不可欠でない関数またはサポートされていない関数では、この実装は eWiFiNotSupported を返す必要があります。

Wi-Fi ライブラリを移植する方法については、FreeRTOS 移植ガイドの Wi-Fi ライブラリの移植を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Transport Layer Security

FreeRTOS デモ