net_thread_test.h

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