Libreria Wi-Fi

Importante

Questa libreria è ospitata nel repository Amazon-FreeRTOS che è obsoleto. Ti consigliamo di iniziare da qui quando crei un nuovo progetto. Se hai già un progetto FreeRTOS esistente basato sull'ormai obsoleto repository Amazon-FreerTOS, consulta il. Guida alla migrazione del repository Github di Amazon-FreeRTOS

Panoramica

La libreria Wi-Fi FreeRTOS riassume le implementazioni Wi-Fi specifiche delle porte in un'API comune che semplifica lo sviluppo e il porting delle applicazioni per tutte le schede qualificate FreerTOS con funzionalità Wi-Fi. Utilizzando queste API comuni, le applicazioni possono comunicare con il loro stack wireless di livello inferiore attraverso un'interfaccia comune.

Dipendenze e requisiti

La libreria Wi-Fi FreeRTOS richiede il core FreeRTOS+TCP.

Funzionalità

La libreria Wi-Fi include le seguenti caratteristiche:

• Support per l'autenticazione WEP, WPA, WPA2 e WPA3

• Scansione del punto di accesso

• Risparmio energetico

• Profiling di rete

Ulteriori informazioni sulle caratteristiche della libreria Wi-Fi sono riportate di seguito.

Modalità Wi-Fi

I dispositivi Wi-Fi possono essere in una di tre modalità: Station, Access Point o P2P. È possibile ottenere la modalità corrente di un dispositivo Wi-Fi chiamando WIFI_GetMode. È possibile impostare la modalità Wi-Fi di un dispositivo chiamando WIFI_SetMode. Cambiando le modalità chiamando WIFI_SetMode, si disconnette il dispositivo, se connesso a una rete.

Modalità Station

Imposta il dispositivo in modalità Station per collegare la scheda a un punto di accesso esistente.

Modalità Access Point (AP)

Imposta il dispositivo in modalità AP per renderlo un punto di accesso a cui altri dispositivi possano connettersi. Quando il dispositivo è in modalità AP, puoi connettere un altro dispositivo al tuo dispositivo FreeRTOS e configurare le nuove credenziali Wi-Fi. Per configurare la modalità del punto di accesso, chiamare WIFI_ConfigureAP. Per inserire il dispositivo in modalità AP, chiama WIFI_StartAP. Per disattivare la modalità AP, chiama WIFI_StopAP.

Nota

Le librerie FreerTOS non forniscono il provisioning Wi-Fi in modalità AP. È necessario fornire le funzionalità aggiuntive, incluse le funzionalità del server DHCP e HTTP, per ottenere il supporto completo della modalità AP.

Modalità P2P

Imposta il dispositivo in modalità P2P per consentire a più dispositivi di connettersi l'un l'altro direttamente, senza un punto di accesso.

Sicurezza

L'API Wi-Fi supporta i tipi di sicurezza WEP, WPA, WPA2 e WPA3. Se un dispositivo è in modalità Station, è necessario specificare il tipo di sicurezza di rete quando si chiama la funzione WIFI_ConnectAP. Se è in modalità AP, un dispositivo può essere configurato per l'utilizzo di qualsiasi tipo di sicurezza supportato:

• eWiFiSecurityOpen

• eWiFiSecurityWEP

• eWiFiSecurityWPA

• eWiFiSecurityWPA2

• eWiFiSecurityWPA3

Scansione e connessione

Per eseguire la scansione di punti di accesso nelle vicinanze, imposta il dispositivo in modalità Station e chiama la funzione WIFI_Scan. Se la scansione trova la rete a cui intendi connetterti, puoi effettuare la connessione chiamando WIFI_ConnectAP e fornendo le credenziali di rete. Puoi disconnettere un dispositivo Wi-Fi dalla rete chiamando WIFI_Disconnect. Per ulteriori informazioni sulla scansione e la connessione, consulta Esempio di utilizzo e Riferimento API.

Risparmio energetico

Dispositivi Wi-Fi diversi prevedono requisiti di alimentazione diversi, a seconda dell'applicazione e delle sorgenti di alimentazione disponibili. Un dispositivo potrebbe essere sempre acceso per ridurre la latenza oppure potrebbe essere connesso a intermittenza e passare a una modalità a basso consumo quando non è richiesta una connessione Wi-Fi. L'API dell'interfaccia supporta vari metodi di gestione dell'alimentazione, ad esempio sempre acceso, modalità a basso consumo e modalità normale. È possibile impostare la modalità di alimentazione per un dispositivo utilizzando la funzione WIFI_SetPMMode. È possibile conoscere la modalità di alimentazione attuale di un dispositivo chiamando la funzione WIFI_GetPMMode.

Profili di rete

La libreria Wi-Fi consente di salvare i profili di rete nella memoria non volatile dei tuoi dispositivi. In questo modo è possibile salvare le impostazioni di rete in modo che possano essere recuperate quando un dispositivo si riconnette a una rete Wi-Fi, eliminando la necessità di effettuare nuovamente il provisioning dei dispositivi dopo che sono stati connessi a una rete. WIFI_NetworkAdd aggiunge un profilo di rete. WIFI_NetworkGet recupera un profilo di rete. WIFI_NetworkDel elimina un profilo di rete. Il numero di profili che è possibile salvare dipende dalla piattaforma.

Configurazione

Per usare la libreria Wi-Fi, è necessario definire diversi identificatori in un file di configurazione. Per ulteriori informazioni su questi identificatori, consulta la Riferimento API.

Nota

La libreria non include il file di configurazione necessario. Devi crearne uno. Quando crei il tuo file di configurazione, assicurati di includere qualsiasi identificatore di configurazione specificatamente richiesto dalla scheda.

Inizializzazione

Prima di utilizzare la libreria Wi-Fi, oltre ai componenti FreeRTOS è necessario inizializzare alcuni componenti specifici per la scheda. Utilizzando il file vendors/vendor/boards/board/aws_demos/application_code/main.c come modello per l'inizializzazione, procedi come segue:

1. Se la tua applicazione è in grado di gestire le connessioni Wi-Fi, rimuovi la logica di connessione Wi-Fi di esempio in main.c. Sostituisci la seguente chiamata di funzione DEMO_RUNNER_RunDemos():

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

   Con una chiamata alla tua applicazione:

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

2. Chiama WIFI_On() per inizializzare e accendere il chip Wi-Fi.

   Nota

   Alcune schede potrebbero richiedere un'inizializzazione hardware aggiuntiva.

3. Passa una struttura WIFINetworkParams_t configurata a WIFI_ConnectAP() per connettere la scheda a una rete Wi-Fi disponibile. Per ulteriori informazioni sulla struttura WIFINetworkParams_t, consulta Esempio di utilizzo e Riferimento API.

Riferimento API

Per informazioni di riferimento complete sull'API, consulta Documentazione di riferimento sull'API Wi-Fi.

Esempio di utilizzo

Connessione a un punto di accesso noto

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

Scansione di punti di accesso nelle vicinanze

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

Portabilità

L'implementazione iot_wifi.c deve introdurre le funzioni definite in iot_wifi.h. Come minimo, l'implementazione deve restituire eWiFiNotSupported per qualsiasi funzione non essenziale o non supportata.

Per ulteriori informazioni sul porting della libreria Wi-Fi, consulta Porting the Wi-Fi Library nella FreerTOS Porting Guide.