Diff: inc/net/net_nwk_scan.h

Revision:

4:c449bead5cf3

Child:

11:1b7aaf37a131

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/net/net_nwk_scan.h	Tue Jun 24 16:48:01 2014 +0300
@@ -0,0 +1,194 @@
+#ifndef _NS_NWK_SCAN_H
+#define _NS_NWK_SCAN_H
+/*
+ * Copyright Sensinode Ltd 2011
+ * net_nwk_scan.h
+ */
+
+/**
+ * \file net_nwk_scan.h
+ * \brief Link layer Scan API for Active and Energy Detection Scan API.
+ *
+ * - arm_net_energy_scan(), Energy scan start (Use only with ZIP node library)
+ * - arm_net_nwk_scan(), Active scan for network (Use only with ZIP node library)
+ * - arm_net_get_scanned_nwk_list(), Active scan result read
+ *
+ * Scan API works only when stack is at idle state.
+ *
+ * Scan operation result will be handled at call back function which is defined by scan function call.
+ * Scan result format is as follows:
+ *
+ * | Data pointer | VALUE  										          |
+ * | :----------: | :---------------------------------------------------: |
+ * | 1.Byte       | Scan Type: NET_NWK_ENERGY_SCAN or NET_NWK_ACTIVE_SCAN |
+ * | 2.Byte       | Result length 										  |
+ * | 3+n Bytes    | Payload :Read Only at Energy Detection type	          |
+ *
+ * Result length indicates scan response size as follows:
+ *  - NET_NWK_ENERGY_SCAN payload length is result length *2 bytes after length field
+ *   * 1.Byte Channel
+ *   * 2.Byte Energy Level
+ *  - NET_NWK_ACTIVE_SCAN result indicate network count
+ *   * Network list need to read by net_get_scanned_nwk_list()
+ *
+ *
+ * Here is reference code for call back function:
+ *
+ * @code
+  	void linklayer_scan_cb(uint8_t * response)
+	{
+		uint8_t * ptr = response;
+		uint8_t response_size = 0, scan_type = 0;
+		scan_type = *ptr++;
+		response_size = *ptr++;
+
+		if(scan_type == NET_NWK_ENERGY_SCAN)
+		{
+			debug("ED Scan Ready\r\n");
+			if(response_size)
+			{
+				uint8_t channel, ed_value;
+				debug("Good channel count:");
+				debug_hex(response_size);
+				debug("\r\n");
+				while(response_size--)
+				{
+					channel = *ptr++;
+					ed_value = *ptr++;
+					debug("CH:");
+					debug_int(channel);
+					debug(",ED Level");
+					debug_int(ed_value);
+					debug("\r\n");
+				}
+			}
+		}
+		else if(scan_type == NET_NWK_ACTIVE_SCAN)
+		{
+			nwk_pan_descriptor_t *result = 0;
+			debug("Active Scan\r\n");
+			result = net_get_scanned_nwk_list();
+			if(result)
+			{
+				debug("Finded PAN-nwk\r\n");
+				debug_int(response_size);
+				debug("\r\n");
+				while(result)
+				{
+					debug("PAN-ID:");
+					printf_array(result->CoordPANId,2);
+					debug("Address:");
+					if(result->CoordAddrMode == NET_PARET_SHORT_16_BIT) //Short Address
+					{
+						printf_array(result->CoordAddress,2);
+					}
+					else
+					{
+						printf_array(result->CoordAddress,8);
+					}
+					debug("Chan:");
+					debug_int(result->LogicalChannel);
+					debug(" , LQI");
+					debug_hex(result->LinkQuality);
+					debug("\r\n");
+					if(result->beacon_length)
+					{
+						debug("Payload:");
+						printf_array(result->beacon_payload,result->beacon_length);
+					}
+					result = result->next;
+				}
+			}
+		}
+	}
+ *@endcode
+ *
+ */
+
+/** Network Energy Detection Scan Type  */
+#define NET_NWK_ENERGY_SCAN 0
+/** Network Active Scan Type  */
+#define NET_NWK_ACTIVE_SCAN 1
+
+/** Network Parent Address Type 16-bit Short */
+#define NET_PARET_SHORT_16_BIT 2
+/** Network Parent Address Type 64-bit Long */
+#define NET_PARET_LONG_64_BIT 3
+
+/* Active scan level definition */
+/** List only PAN-networks at channels */
+#define NET_ACTIVE_SCAN_ONLY_NWK 0
+/** List PAN-networks with any beacon payload */
+#define NET_ACTIVE_SCAN_ACCEPT_ANY_BEACON_PAYLOAD 1
+/** List PAN-networks with ZIP specific payload which accept join */
+#define NET_ACTIVE_SCAN_ACCEPT_ONLY_ZIP_SPESIFIC  2
+/*!
+ * \struct nwk_pan_alternative_parent_t
+ * \brief Network Alternative Parent structure.
+ */
+typedef struct nwk_pan_alternative_parent_t
+{
+    uint8_t CoordAddrMode; /**< Parent Address Mode NET_PARET_SHORT_16_BIT or NET_PARET_LONG_64_BIT*/
+    uint8_t CoordAddress[8]; /**< Parent Address based on  CoordAddrMode */
+    uint8_t LinkQuality; /**< LQI to parent */
+}nwk_pan_alternative_parent_t;
+
+/*!
+ * \struct nwk_pan_descriptor_t
+ * \brief Linked Network response list.
+ */
+typedef struct nwk_pan_descriptor_t
+{
+    uint8_t CoordAddrMode; 								/**< Parent Address Mode NET_PARET_SHORT_16_BIT or NET_PARET_LONG_64_BIT*/
+    uint16_t CoordPANId;								/**< Network PAN-ID */
+    uint8_t CoordAddress[8];							/**< Parent Address based on  CoordAddrMode */
+	uint8_t LogicalChannel;								/**< Network Channel */
+    uint8_t ChannelPage;								/**< Channel Page 0 at 2.4Ghz */
+    uint8_t SuperframeSpec[2];							/**< Network SuperFrame setup */
+    uint8_t LinkQuality;								/**< LQI to parent */
+    uint8_t *beacon_payload;							/**< Beacon Payload pointer */
+    uint8_t beacon_length;								/**< Beacon Payload length */
+    nwk_pan_alternative_parent_t* alternative_parent;	/**< Alternative Parent information pointer */
+   struct nwk_pan_descriptor_t * next;					/**< Link to next network result */
+}nwk_pan_descriptor_t;
+
+/**
+ * \brief Energy Detection scan start for configured channel with application specific threshold.
+ *
+ * \param scan_list Channel List for scan operation.
+ * \param passed_fptr function pointer for scan result notify
+ * \param energy_tresshold scan response will list all channels which level is smaller or equal
+ *
+ * \return 0 Scan operation started OK.
+ * \return -1 Stack is Active
+ * \return -2 Channel list not valid
+ * \return -3 Function not enabled at Border Router
+ *
+ */
+extern int8_t arm_net_energy_scan(int8_t interface_id,uint32_t scan_list, void (*passed_fptr)(uint8_t *), uint8_t energy_tresshold);
+/**
+ * \brief Active Network scan for configured channels.
+ *
+ * \param scan_list Channel List for scan operation.
+ * \param passed_fptr function pointer for scan result notify
+ * \param scan_level NET_ACTIVE_SCAN_ONLY_NWK, NET_ACTIVE_SCAN_ACCEPT_ANY_BEACON_PAYLOAD,NET_ACTIVE_SCAN_ACCEPT_ONLY_ZIP_SPESIFIC
+ *
+ * \return 0 Scan operation started OK.
+ * \return -1 Stack is Active
+ * \return -2 Channel list not valid
+ * \return -3 Function not enabled at Border Router
+ *
+ */
+extern int8_t arm_net_nwk_scan(int8_t interface_id,uint32_t scan_list, void (*passed_fptr)(uint8_t *), uint8_t scan_level);
+/**
+ * \brief Active scan result read.
+ *
+ * Note: Pointer is only valid at Call back function call time. Application need to allocate memory if it wants to save the result.
+ *
+ * \return >0 Pointer to Scan result.
+ * \return 0 When no network result available
+ *
+ */
+extern nwk_pan_descriptor_t * arm_net_get_scanned_nwk_list(int8_t interface_id);
+
+#endif /*_NS_NWK_SCAN_H*/