net_nwk_scan.h

00001 /*
00002  * Copyright (c) 2013-2016 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 #ifndef _NS_NWK_SCAN_H
00015 #define _NS_NWK_SCAN_H
00016 #ifdef __cplusplus
00017 extern "C" {
00018 #endif
00019 
00020 #include "ns_types.h"
00021 #include "net_interface.h" /* needed for channel_list_s */
00022 #include "mlme.h"
00023 
00024 /**
00025  * \file net_nwk_scan.h
00026  * \brief Link layer Scan API for Active and Energy Detection Scan API.
00027  *
00028  * - arm_net_energy_scan(), Energy scan start (Use only with ZIP node library).
00029  * - arm_net_nwk_scan(), Active scan for network (Use only with ZIP node library).
00030  * - arm_net_get_scanned_nwk_list(), Active scan result read.
00031  *
00032  * Scan API works only when stack is in idle state.
00033  *
00034  * The scan operation result is handled at callback function that is defined by scan function call.
00035  * The scan result format is as follows:
00036  *
00037  * | Data pointer | VALUE                                                 |
00038  * | :----------: | :---------------------------------------------------: |
00039  * | 1.Byte       | Scan Type: NET_NWK_ENERGY_SCAN or NET_NWK_ACTIVE_SCAN |
00040  * | 2.Byte       | Result length                                         |
00041  * | 3+n Bytes    | Payload :Read Only at Energy Detection type           |
00042  *
00043  * The result length indicates the scan response size as follows:
00044  *  - NET_NWK_ENERGY_SCAN Payload length is result length *2 bytes after length field.
00045  *   * 1.Byte Channel
00046  *   * 2.Byte Energy Level
00047  *  - NET_NWK_ACTIVE_SCAN result indicates the the number of networks.
00048  *   * The network list needs to be read by net_get_scanned_nwk_list().
00049  *
00050  */
00051 
00052 /** Network energy detection scan type  */
00053 #define NET_NWK_ENERGY_SCAN 0
00054 /** Network active scan type  */
00055 #define NET_NWK_ACTIVE_SCAN 1
00056 
00057 /** Network parent address type 16-bit short */
00058 #define NET_PARET_SHORT_16_BIT 2
00059 /** Network parent address type 64-bit long */
00060 #define NET_PARET_LONG_64_BIT 3
00061 
00062 /* Active scan level definition */
00063 /** List only PAN networks at channels */
00064 #define NET_ACTIVE_SCAN_ONLY_NWK 0
00065 /** List PAN networks with any beacon payload */
00066 #define NET_ACTIVE_SCAN_ACCEPT_ANY_BEACON_PAYLOAD 1
00067 /** List PAN networks with ZIP-specific payload that accept join */
00068 #define NET_ACTIVE_SCAN_ACCEPT_ONLY_ZIP_SPESIFIC  2
00069 /*!
00070  * \struct nwk_pan_alternative_parent_t
00071  * \brief Network alternative parent structure.
00072  */
00073 typedef struct nwk_pan_alternative_parent_t {
00074     uint8_t CoordAddrMode; /**< Parent address mode NET_PARET_SHORT_16_BIT or NET_PARET_LONG_64_BIT. */
00075     uint8_t CoordAddress[8]; /**< Parent address based on CoordAddrMode. */
00076     uint8_t LinkQuality; /**< LQI to parent. */
00077 } nwk_pan_alternative_parent_t;
00078 
00079 /*!
00080  * \struct nwk_pan_descriptor_t
00081  * \brief Linked network response list.
00082  */
00083 typedef struct nwk_pan_descriptor_t {
00084     mlme_pan_descriptor_t *pan_descriptor;              /**< Pan Description */
00085     uint8_t *beacon_payload;                            /**< Beacon Payload pointer */
00086     uint8_t beacon_length;                              /**< Beacon Payload length */
00087     nwk_pan_alternative_parent_t alternative_parent;   /**< Alternative Parent information pointer */
00088     struct nwk_pan_descriptor_t *next;                   /**< Link to next network result */
00089 } nwk_pan_descriptor_t;
00090 
00091 /**
00092  * \brief Energy detection scan start for configured channel with application-specific threshold.
00093  *
00094  * \param interface_id Interface id.
00095  * \param scan_list Channel list for scan operation.
00096  * \param passed_fptr A function pointer for scan result notify.
00097  * \param energy_tresshold Scan response lists all channels with smaller or equal level.
00098  *
00099  * \return 0 Scan operation started OK.
00100  * \return -1 Stack is active.
00101  * \return -2 Channel list not valid.
00102  * \return -3 Function not enabled at border router.
00103  *
00104  */
00105 extern int8_t arm_net_energy_scan(int8_t interface_id, channel_list_s *scan_list, void (*passed_fptr)(int8_t if_id, const mlme_scan_conf_t *conf), uint8_t energy_tresshold);
00106 /**
00107  * \brief Active network scan for configured channels.
00108  *
00109  * \param interface_id Interface id.
00110  * \param scan_list Channel list for scan operation.
00111  * \param passed_fptr A function pointer for scan result notify.
00112  * \param scan_level NET_ACTIVE_SCAN_ONLY_NWK, NET_ACTIVE_SCAN_ACCEPT_ANY_BEACON_PAYLOAD,NET_ACTIVE_SCAN_ACCEPT_ONLY_ZIP_SPESIFIC
00113  *
00114  * \return 0 Scan operation started OK.
00115  * \return -1 Stack is active.
00116  * \return -2 Channel list not valid.
00117  * \return -3 Function not enabled at border router.
00118  *
00119  */
00120 extern int8_t arm_net_nwk_scan(int8_t interface_id, channel_list_s *scan_list, void (*passed_fptr)(int8_t if_id, const mlme_scan_conf_t *conf), uint8_t scan_level);
00121 /**
00122  * \brief Active scan result read.
00123  *
00124  * Note: The pointer is only valid at callback function call time. The application needs to allocate memory if it wants to save the result.
00125  *
00126  * \return >0 A pointer to scan result.
00127  * \return 0 No network results available.
00128  *
00129  */
00130 extern nwk_pan_descriptor_t *arm_net_get_scanned_nwk_list(int8_t interface_id);
00131 #ifdef __cplusplus
00132 }
00133 #endif
00134 #endif /*_NS_NWK_SCAN_H*/