1 //***************************************************************************** 2 // 3 //! @file am_util_ble_cooper.h 4 //! 5 //! @brief Cooper BLE functions not covered by the HAL. 6 //! 7 //! This file contains functions for interacting with the Apollo4 BLE hardware 8 //! that are not already covered by the HAL. Most of these commands either 9 //! adjust RF settings or facilitate RF testing operations. 10 //! 11 //! @addtogroup ble_cooper Cooper - BLE Functions 12 //! @ingroup utils 13 //! @{ 14 // 15 //***************************************************************************** 16 17 //***************************************************************************** 18 // 19 // Copyright (c) 2023, Ambiq Micro, Inc. 20 // All rights reserved. 21 // 22 // Redistribution and use in source and binary forms, with or without 23 // modification, are permitted provided that the following conditions are met: 24 // 25 // 1. Redistributions of source code must retain the above copyright notice, 26 // this list of conditions and the following disclaimer. 27 // 28 // 2. Redistributions in binary form must reproduce the above copyright 29 // notice, this list of conditions and the following disclaimer in the 30 // documentation and/or other materials provided with the distribution. 31 // 32 // 3. Neither the name of the copyright holder nor the names of its 33 // contributors may be used to endorse or promote products derived from this 34 // software without specific prior written permission. 35 // 36 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 37 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 38 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 39 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 40 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 41 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 42 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 43 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 44 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 45 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 46 // POSSIBILITY OF SUCH DAMAGE. 47 // 48 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 49 // 50 //***************************************************************************** 51 52 #ifndef AM_UTIL_BLE_COOPER_H 53 #define AM_UTIL_BLE_COOPER_H 54 55 //***************************************************************************** 56 // 57 // External function declarations. 58 // 59 //***************************************************************************** 60 #ifdef __cplusplus 61 extern "C" 62 { 63 #endif 64 65 //***************************************************************************** 66 // 67 //! @brief Read a register value from the BLE core. 68 //! 69 //! @param pHandle - pointer to BLE Handle 70 //! @param ui32Address - address to read 71 //! @param pui32Value - pointer to read value 72 //! 73 //! @return Status Code 74 // 75 //***************************************************************************** 76 extern uint32_t am_util_ble_plf_reg_read(void* pHandle, 77 uint32_t ui32Address, 78 uint32_t* pui32Value); 79 80 //***************************************************************************** 81 // 82 //! @brief Write a register value to the BLE core. 83 //! 84 //! @param pHandle - pointer to BLE Handle 85 //! @param ui32Address - address to read 86 //! @param ui32Value - write value 87 //! 88 //! @return Status Code 89 // 90 //***************************************************************************** 91 extern uint32_t am_util_ble_plf_reg_write(void* pHandle, 92 uint32_t ui32Address, 93 uint32_t ui32Value); 94 95 //***************************************************************************** 96 // 97 //! @brief Manually enable/disable transmitter to output carrier signal 98 //! set ui8TxChannel as 0 to 0x27 for each transmit channel, 0xFF back to normal 99 //! modulate mode 100 //! 101 //! @param pHandle - pointer to BLE Handle 102 //! 103 //! @return Status Code 104 // 105 //***************************************************************************** 106 extern uint32_t am_util_ble_hci_reset(void *pHandle); 107 108 //***************************************************************************** 109 // 110 //! @brief Set BLE sleep enable/disable for the BLE core. 111 //! enable = 'true' set sleep enable, enable = 'false' set sleep disable 112 //! 113 //! @param pHandle - pointer to BLE Handle 114 //! @param enable - enable/disable 115 //! 116 //! @return Status Code 117 // 118 //***************************************************************************** 119 extern uint32_t am_util_ble_sleep_set(void* pHandle, bool enable); 120 121 //***************************************************************************** 122 // 123 //! @brief set the tx power of BLE 124 //! 125 //! @param pHandle - pointer to BLE Handle 126 //! @param ui32TxPower - enum txPowerLevel_t defined in hci_drv_cooper.h 127 //! 128 //! @return Status Code 129 // 130 //***************************************************************************** 131 extern uint32_t am_util_ble_tx_power_set(void* pHandle, uint8_t ui32TxPower); 132 133 //***************************************************************************** 134 // 135 //! @brief Write NVDS parameters to the BLE core. 136 //! 137 //! @param pHandle - pointer to BLE Handle 138 //! @param pui8NVDS - pointer to NVDS parameters 139 //! @param ui8Length - length of parameters 140 //! 141 //! @return Status Code 142 // 143 //***************************************************************************** 144 extern uint32_t am_util_ble_nvds_set(void *pHandle, 145 uint8_t* pui8NVDS, 146 uint8_t ui8Length); 147 148 #if defined(AM_PART_APOLLO4B) || defined(AM_PART_APOLLO4L) || defined(AM_PART_APOLLO4P) 149 //***************************************************************************** 150 // 151 //! @brief Write update signature to the BLE core. 152 //! 153 //! @param pHandle - pointer to BLE Handle 154 //! @param ui32Sign - signature to update 155 //! 156 //! @return Status Code 157 // 158 //***************************************************************************** 159 extern uint32_t am_util_ble_update_sign_set(void *pHandle, uint32_t ui32Sign); 160 #endif 161 162 //***************************************************************************** 163 // 164 //! @brief to do directly output modulation signal. 165 //! channel ranges from 0 to 0x27, pattern from 0 to 7. 166 //! 167 //! @param pHandle - pointer to BLE Handle 168 //! @param channel - channel number 169 //! @param pattern - pattern for TX test 170 //! 171 //! @return Status Code 172 // 173 //***************************************************************************** 174 extern uint32_t am_util_ble_trasmitter_test_ex(void *pHandle, 175 uint8_t channel, 176 uint8_t pattern); 177 178 //***************************************************************************** 179 // 180 //! @brief Receiver test. 181 //! change channel ranges from 0 to 0x27, return received packets in 100ms. 182 //! 183 //! @param pHandle - pointer to BLE Handle 184 //! @param channel - channel number 185 //! @param recvpackets - pointer for RX Packets 186 //! 187 //! @return Status Code 188 // 189 //***************************************************************************** 190 extern uint32_t am_util_ble_receiver_test_ex(void *pHandle, 191 uint8_t channel, 192 uint32_t *recvpackets); 193 194 //***************************************************************************** 195 // 196 //! @brief Dump info0 of BLE controller for debug use. 197 //! 198 //! @return Status Code 199 // 200 //***************************************************************************** 201 extern uint32_t am_util_ble_info0_dump(void *pHandle); 202 203 //***************************************************************************** 204 // 205 //! @brief get cooper TRIM version. 206 //! 207 //! @param pHandle - pointer to BLE Handle 208 //! @param pui32TrimVer - pointer to Trim Version 209 //! @param pui32RetvTrimVer - pointer to Return Value for Trim Version 210 //! 211 //! @return Status Code 212 // 213 //***************************************************************************** 214 extern uint32_t am_util_ble_trim_version_get(void* pHandle, 215 uint32_t *pui32TrimVer, 216 uint32_t *pui32RetvTrimVer); 217 218 //***************************************************************************** 219 // 220 //! @brief API to disable the BLE controller's firmware rollback version 221 //! (Enabled in default) 222 //! Should be called as the very last step during manufacturing, after it done, 223 //! the BLE controller will reset. 224 //! 225 //! @param pHandle - pointer to BLE Handle 226 //! @param pDevConfig - pointer to Device Configuration 227 //! 228 //! @return Status Code 229 // 230 //***************************************************************************** 231 extern uint32_t am_util_ble_disable_rollback(void* pHandle, void* pDevConfig); 232 233 #ifdef __cplusplus 234 } 235 #endif 236 237 #endif // AM_UTIL_BLE_COOPER_H 238 239 //***************************************************************************** 240 // 241 // End Doxygen group. 242 //! @} 243 // 244 //***************************************************************************** 245 246
