Wouter Van den Bogaert
/
PGO6_VoteController_template
PGO6
easy-connect/README-old.md@6:754d3e8f9ae9, 2019-11-14 (annotated)
- Committer:
- s0130594
- Date:
- Thu Nov 14 15:07:12 2019 +0100
- Revision:
- 6:754d3e8f9ae9
- Parent:
- 5:2ce5049b9c14
Added MQTT functionality
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
s0130594 | 5:2ce5049b9c14 | 1 | # Deprecated content |
s0130594 | 5:2ce5049b9c14 | 2 | |
s0130594 | 5:2ce5049b9c14 | 3 | Information below is for historical reference and is valid only if you are using easy-connect with Mbed OS 5.9 and earlier. |
s0130594 | 5:2ce5049b9c14 | 4 | |
s0130594 | 5:2ce5049b9c14 | 5 | ## Introduction |
s0130594 | 5:2ce5049b9c14 | 6 | |
s0130594 | 5:2ce5049b9c14 | 7 | 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. |
s0130594 | 5:2ce5049b9c14 | 8 | |
s0130594 | 5:2ce5049b9c14 | 9 | ## Specifying the connectivity method |
s0130594 | 5:2ce5049b9c14 | 10 | |
s0130594 | 5:2ce5049b9c14 | 11 | Add the following to your `mbed_app.json` file: |
s0130594 | 5:2ce5049b9c14 | 12 | |
s0130594 | 5:2ce5049b9c14 | 13 | ```json |
s0130594 | 5:2ce5049b9c14 | 14 | { |
s0130594 | 5:2ce5049b9c14 | 15 | "config": { |
s0130594 | 5:2ce5049b9c14 | 16 | "network-interface":{ |
s0130594 | 5:2ce5049b9c14 | 17 | "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, WIFI_ISM43362, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD", |
s0130594 | 5:2ce5049b9c14 | 18 | "value": "ETHERNET" |
s0130594 | 5:2ce5049b9c14 | 19 | } |
s0130594 | 5:2ce5049b9c14 | 20 | }, |
s0130594 | 5:2ce5049b9c14 | 21 | "target_overrides": { |
s0130594 | 5:2ce5049b9c14 | 22 | "*": { |
s0130594 | 5:2ce5049b9c14 | 23 | "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"], |
s0130594 | 5:2ce5049b9c14 | 24 | "mbed-mesh-api.6lowpan-nd-channel-page": 0, |
s0130594 | 5:2ce5049b9c14 | 25 | "mbed-mesh-api.6lowpan-nd-channel": 12 |
s0130594 | 5:2ce5049b9c14 | 26 | } |
s0130594 | 5:2ce5049b9c14 | 27 | } |
s0130594 | 5:2ce5049b9c14 | 28 | } |
s0130594 | 5:2ce5049b9c14 | 29 | ``` |
s0130594 | 5:2ce5049b9c14 | 30 | |
s0130594 | 5:2ce5049b9c14 | 31 | ### UBLOX ODIN/Ethernet |
s0130594 | 5:2ce5049b9c14 | 32 | |
s0130594 | 5:2ce5049b9c14 | 33 | #### Mbed OS 5.8 and older |
s0130594 | 5:2ce5049b9c14 | 34 | |
s0130594 | 5:2ce5049b9c14 | 35 | If you select `ETHERNET` with `UBLOX_ODIN_EVK_W2` you must add this to your `target-overrides` section in `mbed_app.json`: |
s0130594 | 5:2ce5049b9c14 | 36 | |
s0130594 | 5:2ce5049b9c14 | 37 | ```json |
s0130594 | 5:2ce5049b9c14 | 38 | "UBLOX_EVK_ODIN_W2": { |
s0130594 | 5:2ce5049b9c14 | 39 | "target.device_has_remove": ["EMAC"] |
s0130594 | 5:2ce5049b9c14 | 40 | } |
s0130594 | 5:2ce5049b9c14 | 41 | ``` |
s0130594 | 5:2ce5049b9c14 | 42 | |
s0130594 | 5:2ce5049b9c14 | 43 | #### Mbed OS 5.9 and newer |
s0130594 | 5:2ce5049b9c14 | 44 | |
s0130594 | 5:2ce5049b9c14 | 45 | 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`: |
s0130594 | 5:2ce5049b9c14 | 46 | |
s0130594 | 5:2ce5049b9c14 | 47 | ```json |
s0130594 | 5:2ce5049b9c14 | 48 | "UBLOX_EVK_ODIN_W2": { |
s0130594 | 5:2ce5049b9c14 | 49 | "target.network-default-interface-type": "ETHERNET" |
s0130594 | 5:2ce5049b9c14 | 50 | } |
s0130594 | 5:2ce5049b9c14 | 51 | ``` |
s0130594 | 5:2ce5049b9c14 | 52 | |
s0130594 | 5:2ce5049b9c14 | 53 | ### Other WiFi stacks |
s0130594 | 5:2ce5049b9c14 | 54 | |
s0130594 | 5:2ce5049b9c14 | 55 | If you select `WIFI_ESP8266`, `WIFI_IDW0XX1`, `WIFI_ODIN` or `WIFI_RTW`, `WIFI_WIZFI310` you also need to add the WiFi SSID and password: |
s0130594 | 5:2ce5049b9c14 | 56 | |
s0130594 | 5:2ce5049b9c14 | 57 | ```json |
s0130594 | 5:2ce5049b9c14 | 58 | "config": { |
s0130594 | 5:2ce5049b9c14 | 59 | "network-interface":{ |
s0130594 | 5:2ce5049b9c14 | 60 | "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, WIFI_ISM43362, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD", |
s0130594 | 5:2ce5049b9c14 | 61 | "value": "WIFI_ESP8266" |
s0130594 | 5:2ce5049b9c14 | 62 | }, |
s0130594 | 5:2ce5049b9c14 | 63 | "wifi-ssid": { |
s0130594 | 5:2ce5049b9c14 | 64 | "value": "\"SSID\"" |
s0130594 | 5:2ce5049b9c14 | 65 | }, |
s0130594 | 5:2ce5049b9c14 | 66 | "wifi-password": { |
s0130594 | 5:2ce5049b9c14 | 67 | "value": "\"Password\"" |
s0130594 | 5:2ce5049b9c14 | 68 | } |
s0130594 | 5:2ce5049b9c14 | 69 | } |
s0130594 | 5:2ce5049b9c14 | 70 | ``` |
s0130594 | 5:2ce5049b9c14 | 71 | |
s0130594 | 5:2ce5049b9c14 | 72 | If you use `MESH_LOWPAN_ND` or `MESH_THREAD` you need to specify your radio module: |
s0130594 | 5:2ce5049b9c14 | 73 | |
s0130594 | 5:2ce5049b9c14 | 74 | ```json |
s0130594 | 5:2ce5049b9c14 | 75 | "config": { |
s0130594 | 5:2ce5049b9c14 | 76 | "network-interface":{ |
s0130594 | 5:2ce5049b9c14 | 77 | "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, WIFI_WIZFI310, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD", |
s0130594 | 5:2ce5049b9c14 | 78 | "value": "MESH_LOWPAN_ND" |
s0130594 | 5:2ce5049b9c14 | 79 | }, |
s0130594 | 5:2ce5049b9c14 | 80 | "mesh_radio_type": { |
s0130594 | 5:2ce5049b9c14 | 81 | "help": "options are ATMEL, MCR20, SPIRIT1, EFR32", |
s0130594 | 5:2ce5049b9c14 | 82 | "value": "ATMEL" |
s0130594 | 5:2ce5049b9c14 | 83 | } |
s0130594 | 5:2ce5049b9c14 | 84 | } |
s0130594 | 5:2ce5049b9c14 | 85 | ``` |
s0130594 | 5:2ce5049b9c14 | 86 | |
s0130594 | 5:2ce5049b9c14 | 87 | ### CELLULAR_ONBOARD |
s0130594 | 5:2ce5049b9c14 | 88 | |
s0130594 | 5:2ce5049b9c14 | 89 | If you use [`CELLULAR_ONBOARD`](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/cellular/) you must specify the following: |
s0130594 | 5:2ce5049b9c14 | 90 | |
s0130594 | 5:2ce5049b9c14 | 91 | ```json |
s0130594 | 5:2ce5049b9c14 | 92 | "target_overrides": { |
s0130594 | 5:2ce5049b9c14 | 93 | "*": { |
s0130594 | 5:2ce5049b9c14 | 94 | "ppp-cell-iface.apn-lookup": true |
s0130594 | 5:2ce5049b9c14 | 95 | } |
s0130594 | 5:2ce5049b9c14 | 96 | } |
s0130594 | 5:2ce5049b9c14 | 97 | ``` |
s0130594 | 5:2ce5049b9c14 | 98 | ...and you may also need to specify one or more of the following: |
s0130594 | 5:2ce5049b9c14 | 99 | |
s0130594 | 5:2ce5049b9c14 | 100 | ```json |
s0130594 | 5:2ce5049b9c14 | 101 | "config": { |
s0130594 | 5:2ce5049b9c14 | 102 | "cellular-apn": { |
s0130594 | 5:2ce5049b9c14 | 103 | "help": "Please provide the APN string for your SIM if it is not already included in APN_db.h.", |
s0130594 | 5:2ce5049b9c14 | 104 | "value": "\"my_sims_apn\"" |
s0130594 | 5:2ce5049b9c14 | 105 | }, |
s0130594 | 5:2ce5049b9c14 | 106 | "cellular-username": { |
s0130594 | 5:2ce5049b9c14 | 107 | "help": "May or may not be required for your APN, please consult your SIM provider.", |
s0130594 | 5:2ce5049b9c14 | 108 | "value": "\"my_sim_apns_username\"" |
s0130594 | 5:2ce5049b9c14 | 109 | }, |
s0130594 | 5:2ce5049b9c14 | 110 | "cellular-password": { |
s0130594 | 5:2ce5049b9c14 | 111 | "help": "May or may not be required for your APN, please consult your SIM provider.", |
s0130594 | 5:2ce5049b9c14 | 112 | "value": "\"my_sim_apns_password\"" |
s0130594 | 5:2ce5049b9c14 | 113 | }, |
s0130594 | 5:2ce5049b9c14 | 114 | "cellular-sim-pin": { |
s0130594 | 5:2ce5049b9c14 | 115 | "help": "Please provide the PIN for your SIM (as a four digit string) if your SIM is normally locked", |
s0130594 | 5:2ce5049b9c14 | 116 | "value": "\"1234\"" |
s0130594 | 5:2ce5049b9c14 | 117 | } |
s0130594 | 5:2ce5049b9c14 | 118 | } |
s0130594 | 5:2ce5049b9c14 | 119 | ``` |
s0130594 | 5:2ce5049b9c14 | 120 | |
s0130594 | 5:2ce5049b9c14 | 121 | 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`. |
s0130594 | 5:2ce5049b9c14 | 122 | |
s0130594 | 5:2ce5049b9c14 | 123 | ## Using Easy Connect from your application |
s0130594 | 5:2ce5049b9c14 | 124 | |
s0130594 | 5:2ce5049b9c14 | 125 | Easy Connect has just one function that returns either a `NetworkInterface`-pointer or `NULL`: |
s0130594 | 5:2ce5049b9c14 | 126 | |
s0130594 | 5:2ce5049b9c14 | 127 | ```cpp |
s0130594 | 5:2ce5049b9c14 | 128 | #include "easy-connect.h" |
s0130594 | 5:2ce5049b9c14 | 129 | |
s0130594 | 5:2ce5049b9c14 | 130 | int main(int, char**) { |
s0130594 | 5:2ce5049b9c14 | 131 | NetworkInterface* network = easy_connect(true); /* has 1 argument, enable_logging (pass in true to log to serial port) */ |
s0130594 | 5:2ce5049b9c14 | 132 | if (!network) { |
s0130594 | 5:2ce5049b9c14 | 133 | printf("Connecting to the network failed... See serial output.\r\n"); |
s0130594 | 5:2ce5049b9c14 | 134 | return 1; |
s0130594 | 5:2ce5049b9c14 | 135 | } |
s0130594 | 5:2ce5049b9c14 | 136 | |
s0130594 | 5:2ce5049b9c14 | 137 | // Rest of your program |
s0130594 | 5:2ce5049b9c14 | 138 | } |
s0130594 | 5:2ce5049b9c14 | 139 | ``` |
s0130594 | 5:2ce5049b9c14 | 140 | |
s0130594 | 5:2ce5049b9c14 | 141 | ## Using Easy connect with WiFi |
s0130594 | 5:2ce5049b9c14 | 142 | |
s0130594 | 5:2ce5049b9c14 | 143 | The easy-connect `easy_connect()` is overloaded now for WiFi so that you can submit your WiFi SSID and password programmatically in you want |
s0130594 | 5:2ce5049b9c14 | 144 | the user to be able to supply them via some means. |
s0130594 | 5:2ce5049b9c14 | 145 | |
s0130594 | 5:2ce5049b9c14 | 146 | ```cpp |
s0130594 | 5:2ce5049b9c14 | 147 | #include "easy-connect.h" |
s0130594 | 5:2ce5049b9c14 | 148 | |
s0130594 | 5:2ce5049b9c14 | 149 | int main(int, char**) { |
s0130594 | 5:2ce5049b9c14 | 150 | char* wifi_SSID = "SSID"; |
s0130594 | 5:2ce5049b9c14 | 151 | char* wifi_password = "password"; |
s0130594 | 5:2ce5049b9c14 | 152 | |
s0130594 | 5:2ce5049b9c14 | 153 | NetworkInterface* network = easy_connect(true, wifi_SSID, wifi_password); |
s0130594 | 5:2ce5049b9c14 | 154 | if (!network) { |
s0130594 | 5:2ce5049b9c14 | 155 | printf("Connecting to the network failed... See serial output.\r\n"); |
s0130594 | 5:2ce5049b9c14 | 156 | return 1; |
s0130594 | 5:2ce5049b9c14 | 157 | } |
s0130594 | 5:2ce5049b9c14 | 158 | |
s0130594 | 5:2ce5049b9c14 | 159 | // Rest of your program |
s0130594 | 5:2ce5049b9c14 | 160 | } |
s0130594 | 5:2ce5049b9c14 | 161 | ``` |
s0130594 | 5:2ce5049b9c14 | 162 | |
s0130594 | 5:2ce5049b9c14 | 163 | ## Overriding settings |
s0130594 | 5:2ce5049b9c14 | 164 | |
s0130594 | 5:2ce5049b9c14 | 165 | 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 |
s0130594 | 5:2ce5049b9c14 | 166 | moved to the [`mbed_lib.json`](https://github.com/ARMmbed/easy-connect/blob/master/mbed_lib.json). |
s0130594 | 5:2ce5049b9c14 | 167 | This minimises the amount of lines needed (in typical cases) in the applications `mbed_app.json`. However, due to this the overrides |
s0130594 | 5:2ce5049b9c14 | 168 | need to be done slightly differently, as you need to override the `easy-connect` defines. |
s0130594 | 5:2ce5049b9c14 | 169 | |
s0130594 | 5:2ce5049b9c14 | 170 | So, for example changing the ESP8266 TX/RX pins and enable debugs - you would now have modify as below. |
s0130594 | 5:2ce5049b9c14 | 171 | |
s0130594 | 5:2ce5049b9c14 | 172 | ```json |
s0130594 | 5:2ce5049b9c14 | 173 | "target_overrides": { |
s0130594 | 5:2ce5049b9c14 | 174 | "*": { |
s0130594 | 5:2ce5049b9c14 | 175 | "easy-connect.wifi-esp8266-tx": "A1", |
s0130594 | 5:2ce5049b9c14 | 176 | "easy-connect.wifi-esp8266-rx": "A2", |
s0130594 | 5:2ce5049b9c14 | 177 | "easy-connect.wifi-esp8266-debug: true |
s0130594 | 5:2ce5049b9c14 | 178 | } |
s0130594 | 5:2ce5049b9c14 | 179 | } |
s0130594 | 5:2ce5049b9c14 | 180 | ``` |
s0130594 | 5:2ce5049b9c14 | 181 | |
s0130594 | 5:2ce5049b9c14 | 182 | |
s0130594 | 5:2ce5049b9c14 | 183 | ## Configuration examples |
s0130594 | 5:2ce5049b9c14 | 184 | |
s0130594 | 5:2ce5049b9c14 | 185 | 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. |
s0130594 | 5:2ce5049b9c14 | 186 | |
s0130594 | 5:2ce5049b9c14 | 187 | ## Linking error with UBLOX_EVK_ODIN_W2 |
s0130594 | 5:2ce5049b9c14 | 188 | |
s0130594 | 5:2ce5049b9c14 | 189 | 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`. |
s0130594 | 5:2ce5049b9c14 | 190 | |
s0130594 | 5:2ce5049b9c14 | 191 | ``` |
s0130594 | 5:2ce5049b9c14 | 192 | Link: tls-client |
s0130594 | 5:2ce5049b9c14 | 193 | ./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*)': |
s0130594 | 5:2ce5049b9c14 | 194 | OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()' |
s0130594 | 5:2ce5049b9c14 | 195 | OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()' |
s0130594 | 5:2ce5049b9c14 | 196 | collect2: error: ld returned 1 exit status |
s0130594 | 5:2ce5049b9c14 | 197 | [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*)': |
s0130594 | 5:2ce5049b9c14 | 198 | OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()' |
s0130594 | 5:2ce5049b9c14 | 199 | OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()' |
s0130594 | 5:2ce5049b9c14 | 200 | collect2: error: ld returned 1 exit status |
s0130594 | 5:2ce5049b9c14 | 201 | |
s0130594 | 5:2ce5049b9c14 | 202 | [mbed] ERROR: "/usr/bin/python" returned error code 1. |
s0130594 | 5:2ce5049b9c14 | 203 | ``` |
s0130594 | 5:2ce5049b9c14 | 204 | |
s0130594 | 5:2ce5049b9c14 | 205 | ## Network errors |
s0130594 | 5:2ce5049b9c14 | 206 | |
s0130594 | 5:2ce5049b9c14 | 207 | 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). |
s0130594 | 5:2ce5049b9c14 | 208 | |
s0130594 | 5:2ce5049b9c14 | 209 | ## CR/LF in serial output |
s0130594 | 5:2ce5049b9c14 | 210 | |
s0130594 | 5:2ce5049b9c14 | 211 | 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`: |
s0130594 | 5:2ce5049b9c14 | 212 | |
s0130594 | 5:2ce5049b9c14 | 213 | ```json |
s0130594 | 5:2ce5049b9c14 | 214 | "target_overrides": { |
s0130594 | 5:2ce5049b9c14 | 215 | "*": { |
s0130594 | 5:2ce5049b9c14 | 216 | "platform.stdio-baud-rate": 115200, |
s0130594 | 5:2ce5049b9c14 | 217 | "platform.stdio-convert-newlines": true |
s0130594 | 5:2ce5049b9c14 | 218 | } |
s0130594 | 5:2ce5049b9c14 | 219 | } |
s0130594 | 5:2ce5049b9c14 | 220 | ``` |
s0130594 | 5:2ce5049b9c14 | 221 | |
s0130594 | 5:2ce5049b9c14 | 222 | ## For network stack developers |
s0130594 | 5:2ce5049b9c14 | 223 | |
s0130594 | 5:2ce5049b9c14 | 224 | Please try out the reliability of your networking stack using |
s0130594 | 5:2ce5049b9c14 | 225 | [stress-test](https://github.com/ARMmbed/mbed-stress-test) to ensure |
s0130594 | 5:2ce5049b9c14 | 226 | your stack is performing as expected. |
s0130594 | 5:2ce5049b9c14 | 227 | |
s0130594 | 5:2ce5049b9c14 | 228 | ## Extra defines |
s0130594 | 5:2ce5049b9c14 | 229 | |
s0130594 | 5:2ce5049b9c14 | 230 | 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. |