Bibliothèque Wi-Fi

Important

Cette bibliothèque est hébergée sur le référentiel Amazon-FreeRTOS, qui est obsolète. Nous vous recommandons de commencer ici lorsque vous créez un nouveau projet. Si vous possédez déjà un projet FreeRTOS basé sur le référentiel Amazon-FreeRTOS, désormais obsolète, consultez le. Guide de migration du référentiel Github d'Amazon-FreeRTOS

Présentation

La bibliothèque Wi-Fi FreeRTOS extrait les implémentations Wi-Fi spécifiques aux ports dans une API commune qui simplifie le développement et le portage d'applications pour toutes les cartes compatibles FreeRTOS dotées de fonctionnalités Wi-Fi. À l'aide de cette API courante, les applications peuvent communiquer avec leur pile sans fil de niveau inférieur via une interface commune.

Dépendances et exigences

La bibliothèque Wi-Fi FreeRTOS nécessite le noyau FreeRTOS+TCP.

Fonctionnalités

La bibliothèque Wi-Fi comprend les fonctions suivantes :

• Support pour l'authentification WEP, WPA, WPA2 et WPA3

• Balayage de point d'accès

• Gestion de l'alimentation

• Profils réseau

Pour plus d'informations sur les fonctions de la bibliothèque Wi-Fi, voir ci-dessous.

Modes Wi-Fi

Les appareils Wi-Fi peuvent être dans l'un de ces trois modes : Station, Access Point ou P2P. Vous pouvez obtenir le mode en cours d'un appareil Wi-Fi en appelant WIFI_GetMode. Vous pouvez définir le mode Wi-Fi d'un appareil Wi-Fi en appelant WIFI_SetMode. Le changement de mode en appelant WIFI_SetMode déconnecte l'appareil, s'il est déjà connecté à un réseau.

Mode Station

Configurez votre appareil en mode Station pour connecter la carte à un point d'accès existant.

Mode Access Point (AP)

Configurez votre appareil en mode AP de façon à rendre en faire un point d'accès auquel d'autres appareils peuvent se connecter. Lorsque votre appareil est en mode AP, vous pouvez connecter un autre appareil à votre appareil FreeRTOS et configurer les nouvelles informations d'identification Wi-Fi. Pour configurer le mode AP, appelez WIFI_ConfigureAP. Pour placer votre appareil en mode AP, appelez WIFI_StartAP. Pour désactiver le mode AP, appelez WIFI_StopAP.

Note

Les bibliothèques FreeRTOS ne fournissent pas de connexion Wi-Fi en mode AP. Vous devez fournir les fonctionnalités supplémentaires, y compris les capacités de serveur DHCP et HTTP, pour obtenir la prise en charge complète du mode point d’accès.

Mode P2P

Configurez votre appareil en mode P2P pour permettre à plusieurs appareils de se connecter directement l'un à l'autre, sans point d'accès.

Sécurité

L'API Wi-Fi prend en charge les types de sécurité WEP, WPA, WPA2 et WPA3. Lorsqu'un appareil se trouve en mode Station, vous devez spécifier le type de sécurité réseau lors de l'appel de la fonction WIFI_ConnectAP. Lorsqu'un appareil est en mode AP, l'appareil peut être configuré pour utiliser n'importe lequel des types de sécurité pris en charge :

• eWiFiSecurityOpen

• eWiFiSecurityWEP

• eWiFiSecurityWPA

• eWiFiSecurityWPA2

• eWiFiSecurityWPA3

Analyse et connexion

Pour rechercher des points d'accès à proximité, configurez votre appareil en mode Station et appelez la fonction WIFI_Scan. Si vous trouvez un certain réseau dans l'analyse, vous pouvez vous y connecter en appelant WIFI_ConnectAP et en fournissant les informations d'identification du réseau. Vous pouvez déconnecter un appareil Wi-Fi du réseau en appelant WIFI_Disconnect. Pour plus d'informations sur l'analyse et la connexion, consultez Exemple d’utilisation et Référence d’API.

Gestion de l'alimentation

Les différents appareils Wi-Fi ont différentes exigences en matière d'alimentation, en fonction de l'application et des sources d'alimentation disponibles. Un appareil peut être toujours allumé pour réduire la latence, ou être connecté par intermittence et basculer en mode alimentation basse lorsque le mode Wi-Fi n'est pas requis. L'API d'interface prend en charge divers modes de gestion de l'alimentation, comme toujours activée, alimentation basse et mode normal. Vous définissez le mode d'alimentation d'un appareil à l'aide de la fonction WIFI_SetPMMode. Vous pouvez obtenir le mode d'alimentation en cours d'un appareil Wi-Fi en appelant la fonction WIFI_GetPMMode.

Profils réseau

La bibliothèque Wi-Fi vous permet d'enregistrer les profils de réseau dans la mémoire non volatile de vos appareils. Cela vous permet d'enregistrer les paramètres réseau afin qu'ils puissent être récupérés lorsqu'un appareil se reconnecte à un réseau Wi-Fi, supprimant ainsi la nécessité de mettre à nouveau en service les appareils une fois qu'ils ont été connectés à un réseau. WIFI_NetworkAdd ajoute un profil réseau. WIFI_NetworkGet récupère un profil réseau. WIFI_NetworkDel supprime un profil réseau. Le nombre de profils que vous pouvez enregistrer dépend de la plateforme.

Configuration

Pour utiliser la bibliothèque Wi-Fi, vous devez définir plusieurs identifiants dans un fichier de configuration. Pour plus d'informations sur ces identifiants, consultez Référence d’API.

Note

La bibliothèque n'inclut pas le fichier de configuration nécessaire. Vous devez en créer un. Lorsque vous créez votre fichier de configuration, veillez à inclure les identifiants de configuration spécifiques à votre carte.

Initialisation

Avant d'utiliser la bibliothèque Wi-Fi, vous devez initialiser certains composants spécifiques à la carte, en plus des composants FreeRTOS. En utilisant le fichier vendors/vendor/boards/board/aws_demos/application_code/main.c comme modèle pour l'initialisation, procédez de la façon suivante :

1. Supprimez l'exemple de logique de connexion Wi-Fi dans main.c si votre application gère les connexions Wi-Fi. Remplacez l'appel de fonction DEMO_RUNNER_RunDemos() suivant :

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

   Par un appel à votre propre application :

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

2. Appelez WIFI_On() pour initialiser et mettre en service votre puce Wi-Fi.

   Note

   Certaines cartes peuvent nécessiter une initialisation du matériel supplémentaire.

3. Transmettez une structure WIFINetworkParams_t configurée à WIFI_ConnectAP() pour connecter la carte à un réseau Wi-Fi disponible. Pour plus d'informations sur la structure WIFINetworkParams_t, consultez Exemple d’utilisation et Référence d’API.

Référence d’API

Pour obtenir une référence d'API complète, consultez la Référence d'API Wi-Fi.

Exemple d’utilisation

Connexion à un point d'accès connu

#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
}

Recherche des points d'accès à proximité

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);
}

Portage

L'implémentation iot_wifi.c nécessite l'implémentation des fonctions définies dans iot_wifi.h. Au minimum, l'implémentation doit retourner eWiFiNotSupported pour toute fonction non essentielle ou non prise en charge.

Pour plus d'informations sur le portage de la bibliothèque Wi-Fi, voir Portage de la bibliothèque Wi-Fi dans le Guide de portage de FreeRTOS.