Toyomasa Watarai / easy-connect-type-yd

Easily add all supported connectivity methods to your mbed OS project

Dependencies:   type-yd-driver

README.md@0:615f90842ce8, 2017-07-12 (annotated)

Committer:
MACRUM
Date:
Wed Jul 12 10:52:58 2017 +0000
Revision:
0:615f90842ce8
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MACRUM 0:615f90842ce8 1 # Easy Connect - Easily add all supported connectivity methods to your mbed OS project
MACRUM 0:615f90842ce8 2
MACRUM 0:615f90842ce8 3 Often you want to give users of your application the choice to switch between connectivity methods. The `NetworkInterface` API makes this easy, but you'll still need a mechanism for the user to chooce the method, throw in some `#define`'s, etc. Easy Connect handles all this for you. Just declare the desired connectivity method in your `mbed_app.json` file, and call `easy_connect()` from your application.
MACRUM 0:615f90842ce8 4
MACRUM 0:615f90842ce8 5 ## Specifying connectivity method
MACRUM 0:615f90842ce8 6
MACRUM 0:615f90842ce8 7 Add the following to your ``mbed_app.json`` file:
MACRUM 0:615f90842ce8 8
MACRUM 0:615f90842ce8 9 ```json
MACRUM 0:615f90842ce8 10 {
MACRUM 0:615f90842ce8 11 "config": {
MACRUM 0:615f90842ce8 12 "network-interface":{
MACRUM 0:615f90842ce8 13 "help": "options are ETHERNET,WIFI_ESP8266,WIFI_ODIN,MESH_LOWPAN_ND,MESH_THREAD",
MACRUM 0:615f90842ce8 14 "value": "ETHERNET"
MACRUM 0:615f90842ce8 15 }
MACRUM 0:615f90842ce8 16 },
MACRUM 0:615f90842ce8 17 "target_overrides": {
MACRUM 0:615f90842ce8 18 "*": {
MACRUM 0:615f90842ce8 19 "target.features_add": ["NANOSTACK", "LOWPAN_ROUTER", "COMMON_PAL"],
MACRUM 0:615f90842ce8 20 "mbed-mesh-api.6lowpan-nd-channel-page": 0,
MACRUM 0:615f90842ce8 21 "mbed-mesh-api.6lowpan-nd-channel": 12
MACRUM 0:615f90842ce8 22 }
MACRUM 0:615f90842ce8 23 }
MACRUM 0:615f90842ce8 24 }
MACRUM 0:615f90842ce8 25 ```
MACRUM 0:615f90842ce8 26 If you choose `ETHERNET` with `UBLOX_ODIN_EVK_W2` you must add this to your `target-overrides` section in `mbed_app.json`:
MACRUM 0:615f90842ce8 27 ```json
MACRUM 0:615f90842ce8 28 "UBLOX_EVK_ODIN_W2": {
MACRUM 0:615f90842ce8 29 "target.device_has_remove": ["EMAC"]
MACRUM 0:615f90842ce8 30 ```
MACRUM 0:615f90842ce8 31
MACRUM 0:615f90842ce8 32 If you choose `WIFI_ESP8266` or `WIFI_ODIN`, you'll also need to add the WiFi SSID and password:
MACRUM 0:615f90842ce8 33
MACRUM 0:615f90842ce8 34 ```json
MACRUM 0:615f90842ce8 35 "config": {
MACRUM 0:615f90842ce8 36 "network-interface":{
MACRUM 0:615f90842ce8 37 "help": "options are ETHERNET,WIFI_ESP8266,WIFI_ODIN,MESH_LOWPAN_ND,MESH_THREAD",
MACRUM 0:615f90842ce8 38 "value": "WIFI_ESP8266"
MACRUM 0:615f90842ce8 39 },
MACRUM 0:615f90842ce8 40 "esp8266-tx": {
MACRUM 0:615f90842ce8 41 "help": "Pin used as TX (connects to ESP8266 RX)",
MACRUM 0:615f90842ce8 42 "value": "PTD3"
MACRUM 0:615f90842ce8 43 },
MACRUM 0:615f90842ce8 44 "esp8266-rx": {
MACRUM 0:615f90842ce8 45 "help": "Pin used as RX (connects to ESP8266 TX)",
MACRUM 0:615f90842ce8 46 "value": "PTD2"
MACRUM 0:615f90842ce8 47 },
MACRUM 0:615f90842ce8 48 "esp8266-debug": {
MACRUM 0:615f90842ce8 49 "value": true
MACRUM 0:615f90842ce8 50 },
MACRUM 0:615f90842ce8 51 "wifi-ssid": {
MACRUM 0:615f90842ce8 52 "value": "\"SSID\""
MACRUM 0:615f90842ce8 53 },
MACRUM 0:615f90842ce8 54 "wifi-password": {
MACRUM 0:615f90842ce8 55 "value": "\"Password\""
MACRUM 0:615f90842ce8 56 }
MACRUM 0:615f90842ce8 57 }
MACRUM 0:615f90842ce8 58 ```
MACRUM 0:615f90842ce8 59
MACRUM 0:615f90842ce8 60 If you use `MESH_LOWPAN_ND` or `MESH_THREAD` you will need to specify your radio module:
MACRUM 0:615f90842ce8 61
MACRUM 0:615f90842ce8 62 ```json
MACRUM 0:615f90842ce8 63 "config": {
MACRUM 0:615f90842ce8 64 "network-interface":{
MACRUM 0:615f90842ce8 65 "help": "options are ETHERNET,WIFI_ESP8266,WIFI_ODIN,MESH_LOWPAN_ND,MESH_THREAD",
MACRUM 0:615f90842ce8 66 "value": "MESH_LOWPAN_ND"
MACRUM 0:615f90842ce8 67 },
MACRUM 0:615f90842ce8 68 "mesh_radio_type": {
MACRUM 0:615f90842ce8 69 "help": "options are ATMEL, MCR20, SPIRIT1",
MACRUM 0:615f90842ce8 70 "value": "ATMEL"
MACRUM 0:615f90842ce8 71 }
MACRUM 0:615f90842ce8 72 }
MACRUM 0:615f90842ce8 73 ```
MACRUM 0:615f90842ce8 74
MACRUM 0:615f90842ce8 75 ## Using Easy Connect from your application
MACRUM 0:615f90842ce8 76
MACRUM 0:615f90842ce8 77 Easy Connect has just one function which will either return a `NetworkInterface`-pointer or `NULL`:
MACRUM 0:615f90842ce8 78
MACRUM 0:615f90842ce8 79 ```cpp
MACRUM 0:615f90842ce8 80 #include "easy-connect.h"
MACRUM 0:615f90842ce8 81
MACRUM 0:615f90842ce8 82 int main(int, char**) {
MACRUM 0:615f90842ce8 83 NetworkInterface* network = easy_connect(true); /* has 1 argument, enable_logging (pass in true to log to serial port) */
MACRUM 0:615f90842ce8 84 if (!network) {
MACRUM 0:615f90842ce8 85 printf("Connecting to the network failed... See serial output.\r\n");
MACRUM 0:615f90842ce8 86 return 1;
MACRUM 0:615f90842ce8 87 }
MACRUM 0:615f90842ce8 88
MACRUM 0:615f90842ce8 89 // Rest of your program
MACRUM 0:615f90842ce8 90 }
MACRUM 0:615f90842ce8 91 ```
MACRUM 0:615f90842ce8 92 ## CR/LF in serial output
MACRUM 0:615f90842ce8 93
MACRUM 0:615f90842ce8 94 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:615f90842ce8 95
MACRUM 0:615f90842ce8 96 ```json
MACRUM 0:615f90842ce8 97 "target_overrides": {
MACRUM 0:615f90842ce8 98 "*": {
MACRUM 0:615f90842ce8 99 "platform.stdio-baud-rate": 115200,
MACRUM 0:615f90842ce8 100 "platform.stdio-convert-newlines": true
MACRUM 0:615f90842ce8 101 }
MACRUM 0:615f90842ce8 102 }
MACRUM 0:615f90842ce8 103 ```
MACRUM 0:615f90842ce8 104
MACRUM 0:615f90842ce8 105 ## Network errors
MACRUM 0:615f90842ce8 106
MACRUM 0:615f90842ce8 107 If easy-connect cannot connect to the network it returns a network error, with an error code. To see what these error code mean, see the [mbed OS Communication API](https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/communication/network_sockets/#network-errors).
MACRUM 0:615f90842ce8 108
MACRUM 0:615f90842ce8 109 ## Extra defines
MACRUM 0:615f90842ce8 110
MACRUM 0:615f90842ce8 111 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.