mbed-os-examples / Mbed OS nanostack-border-router-mbed5

Nanostack Border Router is a generic mbed border router implementation that provides the 6LoWPAN ND or Thread border router initialization logic.

README.md@108:0c14bd1d3334, 2019-11-27 (annotated)

Committer:
mbed_official
Date:
Wed Nov 27 10:02:22 2019 +0000
Revision:
108:0c14bd1d3334
Parent:
105:d9f83743ed4f 
Fix conflicting declarations of main() (#197)



Update the main() to be compatible with the declaration from

platform/mbed_toolchain.h that adds the MBED_USED attribute.

Without the attribute the main() symbol is not emitted with the

GCC toolchain using "-Wl,--wrap,main" and "-flto" flags.

.

Commit copied from https://github.com/ARMmbed/nanostack-border-router

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 0:85f4174a8e29 1 # Nanostack Border Router
mbed_official 0:85f4174a8e29 2
mbed_official 104:bffd39796f7c 3 Nanostack Border Router is a generic Mbed border router implementation that provides the 6LoWPAN ND, Thread or Wi-SUN border router initialization logic.
mbed_official 90:74901a61be61 4
mbed_official 105:d9f83743ed4f 5 A border router is a network gateway between a wireless 6LoWPAN mesh network and a backhaul network. It controls and relays traffic between the two networks. In a typical setup, a 6LoWPAN border router is connected to another router in the backhaul network (over Ethernet, Cellular or a serial line) which in turn forwards traffic to and from the internet or a private company LAN, for instance.
mbed_official 0:85f4174a8e29 6
mbed_official 0:85f4174a8e29 7 ![](images/br_role.png)
mbed_official 0:85f4174a8e29 8
mbed_official 0:85f4174a8e29 9 ## Structure
mbed_official 0:85f4174a8e29 10
mbed_official 104:bffd39796f7c 11 This application runs on Mbed OS and uses PHY drivers and Nanostack to form a border router.
mbed_official 0:85f4174a8e29 12
mbed_official 0:85f4174a8e29 13 ![](images/structure.png)
mbed_official 0:85f4174a8e29 14
mbed_official 0:85f4174a8e29 15 The code layout is organized like this:
mbed_official 0:85f4174a8e29 16
mbed_official 0:85f4174a8e29 17 ```
mbed_official 0:85f4174a8e29 18 configs/ Contains example configuration files
mbed_official 0:85f4174a8e29 19 drivers/ Contains PHY drivers
mbed_official 104:bffd39796f7c 20 mbed-os/ Contains Mbed OS, itself
mbed_official 0:85f4174a8e29 21 source/ Contains the application code
mbed_official 0:85f4174a8e29 22 mbed_app.json Build time configuration file
mbed_official 0:85f4174a8e29 23 ```
mbed_official 0:85f4174a8e29 24
mbed_official 0:85f4174a8e29 25 ## Building
mbed_official 0:85f4174a8e29 26
mbed_official 0:85f4174a8e29 27 1. Clone this repository.
mbed_official 0:85f4174a8e29 28 1. Run `mbed deploy`.
mbed_official 104:bffd39796f7c 29 1. Add connectivity driver, if not provided by Mbed OS.
mbed_official 0:85f4174a8e29 30 1. Select target platform.
mbed_official 0:85f4174a8e29 31 1. Select toolchain.
mbed_official 0:85f4174a8e29 32 1. Configure.
mbed_official 0:85f4174a8e29 33 1. Build.
mbed_official 0:85f4174a8e29 34
mbed_official 0:85f4174a8e29 35 For example:
mbed_official 0:85f4174a8e29 36
mbed_official 0:85f4174a8e29 37 ```
mbed_official 0:85f4174a8e29 38 $ mbed deploy
mbed_official 0:85f4174a8e29 39
mbed_official 0:85f4174a8e29 40 $ mbed target K64F
mbed_official 0:85f4174a8e29 41 OR
mbed_official 0:85f4174a8e29 42 $ mbed target NUCLEO_F429ZI
mbed_official 0:85f4174a8e29 43
mbed_official 0:85f4174a8e29 44 $ mbed toolchain GCC_ARM
mbed_official 0:85f4174a8e29 45
mbed_official 0:85f4174a8e29 46 $ mbed compile
mbed_official 0:85f4174a8e29 47 ```
mbed_official 0:85f4174a8e29 48
mbed_official 75:ed8b10db9b5a 49 ### Adding connectivity driver
mbed_official 75:ed8b10db9b5a 50
mbed_official 104:bffd39796f7c 51 This application requires the 802.15.4 RF driver to be provided for the networking stack. The driver can be either external, or provided by Mbed OS.
mbed_official 75:ed8b10db9b5a 52
mbed_official 104:bffd39796f7c 53 You can add an external driver by calling:
mbed_official 75:ed8b10db9b5a 54
mbed_official 75:ed8b10db9b5a 55 ```
mbed_official 75:ed8b10db9b5a 56 mbed add <driver>
mbed_official 75:ed8b10db9b5a 57 ```
mbed_official 104:bffd39796f7c 58
mbed_official 104:bffd39796f7c 59 For example, STM Spirit1 RF driver is added by calling `mbed add stm-spirit1-rf-driver`
mbed_official 75:ed8b10db9b5a 60
mbed_official 0:85f4174a8e29 61 ## Selecting the target platform
mbed_official 0:85f4174a8e29 62
mbed_official 104:bffd39796f7c 63 The target platform is the hardware on which the border router runs. There are target platforms already available in Mbed OS.
mbed_official 0:85f4174a8e29 64
mbed_official 104:bffd39796f7c 65 To write your own target, follow the instructions in [Adding target support to Mbed OS 5](https://os.mbed.com/docs/mbed-os/latest/porting/porting-targets.html).
mbed_official 0:85f4174a8e29 66
mbed_official 85:7f1b82a282d7 67 The border router requires an RF driver to be provided for Nanostack. Currently, there are the following drivers available in the Mbed OS:
mbed_official 0:85f4174a8e29 68
mbed_official 104:bffd39796f7c 69 * [Atmel AT86RF233](https://github.com/ARMmbed/atmel-rf-driver).
mbed_official 104:bffd39796f7c 70 * [Atmel AT86RF212B](https://github.com/ARMmbed/atmel-rf-driver).
mbed_official 104:bffd39796f7c 71 * [NXP MCR20A](https://github.com/ARMmbed/mcr20a-rf-driver).
mbed_official 104:bffd39796f7c 72 * [STM-s2lp](https://github.com/ARMmbed/mbed-os/tree/master/components/802.15.4_RF).
mbed_official 85:7f1b82a282d7 73
mbed_official 85:7f1b82a282d7 74 Following external driver can be added as described [above](#adding-connectivity-driver):
mbed_official 85:7f1b82a282d7 75
mbed_official 104:bffd39796f7c 76 * [STM Spirit1](https://github.com/ARMmbed/stm-spirit1-rf-driver).
mbed_official 0:85f4174a8e29 77
mbed_official 105:d9f83743ed4f 78 The backhaul is either SLIP, Ethernet or Cellular. For Ethernet either an Mbed OS "EMAC" driver can be used, or a native Nanostack driver. Currently, native Nanostack drivers exists for the following backhauls:
mbed_official 65:92e581c01e8c 79
mbed_official 104:bffd39796f7c 80 * [K64F Ethernet](https://github.com/ARMmbed/sal-nanostack-driver-k64f-eth).
mbed_official 104:bffd39796f7c 81 * [SLIP driver](https://github.com/ARMmbed/sal-stack-nanostack-slip).
mbed_official 65:92e581c01e8c 82
mbed_official 104:bffd39796f7c 83 The existing drivers are in the `drivers/` folder. More drivers can be linked in.
mbed_official 0:85f4174a8e29 84
mbed_official 0:85f4174a8e29 85 See [Notes on different hardware](https://github.com/ARMmbed/mbed-os-example-mesh-minimal/blob/master/Hardware.md) to see known combinations that work.
mbed_official 0:85f4174a8e29 86
mbed_official 0:85f4174a8e29 87 ## Configuring Nanostack Border Router
mbed_official 0:85f4174a8e29 88
mbed_official 104:bffd39796f7c 89 Applications using Nanostack Border Router need to use a `.json` file for the configuration. You can find the example configurations in the `configs/` folder.
mbed_official 0:85f4174a8e29 90
mbed_official 0:85f4174a8e29 91 ### The backhaul configuration options
mbed_official 0:85f4174a8e29 92
mbed_official 0:85f4174a8e29 93 | Field | Description |
mbed_official 0:85f4174a8e29 94 |-------------------------------------|---------------------------------------------------------------|
mbed_official 0:85f4174a8e29 95 | `backhaul-dynamic-bootstrap` | Defines whether the manually configured backhaul prefix and default route are used, or whether they are learnt automatically via the IPv6 neighbor discovery. False means static and true means automatic configuration. |
mbed_official 0:85f4174a8e29 96 | `backhaul-prefix` | The IPv6 prefix (64 bits) assigned to and advertised on the backhaul interface. Example format: `fd00:1:2::` |
mbed_official 0:85f4174a8e29 97 | `backhaul-default-route` | The default route (prefix and prefix length) where packets should be forwarded on the backhaul device, default: `::/0`. Example format: `fd00:a1::/10` |
mbed_official 0:85f4174a8e29 98 | `backhaul-next-hop` | The next-hop value for the backhaul default route; should be a link-local address of a neighboring router, default: empty (on-link prefix). Example format: `fe80::1` |
mbed_official 22:8740285d8f09 99 | `backhaul-mld` | Enable sending Multicast Listener Discovery reports to backhaul network when a new multicast listener is registered in mesh network. Values: true or false |
mbed_official 0:85f4174a8e29 100
mbed_official 0:85f4174a8e29 101 ### 6LoWPAN ND border router options
mbed_official 0:85f4174a8e29 102
mbed_official 0:85f4174a8e29 103 | Field | Description |
mbed_official 0:85f4174a8e29 104 |-------------------------------------|---------------------------------------------------------------|
mbed_official 0:85f4174a8e29 105 | `security-mode` | The 6LoWPAN mesh network traffic (link layer) can be protected with the Private Shared Key (PSK) security mode, allowed values: `NONE` and `PSK`. |
mbed_official 0:85f4174a8e29 106 | `psk-key` | A 16-bytes long private shared key to be used when the security mode is PSK. Example format (hexadecimal byte values separated by commas inside brackets): `{0x00, ..., 0x0f}` |
mbed_official 0:85f4174a8e29 107 | `multicast-addr` | Multicast forwarding is supported by default. This defines the multicast address to which the border router application forwards multicast packets (on the backhaul and RF interface). Example format: `ff05::5` |
mbed_official 0:85f4174a8e29 108 |`ra-router-lifetime`|Defines the router advertisement interval in seconds (default 1024 if left out).|
mbed_official 0:85f4174a8e29 109 |`beacon-protocol-id`|Is used to identify beacons. This should not be changed (default 4 if left out).|
mbed_official 0:85f4174a8e29 110
mbed_official 104:bffd39796f7c 111 To learn more about 6LoWPAN and the configuration parameters, please read the [6LoWPAN overview](https://os.mbed.com/docs/latest/reference/mesh-tech.html).
mbed_official 0:85f4174a8e29 112
mbed_official 0:85f4174a8e29 113 See [configs/6lowpan_Atmel_RF.json](configs/6lowpan_Atmel_RF.json) for an example configuration file.
mbed_official 0:85f4174a8e29 114
mbed_official 0:85f4174a8e29 115 #### The routing protocol RPL (6LoWPAN ND)
mbed_official 0:85f4174a8e29 116
mbed_official 0:85f4174a8e29 117 Nanostack Border Router uses [RPL](https://tools.ietf.org/html/rfc6550) as the routing protocol on the mesh network side (RF interface) when in 6LoWPAN-ND mode. Currently, only the `grounded/non-storing` operation mode is supported.
mbed_official 0:85f4174a8e29 118
mbed_official 0:85f4174a8e29 119 Nanostack Border Router offers the following configuration options for RPL:
mbed_official 0:85f4174a8e29 120
mbed_official 0:85f4174a8e29 121 | Field | Description |
mbed_official 0:85f4174a8e29 122 |-------------------------------------|---------------------------------------------------------------|
mbed_official 0:85f4174a8e29 123 | rpl-instance-id | The RPL instance ID value that identifies the RPL instance, default: 1 |
mbed_official 0:85f4174a8e29 124 | rpl-idoublings | RPL Trickle parameter: DIOIntervalDoublings value, default: 12 |
mbed_official 0:85f4174a8e29 125 | rpl-imin | RPL Trickle parameter: DIOIntervalMin value, default: 9 |
mbed_official 0:85f4174a8e29 126 | rpl-k | RPL Trickle parameter: the redundacy constant k, default: 10 |
mbed_official 0:85f4174a8e29 127 | rpl-max-rank-inc | Maximum rank increase value, default: 2048|
mbed_official 0:85f4174a8e29 128 | rpl-min-hop-rank-inc | Minimum rank increase value, default: 128 |
mbed_official 0:85f4174a8e29 129 | rpl-default-lifetime | Default lifetime for the RPL routes, default: 64 |
mbed_official 0:85f4174a8e29 130 | rpl-lifetime-unit | The value of the unit that describes the lifetime (in seconds), default: 60 |
mbed_official 0:85f4174a8e29 131 | rpl-pcs | The number of bits that may be allocated to the path control field. |
mbed_official 0:85f4174a8e29 132 | rpl-ocp | The Objective Function (OF) to use, values: 1=OF0 (default), 2=MRHOF |
mbed_official 0:85f4174a8e29 133
mbed_official 0:85f4174a8e29 134 ### Thread configuration
mbed_official 0:85f4174a8e29 135
mbed_official 0:85f4174a8e29 136 The Thread-specific parameters are listed below.
mbed_official 0:85f4174a8e29 137
mbed_official 0:85f4174a8e29 138 | Field | Description |
mbed_official 0:85f4174a8e29 139 |-------------------------------------|---------------------------------------------------------------|
mbed_official 0:85f4174a8e29 140 | `commissioning-dataset-timestamp` | Used for updating the Thread network parameters. The device with the highest value propagates the parameters to the network (in the same Realm-Local scope). |
mbed_official 0:85f4174a8e29 141 | `pan-id` | 2-byte Personal Area Network ID. |
mbed_official 0:85f4174a8e29 142 | `extended-pan-id` | 8-byte value used to identify Thread networks in range. |
mbed_official 0:85f4174a8e29 143 | `mesh-local-prefix` | ULA prefix used for communication within the Thread network. |
mbed_official 0:85f4174a8e29 144 | `network-name` | A human-readable name for the network. |
mbed_official 104:bffd39796f7c 145 | `pskc` | Preshared Key for the commissioner. |
mbed_official 104:bffd39796f7c 146 | `pskd` | Preshared Key for the device. |
mbed_official 0:85f4174a8e29 147 | `thread-master-key` | A key used to derive security material for MAC and MLE protection. |
mbed_official 0:85f4174a8e29 148
mbed_official 90:74901a61be61 149 ### Wi-SUN configuration
mbed_official 90:74901a61be61 150
mbed_official 104:bffd39796f7c 151 The Wi-SUN specific parameters are listed below.
mbed_official 90:74901a61be61 152
mbed_official 90:74901a61be61 153 | Field | Description |
mbed_official 90:74901a61be61 154 |-------------------------------------|---------------------------------------------------------------|
mbed_official 90:74901a61be61 155 | `network-name` | Network name for Wi-SUN the network, MUST be same for all the devices in the network |
mbed_official 90:74901a61be61 156 | `regulatory-domain` | Defines regulatory domain, refer to [ws_management_api](https://github.com/ARMmbed/mbed-os/blob/master/features/nanostack/sal-stack-nanostack/nanostack/ws_management_api.h) for correct values for your region. |
mbed_official 90:74901a61be61 157 | `operating-class` | Defines operating class, limited by the regulatory domain |
mbed_official 90:74901a61be61 158 | `operating-mode` | Defines the operating mode, limited by the regulatory domain |
mbed_official 90:74901a61be61 159 | `uc-channel-function` | Unicast channel function |
mbed_official 90:74901a61be61 160 | `bc-channel-function` | Broadcast channel function |
mbed_official 90:74901a61be61 161 | `uc-fixed-channel` | Fixed channel for unicast |
mbed_official 90:74901a61be61 162 | `bc-fixed-channel` | Fixed channel for broadcast |
mbed_official 90:74901a61be61 163 | `uc-dwell-interval` | Unicast dwell interval. Range: 15-255 milliseconds |
mbed_official 90:74901a61be61 164 | `bc-interval` | Broadcast interval. Duration between broadcast dwell intervals. Range: 0-16777216 milliseconds |
mbed_official 90:74901a61be61 165 | `bc-dwell-interval` | Broadcast dwell interval. Range: 15-255 milliseconds |
mbed_official 94:0c008659750c 166 | `certificate-header` | Wi-SUN certificate header file |
mbed_official 94:0c008659750c 167 | `root-certificate` | Root certificate |
mbed_official 94:0c008659750c 168 | `own-certificate` | Own certificate |
mbed_official 94:0c008659750c 169 | `own-certificate-key` | Own certificate's key |
mbed_official 90:74901a61be61 170
mbed_official 90:74901a61be61 171 Regulatory domain, operating class and operating mode are defined in the Wi-SUN PHY-specification.
mbed_official 90:74901a61be61 172
mbed_official 0:85f4174a8e29 173
mbed_official 0:85f4174a8e29 174 For the Thread Border Router, there are example configuration files for `SLIP` and `ETH` backhaul connectivity:
mbed_official 0:85f4174a8e29 175
mbed_official 104:bffd39796f7c 176 * [configs/Thread_Atmel_RF.json](configs/Thread_Atmel_RF.json).
mbed_official 104:bffd39796f7c 177 * [configs/Thread_SLIP_Atmel_RF.json](configs/Thread_SLIP_Atmel_RF.json).
mbed_official 0:85f4174a8e29 178
mbed_official 104:bffd39796f7c 179 The [mbedtls_thread_config.h](source/mbedtls_thread_config.h) file configures Mbed TLS for Thread use.
mbed_official 0:85f4174a8e29 180
mbed_official 0:85f4174a8e29 181 <span class="notes">**Note:** The configuration examples are for testing purposes only; do not use them for production or expose them.</span>
mbed_official 0:85f4174a8e29 182
mbed_official 0:85f4174a8e29 183 #### Backhaul connectivity
mbed_official 0:85f4174a8e29 184
mbed_official 105:d9f83743ed4f 185 The Nanostack border router application can be connected to a backhaul network. This enables you to connect the devices in a 6LoWPAN mesh network to the internet or a private LAN. The application supports SLIP (IPv6 encapsulation over a serial line), Ethernet and Cellular backhaul connectivity:
mbed_official 0:85f4174a8e29 186
mbed_official 0:85f4174a8e29 187 ```
mbed_official 0:85f4174a8e29 188 "config": {
mbed_official 0:85f4174a8e29 189 "backhaul-driver": {
mbed_official 105:d9f83743ed4f 190 "help": "options are ETH, SLIP, EMAC, CELL",
mbed_official 85:7f1b82a282d7 191 "value": "EMAC"
mbed_official 0:85f4174a8e29 192 },
mbed_official 0:85f4174a8e29 193 "backhaul-mac-src": {
mbed_official 0:85f4174a8e29 194 "help": "Where to get EUI48 address. Options are BOARD, CONFIG",
mbed_official 0:85f4174a8e29 195 "value": "BOARD"
mbed_official 0:85f4174a8e29 196 },
mbed_official 0:85f4174a8e29 197 "backhaul-mac": "{0x02, 0x00, 0x00, 0x00, 0x00, 0x01}",
mbed_official 0:85f4174a8e29 198 "backhaul-dynamic-bootstrap": true,
mbed_official 0:85f4174a8e29 199 "backhaul-prefix": "\"fd00:300::\"",
mbed_official 0:85f4174a8e29 200 "backhaul-next-hop": "\"fe80::1\"",
mbed_official 0:85f4174a8e29 201 "backhaul-default-route": "\"::/0\"",
mbed_official 0:85f4174a8e29 202 .............
mbed_official 0:85f4174a8e29 203 }
mbed_official 0:85f4174a8e29 204 ```
mbed_official 0:85f4174a8e29 205
mbed_official 105:d9f83743ed4f 206 You can select your preferred option through the configuration file (field `backhaul-driver` in the `config` section). The value `SLIP` includes the SLIP driver, and the value `ETH` compiles the border router application with Nanostack native Ethernet backhaul support. `EMAC` uses the board's default Mbed OS network driver, which must be EMAC-based (derived from EMACInterface). `CELL` uses the boards's default Mbed OS cellular device or external cellular device that is configured to provide the default cellular device.
mbed_official 65:92e581c01e8c 207
mbed_official 85:7f1b82a282d7 208 You can define the MAC address on the backhaul interface manually (field `backhaul-mac-src` value `CONFIG`). Alternatively, you can use the MAC address provided by the development board (field `backhaul-mac-src` value `BOARD`). By default, the backhaul driver is set to `EMAC` and the MAC address source is `BOARD`.
mbed_official 0:85f4174a8e29 209
mbed_official 0:85f4174a8e29 210 You can also set the backhaul bootstrap mode (field `backhaul-dynamic-bootstrap`). By default, the bootstrap mode is set to true, which means the autonomous mode. With the autonomous mode, the border router learns the prefix information automatically from an IPv6 gateway in the Ethernet/SLIP segment. When the parameter is set to false, it enables you to set up a manual configuration of `backhaul-prefix` and `backhaul-default-route`.
mbed_official 0:85f4174a8e29 211
mbed_official 0:85f4174a8e29 212 If you use the static bootstrap mode, you need to configure a default route on the backhaul interface to properly forward packets between the backhaul and the 6LoWPAN mesh network. In addition to this, you need to set a backhaul prefix. The static mode creates a site-local IPv6 network from which packets cannot be routed outside.
mbed_official 0:85f4174a8e29 213
mbed_official 0:85f4174a8e29 214 When using the autonomous mode in the 6LoWPAN ND configuration, you can set the `prefix-from-backhaul` option to `true` to use the same backhaul prefix on the mesh network side as well. This allows the mesh nodes to be directly connectable from the outside of the mesh network. In the Thread network, it is enough that `backhaul-dynamic-bootstrap` is set to true.
mbed_official 0:85f4174a8e29 215
mbed_official 105:d9f83743ed4f 216 For `CELL` backhaul, no configuration options for addresses are provided. Cellular backhaul device works always in autonomous mode and the border router learns the IPv6 prefix information from the cellular access.
mbed_official 105:d9f83743ed4f 217
mbed_official 0:85f4174a8e29 218 #### Note on the SLIP backhaul driver
mbed_official 0:85f4174a8e29 219
mbed_official 104:bffd39796f7c 220 If you are using a K64F board, use the UART1 serial line of the board with the SLIP driver. See the `pins` section in the [mbed_app.json](./mbed_app.json) configuration file. To use a different UART line, replace the `SERIAL_TX` and `SERIAL_RX` values with correct TX/RX pin names.
mbed_official 0:85f4174a8e29 221
mbed_official 104:bffd39796f7c 222 To use the hardware flow control, set the configuration field `slip_hw_flow_control` to true. By default, it is set to false. Before using hardware flow control, make sure the other end of your SLIP interface can handle the flow control.
mbed_official 0:85f4174a8e29 223
mbed_official 0:85f4174a8e29 224 For the pin names of your desired UART line, refer to your development board's documentation.
mbed_official 0:85f4174a8e29 225
mbed_official 0:85f4174a8e29 226 An example configuration for the SLIP driver:
mbed_official 0:85f4174a8e29 227
mbed_official 0:85f4174a8e29 228 ```
mbed_official 0:85f4174a8e29 229 "target_overrides": {
mbed_official 0:85f4174a8e29 230 "K64F": {
mbed_official 0:85f4174a8e29 231 "SERIAL_TX": "PTE0",
mbed_official 0:85f4174a8e29 232 "SERIAL_RX": "PTE1",
mbed_official 0:85f4174a8e29 233 "SERIAL_CTS": "PTE2",
mbed_official 0:85f4174a8e29 234 "SERIAL_RTS": "PTE3"
mbed_official 0:85f4174a8e29 235 }
mbed_official 0:85f4174a8e29 236 ```
mbed_official 0:85f4174a8e29 237
mbed_official 65:92e581c01e8c 238 #### Note on EMAC backhaul
mbed_official 65:92e581c01e8c 239
mbed_official 104:bffd39796f7c 240 When `backhaul_driver` is set to `EMAC`, the border router uses the target's default network driver, as supplied by `NetworkInterface::get_default_instance`. This must be EMAC-based, derived from EMACInterface. If it is the same driver that a default-constructed `EthernetInterface` would use, so in principle it should work on any board where `EthernetInterface` works.
mbed_official 65:92e581c01e8c 241
mbed_official 104:bffd39796f7c 242 To use a different interface, change the setting of `target.default-network-interface-type` in `mbed_app.json` to point to a different interface type, or add an overriding definition of `NetworkInterface::get_default_instance` to the application - this overrides any default supplied by the target board.
mbed_official 65:92e581c01e8c 243
mbed_official 104:bffd39796f7c 244 To use Wi-Fi or other more complex EMAC drivers, necessary configuration parameters must be supplied, either using `mbed_app.json` or configuration in the `NetworkInterface::get_default_instance` override. Also, the driver must follow the guidelines of `EMACInterface` - the border router does not call the `EMACInterface`'s `connect` method, so the driver must work with only a `powerup` call to the `EMAC`.
mbed_official 65:92e581c01e8c 245
mbed_official 105:d9f83743ed4f 246 #### Note on CELL backhaul
mbed_official 105:d9f83743ed4f 247
mbed_official 105:d9f83743ed4f 248 When `backhaul_driver` is set to `CELL`, the border router will use the target's default cellular device, as supplied by `CellularInterface::get_default_instance`. Cellular device must support IPv6 PPP connection mode. Board must supply the default Mbed OS cellular device or there must be an external cellular device that is configured to provide default cellular device to Mbed OS.
mbed_official 105:d9f83743ed4f 249
mbed_official 0:85f4174a8e29 250 ### Switching the RF shield
mbed_official 0:85f4174a8e29 251
mbed_official 0:85f4174a8e29 252 By default, the application uses an Atmel AT86RF233/212B RF driver. You can alternatively use any RF driver provided in the `drivers/` folder or link in your own driver. You can set the configuration for the RF driver in the `json` file.
mbed_official 0:85f4174a8e29 253
mbed_official 104:bffd39796f7c 254 To select the Atmel radio shield, use:
mbed_official 0:85f4174a8e29 255
mbed_official 0:85f4174a8e29 256 ```
mbed_official 0:85f4174a8e29 257 "radio-type":{
mbed_official 90:74901a61be61 258 "help": "options are ATMEL, MCR20, SPIRIT1, S2LP",
mbed_official 0:85f4174a8e29 259 "value": "ATMEL"
mbed_official 0:85f4174a8e29 260 },
mbed_official 0:85f4174a8e29 261 ```
mbed_official 0:85f4174a8e29 262
mbed_official 104:bffd39796f7c 263 To select the NXP radio shield, use:
mbed_official 0:85f4174a8e29 264
mbed_official 0:85f4174a8e29 265 ```
mbed_official 0:85f4174a8e29 266 "radio-type":{
mbed_official 90:74901a61be61 267 "help": "options are ATMEL, MCR20, SPIRIT1, S2LP",
mbed_official 0:85f4174a8e29 268 "value": "MCR20"
mbed_official 0:85f4174a8e29 269 },
mbed_official 0:85f4174a8e29 270 ```
mbed_official 0:85f4174a8e29 271
mbed_official 104:bffd39796f7c 272 To select the STM Spirit1 radio shield, use:
mbed_official 0:85f4174a8e29 273
mbed_official 0:85f4174a8e29 274 ```
mbed_official 0:85f4174a8e29 275 "radio-type":{
mbed_official 90:74901a61be61 276 "help": "options are ATMEL, MCR20, SPIRIT1, S2LP",
mbed_official 0:85f4174a8e29 277 "value": "SPIRIT1"
mbed_official 0:85f4174a8e29 278 },
mbed_official 0:85f4174a8e29 279 ```
mbed_official 0:85f4174a8e29 280
mbed_official 104:bffd39796f7c 281 To select the STM S2LP radio shield, use:
mbed_official 104:bffd39796f7c 282
mbed_official 90:74901a61be61 283 ```
mbed_official 90:74901a61be61 284 "radio-type":{
mbed_official 90:74901a61be61 285 "help": "options are ATMEL, MCR20, SPIRIT1, S2LP",
mbed_official 90:74901a61be61 286 "value": "S2LP"
mbed_official 90:74901a61be61 287 },
mbed_official 90:74901a61be61 288 ```
mbed_official 90:74901a61be61 289
mbed_official 104:bffd39796f7c 290 If you have chosen the STM Spirit1 Sub-1 GHz RF expansion board [X-NUCLEO-IDS01A4](https://github.com/ARMmbed/stm-spirit1-rf-driver), you need to configure its MAC address in the `mbed_app.json` file. For example:
mbed_official 0:85f4174a8e29 291
mbed_official 0:85f4174a8e29 292 ```json
mbed_official 0:85f4174a8e29 293 "target_overrides": {
mbed_official 0:85f4174a8e29 294 "*": {
mbed_official 0:85f4174a8e29 295 "spirit1.mac-address": "{0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7}"
mbed_official 0:85f4174a8e29 296 },
mbed_official 0:85f4174a8e29 297 }
mbed_official 0:85f4174a8e29 298 ```
mbed_official 0:85f4174a8e29 299
mbed_official 85:7f1b82a282d7 300 <span class="notes">**Note**: This MAC address must be unique within the 6LoWPAN mesh network.</span>
mbed_official 0:85f4174a8e29 301
mbed_official 104:bffd39796f7c 302 After changing the radio shield, recompile the application.
mbed_official 0:85f4174a8e29 303
mbed_official 90:74901a61be61 304 #### Wi-SUN RF shield
mbed_official 90:74901a61be61 305
mbed_official 104:bffd39796f7c 306 Currently, only one radio shield, the STM S2LP radio shield, supports Wi-SUN.
mbed_official 90:74901a61be61 307
mbed_official 65:92e581c01e8c 308 ## File system support
mbed_official 65:92e581c01e8c 309
mbed_official 104:bffd39796f7c 310 The application can use the file system as instructed in [Mbed OS storage documentation](https://os.mbed.com/docs/latest/reference/storage.html). The file system is not enabled by default due to a variety of possible configurations.
mbed_official 65:92e581c01e8c 311
mbed_official 104:bffd39796f7c 312 Thread network stack is able to write and read network configuration settings to and from the file system after the feature is activated. Activation happens by telling the file system the root path to Nanostack. To set the root path, use the function:
mbed_official 65:92e581c01e8c 313
mbed_official 65:92e581c01e8c 314 `ns_file_system_set_root_path(root-path)`
mbed_official 65:92e581c01e8c 315
mbed_official 104:bffd39796f7c 316 After you have set the root path, Thread stack reads the configuration settings from the file system. Thread stack writes the configuration back to the file system after the configuration changes.
mbed_official 65:92e581c01e8c 317
mbed_official 0:85f4174a8e29 318 ## Running the border router application
mbed_official 0:85f4174a8e29 319
mbed_official 0:85f4174a8e29 320 1. Find the binary file `nanostack-border-router.bin` in the `BUILD` folder.
mbed_official 0:85f4174a8e29 321 2. Copy the binary to the USB mass storage root of the development board. It is automatically flashed to the target MCU. When the flashing is complete, the board restarts itself. Press the **Reset** button of the development board if it does not restart automatically.
mbed_official 0:85f4174a8e29 322 3. The program begins execution.
mbed_official 0:85f4174a8e29 323 4. Open the [serial connection](#serial-connection-settings), for example PuTTY.
mbed_official 0:85f4174a8e29 324
mbed_official 0:85f4174a8e29 325 ## Serial connection settings
mbed_official 0:85f4174a8e29 326
mbed_official 0:85f4174a8e29 327 Serial connection settings for the Nanorouter are as follows:
mbed_official 0:85f4174a8e29 328
mbed_official 104:bffd39796f7c 329 * Baud-rate = 115200.
mbed_official 104:bffd39796f7c 330 * Data bits = 8.
mbed_official 104:bffd39796f7c 331 * Stop bits = 1.
mbed_official 0:85f4174a8e29 332
mbed_official 0:85f4174a8e29 333 If there is no input from the serial terminal, press the **Reset** button of the development board.
mbed_official 0:85f4174a8e29 334
mbed_official 104:bffd39796f7c 335 In the PuTTY main screen, save the session, and click **Open**. This opens a console window showing debug messages from the application. If the console screen is blank, you may need to press the **Reset** button of the board to see the debug information. The serial output from the 6LoWPAN border router looks something like this in the console:
mbed_official 0:85f4174a8e29 336
mbed_official 0:85f4174a8e29 337 ```
mbed_official 0:85f4174a8e29 338 [INFO][app ]: Starting Nanostack border router...
mbed_official 0:85f4174a8e29 339 [INFO][brro]: NET_IPV6_BOOTSTRAP_AUTONOMOUS
mbed_official 0:85f4174a8e29 340 [INFO][app ]: Using ETH backhaul driver...
mbed_official 0:85f4174a8e29 341 [INFO][Eth ]: Ethernet cable is connected.
mbed_official 0:85f4174a8e29 342 [INFO][addr]: Tentative Address added to IF 1: fe80::ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 343 [INFO][addr]: DAD passed on IF 1: fe80::ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 344 [INFO][addr]: Tentative Address added to IF 1: 2001:999:21:9ce:ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 345 [INFO][addr]: DAD passed on IF 1: 2001:999:21:9ce:ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 346 [INFO][brro]: Backhaul bootstrap ready, IPv6 = 2001:999:21:9ce:ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 347 [INFO][brro]: Backhaul interface addresses:
mbed_official 0:85f4174a8e29 348 [INFO][brro]: [0] fe80::ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 349 [INFO][brro]: [1] 2001:999:21:9ce:ac41:dcff:fe37:72c4
mbed_official 0:85f4174a8e29 350 [INFO][addr]: Address added to IF 0: fe80::ff:fe00:face
mbed_official 0:85f4174a8e29 351 [INFO][br ]: BR nwk base ready for start
mbed_official 0:85f4174a8e29 352 [INFO][br ]: Refresh Contexts
mbed_official 0:85f4174a8e29 353 [INFO][br ]: Refresh Prefixs
mbed_official 0:85f4174a8e29 354 [INFO][addr]: Address added to IF 0: 2001:999:21:9ce:0:ff:fe00:face
mbed_official 0:85f4174a8e29 355 [INFO][addr]: Address added to IF 0: fe80::fec2:3d00:4:a0cd
mbed_official 0:85f4174a8e29 356 [INFO][brro]: RF bootstrap ready, IPv6 = 2001:999:21:9ce:0:ff:fe00:face
mbed_official 0:85f4174a8e29 357 [INFO][brro]: RF interface addresses:
mbed_official 0:85f4174a8e29 358 [INFO][brro]: [0] fe80::ff:fe00:face
mbed_official 0:85f4174a8e29 359 [INFO][brro]: [1] fe80::fec2:3d00:4:a0cd
mbed_official 0:85f4174a8e29 360 [INFO][brro]: [2] 2001:999:21:9ce:0:ff:fe00:face
mbed_official 0:85f4174a8e29 361 [INFO][brro]: 6LoWPAN Border Router Bootstrap Complete.
mbed_official 0:85f4174a8e29 362 ```
mbed_official 65:92e581c01e8c 363