begriffs open source - cmsis-driver-validation/blob

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 Configuration 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 Station 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 Access Point related settings needed for testing Access Point functionality of the WiFi module:

36 - SSID: SSID created by the WiFi module

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 Socket related setting needed for Socket API and Socket Operation tests:

43 - SockServer IP: IP address assigned to the SockServer on your local network

44

45 \note IP address is displayed by the SockServer application (on the embedded board's LCD when using embedded SockServer).

46

47 Under Test Cases select testing functionality as required.

48

49 Control, Management and Socket API (requires SockServer) group of tests enable or disable

50 WiFi Driver API function tests respectively.

51

52 Management (requires user interaction) and Socket Operation (requires SockServer) group of tests

53 are used for more complex operational test of the WiFi driver.

54 A brief description of each test functionality can be viewed by using

55 <a href="http://www.keil.com/support/man/docs/uv4/uv4_ut_configwizard.htm" target="_blank">Configuration Wizard</a>

56 view of the DV_Config.h file and clicking on the test or hovering a mouse pointer over it.

57

58 */

59

60

61 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

62 /**

63 \defgroup wifi_sock_setup WiFi SockServer

64 \ingroup wifi_funcs

65

66 The \b SockServer is an application providing a set of services used by the WiFi CMSIS-Driver Validation suite to test the

67 Socket interface of the WiFi driver. It is located in the .\\Tools\\SockServer subdirectory of the pack root directory.

68 The SockServer is available for different target systems. It runs several standard network services.

69

70 The SockServer is available for following target systems:

71 - Personal Computer running Microsoft Windows (executable located in .\\Tools\\SockServer\\PC\\Win)

72 - Keil MCB4300 evaluation board (µVision project located in .\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCB4300)

73 - Keil MCBSTM32F400 evaluation board (µVision project located in .\\Tools\\SockServer\\Embedded\\MDK\\Board\\MCBSTM32F400)

74

75 \note To run SockServer in an embedded system, you need a license for MDK-Professional (for the MDK-Middleware Network component).

76

77 The following services are available by SockServer:

78 - \b Echo service on port \token{7}, TCP and UDP

79 \n (two instances of TCP service, one instance of UDP service)

80 - \b Discard service on port \token{9}, TCP and UDP

81 \n (one instance of TCP service, one instance of UDP service)

82 - \b Chargen service on port \token{19}, TCP and UDP

83 \n (two instances of TCP service, one instance of UDP service)

84 - \b Assistant service on port \token{5000}

85 \n (helper service used to test WiFi sockets in server mode (socket accept functionality))

86 - \b Telnet service on port \token{23}

87 \n (SockServer status monitoring service)

88

89 \note SockServer provides the Telnet service only in embedded systems.

90

91 \section sockserver_pc SockServer for PC running Microsoft Windows

92

93 \b Requirements:

94 - Personal Computer running Microsoft Windows

95 - PC connection to local network

96

97 SockServer is already built and can be executed by running the SockServer.exe file in .\\Tools\\SockServer\\PC\\Win

98

99 If you need to change the functionality of SockServer, source files and a batch script for building the executable are

100 available in .\\Tools\\SockServer\\PC\\Win.

101

102 \note

103 - SockServer build process requires Minimalist GNU for Windows (MinGW).

104 - To build the SockServer executable for Windows, follow these steps:

105 - Download and install MinGW from https://osdn.net/projects/mingw/releases/

106 - Set environment path in Microsoft Windows as explained under Environment Settings heading on http://www.mingw.org/wiki/Getting_Started

107 - Run Build.bat located in .\\Tools\\SockServer\\PC\\Win which will result in an executable that is located in

108 .\\Tools\\SockServer\\PC\\Win

109

110 \subsection sockserver_pc_win_troubleshooting Troubleshooting

111

112 Problems and solutions:

113 1. SockServer not responding to requests

114 - Open Windows firewall -> Advanced settings

115 - select inbound rules

116 - create a new custom rule (New Rule...)

117 - Rule type: Program

118 - Program: This program path (select path to SockServer.exe)

119 - Action: Allow the connection

120 - Profile: Domain, Private (Public not advised)

121 - Name: SockServer

122 2. Test computer not responding to ping

123 - Open Windows firewall -> Advanced settings

124 - select inbound rules, enable rule

125 File and Printer sharing (Echo request - ICMPv4-In)

126

127 - If rule does not exist, create a new custom rule (New Rule...)

128 - Rule type: Custom

129 - Program: All programs

130 - Protocol type: ICMPv4

131 - ICMP Settings: Customize - Specific ICMP types: Echo Request

132 - Scope: Any IP address

133 - Action: Allow the connection

134 - Profile: Domain, Private (Public not advised)

135 - Name: Ping Echo

136

137

138 \section sockserver_embedded SockServer for embedded systems

139

140 \b Requirements:

141 - Keil MCB4300 or Keil MCBSTM32F400 evaluation board

142 - Wired Ethernet connection to local network

143

144 \subsection sockserver_embedded_telnet Using the Telnet service

145

146 The Telnet service provides information about received and sent data. This can help to resolve driver problems when WiFi

147 socket sending and receiving does not work. For example, when the transfer test fails, either \b SocketSend or

148 \b SocketRecv functions may have failed or both.

149

150 For the Telnet connection from the PC, open a CMD window. At the prompt, type the following command or use another Telnet

151 client application:

152 \code

153 c:\>telnet sockserver

154 \endcode

155

156 The initial page opens:

157 \image html SockServer.png "Initial telnet connection"

158

159 You can view the remote IP address, port number, receiving and transmitting counters with the \b stat command:

160 \image html SockMonitor.png "Status monitoring"

161

162 Status monitor constantly updates the SockServer status on the screen. To stop the screen update, press any

163 telnet client key.

164

165 \note You might need to enable the Telnet service in Windows 10 first. Here's a

166 <a href="https://www.technipages.com/windows-10-enable-telnet" target="_blank">tutorial</a> on how to do this.

167

168 \subsection sockserver_embedded_porting Porting SockServer to other targets

169

170 Currently, the \b SockServer application is available for the \b MCB4300 and \b MCBSTM32F400 evaluation boards.

171 To create SockServer application for a different target device, follow the steps below:

172 -# Create new network project in µVision

173 -# Select and configure the following software components:

174 - \b Network:Core and configure the host name and pool size in \b Net_Config.c

175 \code

176 #define NET_HOST_NAME "SockServer"

177 #define NET_MEM_POOL_SIZE 16384

178 \endcode

179 - \b Network:Interface:Ethernet and configure the MAC address in \b Net_Config_ETH0.h to avoid collisions

180 \code

181 #define ETH0_MAC_ADDR "1E-30-6C-A2-45-5A"

182 \endcode

183 - \b Network:Socket:BSD and configure number of sockets in \b Net_Config_BSD.h

184 \code

185 #define BSD_NUM_SOCKS 8

186 #define BSD_SERVER_SOCKS 4

187 \endcode

188 - \b Network:Socket:TCP and configure number of sockets in \b Net_Config_TCP.h

189 \code

190 #define TCP_NUM_SOCKS 9

191 \endcode

192 - \b Network:Socket:UDP and configure number of sockets in \b Net_Config_UDP.h

193 \code

194 #define UDP_NUM_SOCKS 10

195 \endcode

196 - \b Network:Service:Telnet server and disable authentication in \b Net_Config_Telnet_Server.h

197 \code

198 #define TELNET_SERVER_AUTH_ENABLE 0

199 \endcode

200 - \b CMSIS \b Driver:Ethernet/MAC/PHY(API) depending on your hardware

201 -# Configure device specific hardware:

202 - Configure the CMSIS-Driver for Ethernet and other device specific components (clock system, I/O, ...)

203 as required. Please consult your device's/board's documentation for more information.

204 -# Copy and add \b SockServer.c and \b SockServer.h files to the project

205 -# Copy and add \b Telnet_Server_UIF.c to the project

206 -# Add the code to start the services in \b main.c

207 \code

208 // Application main thread

209 static void app_main (void *argument) {

210

211 netInitialize ();

212 osDelay (500);

213

214 osThreadNew(DgramServer, NULL, NULL);

215 osThreadNew(StreamServer, NULL, NULL);

216 osThreadNew(TestAssistant, NULL, NULL);

217 }

218 \endcode

219 -# Increase the default RTX stack size to 400 bytes in \b RTX_Config.h

220 \code

221 #define OS_STACK_SIZE 400

222 \endcode

223 -# Set the default global stack to 1024 bytes and heap to 6144 bytes in your device's \b startup \b file

224 \code

225 Stack_Size EQU 0x00000400

226 Heap_Size EQU 0x00001800

227 \endcode

228

229 \subsection sockserver_embedded_troubleshooting Troubleshooting

230

231 Problems and solutions:

232 1. SockServer on multiple embedded systems on the same local network

233 - Set unique ETH0_MAC_ADDR in Net_Config_ETH0.h for each embedded system in embedded system project

234

235 */

236

237 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/

238 /**

239 \defgroup wifi_sock_testing WiFi Socket testing

240 \ingroup wifi_funcs

241

242 Due to limitations of WiFi modules and their Software Development Kits (SDK), often it is not possible to comply with

243 CMSIS-Driver BSD rules regarding function behavior or function return codes. Hence, the WiFi Driver tests accept alternative

244 error codes and report them as Warnings and considers certain error codes as acceptable for certain functions.

245 Exceptions to BSD-strict error codes and functionality are written below:

246

247 WiFi socket deviations from the BSD-strict specification

248 ========================================================

249

250 -# \b SocketBind

251 - bind socket to same address again

252 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

253

254 - bind another socket to used address

255 BSD-strict expected return code \b ARM_SOCKET_EADDRINUSE non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

256

257 - bind on closed socket

258 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

259

260 -# \b SocketListen

261 - listen on already listening socket

262 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

263

264 - listen on unbound socket

265 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

266

267 - listen on closed socket

268 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

269

270 - listen on datagram socket

271 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

272

273 -# \b SocketAccept

274 - receive on disconnected socket

275 BSD-strict expected return code \b ARM_SOCKET_ECONNRESET non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

276

277 - accept on closed socket

278 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

279

280 - listen on datagram socket

281 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

282

283 - accept on datagram socket

284 BSD-strict expected return code \b ARM_SOCKET_ENOTSUP non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

285

286 -# \b SocketConnect

287 - connect socket to same address again

288 BSD-strict expected return code \b ARM_SOCKET_EISCONN non BSD-strict accepted return codes: \token{0} or \token{ARM_SOCKET_ERROR}

289

290 - bind on connected socket

291 BSD-strict expected return code \b ARM_SOCKET_EISCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

292

293 - connect on closed socket

294 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

295

296 - connect to non-existent port

297 BSD-strict expected return code \b ARM_SOCKET_ECONNREFUSED non BSD-strict accepted return codes: \token{ARM_SOCKET_ETIMEDOUT} or \token{ARM_SOCKET_ERROR}

298

299 - connect to non-existent stream server

300 BSD-strict expected return code \b ARM_SOCKET_ETIMEDOUT non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

301

302 - connect on listening socket

303 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

304

305 - connect datagram socket to unspecified address (0.0.0.0)

306 BSD-strict expected return code \b 0 non BSD-strict accepted return codes: \token{ARM_SOCKET_EINVAL} or \token{ARM_SOCKET_ERROR}

307 (special case that deletes the socket destination & filtering address)

308

309 -# \b SocketRecv

310 - recv on closed socket

311 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

312

313 - recv on created socket

314 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

315

316 - recv on bound socket

317 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

318

319 - recv on listening socket

320 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

321

322 -# \b SocketRecvFrom

323 - recvfrom on closed socket

324 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

325

326 -# \b SocketSend

327 - send on closed socket

328 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

329

330 - send on disconnected socket

331 BSD-strict expected return code \b ARM_SOCKET_ECONNRESET non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

332

333 - send on created socket

334 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

335

336 - send on bound socket

337 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

338

339 - send on listening socket

340 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

341

342 - send on closed socket

343 BSD-strict expected return code \b ARM_SOCKET_ECONNRESET non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

344

345 -# \b SocketSendTo

346 - sendto on closed socket

347 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

348

349 -# \b SocketGetSockName

350 - getsockname on closed socket

351 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

352

353 - getsockname on unbound socket

354 BSD-strict expected return code \b ARM_SOCKET_EINVAL non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

355

356 -# \b SocketGetPeerName

357 - getpeername on closed socket

358 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

359

360 - getpeername on created socket

361 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

362

363 - getpeername on bound socket

364 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

365

366 - getpeername on listening socket

367 BSD-strict expected return code \b ARM_SOCKET_ENOTCONN non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

368

369 -# \b SocketGetOpt

370 - getsockopt on closed socket

371 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

372

373 -# \b SocketSetOpt

374 - setsockopt on closed socket

375 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

376

377 -# \b SocketClose

378 - close already closed socket

379 BSD-strict expected return code \b ARM_SOCKET_ESOCK non BSD-strict accepted return code \token{0}

380

381 -# \b SocketGetHostByName

382 - gethostbyname for non-existing host

383 BSD-strict expected return code \b ARM_SOCKET_EHOSTNOTFOUND non BSD-strict accepted return code \token{ARM_SOCKET_ERROR}

384 */