Duy tran / easy-connect-v16

version 1.6

Dependents:   iot_water_monitor_v2

README.md@0:9fa9929d1a8c, 2017-12-12 (annotated)

Committer:
DuyLionTran
Date:
Tue Dec 12 15:57:57 2017 +0000
Revision:
0:9fa9929d1a8c
version 1.6

Who changed what in which revision?

UserRevisionLine numberNew contents of line
DuyLionTran 0:9fa9929d1a8c 1 # Easy Connect - Easily add all supported connectivity methods to your mbed OS project
DuyLionTran 0:9fa9929d1a8c 2
DuyLionTran 0:9fa9929d1a8c 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.
DuyLionTran 0:9fa9929d1a8c 4
DuyLionTran 0:9fa9929d1a8c 5 ## Specifying the connectivity method
DuyLionTran 0:9fa9929d1a8c 6
DuyLionTran 0:9fa9929d1a8c 7 Add the following to your `mbed_app.json` file:
DuyLionTran 0:9fa9929d1a8c 8
DuyLionTran 0:9fa9929d1a8c 9 ```json
DuyLionTran 0:9fa9929d1a8c 10 {
DuyLionTran 0:9fa9929d1a8c 11 "config": {
DuyLionTran 0:9fa9929d1a8c 12 "network-interface":{
DuyLionTran 0:9fa9929d1a8c 13 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
DuyLionTran 0:9fa9929d1a8c 14 "value": "ETHERNET"
DuyLionTran 0:9fa9929d1a8c 15 }
DuyLionTran 0:9fa9929d1a8c 16 },
DuyLionTran 0:9fa9929d1a8c 17 "target_overrides": {
DuyLionTran 0:9fa9929d1a8c 18 "*": {
DuyLionTran 0:9fa9929d1a8c 19 "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"],
DuyLionTran 0:9fa9929d1a8c 20 "mbed-mesh-api.6lowpan-nd-channel-page": 0,
DuyLionTran 0:9fa9929d1a8c 21 "mbed-mesh-api.6lowpan-nd-channel": 12
DuyLionTran 0:9fa9929d1a8c 22 }
DuyLionTran 0:9fa9929d1a8c 23 }
DuyLionTran 0:9fa9929d1a8c 24 }
DuyLionTran 0:9fa9929d1a8c 25 ```
DuyLionTran 0:9fa9929d1a8c 26
DuyLionTran 0:9fa9929d1a8c 27 If you select `ETHERNET` with `UBLOX_ODIN_EVK_W2` you must add this to your `target-overrides` section in `mbed_app.json`:
DuyLionTran 0:9fa9929d1a8c 28
DuyLionTran 0:9fa9929d1a8c 29 ```json
DuyLionTran 0:9fa9929d1a8c 30 "UBLOX_EVK_ODIN_W2": {
DuyLionTran 0:9fa9929d1a8c 31 "target.device_has_remove": ["EMAC"]
DuyLionTran 0:9fa9929d1a8c 32 }
DuyLionTran 0:9fa9929d1a8c 33 ```
DuyLionTran 0:9fa9929d1a8c 34
DuyLionTran 0:9fa9929d1a8c 35 If you select `WIFI_ESP8266`, `WIFI_IDW0XX1`, `WIFI_ODIN` or `WIFI_RTW`, you also need to add the WiFi SSID and password:
DuyLionTran 0:9fa9929d1a8c 36
DuyLionTran 0:9fa9929d1a8c 37 ```json
DuyLionTran 0:9fa9929d1a8c 38 "config": {
DuyLionTran 0:9fa9929d1a8c 39 "network-interface":{
DuyLionTran 0:9fa9929d1a8c 40 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
DuyLionTran 0:9fa9929d1a8c 41 "value": "WIFI_ESP8266"
DuyLionTran 0:9fa9929d1a8c 42 },
DuyLionTran 0:9fa9929d1a8c 43 "esp8266-tx": {
DuyLionTran 0:9fa9929d1a8c 44 "help": "Pin used as TX (connects to ESP8266 RX)",
DuyLionTran 0:9fa9929d1a8c 45 "value": "PTD3"
DuyLionTran 0:9fa9929d1a8c 46 },
DuyLionTran 0:9fa9929d1a8c 47 "esp8266-rx": {
DuyLionTran 0:9fa9929d1a8c 48 "help": "Pin used as RX (connects to ESP8266 TX)",
DuyLionTran 0:9fa9929d1a8c 49 "value": "PTD2"
DuyLionTran 0:9fa9929d1a8c 50 },
DuyLionTran 0:9fa9929d1a8c 51 "esp8266-debug": {
DuyLionTran 0:9fa9929d1a8c 52 "value": true
DuyLionTran 0:9fa9929d1a8c 53 },
DuyLionTran 0:9fa9929d1a8c 54 "wifi-ssid": {
DuyLionTran 0:9fa9929d1a8c 55 "value": "\"SSID\""
DuyLionTran 0:9fa9929d1a8c 56 },
DuyLionTran 0:9fa9929d1a8c 57 "wifi-password": {
DuyLionTran 0:9fa9929d1a8c 58 "value": "\"Password\""
DuyLionTran 0:9fa9929d1a8c 59 }
DuyLionTran 0:9fa9929d1a8c 60 }
DuyLionTran 0:9fa9929d1a8c 61 ```
DuyLionTran 0:9fa9929d1a8c 62
DuyLionTran 0:9fa9929d1a8c 63 If you use `MESH_LOWPAN_ND` or `MESH_THREAD` you need to specify your radio module:
DuyLionTran 0:9fa9929d1a8c 64
DuyLionTran 0:9fa9929d1a8c 65 ```json
DuyLionTran 0:9fa9929d1a8c 66 "config": {
DuyLionTran 0:9fa9929d1a8c 67 "network-interface":{
DuyLionTran 0:9fa9929d1a8c 68 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_IDW0XX1, WIFI_ODIN, WIFI_RTW, MESH_LOWPAN_ND, MESH_THREAD, CELLULAR_ONBOARD",
DuyLionTran 0:9fa9929d1a8c 69 "value": "MESH_LOWPAN_ND"
DuyLionTran 0:9fa9929d1a8c 70 },
DuyLionTran 0:9fa9929d1a8c 71 "mesh_radio_type": {
DuyLionTran 0:9fa9929d1a8c 72 "help": "options are ATMEL, MCR20, SPIRIT1, EFR32",
DuyLionTran 0:9fa9929d1a8c 73 "value": "ATMEL"
DuyLionTran 0:9fa9929d1a8c 74 }
DuyLionTran 0:9fa9929d1a8c 75 }
DuyLionTran 0:9fa9929d1a8c 76 ```
DuyLionTran 0:9fa9929d1a8c 77
DuyLionTran 0:9fa9929d1a8c 78 If you use `CELLULAR_ONBOARD` (for which user documentation can be found [here](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/cellular/)) you must specify the following:
DuyLionTran 0:9fa9929d1a8c 79
DuyLionTran 0:9fa9929d1a8c 80 ```json
DuyLionTran 0:9fa9929d1a8c 81 "target_overrides": {
DuyLionTran 0:9fa9929d1a8c 82 "*": {
DuyLionTran 0:9fa9929d1a8c 83 "ppp-cell-iface.apn-lookup": true
DuyLionTran 0:9fa9929d1a8c 84 }
DuyLionTran 0:9fa9929d1a8c 85 }
DuyLionTran 0:9fa9929d1a8c 86 ```
DuyLionTran 0:9fa9929d1a8c 87 ...and you may also need to specify one or more of the following:
DuyLionTran 0:9fa9929d1a8c 88
DuyLionTran 0:9fa9929d1a8c 89 ```json
DuyLionTran 0:9fa9929d1a8c 90 "config": {
DuyLionTran 0:9fa9929d1a8c 91 "cellular-apn": {
DuyLionTran 0:9fa9929d1a8c 92 "help": "Please provide the APN string for your SIM if it is not already included in APN_db.h.",
DuyLionTran 0:9fa9929d1a8c 93 "value": "\"my_sims_apn\""
DuyLionTran 0:9fa9929d1a8c 94 },
DuyLionTran 0:9fa9929d1a8c 95 "cellular-username": {
DuyLionTran 0:9fa9929d1a8c 96 "help": "May or may not be required for your APN, please consult your SIM provider.",
DuyLionTran 0:9fa9929d1a8c 97 "value": "\"my_sim_apns_username\""
DuyLionTran 0:9fa9929d1a8c 98 },
DuyLionTran 0:9fa9929d1a8c 99 "cellular-password": {
DuyLionTran 0:9fa9929d1a8c 100 "help": "May or may not be required for your APN, please consult your SIM provider.",
DuyLionTran 0:9fa9929d1a8c 101 "value": "\"my_sim_apns_password\""
DuyLionTran 0:9fa9929d1a8c 102 },
DuyLionTran 0:9fa9929d1a8c 103 "cellular-sim-pin": {
DuyLionTran 0:9fa9929d1a8c 104 "help": "Please provide the PIN for your SIM (as a four digit string) if your SIM is normally locked",
DuyLionTran 0:9fa9929d1a8c 105 "value": "\"1234\""
DuyLionTran 0:9fa9929d1a8c 106 }
DuyLionTran 0:9fa9929d1a8c 107 }
DuyLionTran 0:9fa9929d1a8c 108 ```
DuyLionTran 0:9fa9929d1a8c 109
DuyLionTran 0:9fa9929d1a8c 110 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`.
DuyLionTran 0:9fa9929d1a8c 111
DuyLionTran 0:9fa9929d1a8c 112 ## Using Easy Connect from your application
DuyLionTran 0:9fa9929d1a8c 113
DuyLionTran 0:9fa9929d1a8c 114 Easy Connect has just one function that returns either a `NetworkInterface`-pointer or `NULL`:
DuyLionTran 0:9fa9929d1a8c 115
DuyLionTran 0:9fa9929d1a8c 116 ```cpp
DuyLionTran 0:9fa9929d1a8c 117 #include "easy-connect.h"
DuyLionTran 0:9fa9929d1a8c 118
DuyLionTran 0:9fa9929d1a8c 119 int main(int, char**) {
DuyLionTran 0:9fa9929d1a8c 120 NetworkInterface* network = easy_connect(true); /* has 1 argument, enable_logging (pass in true to log to serial port) */
DuyLionTran 0:9fa9929d1a8c 121 if (!network) {
DuyLionTran 0:9fa9929d1a8c 122 printf("Connecting to the network failed... See serial output.\r\n");
DuyLionTran 0:9fa9929d1a8c 123 return 1;
DuyLionTran 0:9fa9929d1a8c 124 }
DuyLionTran 0:9fa9929d1a8c 125
DuyLionTran 0:9fa9929d1a8c 126 // Rest of your program
DuyLionTran 0:9fa9929d1a8c 127 }
DuyLionTran 0:9fa9929d1a8c 128 ```
DuyLionTran 0:9fa9929d1a8c 129
DuyLionTran 0:9fa9929d1a8c 130 ## Configuration examples
DuyLionTran 0:9fa9929d1a8c 131
DuyLionTran 0:9fa9929d1a8c 132 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.
DuyLionTran 0:9fa9929d1a8c 133
DuyLionTran 0:9fa9929d1a8c 134 ## Compilation error NanostackRfPhyAtmel.cpp
DuyLionTran 0:9fa9929d1a8c 135
DuyLionTran 0:9fa9929d1a8c 136 If you encounter a compilation error such as below, you need to add an `.mbedignore` file that tells the mbed compiler to skip compiling the files that require Nanostack. By default, the mbed compiler compiles every single file from all folders.
DuyLionTran 0:9fa9929d1a8c 137
DuyLionTran 0:9fa9929d1a8c 138 ```
DuyLionTran 0:9fa9929d1a8c 139 Scan: env
DuyLionTran 0:9fa9929d1a8c 140 Compile [ 0.2%]: NanostackRfPhyAtmel.cpp
DuyLionTran 0:9fa9929d1a8c 141 [Fatal Error] NanostackRfPhyAtmel.cpp@18,44: nanostack/platform/arm_hal_phy.h: No such file or directory
DuyLionTran 0:9fa9929d1a8c 142 [ERROR] ./easy-connect/atmel-rf-driver/source/NanostackRfPhyAtmel.cpp:18:44: fatal error: nanostack/platform/arm_hal_phy.h: No such file or directory
DuyLionTran 0:9fa9929d1a8c 143 #include "nanostack/platform/arm_hal_phy.h"
DuyLionTran 0:9fa9929d1a8c 144 ^
DuyLionTran 0:9fa9929d1a8c 145 compilation terminated.
DuyLionTran 0:9fa9929d1a8c 146
DuyLionTran 0:9fa9929d1a8c 147 ```
DuyLionTran 0:9fa9929d1a8c 148
DuyLionTran 0:9fa9929d1a8c 149 An example of a suitable `.mbedignore` file is available in the [mbed-os-example-client](https://github.com/ARMmbed/mbed-os-example-client/tree/master/configs) repository.
DuyLionTran 0:9fa9929d1a8c 150
DuyLionTran 0:9fa9929d1a8c 151 ## Linking error with UBLOX_EVK_ODIN_W2
DuyLionTran 0:9fa9929d1a8c 152
DuyLionTran 0:9fa9929d1a8c 153 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`.
DuyLionTran 0:9fa9929d1a8c 154
DuyLionTran 0:9fa9929d1a8c 155 ```
DuyLionTran 0:9fa9929d1a8c 156 Link: tls-client
DuyLionTran 0:9fa9929d1a8c 157 ./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*)':
DuyLionTran 0:9fa9929d1a8c 158 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
DuyLionTran 0:9fa9929d1a8c 159 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
DuyLionTran 0:9fa9929d1a8c 160 collect2: error: ld returned 1 exit status
DuyLionTran 0:9fa9929d1a8c 161 [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*)':
DuyLionTran 0:9fa9929d1a8c 162 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
DuyLionTran 0:9fa9929d1a8c 163 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
DuyLionTran 0:9fa9929d1a8c 164 collect2: error: ld returned 1 exit status
DuyLionTran 0:9fa9929d1a8c 165
DuyLionTran 0:9fa9929d1a8c 166 [mbed] ERROR: "/usr/bin/python" returned error code 1.
DuyLionTran 0:9fa9929d1a8c 167 ```
DuyLionTran 0:9fa9929d1a8c 168
DuyLionTran 0:9fa9929d1a8c 169 ## Network errors
DuyLionTran 0:9fa9929d1a8c 170
DuyLionTran 0:9fa9929d1a8c 171 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).
DuyLionTran 0:9fa9929d1a8c 172
DuyLionTran 0:9fa9929d1a8c 173 ## CR/LF in serial output
DuyLionTran 0:9fa9929d1a8c 174
DuyLionTran 0:9fa9929d1a8c 175 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`:
DuyLionTran 0:9fa9929d1a8c 176
DuyLionTran 0:9fa9929d1a8c 177 ```json
DuyLionTran 0:9fa9929d1a8c 178 "target_overrides": {
DuyLionTran 0:9fa9929d1a8c 179 "*": {
DuyLionTran 0:9fa9929d1a8c 180 "platform.stdio-baud-rate": 115200,
DuyLionTran 0:9fa9929d1a8c 181 "platform.stdio-convert-newlines": true
DuyLionTran 0:9fa9929d1a8c 182 }
DuyLionTran 0:9fa9929d1a8c 183 }
DuyLionTran 0:9fa9929d1a8c 184 ```
DuyLionTran 0:9fa9929d1a8c 185
DuyLionTran 0:9fa9929d1a8c 186 ## Extra defines
DuyLionTran 0:9fa9929d1a8c 187
DuyLionTran 0:9fa9929d1a8c 188 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.