Add active scan to API and CLI. (#27)

* Add active scan functions and definitions to core C api. * Add active scan command to CLI. * Add emulation of PHY channel isolation.
2026-10-23 16:08:01 +00:00 · 2016-05-13 15:14:04 -07:00
parent baa8994190
commit 1f24fa44fa
14 changed files with 546 additions and 278 deletions
@@ -65,6 +65,49 @@ typedef enum ThreadError
    kThreadError_Error = 255,
 } ThreadError;

+
+#define OT_EXT_ADDRESS_SIZE   8   ///< Size of an IEEE 802.15.4 Extended Address (bytes)
+#define OT_EXT_PAN_ID_SIZE    8   ///< Size of a Thread PAN ID (bytes)
+#define OT_NETWORK_NAME_SIZE  16  ///< Size of the Thread Network Name field (bytes)
+
+/**
+ * This type represents the IEEE 802.15.4 PAN ID.
+ *
+ */
+typedef uint16_t otPanId;
+
+/**
+ * This type represents the IEEE 802.15.4 Short Address.
+ *
+ */
+typedef uint16_t otShortAddress;
+
+/**
+ * This type represents the IEEE 802.15.4 Extended Address.
+ *
+ */
+typedef struct otExtAddress
+{
+    uint8_t m8[OT_EXT_ADDRESS_SIZE];  ///< IEEE 802.15.4 Extended Address bytes
+} otExtAddress;
+
+/**
+ * This struct represents a received IEEE 802.15.4 Beacon.
+ *
+ */
+typedef struct otActiveScanResult
+{
+    otExtAddress   mExtAddress;      ///< IEEE 802.15.4 Extended Address
+    const char    *mNetworkName;     ///< Thread Network Name
+    const uint8_t *mExtPanId;        ///< Thread Extended PAN ID
+    uint16_t       mPanId;           ///< IEEE 802.15.4 PAN ID
+    uint8_t        mChannel;         ///< IEEE 802.15.4 Channel
+    int8_t         mRssi;            ///< RSSI (dBm)
+    uint8_t        mVersion : 4;     ///< Version
+    bool           mIsNative : 1;    ///< Native Commissioner flag
+    bool           mIsJoinable : 1;  ///< Joining Permitted flag
+} otActiveScanResult;
+
 /**
 * @addtogroup config  Configuration
 *
@@ -51,6 +51,7 @@ extern "C" {
 * @{
 *
 * @defgroup execution Execution
+ * @defgroup commands Commands
 * @defgroup config Configuration
 * @defgroup diags Diagnostics
 * @defgroup messages Message Buffers
@@ -130,6 +131,57 @@ bool otAreTaskletsPending(void);
 */
 extern void otSignalTaskletPending(void);

+/**
+ * @}
+ *
+ */
+
+/**
+ * @addtogroup commands  Commands
+ *
+ * @brief
+ *   This module includes functions for OpenThread commands.
+ *
+ * @{
+ *
+ */
+
+/**
+ * Enable the Thread interface.
+ *
+ * @retval kThreadErrorNone  Successfully enabled the Thread interface.
+ */
+ThreadError otEnable(void);
+
+/**
+ * Disable the Thread interface.
+ *
+ * @retval kThreadErrorNone  Successfully disabled the Thread interface.
+ */
+ThreadError otDisable(void);
+
+/**
+ * This function pointer is called during an IEEE 802.15.4 Active Scan when an IEEE 802.15.4 Beacon is received or
+ * the scan completes.
+ *
+ * @param[in]  aResult  A valid pointer to the beacon information or NULL when the active scan completes.
+ *
+ */
+typedef void (*otHandleActiveScanResult)(otActiveScanResult *aResult);
+
+/**
+ * This function starts an IEEE 802.15.4 Active Scan
+ *
+ * @param[in]  aScanChannels  A bit vector indicating which channels to scan.
+ * @param[in]  aScanDuration  The time in milliseconds to spend scanning each channel.
+ * @param[in]  aCallback      A pointer to a function that is called when a beacon is received or the scan completes.
+ *
+ * @retval kThreadError_None  Accepted the Active Scan request.
+ * @retval kThreadError_Busy  Already performing an Active Scan.
+ *
+ */
+ThreadError otActiveScan(uint16_t aScanChannels, uint16_t aScanDuration, otHandleActiveScanResult aCallback);
+
 /**
 * @}
 *
@@ -289,7 +341,7 @@ ThreadError otSetNetworkName(const char *aNetworkName);
 *
 * @sa otSetPanId
 */
-uint16_t otGetPanId(void);
+otPanId otGetPanId(void);

 /**
 * Set the IEEE 802.15.4 PAN ID.
@@ -301,7 +353,34 @@ uint16_t otGetPanId(void);
 *
 * @sa otGetPanId
 */
-ThreadError otSetPanId(uint16_t aPanId);
+ThreadError otSetPanId(otPanId aPanId);
+
+/**
+ * Get the list of IPv6 addresses assigned to the Thread interface.
+ *
+ * @returns A pointer to the first Network Inteface Address.
+ */
+const otNetifAddress *otGetUnicastAddresses();
+
+/**
+ * Add a Network Interface Address to the Thread interface.
+ *
+ * @param[in]  aAddress  A pointer to a Network Interface Address.
+ *
+ * @retval kThreadErrorNone  Successfully added the Network Interface Address.
+ * @retval kThreadErrorBusy  The Network Interface Address pointed to by @p aAddress is already added.
+ */
+ThreadError otAddUnicastAddress(otNetifAddress *aAddress);
+
+/**
+ * Remove a Network Interface Address from the Thread interface.
+ *
+ * @param[in]  aAddress  A pointer to a Network Interface Address.
+ *
+ * @retval kThreadErrorNone      Successfully removed the Network Interface Address.
+ * @retval kThreadErrorNotFound  The Network Interface Address point to by @p aAddress was not added.
+ */
+ThreadError otRemoveUnicastAddress(otNetifAddress *aAddress);

 /**
 * @}
@@ -730,47 +809,6 @@ bool otIsIp6AddressEqual(const otIp6Address *a, const otIp6Address *b);
 */
 ThreadError otIp6AddressFromString(const char *aString, otIp6Address *aAddress);

-/**
- * Get the list of IPv6 addresses assigned to the Thread interface.
- *
- * @returns A pointer to the first Network Inteface Address.
- */
-const otNetifAddress *otGetUnicastAddresses();
-
-/**
- * Add a Network Interface Address to the Thread interface.
- *
- * @param[in]  aAddress  A pointer to a Network Interface Address.
- *
- * @retval kThreadErrorNone  Successfully added the Network Interface Address.
- * @retval kThreadErrorBusy  The Network Interface Address pointed to by @p aAddress is already added.
- */
-ThreadError otAddUnicastAddress(otNetifAddress *aAddress);
-
-/**
- * Remove a Network Interface Address from the Thread interface.
- *
- * @param[in]  aAddress  A pointer to a Network Interface Address.
- *
- * @retval kThreadErrorNone      Successfully removed the Network Interface Address.
- * @retval kThreadErrorNotFound  The Network Interface Address point to by @p aAddress was not added.
- */
-ThreadError otRemoveUnicastAddress(otNetifAddress *aAddress);
-
-/**
- * Enable the Thread interface.
- *
- * @retval kThreadErrorNone  Successfully enabled the Thread interface.
- */
-ThreadError otEnable(void);
-
-/**
- * Disable the Thread interface.
- *
- * @retval kThreadErrorNone  Successfully disabled the Thread interface.
- */
-ThreadError otDisable(void);
-
 /**
 * @addtogroup messages  Message Buffers
 *