Skip to content

Commit 5bc65ee

Browse files
jpellikk-armjpellikk-arm
committed
Merge branch 'documentation_update'
* documentation_update: minor edit Editorial changes. Updated the documentation.
2 parents a4620fb + 5d63213 commit 5bc65ee

File tree

2 files changed

+95
-3
lines changed

2 files changed

+95
-3
lines changed

‎README.md‎

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,94 @@
1-
# nanostack-border-router
2-
Nanostack Border Router implementation
1+
# Nanostack Border Router
2+
Nanostack Border Router is a yotta module that provides the 6LoWPAN mesh network (1 RF interface) and backhaul network (1 backhaul interface) connectivity. It is a building block for 3rd party border router applications that implement their own backhaul driver or use some 3rd party driver.
3+
4+
For an example of an application using the Nanostack Border Router module, see [FRDM-K64F border router](https://github.com/ARMmbed/k64f-border-router).
5+
6+
#### Configuring Nanostack Border Router
7+
Applications using the Nanostack Border Router should use a `config.json` file for configuration. The file should contain a *border-router* section under which the Nanostack Border Router specific configuration options are defined. The complete list of all configuration options can be found in the [config.json.example](config.json.example) file.
8+
9+
The minimum set of configuration options required are explained in the table below.
10+
11+
| Field | Description |
12+
|-------------------------------------|---------------------------------------------------------------|
13+
| backhaul-bootstrap-mode | Defines whether the manually configured backhaul prefix and default route are used, or whether they are learnt automatically via the IPv6 neighbor discovery. Allowed values are `NET_IPV_BOOTSTRAP_STATIC` and `NET_IPV_BOOTSTRAP_AUTONOMOUS`. |
14+
| backhaul-prefix | The IPv6 prefix (64 bits) assigned to and advertised on the backhaul interface. Example format: `fd00:1:2::` |
15+
| 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` |
16+
| 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` |
17+
| rf-channel | The wireless (6LoWPAN mesh network) radio channel the border router application listens to. |
18+
| 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`. |
19+
| psk-key | 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}` |
20+
| 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` |
21+
22+
An example of a yotta configuration file `config.json`:
23+
24+
```json
25+
{
26+
"border-router": {
27+
"security-mode": "PSK",
28+
"psk-key-id": 1,
29+
"psk-key": "{0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7, 0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf}",
30+
"backhaul-bootstrap-mode": "NET_IPV6_BOOTSTRAP_STATIC",
31+
"backhaul-prefix": "fd00:abcd::",
32+
"backhaul-default-route": "::/0",
33+
"backhaul-next-hop": "fe80::1",
34+
"rf-channel": 11,
35+
"multicast-addr": "ff05::4"
36+
}
37+
}
38+
```
39+
40+
#### Using Nanostack Border Router in your application
41+
To run a 6LoWPAN border router/gateway, your application needs to:
42+
43+
- Implement a callback for registering a backhaul network driver.
44+
- Call a start function to get your border router up and running.
45+
46+
```C
47+
/* Call this function after your application has been initialised */
48+
void start_border_router(void);
49+
50+
/* Implement this function; backhaul_driver_status_cb() must be called by your app or the backhaul driver */
51+
void backhaul_driver_init(void (*backhaul_driver_status_cb)(uint8_t, int8_t));
52+
```
53+
54+
Steps to create a border router application using the Nanostack Border Router module:
55+
56+
1. Call `ns_dyn_mem_init()` to set the heap size and a handler for memory errors for your application.
57+
58+
2. Set up the Nanostack tracing library.
59+
```C
60+
/* Initialize the tracing library */
61+
trace_init();
62+
63+
/* Define your printing function */
64+
set_trace_print_function(my_print_function);
65+
66+
/* Configure trace output for your taste */
67+
set_trace_config(TRACE_CARRIAGE_RETURN | ...);
68+
```
69+
70+
**Note**: These functions must be called before any Nanostack Border Router functions are called. For the detailed descriptions of the above Nanostack functions, pelase refer to [the Nanostack documentation](https://docs.mbed.com/docs/arm-ipv66lowpan-stack/en/latest/).
71+
72+
3. Call the `start_border_router()` function; Nanostack will call your `backhaul_driver_init()` function to register your backhaul driver.
73+
74+
4. Start the backhaul driver and invoke the `backhaul_driver_status_cb()` callback (performed by your code or the driver code).
75+
76+
For a complete application using Nanostack Border Router, please refer to [FRDM-K64F border router](https://github.com/ARMmbed/k64f-border-router).
77+
78+
#### The routing protocol RPL
79+
Nanostack Border Router uses [RPL](https://tools.ietf.org/html/rfc6550) as the routing protocol on the mesh network side (RF interface). Currently, only the `grounded/non-storing` operation mode is supported.
80+
81+
Nanostack Border Router offers the following yotta configuration options for RPL:
82+
83+
| Field | Description |
84+
|-------------------------------------|---------------------------------------------------------|
85+
| rpl-instance-id | The RPL instance ID value that identifies the RPL instance, default: 1 |
86+
| rpl-idoublings | RPL Trickle parameter: DIOIntervalDoublings value, default: 12 |
87+
| rpl-imin | RPL Trickle parameter: DIOIntervalMin value, default: 9 |
88+
| rpl-k | RPL Trickle parameter: the redundacy constant k, default: 10 |
89+
| rpl-max-rank-inc | Maximum rank increase value, default: 2048|
90+
| rpl-min-hop-rank-inc | Minimum rank increase value, default: 128 |
91+
| rpl-default-lifetime | Default lifetime for the RPL routes, default: 64 |
92+
| rpl-lifetime-unit | The value of the unit that describes the lifetime (in seconds), default: 60 |
93+
| rpl-pcs | The number of bits that may be allocated to the path control field. |
94+
| rpl-ocp | The Objective Function (OF) to use, values: 1=OF0 (default), 2=MRHOF |

‎config.json.example‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
"rpl-imin": 9, # RPL Trickle: DIOIntervalMin value
3434
"rpl-k": 10, # RPL Trickle: the redundacy constant k
3535
"rpl-max-rank-inc": 2048, # RPL: maximum rank increase
36-
"rpl-min-hop-rank-inc": 128, # RPL: minumum rank increase
36+
"rpl-min-hop-rank-inc": 128, # RPL: minimum rank increase
3737
"rpl-default-lifetime": 64, # RPL: default lifetime for the RPL routes
3838
"rpl-lifetime-unit": 60, # RPL: value of the unit the lifetime is described in
3939
"rpl-pcs": 1, # RPL: the number of bits that may be allocated to the path control field

0 commit comments

Comments
 (0)