Wouter Van den Bogaert / Mbed OS PGO6_VoteController_template

PGO6

Dependencies:   MQTT

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?

UserRevisionLine numberNew 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.