Wi-Fi ライブラリ

重要

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

概要

無料RTOS Wi-Fi ライブラリは、ポート固有の Wi-Fi 実装を共通に抽象化します。APIこれにより、Wi-Fi 機能を持つすべての無料RTOS認定ボードのアプリケーション開発と移植が簡素化されます。この共通を使用するとAPI、アプリケーションは共通インターフェイスを介して下位レベルのワイヤレススタックと通信できます。

依存関係と要件

無料RTOS Wi-Fi ライブラリには、無料 RTOS＋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 モードの場合、別のデバイスを無料RTOSデバイスに接続し、新しい Wi-Fi 認証情報を設定できます。AP モードを設定するには、WIFI_ConfigureAP を呼び出します。デバイスを AP モードにするには、WIFI_StartAP を呼び出します。AP モードをオフにするには、WIFI_StopAP を呼び出します。

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

セキュリティ

Wi-Fi は、WEP、、WPAWPA2、および WPA3 セキュリティタイプAPIをサポートしています。デバイスがステーションモードの場合は、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 ライブラリを使用する前に、無料RTOSコンポーネントに加えて、一部のボード固有のコンポーネントを初期化する必要があります。初期化のテンプレートとして 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
}

近くののスキャン APs


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 ライブラリの移植の詳細については、「無料RTOS移植ガイド」の「Wi-Fi ライブラリの移植」を参照してください。

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

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

ドキュメントの表記規則

Transport Layer Security

FreeRTOS デモ