Lee Kai Xuan / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of mbed-os by erkin yucel

features/nanostack/FEATURE_NANOSTACK/sal-stack-nanostack/docs/thread_APIs.md@1:3deb71413561, 2017-07-20 (annotated)

Committer:
xuaner
Date:
Thu Jul 20 14:26:57 2017 +0000
Revision:
1:3deb71413561
Parent:
0:f269e3021894 
mbed_os

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 # Thread APIs
elessair 0:f269e3021894 2
elessair 0:f269e3021894 3 ## API Headers
elessair 0:f269e3021894 4
elessair 0:f269e3021894 5 To manage Thread, include the following headers into your application:
elessair 0:f269e3021894 6
elessair 0:f269e3021894 7 ```
elessair 0:f269e3021894 8 #include thread_commissioning_api.h
elessair 0:f269e3021894 9 #include thread_management_api.h
elessair 0:f269e3021894 10 ```
elessair 0:f269e3021894 11
elessair 0:f269e3021894 12 The subsequent sections describe API functionality for Thread. To understand the ideas behind Thread, read [ARM mbed Thread Stack Overview](thread_overview.md).
elessair 0:f269e3021894 13
elessair 0:f269e3021894 14 ## Thread Commissioning API
elessair 0:f269e3021894 15
elessair 0:f269e3021894 16 Thread Commissioning API is used for enabling the Thread commissioning process.
elessair 0:f269e3021894 17
elessair 0:f269e3021894 18 ### Registering a commissioner candidate
elessair 0:f269e3021894 19
elessair 0:f269e3021894 20 If the Border Router or a Commissioner Router interface is up in the network, a Thread commissioner candidate can begin to register with the network.
elessair 0:f269e3021894 21
elessair 0:f269e3021894 22 To start the registration process:
elessair 0:f269e3021894 23
elessair 0:f269e3021894 24 ```
elessair 0:f269e3021894 25 int commissioning_register(uint8_t interface_id);
elessair 0:f269e3021894 26 ```
elessair 0:f269e3021894 27 Parameter|Description
elessair 0:f269e3021894 28 ---------|-----------
elessair 0:f269e3021894 29 `interface_id`|The interface ID of the commissioner candidate.
elessair 0:f269e3021894 30
elessair 0:f269e3021894 31 <dl>
elessair 0:f269e3021894 32 <dt>Response</dt>
elessair 0:f269e3021894 33 <dd>-1, if a commissioner exists already.</dd>
elessair 0:f269e3021894 34 <dd>-2, if failed to create a commissioner, interface does not exist.</dd>
elessair 0:f269e3021894 35 <dd>0, success.</dd>
elessair 0:f269e3021894 36 </dl>
elessair 0:f269e3021894 37
elessair 0:f269e3021894 38 ### Unregistering a commissioner candidate
elessair 0:f269e3021894 39
elessair 0:f269e3021894 40 Unregisters the commissioner candidate from the network.
elessair 0:f269e3021894 41
elessair 0:f269e3021894 42 To start the unregistration:
elessair 0:f269e3021894 43
elessair 0:f269e3021894 44 ```
elessair 0:f269e3021894 45 int commissioning_unregister(uint8_t interface_id);
elessair 0:f269e3021894 46 ```
elessair 0:f269e3021894 47
elessair 0:f269e3021894 48 Parameter|Description
elessair 0:f269e3021894 49 ---------|-----------
elessair 0:f269e3021894 50 `interface_id`|The interface ID of the commissioner.
elessair 0:f269e3021894 51
elessair 0:f269e3021894 52 <dl>
elessair 0:f269e3021894 53 <dt>Response</dt>
elessair 0:f269e3021894 54 <dd>any value other than 0, failure.</dd>
elessair 0:f269e3021894 55 <dd>0, success.</dd>
elessair 0:f269e3021894 56 </dl>
elessair 0:f269e3021894 57
elessair 0:f269e3021894 58 ### Petitioning process
elessair 0:f269e3021894 59
elessair 0:f269e3021894 60 After the registration to the network, the commissioner candfidate initiates petitioning to validate itself as the sole commissioner of the network via a Commissioner Router or Border Router (Commissioner Representative) to the Thread Leader Router.
elessair 0:f269e3021894 61
elessair 0:f269e3021894 62 To initiate the petitioning process:
elessair 0:f269e3021894 63
elessair 0:f269e3021894 64 ```
elessair 0:f269e3021894 65 int commissioning_petition_start(int8_t interface_id, char *commissioner_id_ptr, commissioning_status_cb *status_cb_ptr);
elessair 0:f269e3021894 66 ```
elessair 0:f269e3021894 67
elessair 0:f269e3021894 68 Parameter|Description
elessair 0:f269e3021894 69 -----------|-----------
elessair 0:f269e3021894 70 `interface_id`|ID of the interface.
elessair 0:f269e3021894 71 `commissioner_id_ptr`|A pointer to the commissioner ID.
elessair 0:f269e3021894 72 `status_cb_ptr`|A pointer to the callback function to receive the state of the commissioning process.
elessair 0:f269e3021894 73
elessair 0:f269e3021894 74 <dl>
elessair 0:f269e3021894 75 <dt>Response</dt>
elessair 0:f269e3021894 76 <dd>any value other than 0, failure.</dd>
elessair 0:f269e3021894 77 <dd>0, success.</dd>
elessair 0:f269e3021894 78 </dl>
elessair 0:f269e3021894 79
elessair 0:f269e3021894 80 ### Commissioning state enumeration
elessair 0:f269e3021894 81
elessair 0:f269e3021894 82 Defines current state of the petition made by the commissioner. The following enumeration type definition is used:
elessair 0:f269e3021894 83
elessair 0:f269e3021894 84 ```
elessair 0:f269e3021894 85 typedef enum {
elessair 0:f269e3021894 86 COMMISSIONING_STATE_ACCEPT,
elessair 0:f269e3021894 87 COMMISSIONING_STATE_PENDING,
elessair 0:f269e3021894 88 COMMISSIONING_STATE_REJECT,
elessair 0:f269e3021894 89 COMMISSIONING_STATE_NO_NETWORK
elessair 0:f269e3021894 90 } commissioning_state_e;
elessair 0:f269e3021894 91
elessair 0:f269e3021894 92 ```
elessair 0:f269e3021894 93
elessair 0:f269e3021894 94 State|Description
elessair 0:f269e3021894 95 -----------|-----------
elessair 0:f269e3021894 96 `COMMISSIONING_STATE_ACCEPT`|Accepted state, everything went fine.
elessair 0:f269e3021894 97 `COMMISSIONING_STATE_PENDING`|Commissioning request is still pending.
elessair 0:f269e3021894 98 `COMMISSIONING_STATE_REJECT`|Request rejected by the Leader Router.
elessair 0:f269e3021894 99 `COMMISSIONING_STATE_NO_NETWORK`|No Thread network found.
elessair 0:f269e3021894 100
elessair 0:f269e3021894 101 ### Petition response callback
elessair 0:f269e3021894 102
elessair 0:f269e3021894 103 This is the callback function that handles the commissioning status response after a petition request is initiated. A pointer to this callback is given as a parameter to the petition initiation function.
elessair 0:f269e3021894 104
elessair 0:f269e3021894 105 ```
elessair 0:f269e3021894 106 typedef int (commissioning_status_cb)(int8_t interface_id, commissioning_state_e state);
elessair 0:f269e3021894 107 ```
elessair 0:f269e3021894 108
elessair 0:f269e3021894 109 ### Petition keep alive messages
elessair 0:f269e3021894 110
elessair 0:f269e3021894 111 The commissioner keeps secure commissioning session via a Commissioner Router or Border Router with the Leader Router using keep alive messages that can be secured and authenticated using DTLS.
elessair 0:f269e3021894 112
elessair 0:f269e3021894 113 To set the keep alive messages going:
elessair 0:f269e3021894 114
elessair 0:f269e3021894 115 ```
elessair 0:f269e3021894 116 int commissioning_petition_keep_alive(int8_t interface_id, commissioning_state_e state);
elessair 0:f269e3021894 117 ```
elessair 0:f269e3021894 118
elessair 0:f269e3021894 119 ### Adding a joiner device
elessair 0:f269e3021894 120
elessair 0:f269e3021894 121 A device that wants to join the Thread network is typically called a joiner device. Such a device is added to the Thread network through the commissioning process.
elessair 0:f269e3021894 122
elessair 0:f269e3021894 123 To add a joiner device to the Thread network:
elessair 0:f269e3021894 124
elessair 0:f269e3021894 125 ```
elessair 0:f269e3021894 126 int commissioning_device_add(int8_t interface_id, bool short_eui64,
elessair 0:f269e3021894 127 uint8_t EUI64[8], uint8_t *PSKd_ptr, uint8_t PSKd_len,
elessair 0:f269e3021894 128 commissioning_joiner_finalisation_cb *joining_device_cb_ptr);
elessair 0:f269e3021894 129 ```
elessair 0:f269e3021894 130
elessair 0:f269e3021894 131 Parameter|Description
elessair 0:f269e3021894 132 -----------|-----------
elessair 0:f269e3021894 133 `interface_id`|ID of the Commissioner interface.
elessair 0:f269e3021894 134 `short_eui64`|A boolean determining if we will use a short EUI64 address for Bloom filter generation or not.
elessair 0:f269e3021894 135 `EUI64[8]`|A pointer to the buffer where the EUI64 bit address is stored.
elessair 0:f269e3021894 136 `PSKd_ptr`|A pointer to the pre-shared key of the device.
elessair 0:f269e3021894 137 `PSKd_len`|Length of the pre-shared key. Minimum of 6 uppercase alphanumeric characters long.
elessair 0:f269e3021894 138 `joining_device_cb_ptr`|A pointer to the callback function, to receive the result of the joining process.
elessair 0:f269e3021894 139
elessair 0:f269e3021894 140 <dl>
elessair 0:f269e3021894 141 <dt>Response</dt>
elessair 0:f269e3021894 142 <dd> 0, success.</dd>
elessair 0:f269e3021894 143 <dd>failure otherwise.</dd>
elessair 0:f269e3021894 144 </dl>
elessair 0:f269e3021894 145
elessair 0:f269e3021894 146 ### Removing a joiner device
elessair 0:f269e3021894 147
elessair 0:f269e3021894 148 To remove a joiner device from the Thread network:
elessair 0:f269e3021894 149
elessair 0:f269e3021894 150 ```
elessair 0:f269e3021894 151 int commissioning_device_delete(int8_t interface_id, uint8_t EUI64[8]);
elessair 0:f269e3021894 152 ```
elessair 0:f269e3021894 153
elessair 0:f269e3021894 154 Parameter|Description
elessair 0:f269e3021894 155 -----------|-----------
elessair 0:f269e3021894 156 `interface_id`|ID of the Commissioner interface.
elessair 0:f269e3021894 157 `EUI64[8]`|A pointer to the buffer where the EUI64 bit address is stored.
elessair 0:f269e3021894 158
elessair 0:f269e3021894 159 <dl>
elessair 0:f269e3021894 160 <dt>Response</dt>
elessair 0:f269e3021894 161 <dd> 0, success.</dd>
elessair 0:f269e3021894 162 <dd>failure otherwise.</dd>
elessair 0:f269e3021894 163 </dl>
elessair 0:f269e3021894 164
elessair 0:f269e3021894 165 ### Joining finalization callback
elessair 0:f269e3021894 166
elessair 0:f269e3021894 167 This is the callback function that provides the handler for the joining process responses.
elessair 0:f269e3021894 168
elessair 0:f269e3021894 169 ```
elessair 0:f269e3021894 170 typedef int (commissioning_joiner_finalisation_cb)(int8_t interface_id,
elessair 0:f269e3021894 171 uint8_t EUI64[8], uint8_t *message_ptr, uint16_t message_len);
elessair 0:f269e3021894 172 ```
elessair 0:f269e3021894 173
elessair 0:f269e3021894 174 Parameter|Description
elessair 0:f269e3021894 175 -----------|-----------
elessair 0:f269e3021894 176 `interface_id`|ID of the Commissioner interface.
elessair 0:f269e3021894 177 `EUI64[8]`|A pointer to the buffer where the EUI64 bit address is stored.
elessair 0:f269e3021894 178 `message_ptr`|A pointer to a MeshCoP TLV message buffer. For parsing this message, you can use `thread_meshcop_lib.h` header.
elessair 0:f269e3021894 179 `message_len`|Length of the message.
elessair 0:f269e3021894 180
elessair 0:f269e3021894 181 <dl>
elessair 0:f269e3021894 182 <dt>Response</dt>
elessair 0:f269e3021894 183 <dd> 0, success.</dd>
elessair 0:f269e3021894 184 <dd>failure otherwise.</dd>
elessair 0:f269e3021894 185 </dl>
elessair 0:f269e3021894 186
elessair 0:f269e3021894 187 ## Thread Management API
elessair 0:f269e3021894 188
elessair 0:f269e3021894 189 This API enables the user to manage a Thread network configuration. This interface essentially provides the capability to read or write various parameters related to Thread network.
elessair 0:f269e3021894 190
elessair 0:f269e3021894 191 Parameter Name | Description
elessair 0:f269e3021894 192 -----------|-----------
elessair 0:f269e3021894 193 `Network Name`| Read/Write.
elessair 0:f269e3021894 194 `Security Policy`| Read/Write.
elessair 0:f269e3021894 195 `Steering Data`| Read/Write.
elessair 0:f269e3021894 196 `Commissioning Data Time-Stamp`| Read/Write.
elessair 0:f269e3021894 197 `Commissioning Credential, PSKc`| Write only.
elessair 0:f269e3021894 198 `Network Master Key`| Read Only when policy allows.
elessair 0:f269e3021894 199 `Network Key Sequence`| Read Only when policy allows.
elessair 0:f269e3021894 200 `Network Mesh Local ULA`| Read Only.
elessair 0:f269e3021894 201 `Border Router Locator`| Read Only.
elessair 0:f269e3021894 202 `Commissioner Session ID`| Read Only.
elessair 0:f269e3021894 203 `XPANID`| Read Only.
elessair 0:f269e3021894 204 `PANID`| Read Only.
elessair 0:f269e3021894 205 `Channel`|Read Only.
elessair 0:f269e3021894 206
elessair 0:f269e3021894 207 ### Registering a Thread Management Interface
elessair 0:f269e3021894 208
elessair 0:f269e3021894 209 To instantiate a Thread Management Interface which can in turn start the Thread Management Session:
elessair 0:f269e3021894 210
elessair 0:f269e3021894 211 ```
elessair 0:f269e3021894 212 int thread_management_register(int8_t interface_id);
elessair 0:f269e3021894 213 ```
elessair 0:f269e3021894 214
elessair 0:f269e3021894 215 Parameter|Description
elessair 0:f269e3021894 216 -----------|-----------
elessair 0:f269e3021894 217 `interface_id`|ID of the management interface.
elessair 0:f269e3021894 218
elessair 0:f269e3021894 219
elessair 0:f269e3021894 220 <dl>
elessair 0:f269e3021894 221 <dt>Response</dt>
elessair 0:f269e3021894 222 <dd> An integer other than 0 or -1, the <code>instance_id</code>, a handle of the management interface.</dd>
elessair 0:f269e3021894 223 <dd>0, if the stack failed to allocate memory for the management session.</dd>
elessair 0:f269e3021894 224 <dd>-1, if the stack failed to free up memory for the management session.</dd>
elessair 0:f269e3021894 225 </dl>
elessair 0:f269e3021894 226
elessair 0:f269e3021894 227 ### Unregister a Thread Management Interface
elessair 0:f269e3021894 228
elessair 0:f269e3021894 229 To remove a Thread Management Interface and therefore remove any management session bound to that interface:
elessair 0:f269e3021894 230
elessair 0:f269e3021894 231 ```
elessair 0:f269e3021894 232 int thread_management_register(int8_t interface_id);
elessair 0:f269e3021894 233 ```
elessair 0:f269e3021894 234
elessair 0:f269e3021894 235 Parameter|Description
elessair 0:f269e3021894 236 -----------|-----------
elessair 0:f269e3021894 237 `interface_id`|ID of the management interface.
elessair 0:f269e3021894 238
elessair 0:f269e3021894 239 <dl>
elessair 0:f269e3021894 240 <dt>Response</dt>
elessair 0:f269e3021894 241 <dd> 0, success.</dd>
elessair 0:f269e3021894 242 <dd>-1, failure.</dd>
elessair 0:f269e3021894 243 </dl>
elessair 0:f269e3021894 244
elessair 0:f269e3021894 245 ### Setting up the Thread network name
elessair 0:f269e3021894 246
elessair 0:f269e3021894 247 To set the name for Thread network:
elessair 0:f269e3021894 248
elessair 0:f269e3021894 249 ```
elessair 0:f269e3021894 250 int thread_management_set_network_name(int8_t instance_id, uint8_t *name_ptr, uint8_t name_len, management_set_response_cb *cb_ptr);
elessair 0:f269e3021894 251 ```
elessair 0:f269e3021894 252
elessair 0:f269e3021894 253 Parameter|Description
elessair 0:f269e3021894 254 -----------|-----------
elessair 0:f269e3021894 255 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 256 `name_ptr`|Pointer to the new name.
elessair 0:f269e3021894 257 `name_len`|Length of the name.
elessair 0:f269e3021894 258 `cb_ptr`|Pointer to the management response callback function.
elessair 0:f269e3021894 259
elessair 0:f269e3021894 260 <dl>
elessair 0:f269e3021894 261 <dt>Response</dt>
elessair 0:f269e3021894 262 <dd> 0, success.</dd>
elessair 0:f269e3021894 263 <dd><0, failure.</dd>
elessair 0:f269e3021894 264 </dl>
elessair 0:f269e3021894 265
elessair 0:f269e3021894 266 ### Thread management response callback
elessair 0:f269e3021894 267
elessair 0:f269e3021894 268 To receive the response to the Thread management commands:
elessair 0:f269e3021894 269
elessair 0:f269e3021894 270 ```
elessair 0:f269e3021894 271 typedef int (management_set_response_cb)(int8_t interface_id, management_state_e status);
elessair 0:f269e3021894 272 ```
elessair 0:f269e3021894 273
elessair 0:f269e3021894 274 Parameter|Description
elessair 0:f269e3021894 275 -----------|-----------
elessair 0:f269e3021894 276 `interface_id`|Interface ID of the management session.
elessair 0:f269e3021894 277 `status`|Result status of the request.
elessair 0:f269e3021894 278
elessair 0:f269e3021894 279 ### Thread management states
elessair 0:f269e3021894 280
elessair 0:f269e3021894 281 An enumeration type definition is used to set and read the state of the Thread management session requests.
elessair 0:f269e3021894 282
elessair 0:f269e3021894 283 ```
elessair 0:f269e3021894 284 typedef enum {
elessair 0:f269e3021894 285 MANAGEMENT_STATE_REJECT,
elessair 0:f269e3021894 286 MANAGEMENT_STATE_PENDING,
elessair 0:f269e3021894 287 MANAGEMENT_STATE_ACCEPT
elessair 0:f269e3021894 288 } management_state_e;
elessair 0:f269e3021894 289 ```
elessair 0:f269e3021894 290
elessair 0:f269e3021894 291 Enumeration|Description
elessair 0:f269e3021894 292 -----------|-----------
elessair 0:f269e3021894 293 `MANAGEMENT_STATE_REJECT`|Thread management suit has rejected the request.
elessair 0:f269e3021894 294 `MANAGEMENT_STATE_PENDING`|Request is still pending.
elessair 0:f269e3021894 295 `MANAGEMENT_STATE_ACCEPT`|Thread management suit has accepted the request.
elessair 0:f269e3021894 296
elessair 0:f269e3021894 297 ### Setting up security policy
elessair 0:f269e3021894 298
elessair 0:f269e3021894 299 The function `thread_management_set_security_policy()` is used to regulate the current security policy in a Thread network. Using this function, you can enable and disable external and native commissioning and set the network security key rotation time.
elessair 0:f269e3021894 300
elessair 0:f269e3021894 301 ```
elessair 0:f269e3021894 302 int thread_management_set_security_policy(int8_t instance_id, uint8_t options, uint16_t rotation_time, management_set_response_cb *cb_ptr);
elessair 0:f269e3021894 303 ```
elessair 0:f269e3021894 304
elessair 0:f269e3021894 305 Parameter|Description
elessair 0:f269e3021894 306 -----------|-----------
elessair 0:f269e3021894 307 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 308 `options`|If the bit number `8` is set to 1, external commissioning is restricted. If bit number `7` is set to 1, native commissioning is restricted.
elessair 0:f269e3021894 309 `rotation_time`|Thread key rotation time in hours.
elessair 0:f269e3021894 310 `cb_ptr`|A pointer to `management_set_response_cb` callback function.
elessair 0:f269e3021894 311
elessair 0:f269e3021894 312 <dl>
elessair 0:f269e3021894 313 <dt>Response</dt>
elessair 0:f269e3021894 314 <dd> 0, success.</dd>
elessair 0:f269e3021894 315 <dd><0, failure.</dd>
elessair 0:f269e3021894 316 </dl>
elessair 0:f269e3021894 317
elessair 0:f269e3021894 318 ### Data Steering
elessair 0:f269e3021894 319
elessair 0:f269e3021894 320 The function `thread_management_set_steering_data()` steers the way how Thread network allows joiners to join the network. Using this function, you can enable and disable the joining process or filter out the joiners. A Bloom filter is used for the filtering. The length of Bloom filter can be set from 1-16 bytes. The first bit of the first byte (set to `0`)indicates whether to use EUI64 addresses or bottom 24 bits of the EUI64 address (set to `1`).
elessair 0:f269e3021894 321
elessair 0:f269e3021894 322 ```
elessair 0:f269e3021894 323 int thread_management_set_steering_data(int8_t instance_id, uint8_t *steering_data_ptr, uint8_t steering_data_len, management_set_response_cb *cb_ptr);
elessair 0:f269e3021894 324 ```
elessair 0:f269e3021894 325
elessair 0:f269e3021894 326 Parameter|Description
elessair 0:f269e3021894 327 -----------|-----------
elessair 0:f269e3021894 328 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 329 `steering_data_ptr`|A pointer to the steering data. If all bits are set to `0`, no joiners will be allowed to join. If all bits are set to 1, any joiner is allowed to join. A mix of 1s and 0s can be defined if you are using a Bloom filter. This filter allows any specific devices to join and prohibits others.
elessair 0:f269e3021894 330 `steering_data_len`|Length of the steering data.
elessair 0:f269e3021894 331 `cb_ptr`|A pointer to `management_set_response_cb` callback function. It can be set to NULL, if no response is required.
elessair 0:f269e3021894 332
elessair 0:f269e3021894 333 <dl>
elessair 0:f269e3021894 334 <dt>Response</dt>
elessair 0:f269e3021894 335 <dd> 0, success.</dd>
elessair 0:f269e3021894 336 <dd><0, failure.</dd>
elessair 0:f269e3021894 337 </dl>
elessair 0:f269e3021894 338
elessair 0:f269e3021894 339 ### Thread commissioning time-stamps
elessair 0:f269e3021894 340
elessair 0:f269e3021894 341 To add time-stamps to the Thread commissioning related chunks of data:
elessair 0:f269e3021894 342
elessair 0:f269e3021894 343 ```
elessair 0:f269e3021894 344 int thread_management_set_commissioning_data_timestamp(int8_t instance_id, uint64_t time, management_set_response_cb *cb_ptr);
elessair 0:f269e3021894 345 ```
elessair 0:f269e3021894 346
elessair 0:f269e3021894 347 Parameter|Description
elessair 0:f269e3021894 348 -----------|-----------
elessair 0:f269e3021894 349 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 350 `time`|64 bits in total. Upper 48 bits are is time in seconds. Lower 16 bits are fractional portion of time.
elessair 0:f269e3021894 351 `rotation_time`|Thread key rotation time in hours.
elessair 0:f269e3021894 352 `cb_ptr`|A pointer to `management_set_response_cb` callback function.
elessair 0:f269e3021894 353
elessair 0:f269e3021894 354 <dl>
elessair 0:f269e3021894 355 <dt>Response</dt>
elessair 0:f269e3021894 356 <dd> 0, success.</dd>
elessair 0:f269e3021894 357 <dd><0, failure.</dd>
elessair 0:f269e3021894 358 </dl>
elessair 0:f269e3021894 359
elessair 0:f269e3021894 360 ### Setting up commissioning credentials
elessair 0:f269e3021894 361
elessair 0:f269e3021894 362 To set up the security credentials for the Thread network:
elessair 0:f269e3021894 363
elessair 0:f269e3021894 364 ```
elessair 0:f269e3021894 365 int thread_management_set_commissioning_credentials(int8_t instance_id, uint8_t PSKc[32], uint8_t PSKc_len, management_set_response_cb *cb_ptr);
elessair 0:f269e3021894 366 ```
elessair 0:f269e3021894 367
elessair 0:f269e3021894 368 Parameter|Description
elessair 0:f269e3021894 369 -----------|-----------
elessair 0:f269e3021894 370 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 371 `PSKc`|Maximum 32 bytes long pre-shared key used as a network security credential.
elessair 0:f269e3021894 372 `PSKc_len`|Length of the pre-shared key used.
elessair 0:f269e3021894 373 `cb_ptr`|A pointer to `management_set_response_cb` callback function.
elessair 0:f269e3021894 374
elessair 0:f269e3021894 375 <dl>
elessair 0:f269e3021894 376 <dt>Response</dt>
elessair 0:f269e3021894 377 <dd> 0, success.</dd>
elessair 0:f269e3021894 378 <dd><0, failure.</dd>
elessair 0:f269e3021894 379 </dl>
elessair 0:f269e3021894 380
elessair 0:f269e3021894 381 ### Collecting Thread management information
elessair 0:f269e3021894 382
elessair 0:f269e3021894 383 The function `thread_management_info_get()` is used to collect Thread management related information from the Leader Router.
elessair 0:f269e3021894 384
elessair 0:f269e3021894 385 Parameter|Description
elessair 0:f269e3021894 386 -----------|-----------
elessair 0:f269e3021894 387 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 388 `fields_ptr`|A pointer to management fields from which the information is fetched.
elessair 0:f269e3021894 389 `field_count`|Number of fields in the field pointer array.
elessair 0:f269e3021894 390 `cb_ptr`|A pointer to `management_get_response_cb` callback function.
elessair 0:f269e3021894 391
elessair 0:f269e3021894 392 <dl>
elessair 0:f269e3021894 393 <dt>Response</dt>
elessair 0:f269e3021894 394 <dd> 0, success.</dd>
elessair 0:f269e3021894 395 <dd><0, failure.</dd>
elessair 0:f269e3021894 396 </dl>
elessair 0:f269e3021894 397
elessair 0:f269e3021894 398 ### Thread management get response callback
elessair 0:f269e3021894 399
elessair 0:f269e3021894 400 The callback function `(management_get_response_cb)` is used for receiving the information regarding Thread management from various fields related to the Thread management. Such fields can be parsed using macros defined in `thread_meshcop_lib.h`.
elessair 0:f269e3021894 401
elessair 0:f269e3021894 402 ```
elessair 0:f269e3021894 403 typedef int (management_get_response_cb)(int8_t instance_id, management_state_e status, uint8_t *response_message_ptr, uint16_t response_message_len);
elessair 0:f269e3021894 404 ```
elessair 0:f269e3021894 405
elessair 0:f269e3021894 406 Parameter|Description
elessair 0:f269e3021894 407 -----------|-----------
elessair 0:f269e3021894 408 `instance_id`|Instance ID of the management session.
elessair 0:f269e3021894 409 `status`|The state of the management interface given by `management_state_e`.
elessair 0:f269e3021894 410 `response_message_ptr`|A pointer to a MeshCoP TLV structure that contains the requested TLVs.
elessair 0:f269e3021894 411 `response_message_len`|Length of the response message.
elessair 0:f269e3021894 412