u-blox / easy-connect

Version of easy-connect with the u-blox cellular platforms C027 and C030 added.

Dependents:   HelloMQTT

README.md@6:304d3ba87a01, 2017-11-03 (annotated)

Committer:
RobMeades
Date:
Fri Nov 03 13:01:23 2017 +0000
Revision:
6:304d3ba87a01
Parent:
0:19aa55d66228 
Add comment concerning N2XX baud rate.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
group-ublox 0:19aa55d66228 1 # Easy Connect - Easily add all supported connectivity methods to your mbed OS project
group-ublox 0:19aa55d66228 2
group-ublox 0:19aa55d66228 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.
group-ublox 0:19aa55d66228 4
group-ublox 0:19aa55d66228 5 ## Specifying the connectivity method
group-ublox 0:19aa55d66228 6
group-ublox 0:19aa55d66228 7 Add the following to your `mbed_app.json` file:
group-ublox 0:19aa55d66228 8
group-ublox 0:19aa55d66228 9 ```json
group-ublox 0:19aa55d66228 10 {
group-ublox 0:19aa55d66228 11 "config": {
group-ublox 0:19aa55d66228 12 "network-interface":{
group-ublox 0:19aa55d66228 13 "help": "options are ETHERNET,WIFI_ESP8266,WIFI_ODIN, WIFI_RTW, MESH_LOWPAN_ND,MESH_THREAD",
group-ublox 0:19aa55d66228 14 "value": "ETHERNET"
group-ublox 0:19aa55d66228 15 }
group-ublox 0:19aa55d66228 16 },
group-ublox 0:19aa55d66228 17 "target_overrides": {
group-ublox 0:19aa55d66228 18 "*": {
group-ublox 0:19aa55d66228 19 "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"],
group-ublox 0:19aa55d66228 20 "mbed-mesh-api.6lowpan-nd-channel-page": 0,
group-ublox 0:19aa55d66228 21 "mbed-mesh-api.6lowpan-nd-channel": 12
group-ublox 0:19aa55d66228 22 }
group-ublox 0:19aa55d66228 23 }
group-ublox 0:19aa55d66228 24 }
group-ublox 0:19aa55d66228 25 ```
group-ublox 0:19aa55d66228 26
group-ublox 0:19aa55d66228 27 If you select `ETHERNET` with `UBLOX_ODIN_EVK_W2` you must add this to your `target-overrides` section in `mbed_app.json`:
group-ublox 0:19aa55d66228 28
group-ublox 0:19aa55d66228 29 ```json
group-ublox 0:19aa55d66228 30 "UBLOX_EVK_ODIN_W2": {
group-ublox 0:19aa55d66228 31 "target.device_has_remove": ["EMAC"]
group-ublox 0:19aa55d66228 32 }
group-ublox 0:19aa55d66228 33 ```
group-ublox 0:19aa55d66228 34
group-ublox 0:19aa55d66228 35 If you select `WIFI_ESP8266`, `WIFI_ODIN` or `WIFI_RTW`, you also need to add the WiFi SSID and password:
group-ublox 0:19aa55d66228 36
group-ublox 0:19aa55d66228 37 ```json
group-ublox 0:19aa55d66228 38 "config": {
group-ublox 0:19aa55d66228 39 "network-interface":{
group-ublox 0:19aa55d66228 40 "help": "options are ETHERNET, WIFI_ESP8266, WIFI_ODIN, WIFI_RTW, MESH_LOWPAN_ND, MESH_THREAD",
group-ublox 0:19aa55d66228 41 "value": "WIFI_ESP8266"
group-ublox 0:19aa55d66228 42 },
group-ublox 0:19aa55d66228 43 "esp8266-tx": {
group-ublox 0:19aa55d66228 44 "help": "Pin used as TX (connects to ESP8266 RX)",
group-ublox 0:19aa55d66228 45 "value": "PTD3"
group-ublox 0:19aa55d66228 46 },
group-ublox 0:19aa55d66228 47 "esp8266-rx": {
group-ublox 0:19aa55d66228 48 "help": "Pin used as RX (connects to ESP8266 TX)",
group-ublox 0:19aa55d66228 49 "value": "PTD2"
group-ublox 0:19aa55d66228 50 },
group-ublox 0:19aa55d66228 51 "esp8266-debug": {
group-ublox 0:19aa55d66228 52 "value": true
group-ublox 0:19aa55d66228 53 },
group-ublox 0:19aa55d66228 54 "wifi-ssid": {
group-ublox 0:19aa55d66228 55 "value": "\"SSID\""
group-ublox 0:19aa55d66228 56 },
group-ublox 0:19aa55d66228 57 "wifi-password": {
group-ublox 0:19aa55d66228 58 "value": "\"Password\""
group-ublox 0:19aa55d66228 59 }
group-ublox 0:19aa55d66228 60 }
group-ublox 0:19aa55d66228 61 ```
group-ublox 0:19aa55d66228 62
group-ublox 0:19aa55d66228 63 If you use `MESH_LOWPAN_ND` or `MESH_THREAD` you need to specify your radio module:
group-ublox 0:19aa55d66228 64
group-ublox 0:19aa55d66228 65 ```json
group-ublox 0:19aa55d66228 66 "config": {
group-ublox 0:19aa55d66228 67 "network-interface":{
group-ublox 0:19aa55d66228 68 "help": "options are ETHERNET,WIFI_ESP8266,WIFI_ODIN,WIFI_RTW,MESH_LOWPAN_ND,MESH_THREAD",
group-ublox 0:19aa55d66228 69 "value": "MESH_LOWPAN_ND"
group-ublox 0:19aa55d66228 70 },
group-ublox 0:19aa55d66228 71 "mesh_radio_type": {
group-ublox 0:19aa55d66228 72 "help": "options are ATMEL, MCR20, SPIRIT1, EFR32",
group-ublox 0:19aa55d66228 73 "value": "ATMEL"
group-ublox 0:19aa55d66228 74 }
group-ublox 0:19aa55d66228 75 }
group-ublox 0:19aa55d66228 76 ```
group-ublox 0:19aa55d66228 77
group-ublox 0:19aa55d66228 78 ## Using Easy Connect from your application
group-ublox 0:19aa55d66228 79
group-ublox 0:19aa55d66228 80 Easy Connect has just one function that returns either a `NetworkInterface`-pointer or `NULL`:
group-ublox 0:19aa55d66228 81
group-ublox 0:19aa55d66228 82 ```cpp
group-ublox 0:19aa55d66228 83 #include "easy-connect.h"
group-ublox 0:19aa55d66228 84
group-ublox 0:19aa55d66228 85 int main(int, char**) {
group-ublox 0:19aa55d66228 86 NetworkInterface* network = easy_connect(true); /* has 1 argument, enable_logging (pass in true to log to serial port) */
group-ublox 0:19aa55d66228 87 if (!network) {
group-ublox 0:19aa55d66228 88 printf("Connecting to the network failed... See serial output.\r\n");
group-ublox 0:19aa55d66228 89 return 1;
group-ublox 0:19aa55d66228 90 }
group-ublox 0:19aa55d66228 91
group-ublox 0:19aa55d66228 92 // Rest of your program
group-ublox 0:19aa55d66228 93 }
group-ublox 0:19aa55d66228 94 ```
group-ublox 0:19aa55d66228 95
group-ublox 0:19aa55d66228 96 ## Configuration examples
group-ublox 0:19aa55d66228 97
group-ublox 0:19aa55d66228 98 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.
group-ublox 0:19aa55d66228 99
group-ublox 0:19aa55d66228 100 ## Compilation error NanostackRfPhyAtmel.cpp
group-ublox 0:19aa55d66228 101
group-ublox 0:19aa55d66228 102 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.
group-ublox 0:19aa55d66228 103
group-ublox 0:19aa55d66228 104 ```
group-ublox 0:19aa55d66228 105 Scan: env
group-ublox 0:19aa55d66228 106 Compile [ 0.2%]: NanostackRfPhyAtmel.cpp
group-ublox 0:19aa55d66228 107 [Fatal Error] NanostackRfPhyAtmel.cpp@18,44: nanostack/platform/arm_hal_phy.h: No such file or directory
group-ublox 0:19aa55d66228 108 [ERROR] ./easy-connect/atmel-rf-driver/source/NanostackRfPhyAtmel.cpp:18:44: fatal error: nanostack/platform/arm_hal_phy.h: No such file or directory
group-ublox 0:19aa55d66228 109 #include "nanostack/platform/arm_hal_phy.h"
group-ublox 0:19aa55d66228 110 ^
group-ublox 0:19aa55d66228 111 compilation terminated.
group-ublox 0:19aa55d66228 112
group-ublox 0:19aa55d66228 113 ```
group-ublox 0:19aa55d66228 114
group-ublox 0:19aa55d66228 115 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.
group-ublox 0:19aa55d66228 116
group-ublox 0:19aa55d66228 117 ## Linking error with UBLOX_EVK_ODIN_W2
group-ublox 0:19aa55d66228 118
group-ublox 0:19aa55d66228 119 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`.
group-ublox 0:19aa55d66228 120
group-ublox 0:19aa55d66228 121 ```
group-ublox 0:19aa55d66228 122 Link: tls-client
group-ublox 0:19aa55d66228 123 ./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*)':
group-ublox 0:19aa55d66228 124 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
group-ublox 0:19aa55d66228 125 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
group-ublox 0:19aa55d66228 126 collect2: error: ld returned 1 exit status
group-ublox 0:19aa55d66228 127 [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*)':
group-ublox 0:19aa55d66228 128 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x46): undefined reference to `wifi_emac_get_interface()'
group-ublox 0:19aa55d66228 129 OdinWiFiInterface.cpp:(.text._ZN17OdinWiFiInterface26handle_wlan_status_startedEP21wlan_status_started_s+0x4c): undefined reference to `wifi_emac_init_mem()'
group-ublox 0:19aa55d66228 130 collect2: error: ld returned 1 exit status
group-ublox 0:19aa55d66228 131
group-ublox 0:19aa55d66228 132 [mbed] ERROR: "/usr/bin/python" returned error code 1.
group-ublox 0:19aa55d66228 133 ```
group-ublox 0:19aa55d66228 134
group-ublox 0:19aa55d66228 135 ## Network errors
group-ublox 0:19aa55d66228 136
group-ublox 0:19aa55d66228 137 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://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/network_sockets/#network-errors).
group-ublox 0:19aa55d66228 138
group-ublox 0:19aa55d66228 139 ## CR/LF in serial output
group-ublox 0:19aa55d66228 140
group-ublox 0:19aa55d66228 141 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`:
group-ublox 0:19aa55d66228 142
group-ublox 0:19aa55d66228 143 ```json
group-ublox 0:19aa55d66228 144 "target_overrides": {
group-ublox 0:19aa55d66228 145 "*": {
group-ublox 0:19aa55d66228 146 "platform.stdio-baud-rate": 115200,
group-ublox 0:19aa55d66228 147 "platform.stdio-convert-newlines": true
group-ublox 0:19aa55d66228 148 }
group-ublox 0:19aa55d66228 149 }
group-ublox 0:19aa55d66228 150 ```
group-ublox 0:19aa55d66228 151
group-ublox 0:19aa55d66228 152 ## Extra defines
group-ublox 0:19aa55d66228 153
group-ublox 0:19aa55d66228 154 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.