net_nwk_scan.h

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