1 /*
2 * Copyright (c) 2020-2024, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33 #ifndef ti_drivers_RCL_handlers_ble5_h__include
34 #define ti_drivers_RCL_handlers_ble5_h__include
35
36 #include <stdint.h>
37 #include <ti/drivers/rcl/RCL_Command.h>
38 #include <ti/drivers/rcl/RCL_Buffer.h>
39 #include <ti/drivers/rcl/LRF.h>
40 #include <ti/drivers/rcl/commands/ble5.h>
41
42 /* Handler functions */
43 RCL_Events RCL_Handler_BLE5_adv(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
44 RCL_Events RCL_Handler_BLE5_scan_init(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
45 RCL_Events RCL_Handler_BLE5_conn(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
46 RCL_Events RCL_Handler_BLE5_dtmTx(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
47 RCL_Events RCL_Handler_BLE5_genericRx(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
48 RCL_Events RCL_Handler_BLE5_genericTx(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
49 RCL_Events RCL_Handler_Ble5_txTest(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
50 RCL_Events RCL_Handler_BLE5_aux_adv(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
51 RCL_Events RCL_Handler_BLE5_periodicAdv(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
52 RCL_Events RCL_Handler_BLE5_periodicScan(RCL_Command *cmd, LRF_Events lrfEvents, RCL_Events rclEventsIn);
53
54 /**
55 * @brief Result of filter list update API
56 *
57 * Tells if RCL_BLE5_FilterListUpdateResult succeeded
58 */
59 typedef enum
60 {
61 RCL_BLE5_FilterListUpdateOk, /*!< Update was successful */
62 RCL_BLE5_FilterListUpdateIndexError, /*!< Index was outside size of filter list or filter list was NULL */
63 } RCL_BLE5_FilterListUpdateResult;
64
65 /* API functions */
66 /**
67 * @brief Update filter list
68 *
69 * Update the given filter list in a way that is safe even if a running command is using
70 * the filter list. The contents of %newEntry will be copied into %filterList->entries[%index].
71 *
72 * If a scanner or initiator function is running, the filter list in use in the radio will also be
73 * updated in a way that ensures no match will be found on a non-existing entry. In a short time,
74 * neither the old nor new entry will give a match.
75 *
76 * If an advertiser command is running, the update will not apply until the next time the advertiser
77 * is started
78 *
79 * @param newEntry New filter list entry to apply
80 * @param filterList Filter accept list to update
81 * @param index Index into filter accept list to update
82 *
83 * @return Result telling if update was successful
84 *
85 */
86 RCL_BLE5_FilterListUpdateResult RCL_BLE5_updateFilterList(const RCL_FL_Entry *newEntry, RCL_FilterList *filterList, uint32_t index);
87
88 /**
89 * @brief Set RF frequency to use if custom frequency is specified
90 *
91 * If a command specifies to use a custom frequency, it will program the frequency last set using
92 * this function.
93 *
94 * @param rfFrequency RF frequency in Hz
95 *
96 */
97 void RCL_BLE5_setDefaultRfFrequency(uint32_t rfFrequency);
98
99 /**
100 * @brief Get channel field from packet
101 *
102 * Returns the channel that the packet was received on
103 *
104 * @param rxEntry Received data entry
105 *
106 * @return Channel for receiving packet
107 */
RCL_BLE5_getRxChannel(const RCL_Buffer_DataEntry * rxEntry)108 static inline RCL_Ble5Channel RCL_BLE5_getRxChannel(const RCL_Buffer_DataEntry *rxEntry)
109 {
110 return (RCL_Ble5Channel) rxEntry->pad0;
111 }
112
113 /**
114 * @brief Get received status field from packet
115 *
116 * Returns the packet status field of a received packet, or {.value = RCL_BLE5_RX_PKT_STATUS_INVALID} if status is not enabled
117 *
118 * @param rxEntry Received data entry
119 *
120 * @return Receive packet status
121 */
122 RCL_Ble5_RxPktStatus RCL_BLE5_getRxStatus(const RCL_Buffer_DataEntry *rxEntry);
123
124 /**
125 * @brief Get received RSSI from packet
126 *
127 * Returns the RSSI field of a received packet, or LRF_RSSI_INVALID if RSSI is not enabled
128 *
129 * @param rxEntry Received data entry
130 *
131 * @return Reported RSSI of received packet
132 */
133 int8_t RCL_BLE5_getRxRssi(const RCL_Buffer_DataEntry *rxEntry);
134
135 /**
136 * @brief Get received timestamp from packet
137 *
138 * Returns the timestamp a received packet, adjusted according to the PHY it was received on
139 * (1 Mbps assumed if packet status is not available). If timestamp is not enabled, 0 is returned.
140 * Note that this is a valid value, so it can not be used for error checking.
141 *
142 * @param rxEntry Received data entry
143 *
144 * @return Timestamp of received packet
145 */
146 uint32_t RCL_BLE5_getRxTimestamp(const RCL_Buffer_DataEntry *rxEntry);
147
148 /**
149 * @brief Get the expected start time delta associated with sending an auxiliary advertising indication
150 *
151 * Returns the expected time delta between the start time of a non-connectable/non-scannable ADV_EXT_IND
152 * sent over a specific PHY on a defined channel map, and the start time of an AUX_ADV_IND that contains
153 * the SyncInfo field needed for periodic advertising establishment.
154 *
155 * @param phyFeatures PHY feature selector
156 * @param chMap Channel map. Bit positions 0-2 correspond to channels 37-39
157 * @param advPayloadLen Payload length of ADV_EXT_IND
158 *
159 * @return Time delta in 250[ns] units between the start time of the ADV_EXT_IND and the start time of the AUX_ADV_IND
160 */
161 uint32_t RCL_BLE5_getAuxAdvStartTimeDelta(uint16_t phyFeatures, uint8_t chMap, uint8_t advPayloadLen);
162
163
164 #endif /* ti_drivers_RCL_handlers_ble5_h__include */
165
