Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
WisunInterface.h
1 /*
2  * Copyright (c) 2018-2019 ARM Limited. All rights reserved.
3  * SPDX-License-Identifier: Apache-2.0
4  * Licensed under the Apache License, Version 2.0 (the License); you may
5  * not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef WISUNINTERFACE_H
18 #define WISUNINTERFACE_H
19 
20 #include "MeshInterfaceNanostack.h"
21 
22 /**
23  * \brief Struct ws_rpl_info Wi-SUN router RPL information.
24  */
25 typedef struct ws_rpl_info {
26  /** Router dodag id */
27  uint8_t rpl_dodag_id[16];
28  /** Router instance identifier */
29  uint8_t instance_id;
30  /** RPL version number */
31  uint8_t version;
32  /** RPL DODAG node current Rank */
33  uint16_t current_rank;
34  /** RPL Primary Parent Rank */
35  uint16_t primary_parent_rank;
36 } ws_rpl_info_t;
37 
38 /**
39  * \brief Struct ws_stack_state Wi-SUN stack information.
40  */
41 typedef struct ws_stack_state {
42  /** Mesh Interface Global IPv6 Address */
43  uint8_t global_addr[16];
44  /** Mesh Interface Link Local IPv6 Address */
45  uint8_t link_local_addr[16];
46  /** Parent link local address */
47  uint8_t parent_addr[16];
48  /** parent RSSI Out measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) to +80 (254) dBm.*/
49  uint8_t rsl_out;
50  /** parent RSSI in measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) to +80 (254) dBm.*/
51  uint8_t rsl_in;
52  /** Wi-SUN join state defined by Wi-SUN specification 1-5 */
53  uint8_t join_state;
54  /** Network PAN ID */
55  uint16_t pan_id;
56  /** Device RF minimum sensitivity configuration. lowest level of radio signal strength packet heard. Range of -174 (0) to +80 (254) dBm*/
57  uint8_t device_min_sens;
58 } ws_stack_state_t;
59 
60 /**
61  * \brief Struct ws_cca_threshold_table Wi-SUN CCA threshold table information.
62  */
63 typedef struct ws_cca_threshold_table {
64  /** Number of channels */
65  uint8_t number_of_channels;
66  /** CCA threshold table */
67  const int8_t *cca_threshold_table;
68 } ws_cca_threshold_table_t;
69 
70 typedef enum {
71  WISUN_OTHER = 0, /**< temporary or soon to be removed neighbor*/
72  WISUN_PRIMARY_PARENT, /**< Primary parent used for upward packets and used from Border router downwards*/
73  WISUN_SECONDARY_PARENT, /**< Secondary parent reported to border router and might be used as alternate route*/
74  WISUN_CANDIDATE_PARENT, /**< Candidate neighbor that is considered as parent if there is problem with active parents*/
75  WISUN_CHILD /**< Child with registered address*/
76 } ws_nbr_type_e;
77 
78 /**
79  * \brief Struct ws_nbr_info_t Gives the neighbor information.
80  */
81 typedef struct ws_nbr_info {
82  /** Link local address*/
83  uint8_t link_local_address[16];
84  /** Global address if it is known set to 0 if not available*/
85  uint8_t global_address[16];
86  /** parent RSSI Out measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) to +80 (254) dBm.*/
87  uint8_t rsl_out;
88  /** parent RSSI in measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) to +80 (254) dBm.*/
89  uint8_t rsl_in;
90  /** RPL Rank value for parents 0xffff for neighbors RANK is unknown*/
91  uint16_t rpl_rank;
92  /** Measured ETX value if known set to 0xFFFF if not known or Child*/
93  uint16_t etx;
94  /** Remaining lifetime Link lifetime for parents and ARO lifetime for children*/
95  uint32_t lifetime;
96  /** Neighbour type (Primary Parent, Secondary Parent, Candidate parent, child, other(Temporary neighbours))*/
97  ws_nbr_type_e type;
98 } ws_nbr_info_t;
99 
100 
101 /** Wi-SUN mesh network interface class
102  *
103  * Configure Nanostack to use Wi-SUN protocol.
104  */
105 class WisunInterface final : public MeshInterfaceNanostack {
106 public:
107  /** Inherit MeshInterfaceNanostack constructors */
108  using MeshInterfaceNanostack::MeshInterfaceNanostack;
109 
110  /**
111  * \brief Set Wi-SUN network name.
112  *
113  * Function stores new network name to mbed-mesh-api and uses it when connect() is called next time.
114  * If device is already connected to the Wi-SUN network then device will restart network discovery after
115  * changing the network name.
116  *
117  * Function overwrites network name defined by Mbed OS configuration.
118  *
119  * \param network_name Network name as NUL terminated string. Can't exceed 32 characters and can't be NULL.
120  * \return MESH_ERROR_NONE on success.
121  * \return MESH_ERROR_UNKNOWN in case of failure.
122  * */
123  mesh_error_t set_network_name(char *network_name);
124 
125  /**
126  * \brief Get Wi-SUN network name.
127  *
128  * Function reads network name from mbed-mesh-api.
129  *
130  * \param network_name Network name as NUL terminated string. Must have space for 33 characters (string and null terminator).
131  * \return MESH_ERROR_NONE on success.
132  * \return MESH_ERROR_UNKNOWN in case of failure.
133  * */
134  mesh_error_t get_network_name(char *network_name);
135 
136  /**
137  * \brief Validate Wi-SUN network name.
138  *
139  * Function validates network name. Function can be used to test that values that will be used on set function are valid.
140  *
141  * \param network_name Network name as NUL terminated string. Can't exceed 32 characters and can't be NULL.
142  * \return MESH_ERROR_NONE on success.
143  * \return MESH_ERROR_UNKNOWN in case of failure.
144  * */
145  mesh_error_t validate_network_name(char *network_name);
146 
147  /**
148  * \brief Set Wi-SUN network regulatory domain, operating class and operating mode.
149  *
150  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
151  * If device is already connected to the Wi-SUN network then device will restart network discovery after
152  * changing the regulatory_domain, operating_class or operating_mode.
153  *
154  * Function overwrites parameters defined by Mbed OS configuration.
155  *
156  * \param regulatory_domain Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
157  * \param operating_class Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
158  * \param operating_mode Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
159  * \return MESH_ERROR_NONE on success.
160  * \return MESH_ERROR_UNKNOWN in case of failure.
161  * */
162  mesh_error_t set_network_regulatory_domain(uint8_t regulatory_domain = 0xff, uint8_t operating_class = 0xff, uint8_t operating_mode = 0xff);
163 
164  /**
165  * \brief Get Wi-SUN network regulatory domain, operating class and operating mode.
166  *
167  * Function reads regulatory_domain, operating_class and operating_mode from mbed-mesh-api.
168  *
169  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
170  * \param operating_class Values defined in Wi-SUN PHY-specification.
171  * \param operating_mode Values defined in Wi-SUN PHY-specification.
172  * \return MESH_ERROR_NONE on success.
173  * \return MESH_ERROR_UNKNOWN in case of failure.
174  * */
175  mesh_error_t get_network_regulatory_domain(uint8_t *regulatory_domain, uint8_t *operating_class, uint8_t *operating_mode);
176 
177  /**
178  * \brief Validate Wi-SUN network regulatory domain, operating class and operating mode.
179  *
180  * Function validates regulatory_domain, operating_class and operating_mode. Function can be used to test that values that will
181  * be used on set function are valid.
182  *
183  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
184  * \param operating_class Values defined in Wi-SUN PHY-specification.
185  * \param operating_mode Values defined in Wi-SUN PHY-specification.
186  * \return MESH_ERROR_NONE on success.
187  * \return MESH_ERROR_UNKNOWN in case of failure.
188  * */
189  mesh_error_t validate_network_regulatory_domain(uint8_t regulatory_domain, uint8_t operating_class, uint8_t operating_mode);
190 
191  /**
192  * \brief Set Wi-SUN network regulatory domain, PHY mode ID and channel plan ID.
193  *
194  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
195  * If device is already connected to the Wi-SUN network then device will restart network discovery after
196  * changing the regulatory_domain, phy_mode_id or channel_plan_id.
197  *
198  * \param regulatory_domain Values defined in Wi-SUN PHY-specification. Use 0 to leave parameter unchanged or 0xff to use default value.
199  * \param phy_mode_id Values defined in Wi-SUN PHY-specification. Use 0 to leave parameter unchanged or 0xff to use default value.
200  * \param channel_plan_id Values defined in Wi-SUN PHY-specification. Use 0 to leave parameter unchanged or 0xff to use default value.
201  * \return MESH_ERROR_NONE on success.
202  * \return MESH_ERROR_UNKNOWN in case of failure.
203  * */
204  mesh_error_t set_network_domain_configuration(uint8_t regulatory_domain, uint8_t phy_mode_id, uint8_t channel_plan_id);
205 
206  /**
207  * \brief Get Wi-SUN network regulatory domain, PHY mode ID and channel plan ID.
208  *
209  * Function reads regulatory_domain, phy_mode_id and channel_plan_id from mbed-mesh-api.
210  *
211  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
212  * \param phy_mode_id Values defined in Wi-SUN PHY-specification.
213  * \param channel_plan_id Values defined in Wi-SUN PHY-specification.
214  * \return MESH_ERROR_NONE on success.
215  * \return MESH_ERROR_UNKNOWN in case of failure.
216  * */
217  mesh_error_t get_network_domain_configuration(uint8_t *regulatory_domain, uint8_t *phy_mode_id, uint8_t *channel_plan_id);
218 
219  /**
220  * \brief Validate Wi-SUN network regulatory domain, PHY mode ID and channel plan ID.
221  *
222  * Function validates regulatory_domain, phy_mode_id and channel_plan_id. Function can be used to test that values that will
223  * be used on set function are valid.
224  *
225  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
226  * \param phy_mode_id Values defined in Wi-SUN PHY-specification.
227  * \param channel_plan_id Values defined in Wi-SUN PHY-specification.
228  * \return MESH_ERROR_NONE on success.
229  * \return MESH_ERROR_UNKNOWN in case of failure.
230  * */
231  mesh_error_t validate_network_domain_configuration(uint8_t regulatory_domain, uint8_t phy_mode_id, uint8_t channel_plan_id);
232 
233  /**
234  * \brief Set Wi-SUN network size.
235  *
236  * Function stores network size parameter to the mbed-mesh-api and uses it when connect() is called for the next
237  * time. If a device is already connected to the Wi-SUN network, then the device will restart network discovery
238  * after changing the network size.
239  *
240  * It is recommended to set the correct network size because some Wi-SUN network configuration parameters are
241  * adjusted based on the selected network size. A network configured for a small amount of devices may not work
242  * optimally for large number of devices. This is because the network bandwidth is divided with all the devices in
243  * the network. Enough bandwidth must be reserved for application data usage as well as the Wi-SUN network
244  * operations. In addition, the application should adapt to the network characteristics by using the InternetSocket
245  * methods get_stagger_estimate_to_address() and get_rtt_estimate_to_address().
246  *
247  * The network size is measured as hundreds of devices that are expected to join to the network. For example,
248  * for a 400-device network set network size to 4.
249  *
250  * The Wi-SUN stack will automatically adjust timing and RPL configuration values based on the selected network
251  * size and data rate. If a customized timing or RPL values are needed, the APIs below should be invoked after
252  * changing the network size:
253  * - set_timing_parameters() to set timing settings to the Wi-SUN interface.
254  * - rpl_parameters_set() to set RPL settings to the Border Router interface.
255  *
256  * By default the Wi-SUN stack is configured to use a few hundreds of devices.
257  *
258  * The network size should be set to 0 when running certification tests.
259  *
260  * \param network_size Network size in hundreds of devices (e.g. 12 for 1200 devices), 0 for certificate testing.
261  * \return MESH_ERROR_NONE on success.
262  * \return MESH_ERROR_UNKNOWN in case of failure.
263  * */
264  mesh_error_t set_network_size(uint8_t network_size);
265 
266  /**
267  * \brief Get Wi-SUN network size.
268  *
269  * Function reads network size from mbed-mesh-api.
270  *
271  * \param network_size Network size in hundreds of devices, 0x00 for network size certificate.
272  * \return MESH_ERROR_NONE on success.
273  * \return MESH_ERROR_UNKNOWN in case of failure.
274  * */
275  mesh_error_t get_network_size(uint8_t *network_size);
276 
277  /**
278  * \brief Validate Wi-SUN network size.
279  *
280  * Function validates network size from mbed-mesh-api. Function can be used to test that values that will
281  * be used on set function are valid.
282  *
283  * \param network_size Network size in hundreds of devices, 0x00 for network size certificate.
284  * \return MESH_ERROR_NONE on success.
285  * \return MESH_ERROR_UNKNOWN in case of failure.
286  * */
287  mesh_error_t validate_network_size(uint8_t network_size);
288 
289  /**
290  * \brief Set Wi-SUN FHSS channel mask
291  *
292  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
293  * If device is already connected to the Wi-SUN network then settings take effect right away.
294  *
295  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
296  * \return MESH_ERROR_NONE on success.
297  * \return MESH_ERROR_UNKNOWN in case of failure.
298  * */
299  mesh_error_t set_channel_mask(uint32_t channel_mask[8]);
300 
301  /**
302  * \brief Get Wi-SUN FHSS channel mask
303  *
304  * Function reads FHSS channel mask from mbed-mesh-api.
305  *
306  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
307  * \return MESH_ERROR_NONE on success.
308  * \return MESH_ERROR_UNKNOWN in case of failure.
309  * */
310  mesh_error_t get_channel_mask(uint32_t *channel_mask);
311 
312  /**
313  * \brief Validate Wi-SUN FHSS channel mask
314  *
315  * Function validates FHSS channel mask. Function can be used to test that values that will
316  * be used on set function are valid.
317  *
318  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
319  * \return MESH_ERROR_NONE on success.
320  * \return MESH_ERROR_UNKNOWN in case of failure.
321  * */
322  mesh_error_t validate_channel_mask(uint32_t channel_mask[8]);
323 
324  /**
325  * \brief Set Wi-SUN FHSS unicast channel function parameters
326  *
327  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
328  * If device is already connected to the Wi-SUN network then device will restart network discovery after
329  * changing the channel function, fixed channel or dwell interval.
330  *
331  * Function overwrites parameters defined by Mbed OS configuration.
332  *
333  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
334  * \param fixed_channel Used channel when channel function is fixed channel. Use 0xffff when fixed channel function not on use.
335  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1. Use 0x00 to use leave parameter unchanged.
336  * \return MESH_ERROR_NONE on success.
337  * \return MESH_ERROR_UNKNOWN in case of failure.
338  * */
339  mesh_error_t set_unicast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel = 0xffff, uint8_t dwell_interval = 0x00);
340 
341  /**
342  * \brief Get Wi-SUN FHSS unicast channel function parameters
343  *
344  * Function reads FHSS unicast channel function parameters from mbed-mesh-api.
345  *
346  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
347  * \param fixed_channel Used channel when channel function is fixed channel.
348  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
349  * \return MESH_ERROR_NONE on success.
350  * \return MESH_ERROR_UNKNOWN in case of failure.
351  * */
352  mesh_error_t get_unicast_channel_function(mesh_channel_function_t *channel_function, uint16_t *fixed_channel, uint8_t *dwell_interval);
353 
354  /**
355  * \brief Validate Wi-SUN FHSS unicast channel function parameters
356  *
357  * Function validates FHSS unicast channel function parameters. Function can be used to test that values that will
358  * be used on set function are valid.
359  *
360  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
361  * \param fixed_channel Used channel when channel function is fixed channel.
362  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
363  * \return MESH_ERROR_NONE on success.
364  * \return MESH_ERROR_UNKNOWN in case of failure.
365  * */
366  mesh_error_t validate_unicast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel, uint8_t dwell_interval);
367 
368  /**
369  * \brief Set Wi-SUN FHSS broadcast channel function parameters
370  *
371  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
372  * If device is already connected to the Wi-SUN network then device will restart network discovery after
373  * changing the channel function, fixed channel, dwell interval or broadcast_interval.
374  *
375  * Function overwrites parameters defined by Mbed OS configuration.
376  *
377  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
378  * \param fixed_channel Used channel when channel function is fixed channel. Use 0xffff when fixed channel function not on use.
379  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1. Use 0x00 to use leave parameter unchanged.
380  * \param broadcast_interval Used broadcast interval. Use 0x00 to use leave parameter unchanged.
381  * \return MESH_ERROR_NONE on success.
382  * \return MESH_ERROR_UNKNOWN in case of failure.
383  * */
384  mesh_error_t set_broadcast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel = 0xffff, uint8_t dwell_interval = 0x00, uint32_t broadcast_interval = 0x00);
385 
386  /**
387  * \brief Get Wi-SUN FHSS broadcast channel function parameters
388  *
389  * Function reads FHSS broadcast channel function parameters from mbed-mesh-api.
390  *
391  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
392  * \param fixed_channel Used channel when channel function is fixed channel.
393  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
394  * \param broadcast_interval Used broadcast interval.
395  * \return MESH_ERROR_NONE on success.
396  * \return MESH_ERROR_UNKNOWN in case of failure.
397  * */
398  mesh_error_t get_broadcast_channel_function(mesh_channel_function_t *channel_function, uint16_t *fixed_channel, uint8_t *dwell_interval, uint32_t *broadcast_interval);
399 
400  /**
401  * \brief Validate Wi-SUN FHSS broadcast channel function parameters
402  *
403  * Function validates FHSS broadcast channel function parameters from mbed-mesh-api. Function can be used to test that values that will
404  * be used on set function are valid.
405  *
406  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
407  * \param fixed_channel Used channel when channel function is fixed channel.
408  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
409  * \param broadcast_interval Used broadcast interval.
410  * \return MESH_ERROR_NONE on success.
411  * \return MESH_ERROR_UNKNOWN in case of failure.
412  * */
413  mesh_error_t validate_broadcast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel, uint8_t dwell_interval, uint32_t broadcast_interval);
414 
415  /**
416  * \brief Set Wi-SUN timing parameters
417  *
418  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
419  * If device is already connected to the Wi-SUN network then settings take effect right away.
420  *
421  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds. Use 0x00 to use leave parameter unchanged.
422  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin. Use 0x00 to use leave parameter unchanged.
423  * \param disc_trickle_k Discovery trickle k. Use 0x00 to use leave parameter unchanged.
424  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds. Use 0x00 to use leave parameter unchanged.
425  * \return MESH_ERROR_NONE on success.
426  * \return MESH_ERROR_UNKNOWN in case of failure.
427  * */
428  mesh_error_t set_timing_parameters(uint16_t disc_trickle_imin = 0x00, uint16_t disc_trickle_imax = 0x00, uint8_t disc_trickle_k = 0x00, uint16_t pan_timeout = 0x00);
429 
430  /**
431  * \brief Get Wi-SUN timing parameters
432  *
433  * Function reads timing parameters from mbed-mesh-api.
434  *
435  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds.
436  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin.
437  * \param disc_trickle_k Discovery trickle k.
438  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds.
439  * \return MESH_ERROR_NONE on success.
440  * \return MESH_ERROR_UNKNOWN in case of failure.
441  * */
442  mesh_error_t get_timing_parameters(uint16_t *disc_trickle_imin, uint16_t *disc_trickle_imax, uint8_t *disc_trickle_k, uint16_t *pan_timeout);
443 
444  /**
445  * \brief Validates Wi-SUN timing parameters
446  *
447  * Function validates timing parameters. Function can be used to test that values that will be used on set
448  * function are valid.
449  *
450  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds.
451  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin.
452  * \param disc_trickle_k Discovery trickle k.
453  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds.
454  * \return MESH_ERROR_NONE on success.
455  * \return MESH_ERROR_UNKNOWN in case of failure.
456  * */
457  mesh_error_t validate_timing_parameters(uint16_t disc_trickle_imin, uint16_t disc_trickle_imax, uint8_t disc_trickle_k, uint16_t pan_timeout);
458 
459  /**
460  * \brief Set Wi-SUN device minimum sensitivity
461  *
462  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
463  * If device is already connected to the Wi-SUN network then settings take effect right away.
464  *
465  * \param device_min_sens Device minimum sensitivity. Range 0(-174 dB) to 254(+80 dB).
466  * \return MESH_ERROR_NONE on success.
467  * \return MESH_ERROR_UNKNOWN in case of failure.
468  * */
469  mesh_error_t set_device_min_sens(uint8_t device_min_sens);
470 
471  /**
472  * \brief Get Wi-SUN device minimum sensitivity.
473  *
474  * Function reads device minimum sensitivity from mbed-mesh-api.
475  *
476  * \param device_min_sens Device minimum sensitivity. Range 0-254.
477  * \return MESH_ERROR_NONE on success.
478  * \return MESH_ERROR_UNKNOWN in case of failure.
479  * */
480  mesh_error_t get_device_min_sens(uint8_t *device_min_sens);
481 
482  /**
483  * \brief Validates Device minimum sensitivity.
484  *
485  * Function validates device minimum sensitivity. Function can be used to test that values that will be used on set
486  * function are valid.
487  *
488  * \param device_min_sens Device minimum sensitivity. Range 0-254.
489  * \return MESH_ERROR_NONE on success.
490  * \return MESH_ERROR_UNKNOWN in case of failure.
491  * */
492  mesh_error_t validate_device_min_sens(uint8_t device_min_sens);
493 
494  /**
495  * \brief Set own certificate and private key reference to the Wi-SUN network.
496  *
497  * Function can be called several times if intermediate certificates are used. Then each call to the function
498  * adds a certificate reference to own certificate chain. Certificates are in bottom up order i.e. own certificate
499  * is given first and the top certificate is given last.
500  *
501  * PEM formatted certificates must use either "\n" or "\r\n" as line separator. PEM formatted certificates
502  * must be NUL terminated and the NUL terminator is counted to certificate length.
503  *
504  * It is possible to add multiple PEM certificates concatenated together in one call set_own_certificate(). In that
505  * case certificates are in bottom up order i.e. own certificate is given first and the top certificate is given
506  * last. NUL terminator is added after the last concatenated certificate and the NUL terminator is counted to
507  * total concatenated certificate length.
508  *
509  * Function must be called before connecting the device i.e before call to connect() method.
510  * Function will not copy certificate or key, therefore addresses must remain valid.
511  *
512  * \param cert Certificate address.
513  * \param cert_len Certificate length in bytes.
514  * \param cert_key Certificate key address.
515  * \param cert_key_len Certificate key length in bytes.
516  * \return MESH_ERROR_NONE on success.
517  * \return MESH_ERROR_STATE if method is called after calling connect().
518  * \return MESH_ERROR_MEMORY in case of memory allocation failure.
519  * */
520  mesh_error_t set_own_certificate(uint8_t *cert, uint16_t cert_len, uint8_t *cert_key = NULL, uint16_t cert_key_len = 0);
521 
522  /**
523  * \brief Remove own certificates from the Wi-SUN network.
524  *
525  * Function must be called before connecting the device i.e before call to connect() method.
526  *
527  * \return MESH_ERROR_NONE on success.
528  * \return MESH_ERROR_STATE if method is called after calling connect().
529  * */
530  mesh_error_t remove_own_certificates(void);
531 
532  /**
533  * \brief Set trusted certificate reference to the Wi-SUN network.
534  *
535  * Function can be called several times. Each call to the function adds a trusted certificate to Wi-SUN.
536  *
537  * PEM formatted certificates must use either "\n" or "\r\n" as line separator. PEM formatted certificates
538  * must be NUL terminated and the NUL terminator is counted to certificate length.
539  *
540  * It is possible to add multiple PEM certificates concatenated together in one call set_trusted_certificate().
541  * NUL terminator is added after the last concatenated certificate and the NUL terminator is counted to
542  * total concatenated certificate length.
543  *
544  * Function must be called before connecting the device i.e before call to connect() method.
545  * Function will not copy certificate, therefore addresses must remain valid.
546  *
547  * \param cert Certificate address.
548  * \param cert_len Certificate length in bytes.
549  * \return MESH_ERROR_NONE on success.
550  * \return MESH_ERROR_STATE if method is called after calling connect().
551  * \return MESH_ERROR_MEMORY in case of memory allocation failure.
552  * */
553  mesh_error_t set_trusted_certificate(uint8_t *cert, uint16_t cert_len);
554 
555  /**
556  * \brief Remove trusted certificates from the Wi-SUN network.
557  *
558  * Function must be called before connecting the device i.e before call to connect() method.
559  *
560  * \return MESH_ERROR_NONE on success.
561  * \return MESH_ERROR_STATE if method is called after calling connect().
562  * */
563  mesh_error_t remove_trusted_certificates(void);
564 
565  /**
566  * \brief Get router IP address
567  *
568  * \param address
569  * \param len
570  * */
571  bool getRouterIpAddress(char *address, int8_t len);
572 
573  /**
574  * \brief Enable Wi-SUN statistics
575  *
576  * After enabling statistics those can be read using the network, physical layer,
577  * MAC and FHSS and Wi-SUN statistics read functions.
578  *
579  * \return MESH_ERROR_NONE on success.
580  * \return MESH_ERROR_UNKNOWN on error
581  * */
582  mesh_error_t enable_statistics(void);
583 
584  /**
585  * \brief Reset Wi-SUN statistics
586  *
587  * Resets MAC statistics and Wi-SUN statistics.
588  *
589  * \return MESH_ERROR_NONE on success.
590  * \return MESH_ERROR_UNKNOWN on error
591  * */
592  mesh_error_t reset_statistics(void);
593 
594  /**
595  * \brief Reads Wi-SUN network statistics
596  *
597  * Reads network statistics.
598  *
599  * \param statistics Network statistics.
600  * \return MESH_ERROR_NONE on success.
601  * \return MESH_ERROR_UNKNOWN on error
602  * */
603  mesh_error_t read_nw_statistics(mesh_nw_statistics_t *statistics);
604 
605  /**
606  * \brief Reads Wi-SUN MAC statistics
607  *
608  * Reads MAC statistics.
609  *
610  * \param statistics MAC statistics.
611  * \return MESH_ERROR_NONE on success.
612  * \return MESH_ERROR_UNKNOWN on error
613  * */
614  mesh_error_t read_mac_statistics(mesh_mac_statistics_t *statistics);
615 
616  /**
617  * \brief Get Wi-SUN Router information.
618  *
619  * Function reads RPL information from nanostack.
620  * Mesh interface must be initialized before calling this function.
621  *
622  * \param info_ptr Structure given to stack where information will be stored
623  *
624  * \return MESH_ERROR_NONE on success.
625  * \return MESH_ERROR_UNKNOWN in case of failure.
626  * */
627  mesh_error_t info_get(ws_rpl_info_t *info_ptr);
628 
629  /**
630  * \brief Get Wi-SUN Stack information.
631  *
632  * Function reads Stack information from nanostack.
633  * Mesh interface must be initialized before calling this function.
634  *
635  * \param stack_info_ptr Structure given to stack where information will be stored
636  *
637  * \return MESH_ERROR_NONE on success.
638  * \return MESH_ERROR_UNKNOWN in case of failure.
639  * */
640  mesh_error_t stack_info_get(ws_stack_state_t *stack_info_ptr);
641 
642  /**
643  * \brief Get Wi-SUN CCA threshold table information.
644  *
645  * Function reads CCA threshold table from nanostack.
646  *
647  ** \param ws_cca_threshold_table_t Structure given to stack where information will be stored
648  **
649  * \return MESH_ERROR_NONE on success.
650  * \return MESH_ERROR_UNKNOWN in case of failure.
651  * */
652  mesh_error_t cca_threshold_table_get(ws_cca_threshold_table_t *table);
653 
654  /**
655  * \brief Get Wi-SUN Neighbor table information.
656  *
657  * To allocate correct amount of memory first use the API with nbr_ptr = NULL to get current amount
658  * of neighbors in count pointer. Then Allocate the memory and call the function to fill the table.
659  *
660  * \param nbr_ptr Pointer to memory where Neighbor table entries can be written.
661  * \param count amount of neighbor table entries allocated to memory.
662  *
663  * \return MESH_ERROR_NONE on success.
664  * \return MESH_ERROR_UNKNOWN in case of failure.
665  * */
666  mesh_error_t nbr_info_get(ws_nbr_info_t *nbr_ptr, uint16_t *count);
667 
668 protected:
669  Nanostack::WisunInterface *get_interface() const;
670  nsapi_error_t do_initialize() override;
671  virtual nsapi_error_t configure();
672 };
673 
674 #endif
ws_nbr_info::rsl_out
uint8_t rsl_out
parent RSSI Out measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) ...
Definition: WisunInterface.h:87
ws_stack_state::join_state
uint8_t join_state
Wi-SUN join state defined by Wi-SUN specification 1-5.
Definition: WisunInterface.h:53
WisunInterface
Wi-SUN mesh network interface class.
Definition: WisunInterface.h:105
ws_rpl_info::version
uint8_t version
RPL version number.
Definition: WisunInterface.h:31
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
ws_nbr_info::rsl_in
uint8_t rsl_in
parent RSSI in measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) t...
Definition: WisunInterface.h:89
ws_nbr_info
Struct ws_nbr_info_t Gives the neighbor information.
Definition: WisunInterface.h:81
ws_rpl_info::primary_parent_rank
uint16_t primary_parent_rank
RPL Primary Parent Rank.
Definition: WisunInterface.h:35
ws_nbr_info::type
ws_nbr_type_e type
Neighbour type (Primary Parent, Secondary Parent, Candidate parent, child, other(Temporary neighbours...
Definition: WisunInterface.h:97
mesh_mac_statistics_t
Mesh physical layer statistics.
Definition: mesh_interface_types.h:108
mesh_nw_statistics_t
Mesh network statistics.
Definition: mesh_interface_types.h:80
ws_stack_state
Struct ws_stack_state Wi-SUN stack information.
Definition: WisunInterface.h:41
ws_rpl_info::instance_id
uint8_t instance_id
Router instance identifier.
Definition: WisunInterface.h:29
ws_cca_threshold_table::cca_threshold_table
const int8_t * cca_threshold_table
CCA threshold table.
Definition: WisunInterface.h:67
ws_cca_threshold_table::number_of_channels
uint8_t number_of_channels
Number of channels.
Definition: WisunInterface.h:65
ws_nbr_info::rpl_rank
uint16_t rpl_rank
RPL Rank value for parents 0xffff for neighbors RANK is unknown.
Definition: WisunInterface.h:91
ws_nbr_info::lifetime
uint32_t lifetime
Remaining lifetime Link lifetime for parents and ARO lifetime for children.
Definition: WisunInterface.h:95
ws_cca_threshold_table
Struct ws_cca_threshold_table Wi-SUN CCA threshold table information.
Definition: WisunInterface.h:63
ws_stack_state::rsl_out
uint8_t rsl_out
parent RSSI Out measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) ...
Definition: WisunInterface.h:49
ws_stack_state::rsl_in
uint8_t rsl_in
parent RSSI in measured RSSI value calculated using EWMA specified by Wi-SUN from range of -174 (0) t...
Definition: WisunInterface.h:51
ws_stack_state::device_min_sens
uint8_t device_min_sens
Device RF minimum sensitivity configuration.
Definition: WisunInterface.h:57
ws_rpl_info::rpl_dodag_id
uint8_t rpl_dodag_id[16]
Router dodag id.
Definition: WisunInterface.h:27
ws_nbr_info::etx
uint16_t etx
Measured ETX value if known set to 0xFFFF if not known or Child.
Definition: WisunInterface.h:93
ws_rpl_info
Struct ws_rpl_info Wi-SUN router RPL information.
Definition: WisunInterface.h:25
ws_rpl_info::current_rank
uint16_t current_rank
RPL DODAG node current Rank.
Definition: WisunInterface.h:33
ws_stack_state::pan_id
uint16_t pan_id
Network PAN ID.
Definition: WisunInterface.h:55
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.