1
2#include "wifi_hal.h"
3
4#ifndef __WIFI_HAL_RTT_H__
5#define __WIFI_HAL_RTT_H__
6
7/* channel operating width */
8
9/* Ranging status */
10typedef enum {
11    RTT_STATUS_SUCCESS,
12    RTT_STATUS_FAILURE,
13    RTT_STATUS_FAIL_NO_RSP,
14    RTT_STATUS_FAIL_REJECTED,
15    RTT_STATUS_FAIL_NOT_SCHEDULED_YET,
16    RTT_STATUS_FAIL_TM_TIMEOUT,
17    RTT_STATUS_FAIL_AP_ON_DIFF_CHANNEL,
18    RTT_STATUS_FAIL_NO_CAPABILITY,
19    RTT_STATUS_ABORTED
20} wifi_rtt_status;
21
22
23/* RTT Type */
24typedef enum {
25    RTT_TYPE_INVALID,
26    RTT_TYPE_1_SIDED,
27    RTT_TYPE_2_SIDED,
28    RTT_TYPE_AUTO,              // Two sided if remote supports; one sided otherwise
29} wifi_rtt_type;
30
31/* RTT configuration */
32typedef struct {
33    mac_addr addr;                     // peer device mac address
34    wifi_rtt_type type;                // optional - rtt type hint. RTT_TYPE_INVALID implies best effort
35    wifi_peer_type peer;               // optional - peer device hint (STA, P2P, AP)
36    wifi_channel_info channel;         // Required for STA-AP mode, optional for P2P, NBD etc.
37    byte continuous;                   // 0 = single shot or 1 = continuous ranging
38    unsigned interval;                 // interval of RTT measurement (unit ms) when continuous = true
39    unsigned num_measurements;         // total number of RTT measurements when continuous = true
40    unsigned num_samples_per_measurement; // num of packets in each RTT measurement
41    unsigned num_retries_per_measurement; // num of retries if sampling fails
42} wifi_rtt_config;
43
44/* RTT results */
45typedef struct {
46    mac_addr addr;               // device mac address
47    unsigned measurement_num;    // measurement number in case of continuous ranging
48    wifi_rtt_status status;      // ranging status
49    wifi_rtt_type type;          // RTT type
50    wifi_peer_type peer;         // peer device type (P2P, AP)
51    wifi_channel_info channel;   // channel information
52    wifi_rssi rssi;              // rssi in 0.5 dB steps e.g. 143 implies -71.5 dB
53    wifi_rssi rssi_spread;       // rssi spread in 0.5 dB steps e.g. 5 implies 2.5 dB spread (optional)
54    wifi_rate tx_rate;           // TX rate
55    wifi_timespan rtt;           // round trip time in nanoseconds
56    wifi_timespan rtt_sd;        // rtt standard deviation in nanoseconds
57    wifi_timespan rtt_spread;    // difference between max and min rtt times recorded
58    int distance;                // distance in cm (optional)
59    int distance_sd;             // standard deviation in cm (optional)
60    int distance_spread;         // difference between max and min distance recorded (optional)
61    wifi_timestamp ts;           // time of the measurement (in microseconds since boot)
62} wifi_rtt_result;
63
64/* RTT result callback */
65typedef struct {
66    void (*on_rtt_results) (wifi_request_id id, unsigned num_results, wifi_rtt_result rtt_result[]);
67} wifi_rtt_event_handler;
68
69/* API to request RTT measurement */
70wifi_error wifi_rtt_range_request(wifi_request_id id, wifi_interface_handle iface,
71        unsigned num_rtt_config, wifi_rtt_config rtt_config[], wifi_rtt_event_handler handler);
72
73/* API to cancel RTT measurements */
74wifi_error wifi_rtt_range_cancel(wifi_request_id id,  wifi_interface_handle iface,
75        unsigned num_devices, mac_addr addr[]);
76
77/* NBD ranging channel map */
78typedef struct {
79    wifi_channel availablity[32];           // specifies the channel map for each of the 16 TU windows
80                                            // frequency of 0 => unspecified; which means firmware is
81                                            // free to do whatever it wants in this window.
82} wifi_channel_map;
83
84/* API to start publishing the channel map on responder device in a NBD cluster.
85   Responder device will take this request and schedule broadcasting the channel map
86   in a NBD ranging attribute in a SDF. DE will automatically remove the ranging
87   attribute from the OTA queue after number of DW specified by num_dw
88   where Each DW is 512 TUs apart */
89wifi_error wifi_rtt_channel_map_set(wifi_request_id id,
90        wifi_interface_handle iface, wifi_channel_map *params, unsigned num_dw);
91
92/* API to clear the channel map on the responder device in a NBD cluster.
93   Responder device will cancel future ranging channel request, starting from next
94   DW interval and will also stop broadcasting NBD ranging attribute in SDF */
95wifi_error wifi_rtt_channel_map_clear(wifi_request_id id,  wifi_interface_handle iface);
96
97/* RTT Capabilities */
98typedef struct {
99   byte rtt_one_sided_supported;  // if 1-sided rtt data collection is supported
100   byte rtt_11v_supported;        // if 11v rtt data collection is supported
101   byte rtt_ftm_supported;        // if ftm rtt data collection is supported
102} wifi_rtt_capabilities;
103
104/*  RTT capabilities of the device */
105wifi_error wifi_get_rtt_capabilities(wifi_interface_handle iface, wifi_rtt_capabilities *capabilities);
106
107#endif
108
109