net_thread_test.h

00001 /*
00002  * Copyright (c) 2014-2019, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: BSD-3-Clause
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions are met:
00007  *
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the copyright holder nor the
00014  *    names of its contributors may be used to endorse or promote products
00015  *    derived from this software without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00018  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
00021  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00022  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00023  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00024  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00025  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00026  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00027  * POSSIBILITY OF SUCH DAMAGE.
00028  */
00029 
00030 #ifndef NET_THREAD_TEST_H_
00031 #define NET_THREAD_TEST_H_
00032 
00033 /* Prevent this file being inserted in public Doxygen generated file
00034  * this is not part of our external API. */
00035 #ifndef DOXYGEN
00036 
00037 /**
00038  * \file net_thread_test.h
00039  * \brief Thread Library Test API.
00040  *
00041  * \warning NOTICE! This is test API must not be used externally.
00042  *
00043  * \warning This file is not part of the version number control and can change any time.
00044  *
00045  */
00046 
00047 
00048 #ifdef __cplusplus
00049 extern "C" {
00050 #endif
00051 
00052 #include "ns_types.h"
00053 
00054 #define thread_test_router_upgrade(iface) thread_test_router_id_request_send(iface, 2) // THREAD_COAP_STATUS_TLV_TOO_FEW_ROUTERS
00055 /**
00056   * \brief Add a static neighbour
00057   *
00058   * Test API: Add a neighbour. Adds, or updates, a non-expiring neighbour to the
00059   * Thread Link Set, and updates the Route Set accordingly. Basically equivalent
00060   * to receiving an MLE advertisement with a Route TLV, except it doesn't expire.
00061   *
00062   * See draft-kelsey-thread-routing-00 for more info on data format.
00063   *
00064   * \param interface_id Interface to modify
00065   * \param neighbour_addr Neighbour short address (must be a router address)
00066   * \param link_margin_db Notional link margin for reception from this neighbour.
00067   * \param id_sequence Sequence number for id_mask
00068   * \param id_mask Bit mask of router IDs
00069   * \param route_data One octet per set bit in id_mask
00070   *
00071   * \return  0 Success
00072   * \return <0 Failure
00073   */
00074 int_fast8_t arm_nwk_6lowpan_thread_test_add_neighbour(
00075     int8_t interface_id,
00076     uint16_t neighbour_short_addr,
00077     uint_fast8_t link_margin_db,
00078     uint8_t id_sequence,
00079     const uint8_t *id_mask,
00080     const uint8_t *route_data);
00081 
00082 /**
00083  * \brief API to set reed advertisement interval
00084  * \param interface_id Interface to modify
00085  * \param advertisement_interval Interval between advertisements to be set
00086  * \param jitter_interval Maximum value of random jitter interval to be added to advertisement_interval
00087  * \return   0 Success
00088  * \return < 0 Other errors
00089  */
00090 int8_t thread_reed_set_advertisement_interval(int8_t interface_id, uint16_t advertisement_interval, uint16_t jitter_interval);
00091 
00092 /**
00093   * \brief Remove a static neighbour
00094   *
00095   * Test API: Remove a neighbour. Remove a neighbour from the Thread Link Set
00096   * (whether added through arm_nwk_6lowpan_thread_test_add_neighbour, or
00097   * automatically through MLE).
00098   *
00099   * \param interface_id Interface to modify
00100   * \param neighbour_addr Neighbour short address (must be a router address)
00101   *
00102   * \return  0 Success
00103   * \return -1 Not an existing neighbour
00104   * \return <-1 Other errors
00105   */
00106 int_fast8_t arm_nwk_6lowpan_thread_test_remove_neighbour(
00107     int8_t interface_id,
00108     uint16_t neighbour_short_addr);
00109 
00110 /**
00111   * \brief Print routing database
00112   *
00113   * Test API: Dump the routing data base (Router ID Set, Link Set and Route
00114   * Set) to the debug channel.
00115   *
00116   * \param interface_id Interface to interrogate
00117   */
00118 void arm_nwk_6lowpan_thread_test_print_routing_database(int8_t interface_id);
00119 
00120 
00121 /**
00122  * \brief Thread Leader max router ID limit set
00123  *
00124  * This function should use just for test purpose Thread define this by default to 32
00125  *
00126  * \param interface_id Network Interface
00127  * \param maxRouterLimit Min Accepted value is 1 and max 32
00128  *
00129  * return 0, Set OK
00130  * return <0 Set Fail
00131  */
00132 int thread_test_max_accepted_router_id_limit_set(
00133     int8_t interface_id,
00134     uint8_t maxRouterLimit);
00135 
00136 /**
00137   * \brief Set Thread network ID timeout
00138   *
00139   * \param interface_id Interface to modify
00140   * \param network_id_timeout network timeout as seconds
00141   *
00142   * \return  0 Success
00143   * \return -1 Invalid interface id
00144   * \return -2 Thread not active
00145   * \return -3 invalid timeout value
00146   */
00147 int8_t thread_routing_set_network_id_timeout(int8_t interface_id, uint16_t network_id_timeout);
00148 
00149 /**
00150   * \brief Get Thread network ID timeout
00151   *
00152   * \param interface_id Interface to modify
00153   * \param network_id_timeout pointer, where current network id timeout will be saved as seconds
00154   *
00155   * \return  0 Success
00156   * \return -1 Invalid interface id
00157   * \return -2 Thread not active
00158   * \return -3 invalid pointer
00159   */
00160 int8_t thread_routing_get_network_id_timeout(int8_t interface_id, uint16_t *network_id_timeout);
00161 
00162 /**
00163  * \brief Print Thread network data
00164  *
00165  * \param interface_id Network Interface
00166  *
00167  * \return 0, OK
00168  * \return <0 Not OK
00169  */
00170 
00171 int thread_test_print_network_data(int8_t interface_id);
00172 
00173 /**
00174  * \brief Thread Leader Context ID reuse timeout set
00175  *
00176  * This function should be used to change default 48 hours to shorter one
00177  *
00178  * \param interface_id Network Interface
00179  * \param timeout Min Accepted value is 60 seconds and max  48 hours (48*3600)
00180  *
00181  * \return 0, Set OK
00182  * \return <0 Set Fail
00183  */
00184 int thread_test_set_context_id_reuse_timeout(
00185     int8_t interface_id,
00186     uint32_t timeout);
00187 
00188 /**
00189  * \brief Leader of Thread network can kick Router out from Network.
00190  *
00191  * \param interface_id Network Interface
00192  * \param routerId Routter id of router that is kicked
00193  *
00194  * \return 0, Remove OK
00195  * \return <0 Remove fail
00196  */
00197 int thread_test_remove_router_by_id(int8_t interface_id, uint8_t routerId);
00198 
00199 /**
00200  * \brief Start router downgrade process.
00201  *
00202  * \param interface_id Network Interface
00203  *
00204  * \return 0, downgrade started
00205  * \return <0 fail
00206  */
00207 int thread_test_router_downgrade(int8_t interface_id);
00208 
00209 /**
00210  * \brief Set Thread Security Material. Terms are defined in Thread security specification
00211  *
00212  * \param interface_id Network Interface
00213  * \param enableSecurity Boolean for enable security or disable
00214  * \param thrMasterKey Master Key material which will be used for generating new key
00215  * \param thrKeySequenceCounter Periodic counter used to generate new MAC and MLE keys
00216  * \param thrKeyRotation Update period (in seconds) for thrKeySequenceCounter
00217  *
00218  * \return 0, ADD OK
00219  * \return <0 Add Not OK
00220  */
00221 int thread_test_security_material_set(int8_t interface_id, bool enableSecurity, uint8_t *thrMasterKey, uint32_t thrKeySequenceCounter, uint32_t thrKeyRotation);
00222 
00223 /**
00224  * \brief Set Thread version number.
00225  *
00226  * \param interface_id Network Interface
00227  * \param version "1 == Thread version 1.0" or "2 == Thread version 1.1"
00228  *
00229  * \return 0, OK
00230  * \return <0 Error
00231  */
00232 int thread_test_version_set(int8_t interface_id, uint8_t version);
00233 /**
00234  * \brief Set Thread router selection jitter.
00235  *
00236  * \param interface_id Network Interface
00237  * \param value must be over 1 default is 120
00238  *
00239  * \return 0, OK
00240  * \return <0 Error
00241  */
00242 int thread_test_router_selection_jitter_set(int8_t interface_id, uint32_t jitter);
00243 
00244 /**
00245  * \brief Set Thread PBBR status response override.
00246  *
00247  * \param interface_id Network Interface
00248  * \param dua_status expected dua response value from PBBR
00249  * \param dua_count number of times dua_response is repeated
00250  * \param ba_failure_count number of times bba failure is repeated
00251  *
00252  * \return 0, OK
00253  * \return <0 Error
00254  */
00255 int thread_test_pbbr_response_override_set(int8_t interface_id, uint8_t dua_status, uint8_t dua_count, uint8_t ba_failure_count);
00256 
00257 /**
00258  * \brief Sets the thread MIN_DELAY_TIMER default value.
00259  *
00260  * \param interface_id Network Interface
00261  * \param delay_timer_value delay timer value in seconds used in leader
00262  *
00263  * \return 0, OK
00264  * \return <0 Error
00265  */
00266 int thread_test_min_delay_timer_set(int8_t interface_id, uint32_t delay_timer_value);
00267 /**
00268  * \brief Increment Thread key sequence counter
00269  *
00270  * \param interface_id Network Interface
00271  *
00272  * \return 0, OK
00273  * \return <0 Error
00274  */
00275 int thread_test_increment_key_sequence_counter(int8_t interface_id);
00276 
00277 /**
00278  * \brief Set new Thread key sequence counter
00279  *
00280  * Call define new key and next key same time
00281  *
00282  * \param interface_id Network Interface
00283  * \param thrKeySequenceCounter this need to be bigger than current sequence
00284  *
00285  * \return 0, OK
00286  * \return <0 Error
00287  */
00288 int thread_test_key_sequence_counter_update(int8_t interface_id, uint32_t thrKeySequenceCounter);
00289 
00290 /**
00291  * \brief Resets cached values from stack
00292  *
00293  Resets link configuration from cache and from  NVM.
00294  *
00295   *
00296  * \param interface_id Network Interface
00297   *
00298  * \return 0, OK
00299  * \return <0 Error
00300  */
00301 int thread_test_stack_cache_reset(int8_t interface_id);
00302 
00303 /**
00304  * \brief Set new Thread key rotation value
00305  *
00306  * \param interface_id Network interface ID
00307  * \param thrKeyRotation Key rotation value in seconds
00308  *
00309  * \return 0, OK
00310  * \return <0 Error
00311  */
00312 int thread_test_key_rotation_update(int8_t interface_id, uint32_t thrKeyRotation);
00313 
00314 /**
00315  * \brief Thread router select threshold values set
00316  *
00317  * \param interface_id Network Interface
00318  * \param upgradeThreshold Set REED up grade to router threshold
00319  * \param downgradeThreshold Set Router down grade to REED threshold
00320  *
00321  * \return 0, Set OK
00322  * \return <0 Set Fail
00323  */
00324 int thread_test_router_select_threshold_values_set(
00325     int8_t interface_id,
00326     uint8_t upgradeThreshold,
00327     uint8_t downgradeThreshold);
00328 
00329 /**
00330  * \brief Send PAN ID query message to destination
00331  *
00332  * \param interface_id Network Interface
00333  *
00334  * \return 0, Set OK
00335  * \return <0 Set Fail
00336  */
00337 int thread_test_panid_query_send(int8_t interface_id, uint8_t *address_ptr, uint16_t session_id, uint16_t panid, uint8_t channel_page, uint8_t *mask_ptr);
00338 
00339 /**
00340  * \brief Send energy scan message to destination
00341  *
00342  * \param interface_id Network Interface
00343  *
00344  * \return 0, Set OK
00345  * \return <0 Set Fail
00346  */
00347 int thread_test_energy_scan_send(int8_t interface_id, uint8_t *address_ptr, uint16_t session_id, uint8_t channel_page, uint8_t *mask_ptr, uint16_t period, uint8_t count, uint16_t duration);
00348 
00349 /**
00350  * \brief Send announcement message
00351  *
00352  * \param interface_id Network Interface
00353  * \param channel high uint16 is the channel page, lower part is the channel number on that page
00354  *
00355  * \return 0, Set OK
00356  * \return <0 Set Fail
00357  */
00358 int thread_test_announce_ntf_send(int8_t interface_id, uint8_t *address_ptr, uint32_t channel, uint16_t panid, uint64_t timestamp);
00359 
00360 /**
00361  * \brief Send energy scan message to destination
00362  *
00363  * \param interface_id Network Interface
00364  *
00365  * \return 0, Set OK
00366  * \return <0 Set Fail
00367  */
00368 int thread_test_announce_begin_send(int8_t interface_id, uint8_t *address_ptr, uint16_t session_id, uint8_t channel_page, uint8_t *mask_ptr, uint16_t period, uint8_t count);
00369 
00370 /**
00371  * \brief Get partition info
00372  *
00373  * \param interface_id Network Interface
00374  * \param partition_id Current partition id can be NULL if not needed.
00375  * \param weighting Current weighting can be NULL if not needed.
00376  * \param data_version Current data version can be NULL if not needed.
00377  * \param stable_data_version Current stable data version can be NULL if not needed.
00378  * \param leader_id Current leader id can be NULL if not needed.
00379  *
00380  * \return 0, Set OK
00381  * \return <0 Set Fail
00382  */
00383 int thread_test_partition_info_get(int8_t interface_id, uint32_t *partition_id, uint8_t *weighting, uint8_t *data_version, uint8_t *stable_data_version, uint8_t *leader_id);
00384 
00385 /**
00386  * \brief Set next partition ID when we next time partition. This is used to control specific behaviour in tests.
00387  *
00388  * \param interface_id Network Interface
00389  *
00390  * \return 0, Set OK
00391  * \return <0 Set Fail
00392  */
00393 int thread_test_partition_info_set(int8_t interface_id, uint32_t partition_id);
00394 
00395 /**
00396  * \brief Get thread information.
00397  *
00398  * \param interface_id Network Interface
00399  * \param short_addr own short address
00400  * \param router_count amount of active routers in network
00401  * \param network_stable stable network achieved no upgrade or downgrade pending
00402  *
00403  * \return 0, Set OK
00404  * \return <0 Set Fail
00405  */
00406 int8_t thread_test_thread_information_get(int8_t interface_id, uint16_t *short_addr, uint8_t *router_count, bool *network_stable);
00407 
00408 /**
00409  * \brief Get child count
00410  *
00411  * \param interface_id Network Interface
00412  *
00413  * \return 0, Set OK
00414  * \return <0 Set Fail
00415  */
00416 int8_t thread_test_child_count_get(int8_t interface_id);
00417 
00418 /**
00419  * \brief Get child information
00420  *
00421  * get information for index child. if found returns 0 with correct information.
00422  *
00423  * \param interface_id Network Interface
00424  *
00425  * \return 0, OK
00426  * \return <0 Fail no child with this index found
00427  */
00428 int8_t thread_test_child_info_get(int8_t interface_id, uint8_t index, uint16_t *short_addr, bool *sleepy, uint8_t *mac64, uint8_t *margin);
00429 
00430 /**
00431  * \brief Get neighbour information
00432  *
00433  * \param interface_id Network Interface
00434  *
00435  * \return 0, Set OK
00436  * \return <0 Set Fail
00437  */
00438 int8_t thread_test_neighbour_info_get(int8_t interface_id, uint8_t index, uint16_t *short_addr, uint8_t *mac64, uint8_t *margin);
00439 
00440 typedef int (response_cb)(int8_t interface_id, uint8_t *response_ptr, uint16_t response_len);
00441 
00442 /**
00443  * \brief Send diagnostic command DEPRECATED
00444  *
00445  * \param interface_id      Network Interface
00446  * \param address_ptr       Address to which the command is sent
00447  * \param uri_ptr           Uri for the command
00448  * \param request_length    The length of the request
00449  * \param request_ptr       Pointer to the beginning of the request contents
00450  * \param resp_cb           Pointer to callback function that is called after the reply for the command is obtained
00451  * \return 0,               Command send OK
00452  * \return <0               Command send Fail
00453  */
00454 int thread_test_diagnostic_command_send(int8_t interface_id, uint8_t *address_ptr, const char *uri_ptr, uint8_t request_length, uint8_t *request_ptr, response_cb *resp_cb);
00455 
00456 typedef int (coap_response_cb)(int8_t interface_id, uint8_t message_code, uint8_t message_type, uint8_t *response_ptr, uint16_t response_len);
00457 
00458 /**
00459  * \brief Send diagnostic request
00460  *
00461  * \param interface_id      Network Interface
00462  * \param address_ptr       Address to which the command is sent
00463  * \param msg_type           Uri for the command
00464  * \param msg_code           Uri for the command
00465  * \param uri_ptr           Uri for the command
00466  * \param request_length    The length of the request
00467  * \param request_ptr       Pointer to the beginning of the request contents
00468  * \param resp_cb           Pointer to callback function that is called after the reply for the command is obtained
00469  *
00470  * \return 0,               Command send OK
00471  * \return <0               Command send Fail
00472  */
00473 int thread_test_coap_request_send(int8_t interface_id, uint8_t *address_ptr, uint16_t port, uint8_t msg_type, uint8_t msg_code, uint16_t content_format, const char *uri_ptr, uint8_t *request_ptr, uint8_t request_length, coap_response_cb *resp_cb);
00474 
00475 /**
00476  * \brief Set initial SLAAC iid.
00477  *
00478  * \param interface_id      Network Interface
00479  * \param iid               Interface identifier pointer must be 8 bytes long buffer. can be NULL to disable.
00480  * \return 0,               Command OK
00481  * \return <0               Command Fail
00482  */
00483 int8_t thread_test_initial_slaac_iid_set(int8_t interface_id, uint8_t *iid);
00484 
00485 /**
00486  * \brief Send router ID request.
00487  *
00488  * \param interface_id      Network Interface
00489  * \param status            Value of router ID request status TLV
00490  * \return 0,               Command OK
00491  * \return <0               Command Fail
00492  */
00493 int8_t thread_test_router_id_request_send(int8_t interface_id, uint8_t status);
00494 
00495 /**
00496  * \brief Set joiner port to joiner router device.
00497  * If port == 0, then default port is used.
00498  *
00499  * \param iid               Joiner port.
00500  * \return 0,               Command OK
00501  * \return <0               Command Fail
00502  */
00503 int8_t thread_test_joiner_router_joiner_port_set(uint16_t port);
00504 
00505 /**
00506  *\brief set a router address to be requested. For a router, this address is sent
00507  *\in address solicit request to leader and for leader this is the router address
00508  *
00509  * \param interface_id               Network Interface
00510  * \param router_addr                Address requested
00511  * \return 0,                        Command OK
00512  * \return <0                        Command Fail
00513  */
00514 int8_t thread_test_router_address_set(int8_t interface_id, uint16_t router_addr);
00515 
00516 /**
00517  *\brief sends any MLE message to any destination.
00518  *
00519  * \param interface_id               Network Interface
00520  * \param dst_address                destination address
00521  * \param msg_id                     MLE message id
00522  * \param write_src_addr             write short address of the device
00523  * \param write_leader_data          write leader data
00524  * \param write_network_data         write network data
00525  * \param write_timestamp            write current timestamps*
00526  * \param write_operational_set      write current operational datasets *
00527  * \param write_challenge            add challenge to the message
00528  * \param msg_ptr                    additional buffer addded to message
00529  * \param msg_len                    length of the additional message
00530  * \return 0,                        Command OK
00531  * \return <0                        Command Fail
00532  */
00533 int thread_test_mle_message_send(int8_t interface_id, uint8_t *dst_address, uint8_t msg_id, bool write_src_addr, bool write_leader_data, bool write_network_data, bool write_timestamp, bool write_operational_set, bool write_challenge, uint8_t *msg_ptr, uint8_t msg_len);
00534 
00535 
00536 /**
00537  * \brief Set extension name.
00538  *
00539  * \param interface_id               Network Interface
00540  * \param extension_name             Extension name string
00541  *
00542  * \return 0                         OK
00543  * \return <0                        Failure
00544  */
00545 int thread_test_extension_name_set(int8_t interface_id, char extension_name[16]);
00546 
00547 /**
00548  * \brief Set multicast addresses per message.
00549  *
00550  * \param value                      Number of addresses per message (valid range 1-15)
00551  *
00552  * \return 0                         OK
00553  * \return <0                        Failure
00554  */
00555 int8_t thread_test_mcast_address_per_message_set(uint8_t value);
00556 
00557 /**
00558  * Thread router parent priority set.
00559  *
00560  * This function is used to set parent priority in connectivity TLV.
00561  *
00562  * \param interface_id Network interface ID.
00563  * \param parent_priority value to be set (0x40 High, 0x00 Medium, 0xC0 Low, 0x80 Do not use) .
00564  *
00565  * \return 0, Set OK.
00566  * \return <0 Set Fail.
00567  */
00568 int thread_test_parent_priority_set(int8_t interface_id, uint8_t parent_priority);
00569 
00570 #ifdef __cplusplus
00571 }
00572 #endif
00573 
00574 #endif /* DOXYGEN */
00575 #endif /* NET_THREAD_TEST_H_ */