Mistake on this page?
Report an issue in GitHub or email us
WisunBorderRouter.h
1 /*
2  * Copyright (c) 2020 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 WISUNBORDERROUTER_H
18 #define WISUNBORDERROUTER_H
19 
20 /**
21  * \brief Struct br_information Border router dynamic information.
22  */
23 typedef struct ws_br_info {
24  /** Address prefix given to devices in network set to 0 if not available*/
25  uint8_t ipv6_prefix[8];
26  /** IID of Border router */
27  uint8_t ipv6_iid[8];
28  /** Border router dodag id */
29  uint8_t rpl_dodag_id[16];
30  /** Border router instance identifier defined in RPL */
31  uint8_t instance_id;
32  /** RPL version number */
33  uint8_t version;
34  /** Timestamp of the the device. Can be used as version number*/
35  uint64_t host_timestamp;
36  /** Amount of devices in the network. */
37  uint16_t device_count;
38  /** Gateway Local Address */
39  uint8_t gateway_addr[16];
40 } ws_br_info_t;
41 
42 /**
43  * \brief Struct br_route_info is parent child relation structure.
44  */
45 typedef struct ws_br_route_info {
46  /** IID of target device
47  * Public IPv6 address can be formed by combining prefix + IID*/
48  uint8_t target[8];
49  /** IID of parent*/
50  uint8_t parent[8];
52 
53 /**
54  * \brief Struct ws_br_radius_timing_t is RADIUS timing configuration structure.
55  */
56 typedef struct ws_br_radius_timing {
57  /** RADIUS retry trickle timer Imin; in 100ms units; range 1-1200; default 20 (2 seconds) */
59  /** RADIUS retry trickle timer Imax; in 100ms units; range 1-1200; default 30 (3 seconds) */
61  /** RADIUS retry trickle count; default 3 */
64 
65 /** Wi-SUN Border Router class
66  *
67  * Class can be used to start, stop and configure Wi-SUN Border Router.
68  */
70 public:
71 
72  /** Create WisunBorderRouter
73  *
74  * */
76 
77  /**
78  * \brief Start Wi-SUN Border Router
79  *
80  * Starts Wi-SUN Border Router and routing between the mesh and backbone interfaces. Network interfaces
81  * must be initialized and connected before calling the start. Backbone interface can be either Ethernet
82  * (EMAC) or Cellular.
83  *
84  * \param mesh_if Wi-SUN mesh network interface
85  * \param backbone_if Backbone network interface
86  * \return MESH_ERROR_NONE on success.
87  * \return MESH_ERROR_UNKNOWN in case of failure.
88  * */
89  mesh_error_t start(NetworkInterface *mesh_if, NetworkInterface *backbone_if);
90 
91  /**
92  * \brief Start Wi-SUN Border Router
93  *
94  * Starts Wi-SUN Border Router and routing between the mesh and backbone interfaces. Mesh network interface
95  * must be initialized and connected before calling the start. Backbone OnboardNetworkStack::Interface must
96  * be brought up before calling the start. Backbone interface can be either Ethernet (EMAC) or Cellular (PPP).
97  *
98  * \param mesh_if Wi-SUN mesh network interface
99  * \param backbone_if Backbone OnboardNetworkStack::Interface interface
100  * \return MESH_ERROR_NONE on success.
101  * \return MESH_ERROR_UNKNOWN in case of failure.
102  * */
103  mesh_error_t start(NetworkInterface *mesh_if, OnboardNetworkStack::Interface *backbone_if);
104 
105  /**
106  * \brief Stop Wi-SUN Border Router
107  *
108  * Stops Wi-SUN Border Router.
109  *
110  * */
111  void stop();
112 
113  /**
114  * \brief Set Wi-SUN RPL DIO trickle parameters.
115  *
116  * Function stores new parameters to Border Router and uses them when mesh interface connect() is called
117  * next time. If device is already connected to the Wi-SUN network then device will restart Wi-SUN network after
118  * changing the RPL DIO trickle parameters. Mesh interface must be initialized before calling this
119  * function.
120  *
121  * \param dio_interval_min DIO trickle timer Imin parameter. Use 0x00 to use leave parameter unchanged.
122  * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin. Use 0x00 to use leave parameter unchanged.
123  * \param dio_redundancy_constant DIO trickle timer redundancy constant. Use 0xff to use leave parameter unchanged.
124  * \return MESH_ERROR_NONE on success.
125  * \return MESH_ERROR_UNKNOWN in case of failure.
126  * */
127  mesh_error_t set_rpl_parameters(uint8_t dio_interval_min, uint8_t dio_interval_doublings, uint8_t dio_redundancy_constant);
128 
129  /**
130  * \brief Get Wi-SUN RPL DIO trickle parameters.
131  *
132  * Function reads DIO trickle timer Imin, DIO trickle timer Imax and DIO trickle timer redundancy
133  * constant from Border Router. Mesh interface must be initialized before calling this function.
134  *
135  * \param dio_interval_min DIO trickle timer Imin parameter.
136  * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin.
137  * \param dio_redundancy_constant DIO trickle timer redundancy constant.
138  * \return MESH_ERROR_NONE on success.
139  * \return MESH_ERROR_UNKNOWN in case of failure.
140  * */
141  mesh_error_t get_rpl_parameters(uint8_t *dio_interval_min, uint8_t *dio_interval_doublings, uint8_t *dio_redundancy_constant);
142 
143  /**
144  * \brief Validate Wi-SUN RPL DIO trickle parameters.
145  *
146  * Function validates DIO trickle timer Imin, DIO trickle timer Imax and DIO trickle timer redundancy
147  * constant. Function can be used to test that values that will be used on set function are valid.
148  * Mesh interface must be initialized before the calling this function.
149  *
150  * \param dio_interval_min DIO trickle timer Imin parameter.
151  * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin.
152  * \param dio_redundancy_constant DIO trickle timer redundancy constant.
153  * \return MESH_ERROR_NONE on success.
154  * \return MESH_ERROR_UNKNOWN in case of failure.
155  * */
156  mesh_error_t validate_rpl_parameters(uint8_t dio_interval_min, uint8_t dio_interval_doublings, uint8_t dio_redundancy_constant);
157 
158  /**
159  * \brief Set Wi-SUN PAN configuration parameters.
160  *
161  * Function stores new parameters to Border Router and uses them when mesh interface connect() is called
162  * next time. If device is already connected to the Wi-SUN network then device will restart Wi-SUN network after
163  * changing the PAN configuration parameters. Mesh interface must be initialized before calling this
164  * function.
165  *
166  * \param pan_id PAN ID. 0xffff will generate the PAN ID on the mesh interface connect() call if not already generated.
167  * \return MESH_ERROR_NONE on success.
168  * \return MESH_ERROR_UNKNOWN in case of failure.
169  * */
170  mesh_error_t set_pan_configuration(uint16_t pan_id);
171 
172  /**
173  * \brief Get Wi-SUN PAN configuration parameters.
174  *
175  * Function reads PAN ID from Border Router. Mesh interface must be initialized before calling this function.
176  *
177  * \param pan_id PAN ID.
178  * \return MESH_ERROR_NONE on success.
179  * \return MESH_ERROR_UNKNOWN in case of failure.
180  * */
181  mesh_error_t get_pan_configuration(uint16_t *pan_id);
182 
183  /**
184  * \brief Validate Wi-SUN PAN configuration parameters.
185  *
186  * Function validates PAN ID. Function can be used to test that values that will be used on set function are valid.
187  * Mesh interface must be initialized before calling this function.
188  *
189  * \param pan_id PAN ID.
190  * \return MESH_ERROR_NONE on success.
191  * \return MESH_ERROR_UNKNOWN in case of failure.
192  * */
193  mesh_error_t validate_pan_configuration(uint16_t pan_id);
194 
195  /**
196  * \brief Get Wi-SUN Border Router information.
197  *
198  * Function reads RPL information from Border Router.
199  * Mesh interface must be initialized before calling this function.
200  *
201  * \param info_ptr Structure given to stack where information will be stored
202  *
203  * \return MESH_ERROR_NONE on success.
204  * \return MESH_ERROR_UNKNOWN in case of failure.
205  * */
206  mesh_error_t info_get(ws_br_info_t *info_ptr);
207 
208  /**
209  * \brief Get Wi-SUN neighbor table information.
210  *
211  * Function reads Routing Table information from Border Router.
212  * Table is Parent child relation using the Global address IID of the devices.
213  * To get the full IPv6 address of the device, IPv6 = Global Prefix + IID.
214  * Mesh interface must be initialized before calling this function.
215  *
216  * \param table_ptr Application allocated memory block where routing table is written.
217  * \param table_len Length of the table allocated by application given as amount of entries.
218  *
219  * \returns 0 - x on success indicates number of entries written to the table_ptr.
220  * \return <0 in case of errors.
221  * */
222  int routing_table_get(ws_br_route_info_t *table_ptr, uint16_t table_len);
223 
224  /**
225  * \brief Set Wi-SUN RADIUS server IPv6 address.
226  *
227  * Function sets external RADIUS server IPv6 address to Border Router. Setting the address enables
228  * external RADIUS server interface on Border Router. To disable external RADIUS server interface,
229  * call the function with address set to NULL. The RADIUS shared secret must be set before address
230  * is set using set_radius_shared_secret() call.
231  *
232  * \param address Pointer to IPv6 address string or NULL to disable RADIUS. Address string format is e.g. 2001:1234::1 and it is NUL terminated.
233  * \return MESH_ERROR_NONE on success.
234  * \return MESH_ERROR_UNKNOWN in case of failure.
235  * */
236  mesh_error_t set_radius_server_ipv6_address(const char *address);
237 
238  /**
239  * \brief Get Wi-SUN RADIUS server IPv6 address.
240  *
241  * Function gets external RADIUS server IPv6 address from Border Router.
242  *
243  * \param address Pointer to buffer where to write IPv6 address string. Must have space at least for 39 characters and NUL terminator.
244  * \return MESH_ERROR_NONE on success.
245  * \return error value in case of failure, e.g. if address has not been set to Border Router.
246  * */
247  mesh_error_t get_radius_server_ipv6_address(char *address);
248 
249  /**
250  * \brief Set Wi-SUN RADIUS shared secret.
251  *
252  * Function sets RADIUS shared secret to Border Router. Shared secret may be an ASCII string. Check
253  * the format and length constraints for the shared secret from the documentation of RADIUS server you
254  * are connecting to.
255  *
256  * \param shared_secret_len The length of the shared secret in bytes.
257  * \param shared_secret Pointer to shared secret. Can be 8-bit ASCII string or byte array. Is not NUL terminated.
258  * \return MESH_ERROR_NONE on success.
259  * \return error value in case of failure.
260  * */
261  mesh_error_t set_radius_shared_secret(uint16_t shared_secret_len, const uint8_t *shared_secret);
262 
263  /**
264  * \brief Get Wi-SUN RADIUS shared secret.
265  *
266  * Function gets RADIUS shared secret from Border Router.
267  *
268  * \param shared_secret_len On function call, is the size of the shared secret write buffer in bytes, on return is the shared secret length in bytes.
269  * \param shared_secret Pointer to buffer where to write shared secret or NULL. At maximum, bytes set by the length parameter are written. If NULL only buffer length is returned.
270  * \return MESH_ERROR_NONE on success.
271  * \return error value in case of failure.
272  * */
273  mesh_error_t get_radius_shared_secret(uint16_t *shared_secret_len, uint8_t *shared_secret);
274 
275  /**
276  * \brief Set Wi-SUN RADIUS timing parameters.
277  *
278  * Function sets RADIUS timing parameters to Border Router. For RADIUS retry trickle timer default
279  * settings are that the first retry is done between 1 to 3 seconds after the initial attempt and
280  * all retries are done in maximum in 9 seconds.
281  *
282  * \param timing Timing parameters.
283  * \return MESH_ERROR_NONE on success.
284  * \return error value in case of failure.
285  * */
286  mesh_error_t set_radius_timing(ws_br_radius_timing_t *timing);
287 
288  /**
289  * \brief Get Wi-SUN RADIUS timing parameters.
290  *
291  * Function gets RADIUS timing parameters from Border Router.
292  *
293  * \param timing Timing parameters.
294  * \return MESH_ERROR_NONE on success.
295  * \return error value in case of failure.
296  * */
297  mesh_error_t get_radius_timing(ws_br_radius_timing_t *timing);
298 
299  /**
300  * \brief Validate Wi-SUN RADIUS timing parameters.
301  *
302  * Function validates RADIUS timing parameters on Border Router.
303  *
304  * \param timing Timing parameters.
305  * \return MESH_ERROR_NONE on success.
306  * \return error value in case of failure.
307  * */
308  mesh_error_t validate_radius_timing(ws_br_radius_timing_t *timing);
309 
310  /**
311  * \brief Set DNS query result to Nanostack cache.
312  *
313  * Function sets DNS query result to Nanostack cache to get distributed to the devices in the Wi-SUN network.
314  * Function must be called for a running Wi-SUN Border Router instance.
315  *
316  * \param address resolved address of domain_name.
317  * \param domain_name name of the domain. Must be non-NULL.
318  * \return MESH_ERROR_NONE on success.
319  * \return error value in case of failure.
320  * */
321  mesh_error_t set_dns_query_result(SocketAddress *address, char *domain_name);
322 
323 private:
324  mesh_error_t configure();
325  mesh_error_t apply_configuration(int8_t mesh_if_id);
326  mesh_error_t set_bbr_radius_address(void);
327  mesh_error_t set_bbr_radius_shared_secret(void);
328  mesh_error_t set_bbr_radius_timing(void);
329  char _radius_ipv6_addr[40];
330  ws_br_radius_timing_t _radius_timing = {
331  .radius_retry_imin = 0,
332  .radius_retry_imax = 0,
333  .radius_retry_count = 0
334  };
335  char *_shared_secret = NULL;
336  uint16_t _shared_secret_len = 0;
337  int8_t _mesh_if_id = -1;
338  bool _radius_ipv6_addr_set = false;
339  bool _configured = false;
340  bool _radius_timing_set = false;
341 };
342 
343 #endif
uint8_t radius_retry_count
RADIUS retry trickle count; default 3.
Wi-SUN Border Router class.
uint16_t radius_retry_imax
RADIUS retry trickle timer Imax; in 100ms units; range 1-1200; default 30 (3 seconds) ...
uint16_t radius_retry_imin
RADIUS retry trickle timer Imin; in 100ms units; range 1-1200; default 20 (2 seconds) ...
uint8_t version
RPL version number.
Representation of a stack&#39;s view of an interface.
Struct br_information Border router dynamic information.
uint8_t rpl_dodag_id[16]
Border router dodag id.
uint64_t host_timestamp
Timestamp of the the device.
uint8_t instance_id
Border router instance identifier defined in RPL.
Struct ws_br_radius_timing_t is RADIUS timing configuration structure.
uint8_t gateway_addr[16]
Gateway Local Address.
uint16_t device_count
Amount of devices in the network.
SocketAddress class.
Definition: SocketAddress.h:37
Common interface that is shared between network devices.
Struct br_route_info is parent child relation structure.
uint8_t ipv6_iid[8]
IID of Border router.
uint8_t ipv6_prefix[8]
Address prefix given to devices in network set to 0 if not available.
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.