net_thread_test.h

00001 /*
00002  * Copyright (c) 2014-2017 ARM Limited. All rights reserved.
00003  *
00004  * SPDX-License-Identifier: LicenseRef-PBL
00005  *
00006  * Licensed under the Permissive Binary License, Version 1.0 (the "License"); you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * https://www.mbed.com/licenses/PBL-1.0
00010  *
00011  * See the License for the specific language governing permissions and limitations under the License.
00012  *
00013  */
00014 
00015 #ifndef NET_THREAD_TEST_H_
00016 #define NET_THREAD_TEST_H_
00017 
00018 /* Prevent this file being inserted in public Doxygen generated file
00019  * this is not part of our external API. */
00020 #ifndef DOXYGEN
00021 
00022 /**
00023  * \file net_thread_test.h
00024  * \brief Thread Library Test API.
00025  *
00026  * \warning NOTICE! This is test API must not be used externally.
00027  *
00028  * \warning This file is not part of the version number control and can change any time.
00029  *
00030  */
00031 
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif
00036 
00037 #include "ns_types.h"
00038 
00039 #define thread_test_router_upgrade(iface) thread_test_router_id_request_send(iface, 2) // THREAD_COAP_STATUS_TLV_TOO_FEW_ROUTERS
00040 /**
00041   * \brief Add a static neighbour
00042   *
00043   * Test API: Add a neighbour. Adds, or updates, a non-expiring neighbour to the
00044   * Thread Link Set, and updates the Route Set accordingly. Basically equivalent
00045   * to receiving an MLE advertisement with a Route TLV, except it doesn't expire.
00046   *
00047   * See draft-kelsey-thread-routing-00 for more info on data format.
00048   *
00049   * \param interface_id Interface to modify
00050   * \param neighbour_addr Neighbour short address (must be a router address)
00051   * \param link_margin_db Notional link margin for reception from this neighbour.
00052   * \param id_sequence Sequence number for id_mask
00053   * \param id_mask Bit mask of router IDs
00054   * \param route_data One octet per set bit in id_mask
00055   *
00056   * \return  0 Success
00057   * \return <0 Failure
00058   */
00059 int_fast8_t arm_nwk_6lowpan_thread_test_add_neighbour(
00060     int8_t interface_id,
00061     uint16_t neighbour_short_addr,
00062     uint_fast8_t link_margin_db,
00063     uint8_t id_sequence,
00064     const uint8_t *id_mask,
00065     const uint8_t *route_data);
00066 
00067 /**
00068  * \brief API to set reed advertisement interval
00069  * \param interface_id Interface to modify
00070  * \param advertisement_interval Interval between advertisements to be set
00071  * \param jitter_interval Maximum value of random jitter interval to be added to advertisement_interval
00072  * \return   0 Success
00073  * \return < 0 Other errors
00074  */
00075 int8_t thread_reed_set_advertisement_interval(int8_t interface_id, uint16_t advertisement_interval, uint16_t jitter_interval);
00076 
00077 /**
00078   * \brief Remove a static neighbour
00079   *
00080   * Test API: Remove a neighbour. Remove a neighbour from the Thread Link Set
00081   * (whether added through arm_nwk_6lowpan_thread_test_add_neighbour, or
00082   * automatically through MLE).
00083   *
00084   * \param interface_id Interface to modify
00085   * \param neighbour_addr Neighbour short address (must be a router address)
00086   *
00087   * \return  0 Success
00088   * \return -1 Not an existing neighbour
00089   * \return <-1 Other errors
00090   */
00091 int_fast8_t arm_nwk_6lowpan_thread_test_remove_neighbour(
00092     int8_t interface_id,
00093     uint16_t neighbour_short_addr);
00094 
00095 /**
00096   * \brief Print routing database
00097   *
00098   * Test API: Dump the routing data base (Router ID Set, Link Set and Route
00099   * Set) to the debug channel.
00100   *
00101   * \param interface_id Interface to interrogate
00102   */
00103 void arm_nwk_6lowpan_thread_test_print_routing_database(int8_t interface_id);
00104 
00105 
00106 /**
00107  * \brief Thread Leader max router ID limit set
00108  *
00109  * This function should use just for test purpose Thread define this by default to 32
00110  *
00111  * \param interface_id Network Interface
00112  * \param maxRouterLimit Min Accepted value is 1 and max 32
00113  *
00114  * return 0, Set OK
00115  * return <0 Set Fail
00116  */
00117 int thread_test_max_accepted_router_id_limit_set(
00118     int8_t interface_id,
00119     uint8_t maxRouterLimit);
00120 
00121 /**
00122   * \brief Set Thread network ID timeout
00123   *
00124   * \param interface_id Interface to modify
00125   * \param network_id_timeout network timeout as seconds
00126   *
00127   * \return  0 Success
00128   * \return -1 Invalid interface id
00129   * \return -2 Thread not active
00130   * \return -3 invalid timeout value
00131   */
00132 int8_t thread_routing_set_network_id_timeout(int8_t interface_id, uint16_t network_id_timeout);
00133 
00134 /**
00135   * \brief Get Thread network ID timeout
00136   *
00137   * \param interface_id Interface to modify
00138   * \param network_id_timeout pointer, where current network id timeout will be saved as seconds
00139   *
00140   * \return  0 Success
00141   * \return -1 Invalid interface id
00142   * \return -2 Thread not active
00143   * \return -3 invalid pointer
00144   */
00145 int8_t thread_routing_get_network_id_timeout(int8_t interface_id, uint16_t *network_id_timeout);
00146 
00147 /**
00148  * \brief Print Thread network data
00149  *
00150  * \param interface_id Network Interface
00151  *
00152  * \return 0, OK
00153  * \return <0 Not OK
00154  */
00155 
00156 int thread_test_print_network_data(int8_t interface_id);
00157 
00158 /**
00159  * \brief Thread Leader Context ID reuse timeout set
00160  *
00161  * This function should be used to change default 48 hours to shorter one
00162  *
00163  * \param interface_id Network Interface
00164  * \param timeout Min Accepted value is 60 seconds and max  48 hours (48*3600)
00165  *
00166  * \return 0, Set OK
00167  * \return <0 Set Fail
00168  */
00169 int thread_test_set_context_id_reuse_timeout(
00170     int8_t interface_id,
00171     uint32_t timeout);
00172 
00173 /**
00174  * \brief Leader of Thread network can kick Router out from Network.
00175  *
00176  * \param interface_id Network Interface
00177  * \param routerId Routter id of router that is kicked
00178  *
00179  * \return 0, Remove OK
00180  * \return <0 Remove fail
00181  */
00182 int thread_test_remove_router_by_id(int8_t interface_id, uint8_t routerId);
00183 
00184 /**
00185  * \brief Start router downgrade process.
00186  *
00187  * \param interface_id Network Interface
00188  *
00189  * \return 0, downgrade started
00190  * \return <0 fail
00191  */
00192 int thread_test_router_downgrade(int8_t interface_id);
00193 
00194 /**
00195  * \brief Set Thread Security Material. Terms are defined in Thread security specification
00196  *
00197  * \param interface_id Network Interface
00198  * \param enableSecurity Boolean for enable security or disable
00199  * \param thrMasterKey Master Key material which will be used for generating new key
00200  * \param thrKeySequenceCounter Periodic counter used to generate new MAC and MLE keys
00201  * \param thrKeyRotation Update period (in seconds) for thrKeySequenceCounter
00202  *
00203  * \return 0, ADD OK
00204  * \return <0 Add Not OK
00205  */
00206 int thread_test_security_material_set(int8_t interface_id, bool enableSecurity, uint8_t *thrMasterKey, uint32_t thrKeySequenceCounter, uint32_t thrKeyRotation);
00207 
00208 /**
00209  * \brief Set Thread version number.
00210  *
00211  * \param interface_id Network Interface
00212  * \param version "1 == Thread version 1.0" or "2 == Thread version 1.1"
00213  *
00214  * \return 0, OK
00215  * \return <0 Error
00216  */
00217 int thread_test_version_set(int8_t interface_id, uint8_t version);
00218 /**
00219  * \brief Set Thread router selection jitter.
00220  *
00221  * \param interface_id Network Interface
00222  * \param value must be over 1 default is 120
00223  *
00224  * \return 0, OK
00225  * \return <0 Error
00226  */
00227 int thread_test_router_selection_jitter_set(int8_t interface_id, uint32_t jitter);
00228 
00229 /**
00230  * \brief Sets the thread MIN_DELAY_TIMER default value.
00231  *
00232  * \param interface_id Network Interface
00233  * \param delay_timer_value delay timer value in seconds used in leader
00234  *
00235  * \return 0, OK
00236  * \return <0 Error
00237  */
00238 int thread_test_min_delay_timer_set(int8_t interface_id, uint32_t delay_timer_value);
00239 /**
00240  * \brief Increment Thread key sequence counter
00241  *
00242  * \param interface_id Network Interface
00243  *
00244  * \return 0, OK
00245  * \return <0 Error
00246  */
00247 int thread_test_increment_key_sequence_counter(int8_t interface_id);
00248 
00249 /**
00250  * \brief Set new Thread key sequence counter
00251  *
00252  * Call define new key and next key same time
00253  *
00254  * \param interface_id Network Interface
00255  * \param thrKeySequenceCounter this need to be bigger than current sequence
00256  *
00257  * \return 0, OK
00258  * \return <0 Error
00259  */
00260 int thread_test_key_sequence_counter_update(int8_t interface_id, uint32_t thrKeySequenceCounter);
00261 
00262 /**
00263  * \brief Set new Thread key rotation value
00264  *
00265  * \param interface_id Network interface ID
00266  * \param thrKeyRotation Key rotation value in seconds
00267  *
00268  * \return 0, OK
00269  * \return <0 Error
00270  */
00271 int thread_test_key_rotation_update(int8_t interface_id, uint32_t thrKeyRotation);
00272 
00273 /**
00274  * \brief Thread router select threshold values set
00275  *
00276  * \param interface_id Network Interface
00277  * \param upgradeThreshold Set REED up grade to router threshold
00278  * \param downgradeThreshold Set Router down grade to REED threshold
00279  *
00280  * \return 0, Set OK
00281  * \return <0 Set Fail
00282  */
00283 int thread_test_router_select_threshold_values_set(
00284     int8_t interface_id,
00285     uint8_t upgradeThreshold,
00286     uint8_t downgradeThreshold);
00287 
00288 /**
00289  * \brief Send PAN ID query message to destination
00290  *
00291  * \param interface_id Network Interface
00292  *
00293  * \return 0, Set OK
00294  * \return <0 Set Fail
00295  */
00296 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);
00297 
00298 /**
00299  * \brief Send energy scan message to destination
00300  *
00301  * \param interface_id Network Interface
00302  *
00303  * \return 0, Set OK
00304  * \return <0 Set Fail
00305  */
00306 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);
00307 
00308 /**
00309  * \brief Send announcement message
00310  *
00311  * \param interface_id Network Interface
00312  * \param channel high uint16 is the channel page, lower part is the channel number on that page
00313  *
00314  * \return 0, Set OK
00315  * \return <0 Set Fail
00316  */
00317 int thread_test_announce_ntf_send(int8_t interface_id, uint8_t *address_ptr, uint32_t channel, uint16_t panid, uint64_t timestamp);
00318 
00319 /**
00320  * \brief Send energy scan message to destination
00321  *
00322  * \param interface_id Network Interface
00323  *
00324  * \return 0, Set OK
00325  * \return <0 Set Fail
00326  */
00327 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);
00328 
00329 /**
00330  * \brief Get partition info
00331  *
00332  * \param interface_id Network Interface
00333  * \param partition_id Current partition id can be NULL if not needed.
00334  * \param weighting Current weighting can be NULL if not needed.
00335  * \param data_version Current data version can be NULL if not needed.
00336  * \param stable_data_version Current stable data version can be NULL if not needed.
00337  * \param leader_id Current leader id can be NULL if not needed.
00338  *
00339  * \return 0, Set OK
00340  * \return <0 Set Fail
00341  */
00342 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);
00343 
00344 /**
00345  * \brief Set next partition ID when we next time partition. This is used to control specific behaviour in tests.
00346  *
00347  * \param interface_id Network Interface
00348  *
00349  * \return 0, Set OK
00350  * \return <0 Set Fail
00351  */
00352 int thread_test_partition_info_set(int8_t interface_id, uint32_t partition_id);
00353 
00354 /**
00355  * \brief Get thread information.
00356  *
00357  * \param interface_id Network Interface
00358  * \param short_addr own short address
00359  * \param router_count amount of active routers in network
00360  * \param network_stable stable network achieved no upgrade or downgrade pending
00361  *
00362  * \return 0, Set OK
00363  * \return <0 Set Fail
00364  */
00365 int8_t thread_test_thread_information_get(int8_t interface_id, uint16_t *short_addr, uint8_t *router_count, bool *network_stable);
00366 
00367 /**
00368  * \brief Get child count
00369  *
00370  * \param interface_id Network Interface
00371  *
00372  * \return 0, Set OK
00373  * \return <0 Set Fail
00374  */
00375 int8_t thread_test_child_count_get(int8_t interface_id);
00376 
00377 /**
00378  * \brief Get child information
00379  *
00380  * get information for index child. if found returns 0 with correct information.
00381  *
00382  * \param interface_id Network Interface
00383  *
00384  * \return 0, OK
00385  * \return <0 Fail no child with this index found
00386  */
00387 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);
00388 
00389 /**
00390  * \brief Get neighbour information
00391  *
00392  * \param interface_id Network Interface
00393  *
00394  * \return 0, Set OK
00395  * \return <0 Set Fail
00396  */
00397 int8_t thread_test_neighbour_info_get(int8_t interface_id, uint8_t index, uint16_t *short_addr, uint8_t *mac64, uint8_t *margin);
00398 
00399 typedef int (response_cb)(int8_t interface_id, uint8_t *response_ptr, uint16_t response_len);
00400 
00401 /**
00402  * \brief Send diagnostic command DEPRECATED
00403  *
00404  * \param interface_id      Network Interface
00405  * \param address_ptr       Address to which the command is sent
00406  * \param uri_ptr           Uri for the command
00407  * \param request_length    The length of the request
00408  * \param request_ptr       Pointer to the beginning of the request contents
00409  * \param resp_cb           Pointer to callback function that is called after the reply for the command is obtained
00410  * \return 0,               Command send OK
00411  * \return <0               Command send Fail
00412  */
00413 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);
00414 
00415 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);
00416 
00417 /**
00418  * \brief Send diagnostic request
00419  *
00420  * \param interface_id      Network Interface
00421  * \param address_ptr       Address to which the command is sent
00422  * \param msg_type           Uri for the command
00423  * \param msg_code           Uri for the command
00424  * \param uri_ptr           Uri for the command
00425  * \param request_length    The length of the request
00426  * \param request_ptr       Pointer to the beginning of the request contents
00427  * \param resp_cb           Pointer to callback function that is called after the reply for the command is obtained
00428  *
00429  * \return 0,               Command send OK
00430  * \return <0               Command send Fail
00431  */
00432 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);
00433 
00434 /**
00435  * \brief Set initial SLAAC iid.
00436  *
00437  * \param interface_id      Network Interface
00438  * \param iid               Interface identifier pointer must be 8 bytes long buffer. can be NULL to disable.
00439  * \return 0,               Command OK
00440  * \return <0               Command Fail
00441  */
00442 int8_t thread_test_initial_slaac_iid_set(int8_t interface_id, uint8_t *iid);
00443 
00444 /**
00445  * \brief Send router ID request.
00446  *
00447  * \param interface_id      Network Interface
00448  * \param status            Value of router ID request status TLV
00449  * \return 0,               Command OK
00450  * \return <0               Command Fail
00451  */
00452 int8_t thread_test_router_id_request_send(int8_t interface_id, uint8_t status);
00453 
00454 /**
00455  * \brief Set joiner port to joiner router device.
00456  * If port == 0, then default port is used.
00457  *
00458  * \param iid               Joiner port.
00459  * \return 0,               Command OK
00460  * \return <0               Command Fail
00461  */
00462 int8_t thread_test_joiner_router_joiner_port_set(uint16_t port);
00463 
00464 /**
00465  *\brief set a router address to be requested. For a router, this address is sent
00466  *\in address solicit request to leader and for leader this is the router address
00467  *
00468  * \param interface_id               Network Interface
00469  * \param router_addr                Address requested
00470  * \return 0,                        Command OK
00471  * \return <0                        Command Fail
00472  */
00473 int8_t thread_test_router_address_set(int8_t interface_id, uint16_t router_addr);
00474 
00475 #ifdef __cplusplus
00476 }
00477 #endif
00478 
00479 #endif /* DOXYGEN */
00480 #endif /* NET_THREAD_TEST_H_ */