EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

features/nanostack/FEATURE_NANOSTACK/mbed-mesh-api/README.md@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

UserRevisionLine numberNew contents of line
be_bryan 0:b74591d5ab33 1 # mbed mesh API
be_bryan 0:b74591d5ab33 2
be_bryan 0:b74591d5ab33 3 ARM mbed mesh API allows the client to use the IPv6 mesh network.
be_bryan 0:b74591d5ab33 4
be_bryan 0:b74591d5ab33 5 The client can use the `LoWPANNDInterface` or `ThreadInterface` object for connecting to the mesh network and when successfully connected, the client can create a socket by using the [mbed C++ socket API](https://developer.mbed.org/teams/NetworkSocketAPI/code/NetworkSocketAPI/docs/tip/) to start communication with a remote peer.
be_bryan 0:b74591d5ab33 6
be_bryan 0:b74591d5ab33 7 For ethernet `NanostackEthernetInterface` is provided.
be_bryan 0:b74591d5ab33 8
be_bryan 0:b74591d5ab33 9 ## Supported mesh networking modes
be_bryan 0:b74591d5ab33 10
be_bryan 0:b74591d5ab33 11 Currently, 6LoWPAN-ND (neighbour discovery) and Thread bootstrap modes are supported.
be_bryan 0:b74591d5ab33 12
be_bryan 0:b74591d5ab33 13 ## Module Configuration
be_bryan 0:b74591d5ab33 14
be_bryan 0:b74591d5ab33 15 This module supports static configuration via **mbed configuration system** by using the `mbed_app.json` file. The application needs to create the configuration file if it wants to use other than default settings.
be_bryan 0:b74591d5ab33 16
be_bryan 0:b74591d5ab33 17 An example of the configuration file:
be_bryan 0:b74591d5ab33 18
be_bryan 0:b74591d5ab33 19 ```
be_bryan 0:b74591d5ab33 20 {
be_bryan 0:b74591d5ab33 21 "target_overrides": {
be_bryan 0:b74591d5ab33 22 "*": {
be_bryan 0:b74591d5ab33 23 "target.features_add": ["IPV6"],
be_bryan 0:b74591d5ab33 24 "mbed-mesh-api.6lowpan-nd-channel": 12,
be_bryan 0:b74591d5ab33 25 "mbed-mesh-api.6lowpan-nd-channel-mask": "(1<<12)",
be_bryan 0:b74591d5ab33 26 "mbed-mesh-api.heap-size": 10000
be_bryan 0:b74591d5ab33 27 }
be_bryan 0:b74591d5ab33 28 }
be_bryan 0:b74591d5ab33 29 }
be_bryan 0:b74591d5ab33 30 ```
be_bryan 0:b74591d5ab33 31
be_bryan 0:b74591d5ab33 32 ### Configurable parameters in section mbed-mesh-api
be_bryan 0:b74591d5ab33 33
be_bryan 0:b74591d5ab33 34 | Parameter name | Value | Description |
be_bryan 0:b74591d5ab33 35 | --------------- | ------------- | ----------- |
be_bryan 0:b74591d5ab33 36 | heap-size | number [0-0xfffe] | Nanostack's internal heap size |
be_bryan 0:b74591d5ab33 37 | use-malloc-for-heap | `false` or `true` | Use `malloc()` for reserving the internal heap. Default: `false` |
be_bryan 0:b74591d5ab33 38
be_bryan 0:b74591d5ab33 39 ### Thread related configuration parameters
be_bryan 0:b74591d5ab33 40
be_bryan 0:b74591d5ab33 41 | Parameter name | Value | Description |
be_bryan 0:b74591d5ab33 42 | --------------- | ------------- | ----------- |
be_bryan 0:b74591d5ab33 43 | thread-pskd | string [6-255 chars] | Human-scaled commissioning credentials. |
be_bryan 0:b74591d5ab33 44 | thread-use-static-link-config | boolean | True: Use the below link config, False: Use commissioning, ignore the below link config. |
be_bryan 0:b74591d5ab33 45 | thread-device-type | enum from mesh_device_type_t | Supported device operating modes: MESH_DEVICE_TYPE_THREAD_ROUTER, MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE, MESH_DEVICE_TYPE_THREAD_MINIMAL_END_DEVICE |
be_bryan 0:b74591d5ab33 46 | thread-config-channel-mask | number [0-0x07fff800] | Channel mask, 0x07fff800 scans all channels. |
be_bryan 0:b74591d5ab33 47 | thread-config-channel-page | number [0, 2]| Channel page, 0 for 2,4 GHz and 2 for sub-GHz radios. |
be_bryan 0:b74591d5ab33 48 | thread-config-channel | number [0-27] | RF channel to use. |
be_bryan 0:b74591d5ab33 49 | thread-config-panid | number [0-0xFFFF] | Network identifier. |
be_bryan 0:b74591d5ab33 50 | thread-config-network-name | string [1-16] |
be_bryan 0:b74591d5ab33 51 | thread-config-commissioning-dataset-timestamp | [0-0xFFFFFFFFFFFFFFFF] | [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] |
be_bryan 0:b74591d5ab33 52 |thread-config-extended-panid | byte array [8] | Extended PAN ID |
be_bryan 0:b74591d5ab33 53 | thread-master-key | byte array [16]| Network master key. |
be_bryan 0:b74591d5ab33 54 | thread-config-ml-prefix | byte array [8] | Mesh local prefix. |
be_bryan 0:b74591d5ab33 55 | thread-config-pskc | byte array [16] | Pre-Shared Key for the Commissioner. |
be_bryan 0:b74591d5ab33 56 | thread-security-policy | number [0-0xFF] | Commissioning security policy bits |
be_bryan 0:b74591d5ab33 57
be_bryan 0:b74591d5ab33 58 ### 6LoWPAN related configuration parameters
be_bryan 0:b74591d5ab33 59
be_bryan 0:b74591d5ab33 60 | Parameter name | Type | Description |
be_bryan 0:b74591d5ab33 61 | --------------- | ---------| ----------- |
be_bryan 0:b74591d5ab33 62 | 6lowpan-nd-channel-mask | number [0-0x07fff800] | Channel mask, bit-mask of channels to use |
be_bryan 0:b74591d5ab33 63 | 6lowpan-nd-channel-page | number [0, 2] | 0 for 2,4 GHz and 2 for sub-GHz radios |
be_bryan 0:b74591d5ab33 64 | 6lowpan-nd-channel | number [0-27] | RF channel to use when `channel_mask` is not defined |
be_bryan 0:b74591d5ab33 65 | 6lowpan-nd-panid-filter | number [0-0xffff] | Beacon PAN ID filter, 0xffff means no filtering |
be_bryan 0:b74591d5ab33 66 | 6lowpan-nd-security-mode | "NONE" or "PSK" | To use either no security, or Pre shared network key |
be_bryan 0:b74591d5ab33 67 | 6lowpan-nd-psk-key-id | number | PSK key id when PSK is enabled |
be_bryan 0:b74591d5ab33 68 | 6lowpan-nd-psk-key | byte array [16] | Pre shared network key |
be_bryan 0:b74591d5ab33 69 | 6lowpan-nd-sec-level | number [1-7] | Network security level. Use default `5` |
be_bryan 0:b74591d5ab33 70 | 6lowpan-nd-device-type | "NET_6LOWPAN_ROUTER" or "NET_6LOWPAN_HOST" | Device mode. Router is routing packets from other device, creating a mesh network. |
be_bryan 0:b74591d5ab33 71
be_bryan 0:b74591d5ab33 72 ## Usage notes
be_bryan 0:b74591d5ab33 73
be_bryan 0:b74591d5ab33 74 This module should not be used directly by the applications. The applications should use the `LoWPANNDInterface`, `ThreadInterface` or `NanostackEthernetInterface` directly.
be_bryan 0:b74591d5ab33 75
be_bryan 0:b74591d5ab33 76 When using Ethernet interface, there is no configuration options available. It is using dynamic mode to learn the IPv6 prefix from the network. No static configuration is supported.
be_bryan 0:b74591d5ab33 77
be_bryan 0:b74591d5ab33 78 ### Network connection states
be_bryan 0:b74591d5ab33 79
be_bryan 0:b74591d5ab33 80 After the initialization, the network state is `MESH_DISCONNECTED`. After a successful connection, the state changes to `MESH_CONNECTED` and when disconnected from the network the state is changed back to `MESH_DISCONNECTED`.
be_bryan 0:b74591d5ab33 81
be_bryan 0:b74591d5ab33 82 In case of connection errors, the state is changed to some of the connection error states. In an error state, there is no need to make a `disconnect` request and the client is allowed to attempt connecting again.
be_bryan 0:b74591d5ab33 83
be_bryan 0:b74591d5ab33 84 ## Getting started
be_bryan 0:b74591d5ab33 85
be_bryan 0:b74591d5ab33 86 See the example application [mbed-os-example-mesh-minimal](https://github.com/ARMmbed/mbed-os-example-mesh-minimal) for usage.
be_bryan 0:b74591d5ab33 87
be_bryan 0:b74591d5ab33 88 ## Usage example for 6LoWPAN ND mode
be_bryan 0:b74591d5ab33 89
be_bryan 0:b74591d5ab33 90 Create a network interface and driver objects.
be_bryan 0:b74591d5ab33 91
be_bryan 0:b74591d5ab33 92 ```
be_bryan 0:b74591d5ab33 93 LoWPANNDInterface mesh;
be_bryan 0:b74591d5ab33 94 NanostackRfPhyNcs36510 rf_phy;
be_bryan 0:b74591d5ab33 95 ```
be_bryan 0:b74591d5ab33 96
be_bryan 0:b74591d5ab33 97 Initialize interface with given PHY driver.
be_bryan 0:b74591d5ab33 98
be_bryan 0:b74591d5ab33 99 ```
be_bryan 0:b74591d5ab33 100 mesh.initialize(&rf_phy);
be_bryan 0:b74591d5ab33 101 ```
be_bryan 0:b74591d5ab33 102
be_bryan 0:b74591d5ab33 103 Then connect to network:
be_bryan 0:b74591d5ab33 104
be_bryan 0:b74591d5ab33 105 ```
be_bryan 0:b74591d5ab33 106 if (mesh.connect()) {
be_bryan 0:b74591d5ab33 107 printf("Connection failed!\r\n");
be_bryan 0:b74591d5ab33 108 return -1;
be_bryan 0:b74591d5ab33 109 }
be_bryan 0:b74591d5ab33 110
be_bryan 0:b74591d5ab33 111 printf("connected. IP = %s\r\n", mesh.get_ip_address());
be_bryan 0:b74591d5ab33 112 ```
be_bryan 0:b74591d5ab33 113
be_bryan 0:b74591d5ab33 114 ## Usage example for 6LoWPAN Thread mode
be_bryan 0:b74591d5ab33 115
be_bryan 0:b74591d5ab33 116 Basically the same as for ND, but the network interface uses different class:
be_bryan 0:b74591d5ab33 117
be_bryan 0:b74591d5ab33 118 ```
be_bryan 0:b74591d5ab33 119 ThreadInterface mesh;
be_bryan 0:b74591d5ab33 120 mesh.connect();
be_bryan 0:b74591d5ab33 121 ```
be_bryan 0:b74591d5ab33 122
be_bryan 0:b74591d5ab33 123 ## Usage example with Ethernet
be_bryan 0:b74591d5ab33 124
be_bryan 0:b74591d5ab33 125 API is still the same, you just need to provide a driver that implements `NanostackEthernetPhy` API.
be_bryan 0:b74591d5ab33 126
be_bryan 0:b74591d5ab33 127 ```
be_bryan 0:b74591d5ab33 128 NanostackEthernetInterface eth;
be_bryan 0:b74591d5ab33 129 NanostackEthernetPhyK64F phy;
be_bryan 0:b74591d5ab33 130
be_bryan 0:b74591d5ab33 131 int main() {
be_bryan 0:b74591d5ab33 132 eth.initialize(&phy);
be_bryan 0:b74591d5ab33 133
be_bryan 0:b74591d5ab33 134 if (eth.connect()) {
be_bryan 0:b74591d5ab33 135 printf("Connection failed!\r\n");
be_bryan 0:b74591d5ab33 136 return -1;
be_bryan 0:b74591d5ab33 137 }
be_bryan 0:b74591d5ab33 138
be_bryan 0:b74591d5ab33 139 printf("connected. IP = %s\r\n", eth.get_ip_address());
be_bryan 0:b74591d5ab33 140 }
be_bryan 0:b74591d5ab33 141 ```