begriffs open source - cmsis-driver-validation/blob - Doxygen/WiFi_DV_test.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 /**
   3 \defgroup wifi_requirements WiFi Requirements
   4 \ingroup wifi_funcs
   5
   6 The WiFi driver validation requires the following hardware:
   7 - WiFi Access Point connected to the local network
   8 - Hardware running SockServer (can be \ref sockserver_pc "PC running Microsoft Windows" or an
   9   \ref sockserver_embedded "embedded system")
  10
  11 The WiFi driver validation requires the following software:
  12 - \ref wifi_sock_setup "SockServer" application running in the same network as WiFi Access Point used for testing
  13 */
  14
  15
  16 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  17 /**
  18 \defgroup wifi_config WiFi Configuration
  19 \ingroup wifi_funcs
  20
  21 The WiFi driver validation settings are available in the \c DV_Config.h file.
  22
  23 Some settings depend on the test environment and need to be changed for proper operation of WiFi driver validation.
  24 These settings can be found under WiFi <b>Configuration</b> settings in the \c DV_Config.h file and need to be set as follows:
  25
  26 \image html dv_config_h_wifi_config.png "DV_Config.h header file in Configuration Wizard view mode"
  27
  28 <b>Station</b> related settings needed for WiFi module to connect to the WiFi Access Point in the local network:
  29 - SSID
  30 - Password
  31 - Security Type
  32 - Channel: use 0 for auto-detect channel
  33 - WPS PIN: PIN used for WPS tests (the Access Point has to have the same PIN enabled and WPS service running)
  34
  35 <b>Access Point</b> related settings needed for testing Access Point functionality (network creation) of the WiFi module:
  36 - SSID
  37 - Password
  38 - Security Type
  39 - Channel: use 0 for auto-detect channel
  40 - WPS PIN: PIN used for WPS tests (auxiliary station has to have the same PIN enabled)
  41
  42 <b>Socket</b> related setting needed for Socket API and Socket Operation tests:
  43 - SockServer IP: IP address assigned to the SockServer on your local network
  44 - Number of sockets: Number of sockets that the driver supports and that will be tested
  45
  46 \note IP address is displayed by the SockServer application (on the embedded board's LCD when using embedded SockServer).
  47
  48 Under <b>Test Cases</b> select testing functionality as required.
  49
  50 <b>Control</b>, <b>Management</b> and <b>Socket API (requires SockServer)</b> group of tests enable or disable
  51 WiFi Driver API function tests respectively.
  52
  53 <b>Management (requires user interaction)</b> and <b>Socket Operation (requires SockServer)</b> group of tests
  54 are used for more complex operational test of the WiFi driver.
  55 A brief description of each test functionality can be viewed by using
  56 <a href="http://www.keil.com/support/man/docs/uv4/uv4_ut_configwizard.htm" target="_blank">Configuration Wizard</a>
  57 view of the \c DV_Config.h file and clicking on the test or hovering a mouse pointer over it.
  58
  59 */
  60
  61
  62 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  63 /**
  64 \defgroup wifi_sock_setup WiFi SockServer
  65 \ingroup wifi_funcs
  66
  67 The \b SockServer is an application providing a set of services used by the WiFi CMSIS-Driver Validation suite to test the
  68 Socket interface of the WiFi driver. It is located in the <b>.\\Tools\\SockServer</b> subdirectory of the pack root directory.
  69 The SockServer is available for different target systems. It runs several standard network services.
  70
  71 The SockServer is available for following target systems:
  72  - <b>Personal Computer</b> running Microsoft Windows (executable located in <b>.\\Tools\\SockServer\\PC\\Win</b>)
  73  - <b>Keil MCB4300</b> evaluation board (µVision project located in <b>.\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCB4300</b>)
  74  - <b>Keil MCBSTM32F400</b> evaluation board (µVision project located in <b>.\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCBSTM32F400</b>)
  75
  76 \note To run SockServer in an embedded system, you need a license for MDK-Professional (for the MDK-Middleware Network component).
  77
  78 The following services are available by SockServer:
  79 - \b Echo service on port \token{7}, TCP and UDP
  80   \n (two instances of TCP service, one instance of UDP service)
  81 - \b Discard service on port \token{9}, TCP and UDP
  82   \n (one instance of TCP service, one instance of UDP service)
  83 - \b Chargen service on port \token{19}, TCP and UDP
  84   \n (two instances of TCP service, one instance of UDP service)
  85 - \b Assistant service on port \token{5000}
  86   \n (helper service used to test WiFi sockets in server mode (socket accept functionality))
  87 - \b Telnet service on port \token{23}
  88   \n (SockServer status monitoring service)
  89
  90 \note SockServer provides the Telnet service only in embedded systems.
  91
  92 \section sockserver_pc SockServer for PC running Microsoft Windows
  93
  94 \b Requirements:
  95  - Personal Computer running Microsoft Windows
  96  - PC connection to local network
  97
  98 SockServer is already built and can be executed by running the SockServer.exe file in <b>.\\Tools\\SockServer\\PC\\Win</b>
  99
 100 If you need to change the functionality of SockServer, source files and a batch script for building the executable are
 101 available in <b>.\\Tools\\SockServer\\PC\\Win</b>.
 102
 103 \note
 104 - SockServer build process requires Minimalist GNU for Windows (MinGW).
 105 - To build the SockServer executable for Windows, follow these steps:
 106   - Download and install MinGW from https://osdn.net/projects/mingw/releases/
 107   - Set environment path in Microsoft Windows as explained under Environment Settings heading on http://www.mingw.org/wiki/Getting_Started
 108   - Run <b>Build.bat</b> located in <b>.\\Tools\\SockServer\\PC\\Win</b> which will result in an executable that is located in
 109     <b>.\\Tools\\SockServer\\PC\\Win</b>
 110
 111 \subsection sockserver_pc_win_troubleshooting Troubleshooting
 112
 113 Problems and solutions:
 114  1. SockServer not responding to requests
 115     - Open Windows firewall -> Advanced settings
 116       - select inbound rules
 117     - create a new custom rule (New Rule...)
 118       - Rule type:     Program
 119       - Program:       This program path (select path to SockServer.exe)
 120       - Action:        Allow the connection
 121       - Profile:       Domain, Private (Public not advised)
 122       - Name:          SockServer
 123  2. Test computer not responding to ping
 124     - Open Windows firewall -> Advanced settings
 125       - select inbound rules, enable rule
 126         File and Printer sharing (Echo request - ICMPv4-In)
 127
 128     - If rule does not exist, create a new custom rule (New Rule...)
 129       - Rule type:     Custom
 130       - Program:       All programs
 131       - Protocol type: ICMPv4
 132       - ICMP Settings: Customize - Specific ICMP types: Echo Request
 133       - Scope:         Any IP address
 134       - Action:        Allow the connection
 135       - Profile:       Domain, Private (Public not advised)
 136       - Name:          Ping Echo
 137
 138
 139 \section sockserver_embedded SockServer for embedded systems
 140
 141 \b Requirements:
 142  - Keil MCB4300 or Keil MCBSTM32F400 evaluation board
 143  - Wired Ethernet connection to local network
 144
 145 \subsection sockserver_embedded_telnet Using the Telnet service
 146
 147 The Telnet service provides information about received and sent data. This can help to resolve driver problems when WiFi
 148 socket sending and receiving does not work. For example, when the transfer test fails, either \b SocketSend or
 149 \b SocketRecv functions may have failed or both.
 150
 151 For the Telnet connection from the PC, open a CMD window. At the prompt, type the following command or use another Telnet
 152 client application:
 153 \code
 154 c:\>telnet sockserver
 155 \endcode
 156
 157 The initial page opens:
 158   \image html SockServer.png "Initial telnet connection"
 159
 160 You can view the remote IP address, port number, receiving and transmitting counters with the \b stat command:
 161   \image html SockMonitor.png "Status monitoring"
 162
 163 Status monitor constantly updates the SockServer status on the screen. To stop the screen update, press any
 164 telnet client key.
 165
 166 \note You might need to enable the Telnet service in Windows 10 first. Here's a
 167 <a href="https://www.technipages.com/windows-10-enable-telnet" target="_blank">tutorial</a> on how to do this.
 168
 169 \subsection sockserver_embedded_porting Porting SockServer to other targets
 170
 171 Currently, the \b SockServer application is available for the \b MCB4300 and \b MCBSTM32F400 evaluation boards.
 172 To create SockServer application for a different target device, follow the steps below:
 173 -# Create new network project in µVision
 174 -# Select and configure the following software components:
 175  - \b Network:Core and configure the host name and pool size in \b Net_Config.c
 176 \code
 177 #define NET_HOST_NAME               "SockServer"
 178 #define NET_MEM_POOL_SIZE           16384
 179 \endcode
 180  - \b Network:Interface:Ethernet and configure the MAC address in \b Net_Config_ETH0.h to avoid collisions
 181 \code
 182 #define ETH0_MAC_ADDR               "1E-30-6C-A2-45-5A"
 183 \endcode
 184  - \b Network:Socket:BSD and configure number of sockets in \b Net_Config_BSD.h
 185 \code
 186 #define BSD_NUM_SOCKS               8
 187 #define BSD_SERVER_SOCKS            4
 188 \endcode
 189  - \b Network:Socket:TCP and configure number of sockets in \b Net_Config_TCP.h
 190 \code
 191 #define TCP_NUM_SOCKS               9
 192 \endcode
 193  - \b Network:Socket:UDP and configure number of sockets in \b Net_Config_UDP.h
 194 \code
 195 #define UDP_NUM_SOCKS               10
 196 \endcode
 197  - \b Network:Service:Telnet server and disable authentication in \b Net_Config_Telnet_Server.h
 198 \code
 199 #define TELNET_SERVER_AUTH_ENABLE   0
 200 \endcode
 201  - \b CMSIS \b Driver:Ethernet/MAC/PHY(API) depending on your hardware
 202 -# Configure device specific hardware:
 203  - Configure the CMSIS-Driver for Ethernet and other device specific components (clock system, I/O, ...)
 204    as required. Please consult your device's/board's documentation for more information.
 205 -# Copy and add \b SockServer.c and \b SockServer.h files to the project
 206 -# Copy and add \b Telnet_Server_UIF.c to the project
 207 -# Add the code to start the services in \b main.c
 208 \code
 209 // Application main thread
 210 static void app_main (void *argument) {
 211
 212   netInitialize ();
 213   osDelay (500);
 214
 215   osThreadNew(DgramServer,   NULL, NULL);
 216   osThreadNew(StreamServer,  NULL, NULL);
 217   osThreadNew(TestAssistant, NULL, NULL);
 218 }
 219 \endcode
 220 -# Increase the default RTX stack size to 400 bytes in \b RTX_Config.h
 221 \code
 222 #define OS_STACK_SIZE           400
 223 \endcode
 224 -# Set the default global stack to 1024 bytes and heap to 6144 bytes in your device's \b startup \b file
 225 \code
 226 Stack_Size      EQU     0x00000400
 227 Heap_Size       EQU     0x00001800
 228 \endcode
 229
 230 \subsection sockserver_embedded_troubleshooting Troubleshooting
 231
 232 Problems and solutions:
 233  1. SockServer on multiple embedded systems on the same local network
 234     - Set unique ETH0_MAC_ADDR in Net_Config_ETH0.h for each embedded system in embedded system project
 235
 236 */
 237
 238 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 239 /**
 240 \defgroup wifi_sock_testing WiFi Socket testing
 241 \ingroup wifi_funcs
 242
 243 Due to limitations of WiFi modules and their Software Development Kits (SDK), often it is not possible to comply with
 244 CMSIS-Driver BSD rules regarding function behavior or function return codes. Hence, the WiFi Driver tests accept alternative
 245 error codes and report them as Warnings and considers certain error codes as acceptable for certain functions.
 246 Exceptions to BSD-strict error codes and functionality are written below:
 247
 248 WiFi socket deviations from the BSD-strict specification
 249 ========================================================
 250
 251 -# \b SocketBind
 252  - bind socket to same address again<br>
 253    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EINVAL<br>non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}
 254
 255  - bind another socket to used address<br>
 256    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EADDRINUSE<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 257
 258  - bind on closed socket<br>
 259    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 260
 261 -# \b SocketListen
 262  - listen on already listening socket<br>
 263    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EINVAL<br>non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}
 264
 265  - listen on unbound socket<br>
 266    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EINVAL<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 267
 268  - listen on closed socket<br>
 269    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 270
 271  - listen on datagram socket<br>
 272    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTSUP<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 273
 274 -# \b SocketAccept
 275  - receive on disconnected socket<br>
 276    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ECONNRESET<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 277
 278  - accept on closed socket<br>
 279    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 280
 281  - listen on datagram socket<br>
 282    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTSUP<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 283
 284  - accept on datagram socket<br>
 285    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTSUP<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 286
 287 -# \b SocketConnect
 288  - connect socket to same address again<br>
 289    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EISCONN<br>non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}
 290
 291  - bind on connected socket<br>
 292    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EISCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 293
 294  - connect on closed socket<br>
 295    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 296
 297  - connect to non-existent port<br>
 298    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ECONNREFUSED<br>non BSD-strict accepted return codes: \token{ARM_SOCKET_ETIMEDOUT} or \token{ARM_SOCKET_ERROR}
 299
 300  - connect to non-existent stream server<br>
 301    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ETIMEDOUT<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 302
 303  - connect on listening socket<br>
 304    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EINVAL<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 305
 306  - connect datagram socket to unspecified address (0.0.0.0)<br>
 307    <b>BSD-strict</b> expected return code \b 0<br>non BSD-strict accepted return codes: \token{ARM_SOCKET_EINVAL} or \token{ARM_SOCKET_ERROR}
 308    (special case that deletes the socket destination & filtering address)
 309
 310 -# \b SocketRecv
 311  - recv on closed socket<br>
 312    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 313
 314  - recv on created socket<br>
 315    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 316
 317  - recv on bound socket<br>
 318    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 319
 320  - recv on listening socket<br>
 321    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 322
 323 -# \b SocketRecvFrom
 324  - recvfrom on closed socket<br>
 325    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 326
 327 -# \b SocketSend
 328  - send on closed socket<br>
 329    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 330
 331  - send on disconnected socket<br>
 332    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ECONNRESET<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 333
 334  - send on created socket<br>
 335    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 336
 337  - send on bound socket<br>
 338    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 339
 340  - send on listening socket<br>
 341    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 342
 343  - send on closed socket<br>
 344    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ECONNRESET<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 345
 346 -# \b SocketSendTo
 347  - sendto on closed socket<br>
 348    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 349
 350 -# \b SocketGetSockName
 351  - getsockname on closed socket<br>
 352    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 353
 354  - getsockname on unbound socket<br>
 355    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EINVAL<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 356
 357 -# \b SocketGetPeerName
 358  - getpeername on closed socket<br>
 359    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 360
 361  - getpeername on created socket<br>
 362    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 363
 364  - getpeername on bound socket<br>
 365    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 366
 367  - getpeername on listening socket<br>
 368    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ENOTCONN<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 369
 370 -# \b SocketGetOpt
 371  - getsockopt on closed socket<br>
 372    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 373
 374 -# \b SocketSetOpt
 375  - setsockopt on closed socket<br>
 376    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 377
 378 -# \b SocketClose
 379  - close already closed socket<br>
 380    <b>BSD-strict</b> expected return code \b ARM_SOCKET_ESOCK<br>non BSD-strict accepted return code \token{0}
 381
 382 -# \b SocketGetHostByName
 383  - gethostbyname for non-existing host<br>
 384    <b>BSD-strict</b> expected return code \b ARM_SOCKET_EHOSTNOTFOUND<br>non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}
 385 */