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