Jim Flynn / Mbed OS wifi_Example

wifi test

Dependencies:   X_NUCLEO_IKS01A2 mbed-http

easy-connect/README.md@0:24d3eb812fd4, 2018-09-05 (annotated)

Committer:
JMF
Date:
Wed Sep 05 14:28:24 2018 +0000
Revision:
0:24d3eb812fd4
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
JMF 0:24d3eb812fd4 1 # Easy Connect - Easily add all supported connectivity methods to your mbed OS project
JMF 0:24d3eb812fd4 2
JMF 0:24d3eb812fd4 3 You may want to give the users of your application the possibility to switch between connectivity methods. The `NetworkInterface` API makes this easy, but you still need a mechanism for the user to chooce the method, and perhaps throw in some `#define`'s. Easy Connect handles all of this for you. Just declare the desired connectivity method in your `mbed_app.json` file and call `easy_connect()` from your application.
JMF 0:24d3eb812fd4 4
JMF 0:24d3eb812fd4 5 ## Specifying the connectivity method
JMF 0:24d3eb812fd4 6
JMF 0:24d3eb812fd4 7 Add the following to your `mbed_app.json` file:
JMF 0:24d3eb812fd4 8
JMF 0:24d3eb812fd4 9 ```json
JMF 0:24d3eb812fd4 10 {
JMF 0:24d3eb812fd4 11 "config": {
JMF 0:24d3eb812fd4 12 "network-interface":{
JMF 0:24d3eb812fd4 13 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, WIFI_ISM43362, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
JMF 0:24d3eb812fd4 14 "value": "ETHERNET"
JMF 0:24d3eb812fd4 15 }
JMF 0:24d3eb812fd4 16 },
JMF 0:24d3eb812fd4 17 "target_overrides": {
JMF 0:24d3eb812fd4 18 "*": {
JMF 0:24d3eb812fd4 19 "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"],
JMF 0:24d3eb812fd4 20 "mbed-mesh-api.6lowpan-nd-channel-page": 0,
JMF 0:24d3eb812fd4 21 "mbed-mesh-api.6lowpan-nd-channel": 12
JMF 0:24d3eb812fd4 22 }
JMF 0:24d3eb812fd4 23 }
JMF 0:24d3eb812fd4 24 }
JMF 0:24d3eb812fd4 25 ```
JMF 0:24d3eb812fd4 26
JMF 0:24d3eb812fd4 27 ### UBLOX ODIN/Ethernet
JMF 0:24d3eb812fd4 28
JMF 0:24d3eb812fd4 29 #### Mbed OS 5.8 and older
JMF 0:24d3eb812fd4 30
JMF 0:24d3eb812fd4 31 If you select `ETHERNET` with `UBLOX_ODIN_EVK_W2` you must add this to your `target-overrides` section in `mbed_app.json`:
JMF 0:24d3eb812fd4 32
JMF 0:24d3eb812fd4 33 ```json
JMF 0:24d3eb812fd4 34 "UBLOX_EVK_ODIN_W2": {
JMF 0:24d3eb812fd4 35 "target.device_has_remove": ["EMAC"]
JMF 0:24d3eb812fd4 36 }
JMF 0:24d3eb812fd4 37 ```
JMF 0:24d3eb812fd4 38
JMF 0:24d3eb812fd4 39 #### Mbed OS 5.9 and newer
JMF 0:24d3eb812fd4 40
JMF 0:24d3eb812fd4 41 With Mbed OS 5.9, the EMAC SW was refactored and a default network selector is used instead. You must add the following `target-overrides` section to `mbed_app.json`:
JMF 0:24d3eb812fd4 42
JMF 0:24d3eb812fd4 43 ```json
JMF 0:24d3eb812fd4 44 "UBLOX_EVK_ODIN_W2": {
JMF 0:24d3eb812fd4 45 "target.network-default-interface-type": "ETHERNET"
JMF 0:24d3eb812fd4 46 }
JMF 0:24d3eb812fd4 47 ```
JMF 0:24d3eb812fd4 48
JMF 0:24d3eb812fd4 49 ### Other WiFi stacks
JMF 0:24d3eb812fd4 50
JMF 0:24d3eb812fd4 51 If you select `WIFI_ESP8266`, `WIFI_IDW0XX1`, `WIFI_ODIN` or `WIFI_RTW`, `WIFI_WIZFI310` you also need to add the WiFi SSID and password:
JMF 0:24d3eb812fd4 52
JMF 0:24d3eb812fd4 53 ```json
JMF 0:24d3eb812fd4 54 "config": {
JMF 0:24d3eb812fd4 55 "network-interface":{
JMF 0:24d3eb812fd4 56 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, WIFI_ISM43362, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
JMF 0:24d3eb812fd4 57 "value": "WIFI_ESP8266"
JMF 0:24d3eb812fd4 58 },
JMF 0:24d3eb812fd4 59 "wifi-ssid": {
JMF 0:24d3eb812fd4 60 "value": "\"SSID\""
JMF 0:24d3eb812fd4 61 },
JMF 0:24d3eb812fd4 62 "wifi-password": {
JMF 0:24d3eb812fd4 63 "value": "\"Password\""
JMF 0:24d3eb812fd4 64 }
JMF 0:24d3eb812fd4 65 }
JMF 0:24d3eb812fd4 66 ```
JMF 0:24d3eb812fd4 67
JMF 0:24d3eb812fd4 68 If you use `MESH_LOWPAN_ND` or `MESH_THREAD` you need to specify your radio module:
JMF 0:24d3eb812fd4 69
JMF 0:24d3eb812fd4 70 ```json
JMF 0:24d3eb812fd4 71 "config": {
JMF 0:24d3eb812fd4 72 "network-interface":{
JMF 0:24d3eb812fd4 73 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
JMF 0:24d3eb812fd4 74 "value": "MESH_LOWPAN_ND"
JMF 0:24d3eb812fd4 75 },
JMF 0:24d3eb812fd4 76 "mesh_radio_type": {
JMF 0:24d3eb812fd4 77 "help": "options are ATMEL, MCR20, SPIRIT1, EFR32",
JMF 0:24d3eb812fd4 78 "value": "ATMEL"
JMF 0:24d3eb812fd4 79 }
JMF 0:24d3eb812fd4 80 }
JMF 0:24d3eb812fd4 81 ```
JMF 0:24d3eb812fd4 82
JMF 0:24d3eb812fd4 83 ### CELLULAR_ONBOARD
JMF 0:24d3eb812fd4 84
JMF 0:24d3eb812fd4 85 If you use [`CELLULAR_ONBOARD`](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/cellular/) you must specify the following:
JMF 0:24d3eb812fd4 86
JMF 0:24d3eb812fd4 87 ```json
JMF 0:24d3eb812fd4 88 "target_overrides": {
JMF 0:24d3eb812fd4 89 "*": {
JMF 0:24d3eb812fd4 90 "ppp-cell-iface.apn-lookup": true
JMF 0:24d3eb812fd4 91 }
JMF 0:24d3eb812fd4 92 }
JMF 0:24d3eb812fd4 93 ```
JMF 0:24d3eb812fd4 94 ...and you may also need to specify one or more of the following:
JMF 0:24d3eb812fd4 95
JMF 0:24d3eb812fd4 96 ```json
JMF 0:24d3eb812fd4 97 "config": {
JMF 0:24d3eb812fd4 98 "cellular-apn": {
JMF 0:24d3eb812fd4 99 "help": "Please provide the APN string for your SIM if it is not already included in APN_db.h.",
JMF 0:24d3eb812fd4 100 "value": "\"my_sims_apn\""
JMF 0:24d3eb812fd4 101 },
JMF 0:24d3eb812fd4 102 "cellular-username": {
JMF 0:24d3eb812fd4 103 "help": "May or may not be required for your APN, please consult your SIM provider.",
JMF 0:24d3eb812fd4 104 "value": "\"my_sim_apns_username\""
JMF 0:24d3eb812fd4 105 },
JMF 0:24d3eb812fd4 106 "cellular-password": {
JMF 0:24d3eb812fd4 107 "help": "May or may not be required for your APN, please consult your SIM provider.",
JMF 0:24d3eb812fd4 108 "value": "\"my_sim_apns_password\""
JMF 0:24d3eb812fd4 109 },
JMF 0:24d3eb812fd4 110 "cellular-sim-pin": {
JMF 0:24d3eb812fd4 111 "help": "Please provide the PIN for your SIM (as a four digit string) if your SIM is normally locked",
JMF 0:24d3eb812fd4 112 "value": "\"1234\""
JMF 0:24d3eb812fd4 113 }
JMF 0:24d3eb812fd4 114 }
JMF 0:24d3eb812fd4 115 ```
JMF 0:24d3eb812fd4 116
JMF 0:24d3eb812fd4 117 None of the optional settings need to be specified for the `UBLOX_C030_U201` cellular target, for which the APN settings are in `APN_db.h`.
JMF 0:24d3eb812fd4 118
JMF 0:24d3eb812fd4 119 ## Using Easy Connect from your application
JMF 0:24d3eb812fd4 120
JMF 0:24d3eb812fd4 121 Easy Connect has just one function that returns either a `NetworkInterface`-pointer or `NULL`:
JMF 0:24d3eb812fd4 122
JMF 0:24d3eb812fd4 123 ```cpp
JMF 0:24d3eb812fd4 124 #include "easy-connect.h"
JMF 0:24d3eb812fd4 125
JMF 0:24d3eb812fd4 126 int main(int, char**) {
JMF 0:24d3eb812fd4 127 NetworkInterface* network = easy_connect(true); /* has 1 argument, enable_logging (pass in true to log to serial port) */
JMF 0:24d3eb812fd4 128 if (!network) {
JMF 0:24d3eb812fd4 129 printf("Connecting to the network failed... See serial output.\r\n");
JMF 0:24d3eb812fd4 130 return 1;
JMF 0:24d3eb812fd4 131 }
JMF 0:24d3eb812fd4 132
JMF 0:24d3eb812fd4 133 // Rest of your program
JMF 0:24d3eb812fd4 134 }
JMF 0:24d3eb812fd4 135 ```
JMF 0:24d3eb812fd4 136
JMF 0:24d3eb812fd4 137 ## Using Easy connect with WiFi
JMF 0:24d3eb812fd4 138
JMF 0:24d3eb812fd4 139 The easy-connect `easy_connect()` is overloaded now for WiFi so that you can submit your WiFi SSID and password programmatically in you want
JMF 0:24d3eb812fd4 140 the user to be able to supply them via some means.
JMF 0:24d3eb812fd4 141
JMF 0:24d3eb812fd4 142 ```cpp
JMF 0:24d3eb812fd4 143 #include "easy-connect.h"
JMF 0:24d3eb812fd4 144
JMF 0:24d3eb812fd4 145 int main(int, char**) {
JMF 0:24d3eb812fd4 146 char* wifi_SSID = "SSID";
JMF 0:24d3eb812fd4 147 char* wifi_password = "password";
JMF 0:24d3eb812fd4 148
JMF 0:24d3eb812fd4 149 NetworkInterface* network = easy_connect(true, wifi_SSID, wifi_password);
JMF 0:24d3eb812fd4 150 if (!network) {
JMF 0:24d3eb812fd4 151 printf("Connecting to the network failed... See serial output.\r\n");
JMF 0:24d3eb812fd4 152 return 1;
JMF 0:24d3eb812fd4 153 }
JMF 0:24d3eb812fd4 154
JMF 0:24d3eb812fd4 155 // Rest of your program
JMF 0:24d3eb812fd4 156 }
JMF 0:24d3eb812fd4 157 ```
JMF 0:24d3eb812fd4 158
JMF 0:24d3eb812fd4 159 ## Overriding settings
JMF 0:24d3eb812fd4 160
JMF 0:24d3eb812fd4 161 Easy-connect was changed recently with [PR #59](https://github.com/ARMmbed/easy-connect/pull/59) - where some of the defines expected via `mbed_app.json` were
JMF 0:24d3eb812fd4 162 moved to the [`mbed_lib.json`](https://github.com/ARMmbed/easy-connect/blob/master/mbed_lib.json).
JMF 0:24d3eb812fd4 163 This minimises the amount of lines needed (in typical cases) in the applications `mbed_app.json`. However, due to this the overrides
JMF 0:24d3eb812fd4 164 need to be done slightly differently, as you need to override the `easy-connect` defines.
JMF 0:24d3eb812fd4 165
JMF 0:24d3eb812fd4 166 So, for example changing the ESP8266 TX/RX pins and enable debugs - you would now have modify as below.
JMF 0:24d3eb812fd4 167
JMF 0:24d3eb812fd4 168 ```json
JMF 0:24d3eb812fd4 169 "target_overrides": {
JMF 0:24d3eb812fd4 170 "*": {
JMF 0:24d3eb812fd4 171 "easy-connect.wifi-esp8266-tx": "A1",
JMF 0:24d3eb812fd4 172 "easy-connect.wifi-esp8266-rx": "A2",
JMF 0:24d3eb812fd4 173 "easy-connect.wifi-esp8266-debug: true
JMF 0:24d3eb812fd4 174 }
JMF 0:24d3eb812fd4 175 }
JMF 0:24d3eb812fd4 176 ```
JMF 0:24d3eb812fd4 177
JMF 0:24d3eb812fd4 178
JMF 0:24d3eb812fd4 179 ## Configuration examples
JMF 0:24d3eb812fd4 180
JMF 0:24d3eb812fd4 181 There are many things that you have to modify for all of the combinations. Examples for configurations are available for example in the [mbed-os-example-client](https://github.com/ARMmbed/mbed-os-example-client/tree/master/configs) repository.
JMF 0:24d3eb812fd4 182
JMF 0:24d3eb812fd4 183 ## Linking error with UBLOX_EVK_ODIN_W2
JMF 0:24d3eb812fd4 184
JMF 0:24d3eb812fd4 185 If you get a linking error such as below, you are compiling the `WIFI_ODIN` with the `EMAC override` section in `mbed_app.json`. Remove the `EMAC override` from your `mbed_app.json`.
JMF 0:24d3eb812fd4 186
JMF 0:24d3eb812fd4 187 ```
JMF 0:24d3eb812fd4 188 Link: tls-client
JMF 0:24d3eb812fd4 189 ./mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_UBLOX_EVK_ODIN_W2/sdk/TOOLCHAIN_GCC_ARM/libublox-odin-w2-driver.a(OdinWiFiInterface.o): In function `OdinWiFiInterface::handle_wlan_status_started(wlan_status_started_s*)':
JMF 0:24d3eb812fd4 190 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
JMF 0:24d3eb812fd4 191 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
JMF 0:24d3eb812fd4 192 collect2: error: ld returned 1 exit status
JMF 0:24d3eb812fd4 193 [ERROR] ./mbed-os/targets/TARGET_STM/TARGET_STM32F4/TARGET_UBLOX_EVK_ODIN_W2/sdk/TOOLCHAIN_GCC_ARM/libublox-odin-w2-driver.a(OdinWiFiInterface.o): In function `OdinWiFiInterface::handle_wlan_status_started(wlan_status_started_s*)':
JMF 0:24d3eb812fd4 194 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
JMF 0:24d3eb812fd4 195 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
JMF 0:24d3eb812fd4 196 collect2: error: ld returned 1 exit status
JMF 0:24d3eb812fd4 197
JMF 0:24d3eb812fd4 198 [mbed] ERROR: "/usr/bin/python" returned error code 1.
JMF 0:24d3eb812fd4 199 ```
JMF 0:24d3eb812fd4 200
JMF 0:24d3eb812fd4 201 ## Network errors
JMF 0:24d3eb812fd4 202
JMF 0:24d3eb812fd4 203 If Easy Connect cannot connect to the network, it returns a network error with an error code. To see what the error code means, see the [mbed OS Communication API](https://os.mbed.com/docs/latest/reference/network-socket.html).
JMF 0:24d3eb812fd4 204
JMF 0:24d3eb812fd4 205 ## CR/LF in serial output
JMF 0:24d3eb812fd4 206
JMF 0:24d3eb812fd4 207 If you want to avoid using `\r\n` in your printouts and just use normal C style `\n` instead, please specify these to your `mbed_app.json`:
JMF 0:24d3eb812fd4 208
JMF 0:24d3eb812fd4 209 ```json
JMF 0:24d3eb812fd4 210 "target_overrides": {
JMF 0:24d3eb812fd4 211 "*": {
JMF 0:24d3eb812fd4 212 "platform.stdio-baud-rate": 115200,
JMF 0:24d3eb812fd4 213 "platform.stdio-convert-newlines": true
JMF 0:24d3eb812fd4 214 }
JMF 0:24d3eb812fd4 215 }
JMF 0:24d3eb812fd4 216 ```
JMF 0:24d3eb812fd4 217
JMF 0:24d3eb812fd4 218 ## For network stack developers
JMF 0:24d3eb812fd4 219
JMF 0:24d3eb812fd4 220 Please try out the reliability of your networking stack using
JMF 0:24d3eb812fd4 221 [stress-test](https://github.com/ARMmbed/mbed-stress-test) to ensure
JMF 0:24d3eb812fd4 222 your stack is performing as expected.
JMF 0:24d3eb812fd4 223
JMF 0:24d3eb812fd4 224 ## Extra defines
JMF 0:24d3eb812fd4 225
JMF 0:24d3eb812fd4 226 If you'd like to use Easy Connect with mbed Client then you're in luck. Easy Connect automatically defines the `MBED_SERVER_ADDRESS` macro depending on your connectivity method (either IPv4 or IPv6 address). Use this address to connect to the right instance of mbed Device Connector.