Maxim nexpaq / nexpaq_dev

Preliminary main mbed library for nexpaq development

features/net/FEATURE_IPV6/mbed-mesh-api/README.md@1:d96dbedaebdb, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:54:50 2016 +0000
Revision:
1:d96dbedaebdb
Parent:
0:6c56fb4bc5f0 
Removed extra directories for other platforms

Who changed what in which revision?

UserRevisionLine numberNew contents of line
nexpaq 0:6c56fb4bc5f0 1 # mbed mesh API
nexpaq 0:6c56fb4bc5f0 2
nexpaq 0:6c56fb4bc5f0 3 ARM mbed mesh API allows the client to use the IPv6 mesh network.
nexpaq 0:6c56fb4bc5f0 4
nexpaq 0:6c56fb4bc5f0 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.
nexpaq 0:6c56fb4bc5f0 6
nexpaq 0:6c56fb4bc5f0 7 ## Supported mesh networking modes
nexpaq 0:6c56fb4bc5f0 8
nexpaq 0:6c56fb4bc5f0 9 Currently, 6LoWPAN-ND (neighbour discovery) and Thread bootstrap modes are supported.
nexpaq 0:6c56fb4bc5f0 10
nexpaq 0:6c56fb4bc5f0 11 ## Module Configuration
nexpaq 0:6c56fb4bc5f0 12
nexpaq 0:6c56fb4bc5f0 13 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.
nexpaq 0:6c56fb4bc5f0 14
nexpaq 0:6c56fb4bc5f0 15 An example of the configuration file:
nexpaq 0:6c56fb4bc5f0 16
nexpaq 0:6c56fb4bc5f0 17 ```
nexpaq 0:6c56fb4bc5f0 18 {
nexpaq 0:6c56fb4bc5f0 19 "target_overrides": {
nexpaq 0:6c56fb4bc5f0 20 "*": {
nexpaq 0:6c56fb4bc5f0 21 "target.features_add": ["IPV6"],
nexpaq 0:6c56fb4bc5f0 22 "mbed-mesh-api.6lowpan-nd-channel": 12,
nexpaq 0:6c56fb4bc5f0 23 "mbed-mesh-api.6lowpan-nd-channel-mask": "(1<<12)",
nexpaq 0:6c56fb4bc5f0 24 "mbed-mesh-api.heap-size": 10000
nexpaq 0:6c56fb4bc5f0 25 }
nexpaq 0:6c56fb4bc5f0 26 }
nexpaq 0:6c56fb4bc5f0 27 }
nexpaq 0:6c56fb4bc5f0 28 ```
nexpaq 0:6c56fb4bc5f0 29
nexpaq 0:6c56fb4bc5f0 30 **Configurable parameters in section `mbed-mesh-api`:**
nexpaq 0:6c56fb4bc5f0 31
nexpaq 0:6c56fb4bc5f0 32 | Parameter name | Value | Description |
nexpaq 0:6c56fb4bc5f0 33 | --------------- | ------------- | ----------- |
nexpaq 0:6c56fb4bc5f0 34 | heap-size | number [0-0xfffe] | Nanostack's internal heap size |
nexpaq 0:6c56fb4bc5f0 35
nexpaq 0:6c56fb4bc5f0 36 **Thread related configuration parameters:**
nexpaq 0:6c56fb4bc5f0 37
nexpaq 0:6c56fb4bc5f0 38 | Parameter name | Value | Description |
nexpaq 0:6c56fb4bc5f0 39 | --------------- | ------------- | ----------- |
nexpaq 0:6c56fb4bc5f0 40 | thread-pskd | string [6-255 chars] | Human-scaled commissioning credentials. |
nexpaq 0:6c56fb4bc5f0 41 | hread-device-type | enum from mesh_device_type_t | Set device operating mode. |
nexpaq 0:6c56fb4bc5f0 42 | thread-config-channel-mask | number [0-0x07fff800] | Channel mask, 0x07fff800 scans all channels. |
nexpaq 0:6c56fb4bc5f0 43 | thread-config-channel-page | number [0, 2]| Channel page, 0 for 2,4 GHz and 2 for sub-GHz radios. |
nexpaq 0:6c56fb4bc5f0 44 | thread-config-channel | number [0-27] | RF channel to use. |
nexpaq 0:6c56fb4bc5f0 45 | thread-config-panid | number [0-0xFFFF] | Network identifier. |
nexpaq 0:6c56fb4bc5f0 46 | thread-master-key | byte array [16]| Network master key. |
nexpaq 0:6c56fb4bc5f0 47 | thread-config-ml-prefix | byte array [8] | Mesh local prefix. |
nexpaq 0:6c56fb4bc5f0 48 | thread-config-pskc | byte array [16] | Pre-Shared Key for the Commissioner. |
nexpaq 0:6c56fb4bc5f0 49
nexpaq 0:6c56fb4bc5f0 50 **6LoWPAN related configuration parameters:**
nexpaq 0:6c56fb4bc5f0 51
nexpaq 0:6c56fb4bc5f0 52 | Parameter name | Type | Description |
nexpaq 0:6c56fb4bc5f0 53 | --------------- | ---------| ----------- |
nexpaq 0:6c56fb4bc5f0 54 | 6lowpan-nd-channel-mask | number [0-0x07fff800] | Channel mask, bit-mask of channels to use |
nexpaq 0:6c56fb4bc5f0 55 | 6lowpan-nd-channel-page | number [0, 2] | 0 for 2,4 GHz and 2 for sub-GHz radios |
nexpaq 0:6c56fb4bc5f0 56 | 6lowpan-nd-channel | number [0-27] | RF channel to use when `channel_mask` is not defined |
nexpaq 0:6c56fb4bc5f0 57 | 6lowpan-nd-security-mode | "NONE" or "PSK" | To use either no security, or Pre shared network key |
nexpaq 0:6c56fb4bc5f0 58 | 6lowpan-nd-psk-key-id | number | PSK key id when PSK is enabled |
nexpaq 0:6c56fb4bc5f0 59 | 6lowpan-nd-psk-key | byte array [16] | Pre shared network key |
nexpaq 0:6c56fb4bc5f0 60 | 6lowpan-nd-sec-level | number [1-7] | Network security level. Use default `5` |
nexpaq 0:6c56fb4bc5f0 61
nexpaq 0:6c56fb4bc5f0 62
nexpaq 0:6c56fb4bc5f0 63 ## Usage notes
nexpaq 0:6c56fb4bc5f0 64
nexpaq 0:6c56fb4bc5f0 65 This module should not be used directly by the applications. The applications should use the `LoWPANNDInterface` or `ThreadInterface` directly.
nexpaq 0:6c56fb4bc5f0 66
nexpaq 0:6c56fb4bc5f0 67 ### Network connection states
nexpaq 0:6c56fb4bc5f0 68
nexpaq 0:6c56fb4bc5f0 69 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`.
nexpaq 0:6c56fb4bc5f0 70
nexpaq 0:6c56fb4bc5f0 71 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.
nexpaq 0:6c56fb4bc5f0 72
nexpaq 0:6c56fb4bc5f0 73 ## Getting started
nexpaq 0:6c56fb4bc5f0 74
nexpaq 0:6c56fb4bc5f0 75 See the example application [mbed-os-example-mesh-minimal](https://github.com/ARMmbed/mbed-os-example-mesh-minimal) for usage.
nexpaq 0:6c56fb4bc5f0 76
nexpaq 0:6c56fb4bc5f0 77 ## Usage example for 6LoWPAN ND mode
nexpaq 0:6c56fb4bc5f0 78
nexpaq 0:6c56fb4bc5f0 79 **Create a network interface:**
nexpaq 0:6c56fb4bc5f0 80
nexpaq 0:6c56fb4bc5f0 81 ```
nexpaq 0:6c56fb4bc5f0 82 LoWPANNDInterface mesh;
nexpaq 0:6c56fb4bc5f0 83 ```
nexpaq 0:6c56fb4bc5f0 84
nexpaq 0:6c56fb4bc5f0 85 **Connect:**
nexpaq 0:6c56fb4bc5f0 86
nexpaq 0:6c56fb4bc5f0 87 ```
nexpaq 0:6c56fb4bc5f0 88 if (mesh.connect()) {
nexpaq 0:6c56fb4bc5f0 89 printf("Connection failed!\r\n");
nexpaq 0:6c56fb4bc5f0 90 return -1;
nexpaq 0:6c56fb4bc5f0 91 }
nexpaq 0:6c56fb4bc5f0 92
nexpaq 0:6c56fb4bc5f0 93 printf("connected. IP = %s\r\n", mesh.get_ip_address());
nexpaq 0:6c56fb4bc5f0 94 ```
nexpaq 0:6c56fb4bc5f0 95
nexpaq 0:6c56fb4bc5f0 96 ## Usage example for 6LoWPAN Thread mode
nexpaq 0:6c56fb4bc5f0 97
nexpaq 0:6c56fb4bc5f0 98 Basically the same as for ND, but the network interface uses different class:
nexpaq 0:6c56fb4bc5f0 99
nexpaq 0:6c56fb4bc5f0 100 ```
nexpaq 0:6c56fb4bc5f0 101 ThreadInterface mesh;
nexpaq 0:6c56fb4bc5f0 102 mesh.connect();
nexpaq 0:6c56fb4bc5f0 103 ```