Mbed OS Reference | WisunBorderRouter.h Source File

 /*
  * Copyright (c) 2020 ARM Limited. All rights reserved.
  * SPDX-License-Identifier: Apache-2.0
  * Licensed under the Apache License, Version 2.0 (the License); you may
  * not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 
 #ifndef WISUNBORDERROUTER_H
 #define WISUNBORDERROUTER_H
 
 /**
  * \brief Struct br_information Border router dynamic information.
  */
 typedef struct ws_br_info {
     /** Address prefix given to devices in network  set to 0 if not available*/
     uint8_t ipv6_prefix[8];
     /** IID of Border router */
     uint8_t ipv6_iid[8];
     /** Border router dodag id */
     uint8_t rpl_dodag_id[16];
     /** Border router instance identifier defined in RPL */
     uint8_t instance_id;
     /** RPL version number */
     uint8_t version;
     /** Timestamp of the the device. Can be used as version number*/
     uint64_t host_timestamp;
     /** Amount of devices in the network. */
     uint16_t device_count;
     /** Gateway Local Address */
     uint8_t gateway_addr[16];
 } ws_br_info_t;
 
 /**
  * \brief Struct br_route_info is parent child relation structure.
  */
 typedef struct ws_br_route_info {
     /** IID of target device
      * Public IPv6 address can be formed by combining prefix + IID*/
     uint8_t target[8];
     /** IID of parent*/
     uint8_t parent[8];
 } ws_br_route_info_t;
 
 /**
  * \brief Struct ws_br_radius_timing_t is RADIUS timing configuration structure.
  */
 typedef struct ws_br_radius_timing {
     /** RADIUS retry trickle timer Imin; in 100ms units; range 1-1200; default 20 (2 seconds) */
     uint16_t radius_retry_imin;
     /** RADIUS retry trickle timer Imax; in 100ms units; range 1-1200; default 30 (3 seconds) */
     uint16_t radius_retry_imax;
     /** RADIUS retry trickle count; default 3 */
     uint8_t radius_retry_count;
 } ws_br_radius_timing_t;
 
 /** Wi-SUN Border Router class
  *
  * Class can be used to start, stop and configure Wi-SUN Border Router.
  */
 class WisunBorderRouter {
 public:
 
     /** Create WisunBorderRouter
      *
      * */
     WisunBorderRouter();
 
     /**
      * \brief Start Wi-SUN Border Router
      *
      * Starts Wi-SUN Border Router and routing between the mesh and backbone interfaces. Network interfaces
      * must be initialized and connected before calling the start. Backbone interface can be either Ethernet
      * (EMAC) or Cellular.
      *
      * \param mesh_if Wi-SUN mesh network interface
      * \param backbone_if Backbone network interface
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t start(NetworkInterface *mesh_if, NetworkInterface *backbone_if);
 
     /**
      * \brief Start Wi-SUN Border Router
      *
      * Starts Wi-SUN Border Router and routing between the mesh and backbone interfaces. Mesh network interface
      * must be initialized and connected before calling the start. Backbone OnboardNetworkStack::Interface must
      * be brought up before calling the start. Backbone interface can be either Ethernet (EMAC) or Cellular (PPP).
      *
      * \param mesh_if Wi-SUN mesh network interface
      * \param backbone_if Backbone OnboardNetworkStack::Interface interface
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t start(NetworkInterface *mesh_if, OnboardNetworkStack::Interface *backbone_if);
 
     /**
      * \brief Stop Wi-SUN Border Router
      *
      * Stops Wi-SUN Border Router.
      *
      * */
     void stop();
 
     /**
      * \brief Set Wi-SUN RPL DIO trickle parameters.
      *
      * Function stores new parameters to Border Router and uses them when mesh interface connect() is called
      * next time. If device is already connected to the Wi-SUN network then device will restart Wi-SUN network after
      * changing the RPL DIO trickle parameters. Mesh interface must be initialized before calling this
      * function.
      *
      * \param dio_interval_min DIO trickle timer Imin parameter. Use 0x00 to use leave parameter unchanged.
      * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin. Use 0x00 to use leave parameter unchanged.
      * \param dio_redundancy_constant DIO trickle timer redundancy constant. Use 0xff to use leave parameter unchanged.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t set_rpl_parameters(uint8_t dio_interval_min, uint8_t dio_interval_doublings, uint8_t dio_redundancy_constant);
 
     /**
      * \brief Get Wi-SUN RPL DIO trickle parameters.
      *
      * Function reads DIO trickle timer Imin, DIO trickle timer Imax and DIO trickle timer redundancy
      * constant from Border Router. Mesh interface must be initialized before calling this function.
      *
      * \param dio_interval_min DIO trickle timer Imin parameter.
      * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin.
      * \param dio_redundancy_constant DIO trickle timer redundancy constant.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t get_rpl_parameters(uint8_t *dio_interval_min, uint8_t *dio_interval_doublings, uint8_t *dio_redundancy_constant);
 
     /**
      * \brief Validate Wi-SUN RPL DIO trickle parameters.
      *
      * Function validates DIO trickle timer Imin, DIO trickle timer Imax and DIO trickle timer redundancy
      * constant. Function can be used to test that values that will be used on set function are valid.
      * Mesh interface must be initialized before the calling this function.
      *
      * \param dio_interval_min DIO trickle timer Imin parameter.
      * \param dio_interval_doublings DIO trickle timer Imax parameter as doublings of Imin.
      * \param dio_redundancy_constant DIO trickle timer redundancy constant.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t validate_rpl_parameters(uint8_t dio_interval_min, uint8_t dio_interval_doublings, uint8_t dio_redundancy_constant);
 
     /**
      * \brief Set Wi-SUN PAN configuration parameters.
      *
      * Function stores new parameters to Border Router and uses them when mesh interface connect() is called
      * next time. If device is already connected to the Wi-SUN network then device will restart Wi-SUN network after
      * changing the PAN configuration parameters. Mesh interface must be initialized before calling this
      * function.
      *
      * \param pan_id PAN ID. 0xffff will generate the PAN ID on the mesh interface connect() call if not already generated.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t set_pan_configuration(uint16_t pan_id);
 
     /**
      * \brief Get Wi-SUN PAN configuration parameters.
      *
      * Function reads PAN ID from Border Router. Mesh interface must be initialized before calling this function.
      *
      * \param pan_id PAN ID.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t get_pan_configuration(uint16_t *pan_id);
 
     /**
      * \brief Validate Wi-SUN PAN configuration parameters.
      *
      * Function validates PAN ID. Function can be used to test that values that will be used on set function are valid.
      * Mesh interface must be initialized before calling this function.
      *
      * \param pan_id PAN ID.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t validate_pan_configuration(uint16_t pan_id);
 
     /**
      * \brief Get Wi-SUN Border Router information.
      *
      * Function reads RPL information from Border Router.
      * Mesh interface must be initialized before calling this function.
      *
      * \param info_ptr Structure given to stack where information will be stored
      *
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t info_get(ws_br_info_t *info_ptr);
 
     /**
      * \brief Get Wi-SUN neighbor table information.
      *
      * Function reads Routing Table information from Border Router.
      * Table is Parent child relation using the Global address IID of the devices.
      * To get the full IPv6 address of the device, IPv6 =  Global Prefix + IID.
      * Mesh interface must be initialized before calling this function.
      *
      * \param table_ptr Application allocated memory block where routing table is written.
      * \param table_len Length of the table allocated by application given as amount of entries.
      *
      * \returns 0 - x on success indicates number of entries written to the table_ptr.
      * \return <0 in case of errors.
      * */
     int routing_table_get(ws_br_route_info_t *table_ptr, uint16_t table_len);
 
     /**
      * \brief Set Wi-SUN RADIUS server IPv6 address.
      *
      * Function sets external RADIUS server IPv6 address to Border Router. Setting the address enables
      * external RADIUS server interface on Border Router. To disable external RADIUS server interface,
      * call the function with address set to NULL. The RADIUS shared secret must be set before address
      * is set using set_radius_shared_secret() call.
      *
      * \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.
      * \return MESH_ERROR_NONE on success.
      * \return MESH_ERROR_UNKNOWN in case of failure.
      * */
     mesh_error_t set_radius_server_ipv6_address(const char *address);
 
     /**
      * \brief Get Wi-SUN RADIUS server IPv6 address.
      *
      * Function gets external RADIUS server IPv6 address from Border Router.
      *
      * \param address Pointer to buffer where to write IPv6 address string. Must have space at least for 39 characters and NUL terminator.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure, e.g. if address has not been set to Border Router.
      * */
     mesh_error_t get_radius_server_ipv6_address(char *address);
 
     /**
      * \brief Set Wi-SUN RADIUS shared secret.
      *
      * Function sets RADIUS shared secret to Border Router. Shared secret may be an ASCII string. Check
      * the format and length constraints for the shared secret from the documentation of RADIUS server you
      * are connecting to.
      *
      * \param shared_secret_len The length of the shared secret in bytes.
      * \param shared_secret Pointer to shared secret. Can be 8-bit ASCII string or byte array. Is not NUL terminated.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t set_radius_shared_secret(uint16_t shared_secret_len, const uint8_t *shared_secret);
 
     /**
      * \brief Get Wi-SUN RADIUS shared secret.
      *
      * Function gets RADIUS shared secret from Border Router.
      *
      * \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.
      * \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.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t get_radius_shared_secret(uint16_t *shared_secret_len, uint8_t *shared_secret);
 
     /**
      * \brief Set Wi-SUN RADIUS timing parameters.
      *
      * Function sets RADIUS timing parameters to Border Router. For RADIUS retry trickle timer default
      * settings are that the first retry is done between 1 to 3 seconds after the initial attempt and
      * all retries are done in maximum in 9 seconds.
      *
      * \param timing Timing parameters.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t set_radius_timing(ws_br_radius_timing_t *timing);
 
     /**
      * \brief Get Wi-SUN RADIUS timing parameters.
      *
      * Function gets RADIUS timing parameters from Border Router.
      *
      * \param timing Timing parameters.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t get_radius_timing(ws_br_radius_timing_t *timing);
 
     /**
      * \brief Validate Wi-SUN RADIUS timing parameters.
      *
      * Function validates RADIUS timing parameters on Border Router.
      *
      * \param timing Timing parameters.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t validate_radius_timing(ws_br_radius_timing_t *timing);
 
     /**
      * \brief Set DNS query result to Nanostack cache.
      *
      * Function sets DNS query result to Nanostack cache to get distributed to the devices in the Wi-SUN network.
      * Function must be called for a running Wi-SUN Border Router instance.
      *
      * \param address resolved address of domain_name.
      * \param domain_name name of the domain. Must be non-NULL.
      * \return MESH_ERROR_NONE on success.
      * \return error value in case of failure.
      * */
     mesh_error_t set_dns_query_result(SocketAddress *address, char *domain_name);
 
 private:
     mesh_error_t configure();
     mesh_error_t apply_configuration(int8_t mesh_if_id);
     mesh_error_t set_bbr_radius_address(void);
     mesh_error_t set_bbr_radius_shared_secret(void);
     mesh_error_t set_bbr_radius_timing(void);
     char _radius_ipv6_addr[40];
     ws_br_radius_timing_t _radius_timing = {
         .radius_retry_imin = 0,
         .radius_retry_imax = 0,
         .radius_retry_count = 0
     };
     char *_shared_secret = NULL;
     uint16_t _shared_secret_len = 0;
     int8_t _mesh_if_id = -1;
     bool _radius_ipv6_addr_set = false;
     bool _configured = false;
     bool _radius_timing_set = false;
 };
 
 #endif
Important Information for this Arm website
