Updated WiFi Driver API 1.0.0-beta

Simplified API:
 - removed Ad-hoc mode
 - merged Configure into Activate

ARM.CMSIS.pdsc

@@ -18,6 +18,8 @@
         - RTX 4.82.0 (updated provisions for Arm Compiler 6 when using Cortex-M0/M0+)
       CMSIS-RTOS2:
         - RTX 5.5.1 (see revision history for details)
+      CMSIS-Driver: 2.7.0
+        - Updated WiFi Interface API 1.0.0-beta
       Devices:
        - Generalized C startup code for all Cortex-M familiy devices.
        - Updated Core(A) default memory regions and MMU configurations

CMSIS/DoxyGen/Driver/src/Driver_WiFi.c

@@ -406,35 +406,10 @@ Many parameters of the WiFi module are configured using the \ref ARM_WIFI_SetOpt
 @}
 */
 
-/**
-\defgroup wifi_oper_mode WiFi Operating Mode
-\ingroup wifi_management_gr
-\brief Specifies WiFi operation for \ref ARM_WIFI_Activate.
-\details
-The WiFi operation mode defines in which mode the WiFi module operates when activated.
-@{
-\def ARM_WIFI_MODE_NONE
-\details WiFi module is inactive (default).
-\sa wifi_oper_mode
-\def ARM_WIFI_MODE_STATION
-\details WiFi module operates in station mode.
-\sa wifi_oper_mode
-\def ARM_WIFI_MODE_AP
-\details WiFi module operates in access point mode.
-\sa wifi_oper_mode
-\def ARM_WIFI_MODE_STATION_AP
-\details WiFi module operates in station mode and access point mode simultaneously.
-\sa wifi_oper_mode
-\def ARM_WIFI_MODE_AD_HOC
-\details WiFi module operates in WiFi Ad-hoc mode.
-\sa wifi_oper_mode
-@}
-*/
-
 /**
 \defgroup wifi_sec_type WiFi Security Type
 \ingroup wifi_management_gr
-\brief Specifies WiFi security type for \ref ARM_WIFI_Configure.
+\brief Specifies WiFi security type for \ref ARM_WIFI_Activate.
 \details
 The WiFi security type defines the standard used to protect the wireless network from unauthorized access.
 @{
@@ -459,7 +434,7 @@ The WiFi security type defines the standard used to protect the wireless network
 /**
 \defgroup wifi_wps_method WiFi Protected Setup (WPS) Method
 \ingroup wifi_management_gr
-\brief Specifies WiFi WPS method for \ref ARM_WIFI_Configure.
+\brief Specifies WiFi WPS method for \ref ARM_WIFI_Activate.
 \details
 The WiFi WPS method defines which WPS method is used.
 @{
@@ -508,7 +483,7 @@ a leased IPv6 address and DNS server addresses.
 Provides information needed to connect to the WiFi network for station or how to configure the access point (AP).
 
 <b>Used in:</b>
-  - \ref ARM_WIFI_Configure
+  - \ref ARM_WIFI_Activate
 *******************************************************************************************************************/
 
 /**
@@ -649,19 +624,29 @@ for (i = 0; i < num; i++) {
 \endcode
 */
 
-int32_t ARM_WIFI_Configure (uint32_t interface, ARM_WIFI_CONFIG_t *config) {
+int32_t ARM_WIFI_Activate (uint32_t interface, ARM_WIFI_CONFIG_t *config) {
   return ARM_DRIVER_OK;
 }
 /**
-\fn int32_t ARM_WIFI_Configure (uint32_t interface, ARM_WIFI_CONFIG_t *config)
+\fn int32_t ARM_WIFI_Activate (uint32_t interface, ARM_WIFI_CONFIG_t *config)
 \details
-The function \b ARM_WIFI_Configure configures the specified interface.
+The function \b ARM_WIFI_Activate activates the specified interface.
 
 The argument \em interface specifies the interface (0 = Station, 1 = Access Point).
 
+When station interface is specified, the WiFi module connects to a wireless network.
+
+The wireless network trying to connect to must be available,
+otherwise the operation will fail after a timeout.
+
+Available wireless networks can be scanned by using the function \ref ARM_WIFI_Scan.
+
+When access point interface is specified, the WiFi module creates a wireless network
+by activating the access point.
+
 The argument \em config is a pointer to the configuration \ref ARM_WIFI_CONFIG_t
-which provides information needed to connect to a WiFi network in station mode
-or information used to configure the access point (AP) in access point mode.
+which provides information needed to connect to a WiFi network for station interface
+or information used to configure the access point (AP) for access point interface.
 
 \em ssid specifies the name of the network to connect to or the network to create.
 
@@ -672,9 +657,8 @@ or information used to configure the access point (AP) in access point mode.
 \em ch specifies the WiFi channel which will be used for the connection.
 Valid channels for 2.4 GHz frequency are from \token{1} to \token{13}. If the value for \em ch = \token{0},
 the system automatically selects the channel.
-When in station mode the channel of the AP being connect to is used.
-When in access point mode the AP automatically selects the best channel
-for the WiFi connection.
+For station interface the channel of the AP being connected to is used.
+For access point interface the module automatically selects the best channel for the WiFi connection.
 
 \note
 Optionally BSSID parameter can be also set using \ref ARM_WIFI_SetOption.
@@ -691,11 +675,11 @@ both at the access point and the station. No credentials are needed.
 With \b PIN method, you must provide the PIN code that you read from the label or screen
 on the wireless device.
 
-WPS configuration for station is used when station is activated and connects to an access point.
+WPS configuration for station is used when station connects to an access point.
 It enables to connect without specifying SSID, Password, Security Type or WiFi Channel.
 The actual network information can be retrieved once connected with \ref ARM_WIFI_GetNetInfo.
 
-WPS configuration for access point is used when access point is activated (\ref ARM_WIFI_Activate).
+WPS configuration for access point is used when access point is activated.
 Subsequent activate calls re-trigger the WPS procedure.
 
 \note
@@ -713,68 +697,27 @@ wifi_config.security = ARM_WIFI_SECURITY_WPA2;
 wifi_config.ch = 0U;
 wifi_config.wps_method = ARM_WIFI_WPS_METHOD_NONE;
  
-// Configure station
-status = wifi->Configure (0U, &wifi_config);
-if (status != ARM_DRIVER_OK) {
-  // error handling
-}
- 
 // Connect to wireless network
-status = wifi->Activate (ARM_WIFI_MODE_STATION);
+status = wifi->Activate (0U, &wifi_config);
 if (status != ARM_DRIVER_OK) {
   // error handling
 }
 \endcode
 */
 
-int32_t ARM_WIFI_Activate (uint32_t mode) {
+int32_t ARM_WIFI_Deactivate (uint32_t interface) {
   return ARM_DRIVER_OK;
 }
 /**
-\fn int32_t ARM_WIFI_Activate (uint32_t mode)
+\fn int32_t ARM_WIFI_Deactivate (uint32_t interface)
 \details
-The function \b ARM_WIFI_Activate activates the specified mode of the WiFi module.
-
-The argument \em mode specifies which mode will be activated:
- - Station mode: connect to a wireless network
- - Access Point mode: activate access point
- - Station and Access point mode: connect to a wireless network and activate access point 
- - Ad-hoc mode: connect to or create a wireless network
-
-The WiFi Station or Access Point needs to be configured before activating.
+The function \b ARM_WIFI_Deactivate deactivates the specified interface.
 
-The function returns once the mode is activated:
- - when station is connected to a wireless network  (Station mode)
- - when access point is activated (Access Point mode)
- - when station is connected and access point is activated (Station and Access point mode)
- - when station is connected or access point is activated (Ad-hoc mode)
-
-When in station mode the wireless network trying to connect to must be available,
-otherwise the connection will fail after a timeout.
-
-Available wireless networks can be scanned by using the function \ref ARM_WIFI_Scan.
-
-\b Ad-hoc mode is very similar to standard infrastructure mode with a difference that there
-are no dedicated access points in the network but a device can temporarily offer access point
-functionality as Soft-AP (no routing capabilities) to other devices in its vicinity.
-
-When in Ad-hoc mode the module tries to connect to network with specified SSID.
-If there is no such network available the module becomes a Soft-AP with BSSID being
-randomly generated (BSSID can be retrieved by using \ref ARM_WIFI_GetOption).
+The argument \em interface specifies the interface (0 = Station, 1 = Access Point).
 
-\b Example:
- - see \ref ARM_WIFI_Initialize
-*/
+When station interface is specified, the WiFi module disconnects from the wireless network.
 
-int32_t ARM_WIFI_Deactivate (void) {
-  return ARM_DRIVER_OK;
-}
-/**
-\fn int32_t ARM_WIFI_Deactivate (void)
-\details
-The function \b ARM_WIFI_Deactivate deactivates the current mode:
- - terminates the connection to a wireless network
- - deactivates the access point
+When access point interface is specified, the WiFi module deactivates the access point.
 
 \b Example:
  - see \ref ARM_WIFI_GetNetInfo
@@ -816,14 +759,8 @@ memset(&wifi_config, 0, sizeof(wifi_config);
  
 wifi_config.wps_method = ARM_WIFI_WPS_METHOD_PBC;
  
-// Configure station (WPS)
-status = wifi->Configure (0U, &wifi_config);
-if (status != ARM_DRIVER_OK) {
-  // error handling
-}
- 
-// Connect to wireless network
-status = wifi->Activate (ARM_WIFI_MODE_STATION);
+// Connect to wireless network (WPS)
+status = wifi->Activate (0U, &wifi_config);
 if (status != ARM_DRIVER_OK) {
   // error handling
 }
@@ -838,7 +775,7 @@ if (wifi->IsConnected ()) {
 }
  
 // Disconnect from wireless network
-wifi->Deactivate ();
+wifi->Deactivate (0U);
 \endcode
 */
 

CMSIS/Driver/Include/Driver_WiFi.h

@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  *
- * $Date:        13. March 2019
+ * $Date:        21. May 2019
  * $Revision:    V1.0 (beta)
  *
  * Project:      WiFi (Wireless Fidelity Interface) Driver definitions
@@ -66,13 +66,6 @@ extern "C"
 #define ARM_WIFI_IP6_DNS2                   21U         ///< Station/AP Set/Get IPv6 secondary DNS address;             data = &ip6,      len = 16, uint8_t[16]
 #define ARM_WIFI_IP6_DHCP_MODE              22U         ///< Station/AP Set/Get IPv6 DHCPv6 client mode;                data = &mode,     len =  4, uint32_t: ARM_WIFI_IP6_DHCP_xxx (default Off)
 
-/****** WiFi Operating Mode *****/
-#define ARM_WIFI_MODE_NONE                  0U          ///< Inactive (default)
-#define ARM_WIFI_MODE_STATION               1U          ///< Station
-#define ARM_WIFI_MODE_AP                    2U          ///< Access Point
-#define ARM_WIFI_MODE_STATION_AP            3U          ///< Station and Access Point
-#define ARM_WIFI_MODE_AD_HOC                4U          ///< Ad-hoc
-
 /****** WiFi Security Type *****/
 #define ARM_WIFI_SECURITY_OPEN              0U          ///< Open
 #define ARM_WIFI_SECURITY_WEP               1U          ///< Wired Equivalent Privacy (WEP) with Pre-Sheared Key (PSK)
@@ -100,12 +93,13 @@ extern "C"
 \brief WiFi Configuration
 */
 typedef struct {
-  char    ssid[32+1];                                   ///< Service Set Identifier (SSID) null-terminated string
-  char    pass[64+1];                                   ///< Password null-terminated string
-  uint8_t security;                                     ///< Security type (ARM_WIFI_SECURITY_xxx)
-  uint8_t ch;                                           ///< WiFi Channel (0 = auto, otherwise = exact channel)
-  uint8_t wps_method;                                   ///< WiFi Protected Setup (WPS) method (ARM_WIFI_WPS_METHOD_xxx)
-  char    wps_pin[8+1];                                 ///< WiFi Protected Setup (WPS) PIN null-terminated string
+  const char   *ssid;                                   ///< Pointer to Service Set Identifier (SSID) null-terminated string
+  const char   *pass;                                   ///< Pointer to Password null-terminated string
+        uint8_t security;                               ///< Security type (ARM_WIFI_SECURITY_xxx)
+        uint8_t ch;                                     ///< WiFi Channel (0 = auto, otherwise = exact channel)
+        uint8_t reserved;                               ///< Reserved
+        uint8_t wps_method;                             ///< WiFi Protected Setup (WPS) method (ARM_WIFI_WPS_METHOD_xxx)
+  const char   *wps_pin;                                ///< Pointer to WiFi Protected Setup (WPS) PIN null-terminated string
 } ARM_WIFI_CONFIG_t;
 
 /**
@@ -257,37 +251,25 @@ typedef struct {
                    - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (NULL scan_info pointer or max_num equal to 0)
 */
 /**
-  \fn            int32_t ARM_WIFI_Configure (uint32_t interface, ARM_WIFI_CONFIG_t *config)
-  \brief         Configure Network Parameters.
+  \fn            int32_t ARM_WIFI_Activate (uint32_t interface, ARM_WIFI_CONFIG_t *config)
+  \brief         Activate interface (Connect to a wireless network or activate an access point).
   \param[in]     interface Interface (0 = Station, 1 = Access Point)
   \param[in]     config    Pointer to ARM_WIFI_CONFIG_t structure where Configuration parameters are located
-  \return        execution status
-                   - \ref ARM_DRIVER_OK                : Operation successful
-                   - \ref ARM_DRIVER_ERROR             : Operation failed
-                   - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported (security type, WPS or channel autodetect not supported)
-                   - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface, security type or NULL config pointer)
-*/
-/**
-  \fn            int32_t ARM_WIFI_Activate (uint32_t mode)
-  \brief         Activate selected mode of operation.
-  \param[in]     mode     Mode of operation
-                   - \ref ARM_WIFI_MODE_STATION        : Station only
-                   - \ref ARM_WIFI_MODE_AP             : Access Point only
-                   - \ref ARM_WIFI_MODE_STATION_AP     : Station and Access Point
-                   - \ref ARM_WIFI_MODE_AD_HOC         : Ad-hoc
   \return        execution status
                    - \ref ARM_DRIVER_OK                : Operation successful
                    - \ref ARM_DRIVER_ERROR             : Operation failed
                    - \ref ARM_DRIVER_ERROR_TIMEOUT     : Timeout occurred
-                   - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
-                   - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid mode)
+                   - \ref ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported (security type, channel autodetect or WPS not supported)
+                   - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface, NULL config pointer or invalid configuration)
 */
 /**
-  \fn            int32_t ARM_WIFI_Deactivate (void)
-  \brief         Deactivate current mode of operation.
+  \fn            int32_t ARM_WIFI_Deactivate (uint32_t interface)
+  \brief         Deactivate interface (Disconnect from a wireless network or deactivate an access point).
+  \param[in]     interface Interface (0 = Station, 1 = Access Point)
   \return        execution status
                    - \ref ARM_DRIVER_OK                : Operation successful
                    - \ref ARM_DRIVER_ERROR             : Operation failed
+                   - \ref ARM_DRIVER_ERROR_PARAMETER   : Parameter error (invalid interface)
 */
 /**
   \fn            uint32_t ARM_WIFI_IsConnected (void)
@@ -616,20 +598,19 @@ typedef void (*ARM_WIFI_SignalEvent_t) (uint32_t event, void *arg); ///< Pointer
 \brief WiFi Driver Capabilities.
 */
 typedef struct {
-  uint32_t mode_station          : 1;   ///< Mode: Station
-  uint32_t mode_ap               : 1;   ///< Mode: Access Point
-  uint32_t mode_station_ap       : 1;   ///< Mode: Station and Access Point
-  uint32_t mode_ad_hoc           : 1;   ///< Mode: Ad-hoc
+  uint32_t station               : 1;   ///< Station
+  uint32_t ap                    : 1;   ///< Access Point
+  uint32_t station_ap            : 1;   ///< Concurrent Station and Access Point
   uint32_t wps_station           : 1;   ///< WiFi Protected Setup (WPS) for Station
   uint32_t wps_ap                : 1;   ///< WiFi Protected Setup (WPS) for Access Point
   uint32_t event_ap_connect      : 1;   ///< Access Point: event generated on Station connect
   uint32_t event_ap_disconnect   : 1;   ///< Access Point: event generated on Station disconnect
-  uint32_t bypass_mode           : 1;   ///< Bypass or pass-through mode (Ethernet interface)
   uint32_t event_eth_rx_frame    : 1;   ///< Event generated on Ethernet frame reception in bypass mode
+  uint32_t bypass_mode           : 1;   ///< Bypass or pass-through mode (Ethernet interface)
   uint32_t ip                    : 1;   ///< IP (UDP/TCP) (Socket interface)
   uint32_t ip6                   : 1;   ///< IPv6 (Socket interface)
   uint32_t ping                  : 1;   ///< Ping (ICMP)
-  uint32_t reserved              : 19;  ///< Reserved (must be zero)
+  uint32_t reserved              : 20;  ///< Reserved (must be zero)
 } ARM_WIFI_CAPABILITIES;
 
 /**
@@ -645,9 +626,8 @@ typedef struct {
   int32_t               (*SetOption)                   (uint32_t interface, uint32_t option, const void *data, uint32_t  len);
   int32_t               (*GetOption)                   (uint32_t interface, uint32_t option,       void *data, uint32_t *len);
   int32_t               (*Scan)                        (ARM_WIFI_SCAN_INFO_t scan_info[], uint32_t max_num);
-  int32_t               (*Configure)                   (uint32_t interface, ARM_WIFI_CONFIG_t *config);
-  int32_t               (*Activate)                    (uint32_t mode);
-  int32_t               (*Deactivate)                  (void);
+  int32_t               (*Activate)                    (uint32_t interface, ARM_WIFI_CONFIG_t *config);
+  int32_t               (*Deactivate)                  (uint32_t interface);
   uint32_t              (*IsConnected)                 (void);
   int32_t               (*GetNetInfo)                  (ARM_WIFI_NET_INFO_t *net_info);
   int32_t               (*BypassControl)               (uint32_t interface, uint32_t mode);