etx.h

00001 /*
00002  * Copyright (c) 2014-2018, 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  * \file etx.h
00019  * \brief Expected transmission count (ETX metric), module
00020  *
00021  *
00022  */
00023 
00024 #ifndef ETX_H_
00025 #define ETX_H_
00026 
00027 #include "NWK_INTERFACE/Include/protocol_abstract.h"
00028 
00029 /* Fraction that is used when calculating moving average
00030    e.g. ETX = 7/8 * current ETX + 1/8 * new ETX sample
00031    Range for value can be from 1 to 11 */
00032 #define ETX_MOVING_AVERAGE_FRACTION      3     // n >> 3, 1/8
00033 
00034 /* ETX cache configuration definitions */
00035 
00036 /* Amount of accelerated ETX samples
00037  * After this value is received the ETX calculation starts to follow the
00038  * slower ETX cache configuration values.
00039  *
00040  * Maximum value is 6
00041  */
00042 #define ETX_ACCELERATED_SAMPLE_COUNT      3
00043 
00044 /* Amount of samples before updating the ETX value when in accelerated mode.
00045  *
00046  * if set to 1 every sample updates an ETX value. if set to 2 every second
00047  * ETX sample updates the ETX value.
00048  *
00049  * This value should be smaller than ETX_ACCELERATED_SAMPLE_COUNT
00050  */
00051 #define ETX_ACCELERATED_INTERVAL          2
00052 
00053 typedef struct etx_storage_s {
00054     uint16_t        etx;                       /*!< 12 bits fraction */
00055     uint16_t        stored_diff_etx;           /*!< 12 bits fraction */
00056     uint8_t         remote_incoming_idr;       /*!< 5 bits fraction */
00057     unsigned        accumulated_failures: 5;
00058     unsigned        tmp_etx: 1;
00059     unsigned        linkIdr: 4;
00060     unsigned        etx_samples: 3;
00061 } etx_storage_t;
00062 
00063 typedef struct etx_sample_storage_s {
00064     uint16_t           attempts_count;         /*!< TX attempt count */
00065     uint8_t            etx_timer;              /*!< Count down from configured value 0 means that ETX Update is possible done again*/
00066     uint8_t            received_acks;          /*!< Received ACK's */
00067     uint8_t            sample_count;           /*!< Finished TX count */
00068 } etx_sample_storage_t;
00069 
00070 /**
00071  * \brief A function to update ETX value based on transmission attempts
00072  *
00073  *  Update is made based on failed and successful message sending
00074  *  attempts for a message.
00075  *
00076  * \param interface_id Interface identifier
00077  * \param attempts number of attempts to send message
00078  * \param success was message sending successful
00079  * \param attribute_index Neighbour attribute index
00080  */
00081 void etx_transm_attempts_update(int8_t interface_id, uint8_t attempts, bool success, uint8_t attribute_index);
00082 
00083 /**
00084  * \brief A function to update ETX value based on remote incoming IDR
00085  *
00086  *  Update is made based on remote incoming IDR received from
00087  *  neighbor.
00088  *
00089  * \param interface_id Interface identifier
00090  * \param remote_incoming_idr Remote incoming IDR
00091  * \param attribute_index Neighbour attribute index
00092  */
00093 void etx_remote_incoming_idr_update(int8_t interface_id, uint8_t remote_incoming_idr, uint8_t attribute_index);
00094 
00095 /**
00096  * \brief A function to read ETX value
00097  *
00098  *  Returns ETX value for an address
00099  *
00100  * \param interface_id network interface id
00101  * \param addr_type address type, ADDR_802_15_4_SHORT or ADDR_802_15_4_LONG
00102  * \param addr_ptr PAN ID with 802.15.4 address
00103  *
00104  * \return 0x0100 to 0xFFFF ETX value (8 bit fraction)
00105  * \return 0xFFFF address not associated
00106  * \return 0x0000 address unknown or other error
00107  * \return 0x0001 no ETX statistics on this interface
00108  */
00109 uint16_t etx_read(int8_t interface_id, addrtype_t addr_type, const uint8_t *addr_ptr);
00110 
00111 /**
00112  * \brief A function to read local incoming IDR value
00113  *
00114  *  Returns local incoming IDR value for an neighbour
00115  *
00116  * \param attribute_index Neighbour attribute index
00117  *
00118  * \return 0x0100 to 0xFFFF incoming IDR value (8 bit fraction)
00119  * \return 0x0000 address unknown
00120  */
00121 uint16_t etx_local_incoming_idr_read(int8_t interface_id, uint8_t attribute_index);
00122 
00123 /**
00124  * \brief A function to read local ETXvalue
00125  *
00126  *  Returns local ETX value for an address
00127  *
00128  * \param mac64_addr_ptr long MAC address
00129  *
00130  * \return 0x0100 to 0xFFFF ETX value (8 bit fraction)
00131  * \return 0x0000 address unknown
00132  */
00133 uint16_t etx_local_etx_read(int8_t interface_id, uint8_t attribute_index);
00134 
00135 /**
00136  * \brief A function to update ETX value based on LQI and dBm
00137  *
00138  *  Update is made based on dBM and LQI of received message.
00139  *
00140  * \param lqi link quality indicator
00141  * \param dbm measured dBm
00142  * \param attribute_index Neighbour attribute index
00143  *
00144  * \return 0x0100 to 0xFFFF local incoming IDR value (8 bit fraction)
00145  */
00146 uint16_t etx_lqi_dbm_update(int8_t interface_id, uint8_t lqi, int8_t dbm, uint8_t attribute_index);
00147 
00148 /**
00149  * \brief A function callback that indicates ETX value change
00150  *
00151  *  Callback indicates when ETX value has changed more or equal to
00152  *  hysteresis value.
00153  *
00154  * \param nwk_interface_id network interface id
00155  * \param previous_etx ETX value to what the current ETX was compared (8 bit fraction)
00156  * \param current_etx current ETX value (8 bit fraction)
00157  * \param attribute_index Neighbour attribute index
00158  *
00159  */
00160 typedef void (etx_value_change_handler_t)(int8_t nwk_id, uint16_t previous_etx, uint16_t current_etx, uint8_t attribute_index);
00161 
00162 /**
00163  * \brief A function callback that indicates the number of accumulated TX failures
00164  *
00165  * Callback indicates when number of accumulated failures is more or equal to threshold value.
00166  *
00167  * \param interface_id interface ID
00168  * \param accumulated_failures number of accumulated failures
00169  * \param attribute_index Neighbour attribute index
00170  *
00171  */
00172 typedef void (etx_accum_failures_handler_t)(int8_t interface_id, uint8_t accumulated_failures, uint8_t attribute_index);
00173 
00174 /**
00175  * \brief A function to register ETX value change callback
00176  *
00177  *  When ETX value has changed more or equal to hysteresis value ETX
00178  *  module calls ETX value change callback.
00179  *
00180  * \param nwk_interface_id network interface id
00181  * \param hysteresis hysteresis value (8 bit fraction)
00182  * \param callback_ptr callback function pointer
00183  *
00184  * \return 0 not 6LowPAN interface
00185  * \return 1 success
00186  */
00187 uint8_t etx_value_change_callback_register(nwk_interface_id nwk_id, int8_t interface_id, uint16_t hysteresis, etx_value_change_handler_t *callback_ptr);
00188 
00189 /**
00190  * \brief A function to allocte ETX storage list
00191  *
00192  * \param interface_id interface id
00193  * \param etx_storage_size Size of storage. 0 will free allocate data
00194  *
00195  * \return false Allocate fail
00196  * \return true Allocate OK
00197  */
00198 bool etx_storage_list_allocate(int8_t interface_id, uint8_t etx_storage_size);
00199 
00200 /**
00201  * \brief A function to read ETX storage for defined neighbour
00202  *
00203  * \param interface_id interface id
00204  * \param attribute_index Neighbour attribute index
00205  *
00206  * \return Pointer to ETX storage
00207  * \return NULL When unknow interface or attribute
00208  */
00209 etx_storage_t *etx_storage_entry_get(int8_t interface_id, uint8_t attribute_index);
00210 
00211 
00212 /**
00213  * \brief A function to register accumulated failures callback
00214  *
00215  *  When the number of accumulated failures has reached the threshold
00216  *  value, the ETX module calls the accumulated failures callback on
00217  *  every transmission failure.
00218  *
00219  * \param nwk_id network ID (6LoWPAN)
00220  * \param interface_id interface ID
00221  * \param threshold threshold value for accumulated failures
00222  * \param callback_ptr callback function pointer
00223  *
00224  * \return 0 not 6LowPAN interface
00225  * \return 1 success
00226  */
00227 uint8_t etx_accum_failures_callback_register(nwk_interface_id nwk_id, int8_t interface_id, uint8_t threshold, etx_accum_failures_handler_t *callback_ptr);
00228 
00229 /**
00230  * \brief A function to remove ETX neighbor
00231  *
00232  *  Notifies ETX module that neighbor has been removed. Calls ETX value change callback
00233  *  if that is set.
00234  *
00235  * \param attribute_index Neighbour attribute index
00236  *
00237  */
00238 void etx_neighbor_remove(int8_t interface_id, uint8_t attribute_index);
00239 
00240 /**
00241  * \brief A function to add ETX neighbor
00242  *
00243  *  Notifies ETX module that neighbor has been added. Calls ETX value change callback
00244  *  if that is set.
00245  *
00246  * \param attribute_index Neighbour attribute index
00247  *
00248  */
00249 void etx_neighbor_add(int8_t interface_id, uint8_t attribute_index);
00250 
00251 /**
00252  * \brief A function for update cached ETX calculation
00253  *
00254  *  Shuold be call second intevall
00255  *
00256  * \param interface_id Interface ID
00257  * \param seconds_update Seconds Update
00258  *
00259  */
00260 void etx_cache_timer(int8_t interface_id, uint16_t seconds_update);
00261 
00262 /**
00263  * \brief A function for enable cached ETX mode and parametrs
00264  *
00265  *  Default values for enabled Cached mode is wait time 60 seconds, etx_max_update is 0 (disabled) and etx_min_sample_count is 4.
00266  *  ETX update will happen when min wait time is reached and also reached min etx sample count.
00267  *
00268  * \param min_wait_time how many seconds must wait before do new ETX
00269  * \param etx_min_sample_count define how many completed TX process must be done for new ETX. Min accepted value is 4.
00270  *
00271  * \return true Enable is OK
00272  * \return false Memory allocation fail
00273  *
00274  */
00275 bool etx_cached_etx_parameter_set(uint8_t min_wait_time, uint8_t etx_min_sample_count);
00276 
00277 
00278 /**
00279  * \brief A function for set Maxium ETX update
00280  *
00281  * ETX RFC define that that Max value for update is 0xffff but this API cuold make that Poor link start go down slowly.
00282  *
00283  * \param etx_max_update 0 No limit for Update higher value means. This pameter will change normal ETX which could be 0xffff.
00284  *
00285  */
00286 void etx_max_update_set(uint16_t etx_max_update);
00287 
00288 #endif /* ETX_H_ */