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  /** Address prefix given to devices in network set to 0 if not available*/
27  uint8_t ipv6_prefix[8];
28  /** IID of router */
29  uint8_t ipv6_iid[8];
30  /** Router dodag id */
31  uint8_t rpl_dodag_id[16];
32  /** Router instance identifier */
33  uint8_t instance_id;
34  /** RPL version number */
35  uint8_t version;
36 } ws_rpl_info_t;
37 
38 /** Wi-SUN mesh network interface class
39  *
40  * Configure Nanostack to use Wi-SUN protocol.
41  */
42 class WisunInterface : public MeshInterfaceNanostack {
43 public:
44 
45  /** Create an uninitialized WisunInterface
46  *
47  * Must initialize to initialize the mesh on a phy.
48  */
49  WisunInterface() { }
50 
51  /** Create an initialized WisunInterface
52  *
53  */
54  WisunInterface(NanostackRfPhy *phy) : MeshInterfaceNanostack(phy) { }
55 
56  /**
57  * \brief Set Wi-SUN network name.
58  *
59  * Function stores new network name to mbed-mesh-api and uses it when connect() is called next time.
60  * If device is already connected to the Wi-SUN network then device will restart network discovery after
61  * changing the network name.
62  *
63  * Function overwrites network name defined by Mbed OS configuration.
64  *
65  * \param network_name Network name as NUL terminated string. Can't exceed 32 characters and can't be NULL.
66  * \return MESH_ERROR_NONE on success.
67  * \return MESH_ERROR_UNKNOWN in case of failure.
68  * */
69  mesh_error_t set_network_name(char *network_name);
70 
71  /**
72  * \brief Get Wi-SUN network name.
73  *
74  * Function reads network name from mbed-mesh-api.
75  *
76  * \param network_name Network name as NUL terminated string. Must have space for 33 characters (string and null terminator).
77  * \return MESH_ERROR_NONE on success.
78  * \return MESH_ERROR_UNKNOWN in case of failure.
79  * */
80  mesh_error_t get_network_name(char *network_name);
81 
82  /**
83  * \brief Validate Wi-SUN network name.
84  *
85  * Function validates network name. Function can be used to test that values that will be used on set function are valid.
86  *
87  * \param network_name Network name as NUL terminated string. Can't exceed 32 characters and can't be NULL.
88  * \return MESH_ERROR_NONE on success.
89  * \return MESH_ERROR_UNKNOWN in case of failure.
90  * */
91  mesh_error_t validate_network_name(char *network_name);
92 
93  /**
94  * \brief Set Wi-SUN network regulatory domain, operating class and operating mode.
95  *
96  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
97  * If device is already connected to the Wi-SUN network then device will restart network discovery after
98  * changing the regulatory_domain, operating_class or operating_mode.
99  *
100  * Function overwrites parameters defined by Mbed OS configuration.
101  *
102  * \param regulatory_domain Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
103  * \param operating_class Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
104  * \param operating_mode Values defined in Wi-SUN PHY-specification. Use 0xff to use leave parameter unchanged.
105  * \return MESH_ERROR_NONE on success.
106  * \return MESH_ERROR_UNKNOWN in case of failure.
107  * */
108  mesh_error_t set_network_regulatory_domain(uint8_t regulatory_domain = 0xff, uint8_t operating_class = 0xff, uint8_t operating_mode = 0xff);
109 
110  /**
111  * \brief Get Wi-SUN network regulatory domain, operating class and operating mode.
112  *
113  * Function reads regulatory_domain, operating_class and operating_mode from mbed-mesh-api.
114  *
115  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
116  * \param operating_class Values defined in Wi-SUN PHY-specification.
117  * \param operating_mode Values defined in Wi-SUN PHY-specification.
118  * \return MESH_ERROR_NONE on success.
119  * \return MESH_ERROR_UNKNOWN in case of failure.
120  * */
121  mesh_error_t get_network_regulatory_domain(uint8_t *regulatory_domain, uint8_t *operating_class, uint8_t *operating_mode);
122 
123  /**
124  * \brief Validate Wi-SUN network regulatory domain, operating class and operating mode.
125  *
126  * Function validates regulatory_domain, operating_class and operating_mode. Function can be used to test that values that will
127  * be used on set function are valid.
128  *
129  * \param regulatory_domain Values defined in Wi-SUN PHY-specification.
130  * \param operating_class Values defined in Wi-SUN PHY-specification.
131  * \param operating_mode Values defined in Wi-SUN PHY-specification.
132  * \return MESH_ERROR_NONE on success.
133  * \return MESH_ERROR_UNKNOWN in case of failure.
134  * */
135  mesh_error_t validate_network_regulatory_domain(uint8_t regulatory_domain, uint8_t operating_class, uint8_t operating_mode);
136 
137  /**
138  * \brief Set Wi-SUN network size.
139  *
140  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
141  * If device is already connected to the Wi-SUN network then device will restart network discovery after
142  * changing the network size.
143  *
144  * Default value: medium
145  * Small network size: less than hundred devices
146  * Medium network size: hundreds of devices
147  * Large network size: thousands of devices
148  * Certificate: used on testing
149  *
150  * When network size is changed, it will override all or some of the following configuration values:
151  * - Timing settings set by set_timing_parameters() of the Wi-SUN interface.
152  * - RPL settings set by rpl_parameters_set() of the Border Router interface.
153  *
154  * When network size is changed, and if timing or RPL values should be other than defaults set by stack for the network size,
155  * they need to set again using above function calls.
156  *
157  * \param network_size Network size in hundreds of devices (e.g. 1200 devices is 12), 0x00 for network size certificate.
158  * \return MESH_ERROR_NONE on success.
159  * \return MESH_ERROR_UNKNOWN in case of failure.
160  * */
161  mesh_error_t set_network_size(uint8_t network_size);
162 
163  /**
164  * \brief Get Wi-SUN network size.
165  *
166  * Function reads network size from mbed-mesh-api.
167  *
168  * \param network_size Network size in hundreds of devices, 0x00 for network size certificate.
169  * \return MESH_ERROR_NONE on success.
170  * \return MESH_ERROR_UNKNOWN in case of failure.
171  * */
172  mesh_error_t get_network_size(uint8_t *network_size);
173 
174  /**
175  * \brief Validate Wi-SUN network size.
176  *
177  * Function validates network size from mbed-mesh-api. Function can be used to test that values that will
178  * be used on set function are valid.
179  *
180  * \param network_size Network size in hundreds of devices, 0x00 for network size certificate.
181  * \return MESH_ERROR_NONE on success.
182  * \return MESH_ERROR_UNKNOWN in case of failure.
183  * */
184  mesh_error_t validate_network_size(uint8_t network_size);
185 
186  /**
187  * \brief Set Wi-SUN FHSS channel mask
188  *
189  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
190  * If device is already connected to the Wi-SUN network then settings take effect right away.
191  *
192  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
193  * \return MESH_ERROR_NONE on success.
194  * \return MESH_ERROR_UNKNOWN in case of failure.
195  * */
196  mesh_error_t set_channel_mask(uint32_t channel_mask[8]);
197 
198  /**
199  * \brief Get Wi-SUN FHSS channel mask
200  *
201  * Function reads FHSS channel mask from mbed-mesh-api.
202  *
203  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
204  * \return MESH_ERROR_NONE on success.
205  * \return MESH_ERROR_UNKNOWN in case of failure.
206  * */
207  mesh_error_t get_channel_mask(uint32_t *channel_mask);
208 
209  /**
210  * \brief Validate Wi-SUN FHSS channel mask
211  *
212  * Function validates FHSS channel mask. Function can be used to test that values that will
213  * be used on set function are valid.
214  *
215  * \param channel_mask Values defined in Wi-SUN management API. Channel mask bit field.
216  * \return MESH_ERROR_NONE on success.
217  * \return MESH_ERROR_UNKNOWN in case of failure.
218  * */
219  mesh_error_t validate_channel_mask(uint32_t channel_mask[8]);
220 
221  /**
222  * \brief Set Wi-SUN FHSS unicast channel function parameters
223  *
224  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
225  * If device is already connected to the Wi-SUN network then device will restart network discovery after
226  * changing the channel function, fixed channel or dwell interval.
227  *
228  * Function overwrites parameters defined by Mbed OS configuration.
229  *
230  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
231  * \param fixed_channel Used channel when channel function is fixed channel. Use 0xffff when fixed channel function not on use.
232  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1. Use 0x00 to use leave parameter unchanged.
233  * \return MESH_ERROR_NONE on success.
234  * \return MESH_ERROR_UNKNOWN in case of failure.
235  * */
236  mesh_error_t set_unicast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel = 0xffff, uint8_t dwell_interval = 0x00);
237 
238  /**
239  * \brief Get Wi-SUN FHSS unicast channel function parameters
240  *
241  * Function reads FHSS unicast channel function parameters from mbed-mesh-api.
242  *
243  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
244  * \param fixed_channel Used channel when channel function is fixed channel.
245  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
246  * \return MESH_ERROR_NONE on success.
247  * \return MESH_ERROR_UNKNOWN in case of failure.
248  * */
249  mesh_error_t get_unicast_channel_function(mesh_channel_function_t *channel_function, uint16_t *fixed_channel, uint8_t *dwell_interval);
250 
251  /**
252  * \brief Validate Wi-SUN FHSS unicast channel function parameters
253  *
254  * Function validates FHSS unicast channel function parameters. Function can be used to test that values that will
255  * be used on set function are valid.
256  *
257  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
258  * \param fixed_channel Used channel when channel function is fixed channel.
259  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
260  * \return MESH_ERROR_NONE on success.
261  * \return MESH_ERROR_UNKNOWN in case of failure.
262  * */
263  mesh_error_t validate_unicast_channel_function(mesh_channel_function_t channel_function, uint16_t fixed_channel, uint8_t dwell_interval);
264 
265  /**
266  * \brief Set Wi-SUN FHSS broadcast channel function parameters
267  *
268  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
269  * If device is already connected to the Wi-SUN network then device will restart network discovery after
270  * changing the channel function, fixed channel, dwell interval or broadcast_interval.
271  *
272  * Function overwrites parameters defined by Mbed OS configuration.
273  *
274  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
275  * \param fixed_channel Used channel when channel function is fixed channel. Use 0xffff when fixed channel function not on use.
276  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1. Use 0x00 to use leave parameter unchanged.
277  * \param broadcast_interval Used broadcast interval. Use 0x00 to use leave parameter unchanged.
278  * \return MESH_ERROR_NONE on success.
279  * \return MESH_ERROR_UNKNOWN in case of failure.
280  * */
281  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);
282 
283  /**
284  * \brief Get Wi-SUN FHSS broadcast channel function parameters
285  *
286  * Function reads FHSS broadcast channel function parameters from mbed-mesh-api.
287  *
288  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
289  * \param fixed_channel Used channel when channel function is fixed channel.
290  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
291  * \param broadcast_interval Used broadcast interval.
292  * \return MESH_ERROR_NONE on success.
293  * \return MESH_ERROR_UNKNOWN in case of failure.
294  * */
295  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);
296 
297  /**
298  * \brief Validate Wi-SUN FHSS broadcast channel function parameters
299  *
300  * Function validates FHSS broadcast channel function parameters from mbed-mesh-api. Function can be used to test that values that will
301  * be used on set function are valid.
302  *
303  * \param channel_function Channel function. Fixed, TR51CF, DH1CF or vendor defined.
304  * \param fixed_channel Used channel when channel function is fixed channel.
305  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
306  * \param broadcast_interval Used broadcast interval.
307  * \return MESH_ERROR_NONE on success.
308  * \return MESH_ERROR_UNKNOWN in case of failure.
309  * */
310  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);
311 
312  /**
313  * \brief Set Wi-SUN timing parameters
314  *
315  * Function stores new parameters to mbed-mesh-api and uses them when connect() is called next time.
316  * If device is already connected to the Wi-SUN network then settings take effect right away.
317  *
318  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds. Use 0x00 to use leave parameter unchanged.
319  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin. Use 0x00 to use leave parameter unchanged.
320  * \param disc_trickle_k Discovery trickle k. Use 0x00 to use leave parameter unchanged.
321  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds. Use 0x00 to use leave parameter unchanged.
322  * \return MESH_ERROR_NONE on success.
323  * \return MESH_ERROR_UNKNOWN in case of failure.
324  * */
325  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);
326 
327  /**
328  * \brief Get Wi-SUN timing parameters
329  *
330  * Function reads timing parameters from mbed-mesh-api.
331  *
332  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds.
333  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin.
334  * \param disc_trickle_k Discovery trickle k.
335  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds.
336  * \return MESH_ERROR_NONE on success.
337  * \return MESH_ERROR_UNKNOWN in case of failure.
338  * */
339  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);
340 
341  /**
342  * \brief Validates Wi-SUN timing parameters
343  *
344  * Function validates timing parameters. Function can be used to test that values that will be used on set
345  * function are valid.
346  *
347  * \param disc_trickle_imin Discovery trickle Imin. Range 1-255 seconds.
348  * \param disc_trickle_imax Discovery trickle Imax. Range (2-2^8)*Imin.
349  * \param disc_trickle_k Discovery trickle k.
350  * \param pan_timeout PAN timeout; seconds; Range 60-15300 seconds.
351  * \return MESH_ERROR_NONE on success.
352  * \return MESH_ERROR_UNKNOWN in case of failure.
353  * */
354  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);
355 
356  /**
357  * \brief Set own certificate and private key reference to the Wi-SUN network.
358  *
359  * Function can be called several times if intermediate certificates are used. Then each call to the function
360  * adds a certificate reference to own certificate chain. Certificates are in bottom up order i.e. the top certificate is given last.
361  *
362  * Function must be called before connecting the device i.e before call to connect() method.
363  * Function will not copy certificate or key, therefore addresses must remain valid.
364  *
365  * \param cert Certificate address.
366  * \param cert_len Certificate length in bytes.
367  * \param cert_key Certificate key address.
368  * \param cert_key_len Certificate key length in bytes.
369  * \return MESH_ERROR_NONE on success.
370  * \return MESH_ERROR_STATE if method is called after calling connect().
371  * \return MESH_ERROR_MEMORY in case of memory allocation failure.
372  * */
373  mesh_error_t set_own_certificate(uint8_t *cert, uint16_t cert_len, uint8_t *cert_key = NULL, uint16_t cert_key_len = 0);
374 
375  /**
376  * \brief Remove own certificates from the Wi-SUN network.
377  *
378  * Function must be called before connecting the device i.e before call to connect() method.
379  *
380  * \return MESH_ERROR_NONE on success.
381  * \return MESH_ERROR_STATE if method is called after calling connect().
382  * */
383  mesh_error_t remove_own_certificates(void);
384 
385  /**
386  * \brief Set trusted certificate reference to the Wi-SUN network.
387  *
388  * Function can be called several times. Certificates are in bottom up order i.e. the top certificate is given last.
389  *
390  * Function must be called before connecting the device i.e before call to connect() method.
391  * Function will not copy certificate, therefore addresses must remain valid.
392  *
393  * \param cert Certificate address.
394  * \param cert_len Certificate length in bytes.
395  * \return MESH_ERROR_NONE on success.
396  * \return MESH_ERROR_STATE if method is called after calling connect().
397  * \return MESH_ERROR_MEMORY in case of memory allocation failure.
398  * */
399  mesh_error_t set_trusted_certificate(uint8_t *cert, uint16_t cert_len);
400 
401  /**
402  * \brief Remove trusted certificates from the Wi-SUN network.
403  *
404  * Function must be called before connecting the device i.e before call to connect() method.
405  *
406  * \return MESH_ERROR_NONE on success.
407  * \return MESH_ERROR_STATE if method is called after calling connect().
408  * */
409  mesh_error_t remove_trusted_certificates(void);
410 
411  /**
412  * \brief Get router IP address
413  *
414  * \param address
415  * \param len
416  * */
417  bool getRouterIpAddress(char *address, int8_t len);
418 
419  /**
420  * \brief Enable Wi-SUN statistics
421  *
422  * After enabling statistics those can be read using the network, physical layer,
423  * MAC and FHSS and Wi-SUN statistics read functions.
424  *
425  * \return MESH_ERROR_NONE on success.
426  * \return MESH_ERROR_UNKNOWN on error
427  * */
428  mesh_error_t enable_statistics(void);
429 
430  /**
431  * \brief Reads Wi-SUN network statistics
432  *
433  * Reads network statistics.
434  *
435  * \param statistics Network statistics.
436  * \return MESH_ERROR_NONE on success.
437  * \return MESH_ERROR_UNKNOWN on error
438  * */
439  mesh_error_t read_nw_statistics(mesh_nw_statistics_t *statistics);
440 
441  /**
442  * \brief Reads Wi-SUN MAC statistics
443  *
444  * Reads MAC statistics.
445  *
446  * \param statistics MAC statistics.
447  * \return MESH_ERROR_NONE on success.
448  * \return MESH_ERROR_UNKNOWN on error
449  * */
450  mesh_error_t read_mac_statistics(mesh_mac_statistics_t *statistics);
451 
452  /**
453  * \brief Get Wi-SUN Router information.
454  *
455  * Function reads RPL information from nanostack.
456  * Mesh interface must be initialized before calling this function.
457  *
458  * \param info_ptr Structure given to stack where information will be stored
459  *
460  * \return MESH_ERROR_NONE on success.
461  * \return MESH_ERROR_UNKNOWN in case of failure.
462  * */
463  mesh_error_t info_get(ws_rpl_info_t *info_ptr);
464 
465 protected:
466  Nanostack::WisunInterface *get_interface() const;
467  virtual nsapi_error_t do_initialize();
468  virtual nsapi_error_t configure();
469 };
470 
471 #endif
NanostackRfPhy
Radio PHY driver class for Nanostack.
Definition: NanostackRfPhy.h:24
WisunInterface
Wi-SUN mesh network interface class.
Definition: WisunInterface.h:42
ws_rpl_info::version
uint8_t version
RPL version number.
Definition: WisunInterface.h:35
nsapi_error_t
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
mesh_mac_statistics_t
Mesh physical layer statistics.
Definition: mesh_interface_types.h:91
mesh_nw_statistics_t
Mesh network statistics.
Definition: mesh_interface_types.h:80
ws_rpl_info::instance_id
uint8_t instance_id
Router instance identifier.
Definition: WisunInterface.h:33
ws_rpl_info::ipv6_iid
uint8_t ipv6_iid[8]
IID of router.
Definition: WisunInterface.h:29
WisunInterface::WisunInterface
WisunInterface()
Create an uninitialized WisunInterface.
Definition: WisunInterface.h:49
WisunInterface::WisunInterface
WisunInterface(NanostackRfPhy *phy)
Create an initialized WisunInterface.
Definition: WisunInterface.h:54
ws_rpl_info::rpl_dodag_id
uint8_t rpl_dodag_id[16]
Router dodag id.
Definition: WisunInterface.h:31
ws_rpl_info
Struct ws_rpl_info Wi-SUN router RPL information.
Definition: WisunInterface.h:25
ws_rpl_info::ipv6_prefix
uint8_t ipv6_prefix[8]
Address prefix given to devices in network set to 0 if not available.
Definition: WisunInterface.h:27
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.