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