ws_management_api.h

00001 /*
00002  * Copyright (c) 2018-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 /**
00019  * \file ws_management_if.h
00020  * \brief Wi-SUN management interface.
00021  *
00022  * This interface is used for configuring Wi-SUN devices.
00023  * After creating the Wi-SUN interface, you can use this interface to configure the Wi-SUN device
00024  * behaviour. When you are done with the configurations, you need to call interface up to enable a Wi-SUN node.
00025  *
00026  */
00027 
00028 #ifndef WS_MANAGEMENT_API_H_
00029 #define WS_MANAGEMENT_API_H_
00030 
00031 #include "ns_types.h"
00032 #include "net_interface.h" /* Declaration for channel_list_s. */
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif
00037 
00038 /* Regulatory domain values*/
00039 #define REG_DOMAIN_WW   0x00 // World wide
00040 #define REG_DOMAIN_NA   0x01 // North America
00041 #define REG_DOMAIN_JP   0x02 // Japan
00042 #define REG_DOMAIN_EU   0x03 // European Union
00043 #define REG_DOMAIN_CH   0x04 // China
00044 #define REG_DOMAIN_IN   0x05 // India
00045 #define REG_DOMAIN_MX   0x06 //
00046 #define REG_DOMAIN_BZ   0x07 // Brazil
00047 #define REG_DOMAIN_AZ   0x08 // Australia
00048 #define REG_DOMAIN_NZ   0x08 // New zealand
00049 #define REG_DOMAIN_KR   0x09 // Korea
00050 #define REG_DOMAIN_PH   0x0A //
00051 #define REG_DOMAIN_MY   0x0B //
00052 #define REG_DOMAIN_HK   0x0C //
00053 #define REG_DOMAIN_SG   0x0D // band 866-869
00054 #define REG_DOMAIN_TH   0x0E //
00055 #define REG_DOMAIN_VN   0x0F //
00056 #define REG_DOMAIN_SG_H 0x10 // band 920-925
00057 
00058 #define OPERATING_MODE_1a 0x1a
00059 #define OPERATING_MODE_1b 0x1b
00060 #define OPERATING_MODE_2a 0x2a
00061 #define OPERATING_MODE_2b 0x2b
00062 #define OPERATING_MODE_3  0x03
00063 #define OPERATING_MODE_4a 0x4a
00064 #define OPERATING_MODE_4b 0x4b
00065 #define OPERATING_MODE_5  0x05
00066 
00067 #define CHANNEL_FUNCTION_FIXED            0x00 // Fixed channel
00068 #define CHANNEL_FUNCTION_TR51CF           0x01 // TR51CF
00069 #define CHANNEL_FUNCTION_DH1CF            0x02 // Direct Hash
00070 #define CHANNEL_FUNCTION_VENDOR_DEFINED   0x03 // vendor given channel hop schedule
00071 
00072 #define CHANNEL_SPACING_200 0x00 // 200 khz
00073 #define CHANNEL_SPACING_400 0x01 // 400 khz
00074 #define CHANNEL_SPACING_600 0x02 // 600 khz
00075 #define CHANNEL_SPACING_100 0x03 // 100 khz
00076 #define CHANNEL_SPACING_250 0x04 // 250 khz
00077 
00078 #define NETWORK_SIZE_AUTOMATIC 0x00
00079 #define NETWORK_SIZE_SMALL 0x01
00080 #define NETWORK_SIZE_MEDIUM 0x08
00081 #define NETWORK_SIZE_LARGE 0x10
00082 #define NETWORK_SIZE_CERTIFICATE 0xFF
00083 
00084 
00085 /** Temporary API change flag. this will be removed when new version of API is implemented on applications
00086  *
00087  */
00088 #define WS_MANAGEMENT_API_VER_2
00089 
00090 /**
00091  * \brief Struct ws_statistics defines the Wi-SUN statistics storage structure.
00092  */
00093 typedef struct ws_statistics {
00094     /** Asynch TX counter */
00095     uint32_t asynch_tx_count;
00096     /** Asynch RX counter */
00097     uint32_t asynch_rx_count;
00098 } ws_statistics_t;
00099 
00100 /**
00101  * Initialize Wi-SUN stack.
00102  *
00103  * Generates the default configuration for Wi-SUN operation
00104  *
00105  * \param interface_id Network interface ID.
00106  * \param regulatory_domain Mandatory regulatory domain value of the device.
00107  * \param network_name_ptr Network name where to join if no configuration found from storage.
00108  * \param fhss_timer_ptr FHSS functions for timer adaptation to platform.
00109  *
00110  * \return 0, Init OK.
00111  * \return <0 Init fail.
00112  */
00113 int ws_management_node_init(
00114     int8_t interface_id,
00115     uint8_t regulatory_domain,
00116     char *network_name_ptr,
00117     fhss_timer_t *fhss_timer_ptr);
00118 
00119 /**
00120  * Change the network name
00121  *
00122  * Change the network name dynamically at a runtime.
00123  * If stack is running the network discovery is restarted.
00124  *
00125  * \param interface_id Network interface ID.
00126  * \param network_name_ptr Nul terminated Network name limited to 32 characters.
00127  *
00128  * \return 0, Init OK.
00129  * \return <0 Init fail.
00130  */
00131 int ws_management_network_name_set(
00132     int8_t interface_id,
00133     char *network_name_ptr);
00134 
00135 /**
00136  * Configure regulatory domain of Wi-SUN stack.
00137  *
00138  * Change the default configuration for Wi-SUN PHY operation.
00139  *
00140  * Supported values:
00141  * Domain: "NA"(0x01), "KR"(0x09)
00142  * Operating class: (1), (2)
00143  * operation mode: "1b" (symbol rate 50, modulation index 1)
00144  *
00145  * if value of 255 is given then previous value is used.
00146  *
00147  * \param interface_id Network interface ID.
00148  * \param regulatory_domain FHSS regulatory domain default to "KR" 0x09.
00149  * \param operating_class FHSS operating class default to 1.
00150  * \param operating_mode FHSS phy operating mode default to "1b".
00151  *
00152  * \return 0, Init OK.
00153  * \return <0 Init fail.
00154  */
00155 int ws_management_regulatory_domain_set(
00156     int8_t interface_id,
00157     uint8_t regulatory_domain,
00158     uint8_t operating_class,
00159     uint8_t operating_mode);
00160 
00161 /**
00162  * Set timing parameters related to network size.
00163  *
00164  * timing parameters follows the specification example from Wi-SUN specification
00165  *
00166  * Default value: automatic
00167  * small network size: hundreds of devices
00168  * Large network size: thousands of devices
00169  * automatic: when discovering the network network size is learned
00170  *            from advertisements and timings adjusted accordingly
00171  *
00172  * \param interface_id Network interface ID.
00173  * \param network_size define from NETWORK_SIZE_*.
00174  *
00175  * \return 0, Init OK.
00176  * \return <0 Init fail.
00177  */
00178 int ws_management_network_size_set(
00179     int8_t interface_id,
00180     uint8_t network_size);
00181 
00182 /**
00183  * Set channel mask for FHSS operation.
00184  *
00185  * Default value: all channels are allowed.
00186  *
00187  * \param interface_id Network interface ID.
00188  * \param channel_mask set bits matching the channel 1 to allow channel 0 to disallow.
00189  *
00190  * \return 0, Init OK.
00191  * \return <0 Init fail.
00192  */
00193 int ws_management_channel_mask_set(
00194     int8_t interface_id,
00195     uint32_t channel_mask[8]);
00196 
00197 /**
00198  * Configure Application defined channel plan.
00199  *
00200  * Change the application defined channel plan.
00201  * This changes our channel plan that is reported to our children.
00202  * PHY driver must be configured to follow these settings to make the configuration active.
00203  *
00204  *
00205  * \param interface_id Network interface ID.
00206  * \param channel_plan Channel plan must be 1 application defined if deviating from regulatory domain (0).
00207  * \param uc_channel_function 0: Fixed channel, 1:TR51CF, 2: Direct Hash, 3: Vendor defined.
00208  * \param bc_channel_function 0: Fixed channel, 1:TR51CF, 2: Direct Hash, 3: Vendor defined.
00209  * \param ch0_freq ch0 center frequency.
00210  * \param channel_spacing Channel spacing value 0:200k, 1:400k, 2:600k, 3:100k.
00211  * \param number_of_channels FHSS phy operating mode default to "1b".
00212  *
00213  * \return 0, Init OK.
00214  * \return <0 Init fail.
00215  */
00216 int ws_management_channel_plan_set(
00217     int8_t interface_id,
00218     uint8_t channel_plan,
00219     uint8_t uc_channel_function,
00220     uint8_t bc_channel_function,
00221     uint32_t ch0_freq, // Stack can not modify this
00222     uint8_t channel_spacing,// Stack can not modify this
00223     uint8_t number_of_channels);// Stack can not modify this
00224 
00225 /**
00226  * Configure timing values for FHSS.
00227  *
00228  * Change the default configuration for Wi-SUN FHSS operation.
00229  *
00230  * \param interface_id Network interface ID.
00231  * \param fhss_uc_dwell_interval default to 250 ms.
00232  * \param fhss_broadcast_interval default to 800 ms.
00233  * \param fhss_bc_dwell_interval default to 200 ms.
00234  *
00235  * \return 0, Init OK.
00236  * \return <0 Init fail.
00237  */
00238 int ws_management_fhss_timing_configure(
00239     int8_t interface_id,
00240     uint8_t fhss_uc_dwell_interval,
00241     uint32_t fhss_broadcast_interval,
00242     uint8_t fhss_bc_dwell_interval);
00243 
00244 /**
00245  * Configure unicast channel function.
00246  *
00247  * Change the default configuration for Wi-SUN FHSS operation.
00248  * if application defined is used the behaviour is undefined
00249  *
00250  *
00251  * \param interface_id Network interface ID.
00252  * \param channel_function Unicast channel function.
00253  * \param fixed_channel Used channel when channel function is fixed channel.
00254  * \param dwell_interval Used dwell interval when channel function is TR51 or DH1.
00255  *
00256  * \return 0, Init OK.
00257  * \return <0 Init fail.
00258  */
00259 int ws_management_fhss_unicast_channel_function_configure(
00260     int8_t interface_id,
00261     uint8_t channel_function,
00262     uint16_t fixed_channel,
00263     uint8_t dwell_interval);
00264 
00265 /**
00266  * Configure broadcast channel function.
00267  *
00268  * Change the default configuration for Wi-SUN FHSS operation.
00269  * if application defined is used the behaviour is undefined
00270  *
00271  *
00272  * \param interface_id Network interface ID.
00273  * \param channel_function Broadcast channel function.
00274  * \param fixed_channel Used channel when channel function is fixed channel.
00275  * \param dwell_interval Broadcast channel dwell interval.
00276  * \param broadcast_interval Broadcast interval.
00277  *
00278  * \return 0, Init OK.
00279  * \return <0 Init fail.
00280  */
00281 int ws_management_fhss_broadcast_channel_function_configure(
00282     int8_t interface_id,
00283     uint8_t channel_function,
00284     uint16_t fixed_channel,
00285     uint8_t dwell_interval,
00286     uint32_t broadcast_interval);
00287 
00288 /**
00289  * Start collecting Wi-SUN statistics.
00290  *
00291  * \param interface_id Network interface ID.
00292  * \param stats_ptr Pointer to stored statistics.
00293  *
00294  * \return 0 Success.
00295  * \return <0 Failure.
00296  */
00297 int ws_statistics_start(
00298     int8_t interface_id,
00299     ws_statistics_t *stats_ptr);
00300 
00301 /**
00302  * Stop collecting Wi-SUN statistics.
00303  *
00304  * \param interface_id Network interface ID.
00305  *
00306  * \return 0 Success.
00307  * \return <0 Failure.
00308  */
00309 int ws_statistics_stop(
00310     int8_t interface_id);
00311 
00312 #ifdef __cplusplus
00313 }
00314 #endif
00315 #endif /* WS_MANAGEMENT_API_H_ */