Provisioning

         Here are listed all the functions that implement the Wifi Provisioning APIs.

Functions
sint8	m2m_wifi_start_provision_mode (tstrM2MAPConfig *pstrM2MAPConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect)
	Asynchronous API for control of Wi-Fi provisioning functionality. More...
sint8	m2m_wifi_start_provision_mode_ext (tstrM2MAPModeConfig *pstrAPModeConfig, char *pcHttpServerDomainName, uint8 bEnableHttpRedirect)
	Asynchronous API for control of Wi-Fi provisioning functionality with extended options. More...
sint8	m2m_wifi_stop_provision_mode (void)
	Synchronous API for terminating provisioning mode on the WINC IC. More...

NMI_API sint8 m2m_wifi_start_provision_mode	(	tstrM2MAPConfig *	pstrAPConfig,
		char *	pcHttpServerDomainName,
		uint8	bEnableHttpRedirect
	)

Asynchronous API for control of Wi-Fi provisioning functionality.

Asynchronous Wi-Fi provisioning function, which starts the WINC HTTP PROVISIONING mode.
The function triggers the WINC to activate the Wi-Fi AP (HOTSPOT) mode with the passed
configuration parameters and then starts the HTTP Provision WEB Server.

Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

Parameters

[in]	pstrAPConfig	AP configuration parameters as defined in tstrM2MAPConfig configuration structure. If a NULL value is passed in, the call will result in a negative error M2M_ERR_FAIL.
[in]	pcHttpServerDomainName	Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: 1. "wincprov.com" 2. "http://wincprov.com" 3. "https://wincprov.com"

Forms 1 and 2 are equivalent, they will both start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection).

Parameters

[in]

bEnableHttpRedirect

A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: ZERO value, which means DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. Non-Zero value, means use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page.

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization m2m_wifi_init function.
• The event M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

Warning

DO NOT use ".local" in the pcHttpServerDomainName.

Returns

The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also

tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPConfig

Example

The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_PROVISION_INFO:
        {
            tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
            if(pstrProvInfo->u8Status == M2M_SUCCESS)
            {
                tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))};
                m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
            }
            else
            {
                printf("(ERR) Provisioning Failed\n");
            }
        }
        break;

        default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPConfig     apConfig;
        uint8               bEnableRedirect = 1;

        strcpy(apConfig.au8SSID, "WINC_SSID");
        apConfig.u8ListenChannel    = 1;
        apConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
        apConfig.u8SsidHide         = 0;

        // IP Address
        apConfig.au8DHCPServerIP[0] = 192;
        apConfig.au8DHCPServerIP[1] = 168;
        apConfig.au8DHCPServerIP[2] = 1;
        apConfig.au8DHCPServerIP[3] = 1;

        m2m_wifi_start_provision_mode(&apConfig, "atmelwincconf.com", bEnableRedirect);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

This function allows the application to start the WINC in 'provisioning mode', a special mode
that triggers the WINC to create a Wi-Fi access point, DHCP server, and HTTP server.

The HTTP server presents a provisioning page to a connected client which lists the access points
detected in the vicinity of the WINC, and allows one of these to be selected and any appropriate
credentials to be entered. This allows a headless system to be provisioned (configured to
connect with an access point).

Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

Parameters

[in]	pstrAPConfig	AP configuration parameters as defined in tstrM2MAPConfig configuration structure. If a NULL value is passed in, the call will result in a negative error M2M_ERR_FAIL.
[in]	pcHttpServerDomainName	Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: 1. "wincprov.com" 2. "http://wincprov.com" 3. "https://wincprov.com"

Forms 1 and 2 are equivalent, they will both start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection).

Parameters

[in]

bEnableHttpRedirect

A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: Zero: DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. Non-Zero: Use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page.

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization m2m_wifi_init function.
• The event M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

Warning

Do not use ".local" in the pcHttpServerDomainName.

Returns

The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

See Also

tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPConfig

Example

The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_PROVISION_INFO:
        {
            tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
            if(pstrProvInfo->u8Status == M2M_SUCCESS)
            {
                tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))};
                m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
            }
            else
            {
                printf("(ERR) Provisioning Failed\n");
            }
        }
        break;

        default:
        break;
    }
}

int main()
{
    tstrWifiInitParam param;
    param.pfAppWifiCb = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPConfig apConfig;
        uint8           bEnableRedirect = 1;

        strcpy(apConfig.au8SSID, "WINC_SSID");
        apConfig.u8ListenChannel = 1;
        apConfig.u8SecType       = M2M_WIFI_SEC_OPEN;
        apConfig.u8SsidHide      = 0;

        // IP Address
        apConfig.au8DHCPServerIP[0] = 192;
        apConfig.au8DHCPServerIP[1] = 168;
        apConfig.au8DHCPServerIP[2] = 1;
        apConfig.au8DHCPServerIP[3] = 1;

        m2m_wifi_start_provision_mode(&apConfig, "atmelwincconf.com", bEnableRedirect);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Referenced by main(), and os_m2m_wifi_start_provision_mode_imp().

NMI_API sint8 m2m_wifi_start_provision_mode_ext	(	tstrM2MAPModeConfig *	pstrAPModeConfig,
		char *	pcHttpServerDomainName,
		uint8	bEnableHttpRedirect
	)

Asynchronous API for control of Wi-Fi provisioning functionality with extended options.

Asynchronous Wi-Fi provisioning function, which starts the WINC HTTP PROVISIONING mode.
The function triggers the WINC to activate the Wi-Fi AP (HOTSPOT) mode with the passed
configuration parameters and then starts the HTTP Provision WEB Server.

Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

Parameters

[in]	pstrAPModeConfig	AP configuration parameters as defined in tstrM2MAPModeConfig configuration structure. A NULL value passed in, will result in a negative error M2M_ERR_FAIL.
[in]	pcHttpServerDomainName	Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: 1. "wincprov.com" 2. "http://wincprov.com" 3. "https://wincprov.com"

The forms 1 and 2 are equivalent, they both will start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection).

Parameters

[in]

bEnableHttpRedirect

A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: ZERO value, which means DO NOT use HTTP Redirect. In this case, the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. Non-Zero value, means use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, etc) will be redirected to the WINC HTTP Provisioning Home page.

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization m2m_wifi_init function.
• The event M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

Warning

DO Not use ".local" in the pcHttpServerDomainName.

See Also

tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPModeConfig

Returns

The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

Example

The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_PROVISION_INFO:
        {
            tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
            if(pstrProvInfo->u8Status == M2M_SUCCESS)
            {
                tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))};
                m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
            }
            else
            {
                printf("(ERR) Provisioning Failed\n");
            }
        }
        break;

        default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPModeConfig apModeConfig;
        uint8               bEnableRedirect = 1;
        
        strcpy(apModeConfig.strApConfig.au8SSID, "WINC_SSID");
        apModeConfig.strApConfig.u8ListenChannel    = 1;
        apModeConfig.strApConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
        apModeConfig.strApConfig.u8SsidHide         = 0;
        
        // IP Address
        apModeConfig.strApConfig.au8DHCPServerIP[0] = 192;
        apModeConfig.strApConfig.au8DHCPServerIP[1] = 168;
        apModeConfig.strApConfig.au8DHCPServerIP[2] = 1;
        apModeConfig.strApConfig.au8DHCPServerIP[3] = 1;

        // Default router IP
        m2m_memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

        // DNS Server IP
        m2m_memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);
        
        // Subnet mask
        apModeConfig.strApConfigExt.au8SubnetMask[0]    = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[1]    = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[2]    = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[3]    = 0;

        m2m_wifi_start_provision_mode_ext(&apModeConfig, "atmelwincconf.com", bEnableRedirect);
                    
        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

This function allows the application to start the WINC in 'provisioning mode', a special mode
that triggers the WINC to create a Wi-Fi access point, DHCP server, and HTTP server.

The HTTP server presents a provisioning page to a connected client which lists the access points
detected in the vicinity of the WINC, and allows one of these to be selected and any appropriate
credentials to be entered. This allows a headless system to be provisioned (configured to
connect with an access point).

Provisioning status is returned in an event @ref M2M_WIFI_RESP_PROVISION_INFO.

Parameters

[in]	pstrAPModeConfig	AP configuration parameters as defined in tstrM2MAPModeConfig configuration structure. A NULL value passed in, will result in a negative error M2M_ERR_FAIL.
[in]	pcHttpServerDomainName	Domain name of the HTTP Provision WEB server which others will use to load the provisioning Home page. The domain name can have one of the following 3 forms: 1. "wincprov.com" 2. "http://wincprov.com" 3. "https://wincprov.com"

The forms 1 and 2 are equivalent, they both will start a plain http server, while form 3 will start a secure HTTP provisioning Session (HTTP over SSL connection).

Parameters

[in]

bEnableHttpRedirect

A flag to enable/disable the HTTP redirect feature. If Secure provisioning is enabled (i.e. the server domain name uses "https" prefix) this flag is ignored (no meaning for redirect in HTTPS). Possible values are: Zero: DO NOT use HTTP Redirect. In this case the associated device could open the provisioning page ONLY when the HTTP Provision URL of the WINC HTTP Server is correctly written on the browser. Non-Zero: Use HTTP Redirect. In this case, all http traffic (http://URL) from the associated device (Phone, PC, ...etc) will be redirected to the WINC HTTP Provisioning Home page.

Returns

The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

Precondition

• A Wi-Fi notification callback of type tpfAppWifiCb MUST be implemented and registered at startup. Registering the callback is done through passing it to the initialization m2m_wifi_init function.
• The event M2M_WIFI_RESP_CONN_INFO must be handled in the callback to receive the requested connection info.

Warning

Do not use ".local" in the pcHttpServerDomainName.

See Also

tpfAppWifiCb m2m_wifi_init M2M_WIFI_RESP_PROVISION_INFO m2m_wifi_stop_provision_mode tstrM2MAPModeConfig

Example

The example demonstrates a code snippet for how provisioning is triggered and the response event received accordingly.

#include "m2m_wifi.h"
#include "m2m_types.h"

void wifi_event_cb(uint8 u8WiFiEvent, void * pvMsg)
{
    switch(u8WiFiEvent)
    {
    case M2M_WIFI_RESP_PROVISION_INFO:
        {
            tstrM2MProvisionInfo    *pstrProvInfo = (tstrM2MProvisionInfo*)pvMsg;
            if(pstrProvInfo->u8Status == M2M_SUCCESS)
            {
                tstrNetworkId   strNetworkId = {NULL, pstrProvInfo->au8SSID, (uint8)strlen((char*)(pstrProvInfo->au8SSID)), M2M_WIFI_CH_ALL};
                tstrAuthPsk     strAuthPsk = {NULL, pstrProvInfo->au8Password, (uint8)strlen((char*)(pstrProvInfo->au8Password))};
                m2m_wifi_connect_psk(WIFI_CRED_SAVE_ENCRYPTED, &strNetworkId, &strAuthPsk);

                printf("PROV SSID : %s\n",pstrProvInfo->au8SSID);
                printf("PROV PSK  : %s\n",pstrProvInfo->au8Password);
            }
            else
            {
                printf("(ERR) Provisioning Failed\n");
            }
        }
        break;

        default:
        break;
    }
}

int main()
{
    tstrWifiInitParam   param;

    param.pfAppWifiCb   = wifi_event_cb;
    if(!m2m_wifi_init(&param))
    {
        tstrM2MAPModeConfig apModeConfig;
        uint8               bEnableRedirect = 1;

        strcpy(apModeConfig.au8SSID, "WINC_SSID");
        apModeConfig.strApConfig.u8ListenChannel    = 1;
        apModeConfig.strApConfig.u8SecType          = M2M_WIFI_SEC_OPEN;
        apModeConfig.strApConfig.u8SsidHide         = 0;

        // IP Address
        apModeConfig.strApConfig.au8DHCPServerIP[0] = 192;
        apModeConfig.strApConfig.au8DHCPServerIP[1] = 168;
        apModeConfig.strApConfig.au8DHCPServerIP[2] = 1;
        apModeConfig.strApConfig.au8DHCPServerIP[3] = 1;

        // Default router IP
        m2m_memcpy(apModeConfig.strApConfigExt.au8DefRouterIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

        // DNS Server IP
        m2m_memcpy(apModeConfig.strApConfigExt.au8DNSServerIP, apModeConfig.strApConfig.au8DHCPServerIP, 4);

        // Subnet mask
        apModeConfig.strApConfigExt.au8SubnetMask[0] = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[1] = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[2] = 255;
        apModeConfig.strApConfigExt.au8SubnetMask[3] = 0;

        m2m_wifi_start_provision_mode_ext(&apModeConfig, "atmelwincconf.com", bEnableRedirect);

        while(1)
        {
            m2m_wifi_handle_events(NULL);
        }
    }
}

Referenced by m2m_wifi_start_provision_mode().

NMI_API sint8 m2m_wifi_stop_provision_mode

(

void

)

Synchronous API for terminating provisioning mode on the WINC IC.

Synchronous API for terminating provisioning mode on the WINC.

This function will terminate any currently active provisioning mode on the WINC IC, returning the 
IC to idle.

Precondition

An active provisioning session must be active before it is terminated through this function.

Returns

The function returns M2M_SUCCESS for success and a negative value otherwise.

See Also

m2m_wifi_start_provision_mode

This function will terminate any currently active provisioning mode on the WINC, returning the WINC to idle.

Precondition

An active provisioning session must be active before it is terminated through this function.

Returns

The function returns M2M_SUCCESS for success and a negative value otherwise.

See Also

m2m_wifi_start_provision_mode

Referenced by os_m2m_wifi_stop_provision_mode().