ant_bpwr.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377
  1. /**
  2. * Copyright (c) 2015 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. /**
  41. * @file
  42. * @defgroup ant_bpwr Bicycle Power profile
  43. * @{
  44. * @ingroup ant_sdk_profiles
  45. * @brief This module implements the Bicycle Power profile.
  46. *
  47. */
  48. #ifndef ANT_BICYCLE_POWER_H__
  49. #define ANT_BICYCLE_POWER_H__
  50. #include <stdint.h>
  51. #include <stdbool.h>
  52. #include "ant_parameters.h"
  53. #include "nrf_sdh_ant.h"
  54. #include "ant_channel_config.h"
  55. #include "ant_bpwr_pages.h"
  56. #include "sdk_errors.h"
  57. #define BPWR_DEVICE_TYPE 0x0Bu ///< Device type reserved for ANT+ Bicycle Power.
  58. #define BPWR_ANTPLUS_RF_FREQ 0x39u ///< Frequency, decimal 57 (2457 MHz).
  59. #define BPWR_MSG_PERIOD 8182u ///< Message period, decimal 8182 (4.0049 Hz).
  60. #define BPWR_EXT_ASSIGN 0x00 ///< ANT ext assign (see Ext. Assign Channel Parameters in ant_parameters.h: @ref ant_parameters).
  61. #define BPWR_DISP_CHANNEL_TYPE CHANNEL_TYPE_SLAVE ///< Display Bicycle Power channel type.
  62. #define BPWR_SENS_CHANNEL_TYPE CHANNEL_TYPE_MASTER ///< Sensor Bicycle Power channel type.
  63. #define BPWR_CALIBRATION_TIMOUT_S 5u ///< Time-out for responding to calibration callback (s).
  64. /**@brief Initialize an ANT channel configuration structure for the Bicycle Power profile (Display).
  65. *
  66. * @param[in] NAME Name of related instance.
  67. * @param[in] CHANNEL_NUMBER Number of the channel assigned to the profile instance.
  68. * @param[in] TRANSMISSION_TYPE Type of transmission assigned to the profile instance.
  69. * @param[in] DEVICE_NUMBER Number of the device assigned to the profile instance.
  70. * @param[in] NETWORK_NUMBER Number of the network assigned to the profile instance.
  71. */
  72. #define BPWR_DISP_CHANNEL_CONFIG_DEF(NAME, \
  73. CHANNEL_NUMBER, \
  74. TRANSMISSION_TYPE, \
  75. DEVICE_NUMBER, \
  76. NETWORK_NUMBER) \
  77. static const ant_channel_config_t CONCAT_2(NAME, _channel_bpwr_disp_config) = \
  78. { \
  79. .channel_number = (CHANNEL_NUMBER), \
  80. .channel_type = BPWR_DISP_CHANNEL_TYPE, \
  81. .ext_assign = BPWR_EXT_ASSIGN, \
  82. .rf_freq = BPWR_ANTPLUS_RF_FREQ, \
  83. .transmission_type = (TRANSMISSION_TYPE), \
  84. .device_type = BPWR_DEVICE_TYPE, \
  85. .device_number = (DEVICE_NUMBER), \
  86. .channel_period = BPWR_MSG_PERIOD, \
  87. .network_number = (NETWORK_NUMBER), \
  88. }
  89. #define BPWR_DISP_CHANNEL_CONFIG(NAME) &CONCAT_2(NAME, _channel_bpwr_disp_config)
  90. /**@brief Initialize an ANT channel configuration structure for the Bicycle Power profile (Sensor).
  91. *
  92. * @param[in] NAME Name of related instance.
  93. * @param[in] CHANNEL_NUMBER Number of the channel assigned to the profile instance.
  94. * @param[in] TRANSMISSION_TYPE Type of transmission assigned to the profile instance.
  95. * @param[in] DEVICE_NUMBER Number of the device assigned to the profile instance.
  96. * @param[in] NETWORK_NUMBER Number of the network assigned to the profile instance.
  97. */
  98. #define BPWR_SENS_CHANNEL_CONFIG_DEF(NAME, \
  99. CHANNEL_NUMBER, \
  100. TRANSMISSION_TYPE, \
  101. DEVICE_NUMBER, \
  102. NETWORK_NUMBER) \
  103. static const ant_channel_config_t CONCAT_2(NAME, _channel_bpwr_sens_config) = \
  104. { \
  105. .channel_number = (CHANNEL_NUMBER), \
  106. .channel_type = BPWR_SENS_CHANNEL_TYPE, \
  107. .ext_assign = BPWR_EXT_ASSIGN, \
  108. .rf_freq = BPWR_ANTPLUS_RF_FREQ, \
  109. .transmission_type = (TRANSMISSION_TYPE), \
  110. .device_type = BPWR_DEVICE_TYPE, \
  111. .device_number = (DEVICE_NUMBER), \
  112. .channel_period = BPWR_MSG_PERIOD, \
  113. .network_number = (NETWORK_NUMBER), \
  114. }
  115. #define BPWR_SENS_CHANNEL_CONFIG(NAME) &CONCAT_2(NAME, _channel_bpwr_sens_config)
  116. /**@brief Initialize an ANT profile configuration structure for the BPWR profile (Display).
  117. *
  118. * @param[in] NAME Name of related instance.
  119. * @param[in] EVT_HANDLER Event handler to be called for handling events in the BPWR profile.
  120. */
  121. #define BPWR_DISP_PROFILE_CONFIG_DEF(NAME, \
  122. EVT_HANDLER) \
  123. static ant_bpwr_disp_cb_t CONCAT_2(NAME, _bpwr_disp_cb); \
  124. static const ant_bpwr_disp_config_t CONCAT_2(NAME, _profile_bpwr_disp_config) = \
  125. { \
  126. .p_cb = &CONCAT_2(NAME, _bpwr_disp_cb), \
  127. .evt_handler = (EVT_HANDLER), \
  128. }
  129. #define BPWR_DISP_PROFILE_CONFIG(NAME) &CONCAT_2(NAME, _profile_bpwr_disp_config)
  130. /**@brief Initialize an ANT profile configuration structure for the BPWR profile (Sensor).
  131. *
  132. * @param[in] NAME Name of related instance.
  133. * @param[in] TORQUE_USED Determines whether the torque page is included.
  134. * @param[in] CALIB_HANDLER Event handler to be called for handling calibration requests.
  135. * @param[in] EVT_HANDLER Event handler to be called for handling events in the BPWR profile.
  136. */
  137. #define BPWR_SENS_PROFILE_CONFIG_DEF(NAME, \
  138. TORQUE_USED, \
  139. CALIB_HANDLER, \
  140. EVT_HANDLER) \
  141. static ant_bpwr_sens_cb_t CONCAT_2(NAME, _bpwr_sens_cb); \
  142. static const ant_bpwr_sens_config_t CONCAT_2(NAME, _profile_bpwr_sens_config) = \
  143. { \
  144. .torque_use = (TORQUE_USED), \
  145. .calib_handler = (CALIB_HANDLER), \
  146. .p_cb = &CONCAT_2(NAME, _bpwr_sens_cb), \
  147. .evt_handler = (EVT_HANDLER), \
  148. }
  149. #define BPWR_SENS_PROFILE_CONFIG(NAME) &NAME##_profile_bpwr_sens_config
  150. /**@brief Configuration values for the Bicycle Power torque page. */
  151. typedef enum
  152. {
  153. TORQUE_NONE = 0,
  154. TORQUE_WHEEL = 1,
  155. TORQUE_CRANK = 2,
  156. } ant_bpwr_torque_t;
  157. /**@brief Bicycle Power page number type. */
  158. typedef enum
  159. {
  160. ANT_BPWR_PAGE_1 = 1, ///< Calibration data page.
  161. ANT_BPWR_PAGE_16 = 16, ///< Standard power-only main data page.
  162. ANT_BPWR_PAGE_17 = 17, ///< Standard wheel torque main data page.
  163. ANT_BPWR_PAGE_18 = 18, ///< Standard crank torque main data page.
  164. ANT_BPWR_PAGE_80 = ANT_COMMON_PAGE_80,
  165. ANT_BPWR_PAGE_81 = ANT_COMMON_PAGE_81
  166. } ant_bpwr_page_t;
  167. /**@brief BPWR profile event type. */
  168. typedef enum
  169. {
  170. ANT_BPWR_PAGE_1_UPDATED = ANT_BPWR_PAGE_1, ///< Data page 1 and speed have been updated (Display) or sent (Sensor).
  171. ANT_BPWR_PAGE_16_UPDATED = ANT_BPWR_PAGE_16, ///< Data page 16 and speed have been updated (Display) or sent (Sensor).
  172. ANT_BPWR_PAGE_17_UPDATED = ANT_BPWR_PAGE_17, ///< Data page 17 and speed have been updated (Display) or sent (Sensor).
  173. ANT_BPWR_PAGE_18_UPDATED = ANT_BPWR_PAGE_18, ///< Data page 18 has been updated (Display) or sent (Sensor).
  174. ANT_BPWR_PAGE_80_UPDATED = ANT_BPWR_PAGE_80, ///< Data page 80 has been updated (Display) or sent (Sensor).
  175. ANT_BPWR_PAGE_81_UPDATED = ANT_BPWR_PAGE_81, ///< Data page 81 has been updated (Display) or sent (Sensor).
  176. ANT_BPWR_CALIB_TIMEOUT, ///< Request of calibration time-out occurred (Display).
  177. ANT_BPWR_CALIB_REQUEST_TX_FAILED, ///< Calibration request did not reach the destination (Display).
  178. } ant_bpwr_evt_t;
  179. // Forward declaration of the ant_bpwr_profile_t type.
  180. typedef struct ant_bpwr_profile_s ant_bpwr_profile_t;
  181. /**@brief BPWR event handler type. */
  182. typedef void (* ant_bpwr_evt_handler_t) (ant_bpwr_profile_t *, ant_bpwr_evt_t);
  183. /**@brief BPWR Sensor calibration request handler type. */
  184. typedef void (* ant_bpwr_calib_handler_t) (ant_bpwr_profile_t *, ant_bpwr_page1_data_t *);
  185. #include "ant_bpwr_local.h"
  186. #ifdef __cplusplus
  187. extern "C" {
  188. #endif
  189. /**@brief Bicycle Power Sensor configuration structure. */
  190. typedef struct
  191. {
  192. ant_bpwr_torque_t torque_use; ///< Determines whether the torque page is included.
  193. ant_bpwr_sens_cb_t * p_cb; ///< Pointer to the data buffer for internal use.
  194. ant_bpwr_evt_handler_t evt_handler; ///< Event handler to be called for handling events in the BPWR profile.
  195. ant_bpwr_calib_handler_t calib_handler; ///< Event handler to be called for handling calibration requests.
  196. } ant_bpwr_sens_config_t;
  197. /**@brief Bicycle Power Display configuration structure. */
  198. typedef struct
  199. {
  200. ant_bpwr_disp_cb_t * p_cb; ///< Pointer to the data buffer for internal use.
  201. ant_bpwr_evt_handler_t evt_handler; ///< Event handler to be called for handling events in the BPWR profile.
  202. } ant_bpwr_disp_config_t;
  203. /**@brief Bicycle Power profile structure. */
  204. struct ant_bpwr_profile_s
  205. {
  206. uint8_t channel_number; ///< Channel number assigned to the profile.
  207. union {
  208. ant_bpwr_disp_cb_t * p_disp_cb;
  209. ant_bpwr_sens_cb_t * p_sens_cb;
  210. } _cb; ///< Pointer to internal control block.
  211. ant_bpwr_evt_handler_t evt_handler; ///< Event handler to be called for handling events in the BPWR profile.
  212. ant_bpwr_page1_data_t page_1; ///< Page 1.
  213. ant_bpwr_page16_data_t page_16; ///< Page 16.
  214. ant_bpwr_page17_data_t page_17; ///< Page 17.
  215. ant_bpwr_page18_data_t page_18; ///< Page 18.
  216. ant_common_page80_data_t page_80; ///< Page 80.
  217. ant_common_page81_data_t page_81; ///< Page 81.
  218. ant_bpwr_common_data_t common; ///< BPWR common data.
  219. };
  220. /** @name Defines for accessing ant_bpwr_profile_t member variables
  221. @{ */
  222. #define BPWR_PROFILE_calibration_id page_1.calibration_id
  223. #define BPWR_PROFILE_auto_zero_status page_1.auto_zero_status
  224. #define BPWR_PROFILE_general_calib_data page_1.data.general_calib
  225. #define BPWR_PROFILE_custom_calib_data page_1.data.custom_calib
  226. #define BPWR_PROFILE_instantaneous_cadence common.instantaneous_cadence
  227. #define BPWR_PROFILE_pedal_power page_16.pedal_power.items
  228. #define BPWR_PROFILE_power_update_event_count page_16.update_event_count
  229. #define BPWR_PROFILE_accumulated_power page_16.accumulated_power
  230. #define BPWR_PROFILE_instantaneous_power page_16.instantaneous_power
  231. #define BPWR_PROFILE_wheel_update_event_count page_17.update_event_count
  232. #define BPWR_PROFILE_wheel_tick page_17.tick
  233. #define BPWR_PROFILE_wheel_period page_17.period
  234. #define BPWR_PROFILE_wheel_accumulated_torque page_17.accumulated_torque
  235. #define BPWR_PROFILE_crank_update_event_count page_18.update_event_count
  236. #define BPWR_PROFILE_crank_tick page_18.tick
  237. #define BPWR_PROFILE_crank_period page_18.period
  238. #define BPWR_PROFILE_crank_accumulated_torque page_18.accumulated_torque
  239. #define BPWR_PROFILE_manuf_id page_80.manuf_id
  240. #define BPWR_PROFILE_hw_revision page_80.hw_revision
  241. #define BPWR_PROFILE_manufacturer_id page_80.manufacturer_id
  242. #define BPWR_PROFILE_model_number page_80.model_number
  243. #define BPWR_PROFILE_sw_revision_minor page_81.sw_revision_minor
  244. #define BPWR_PROFILE_sw_revision_major page_81.sw_revision_major
  245. #define BPWR_PROFILE_serial_number page_81.serial_number
  246. /** @} */
  247. /**@brief Function for initializing the ANT Bicycle Power Display profile instance.
  248. *
  249. * @param[in] p_profile Pointer to the profile instance.
  250. * @param[in] p_channel_config Pointer to the ANT channel configuration structure.
  251. * @param[in] p_disp_config Pointer to the Bicycle Power Display configuration structure.
  252. *
  253. * @retval NRF_SUCCESS If initialization was successful. Otherwise, an error code is returned.
  254. */
  255. ret_code_t ant_bpwr_disp_init(ant_bpwr_profile_t * p_profile,
  256. ant_channel_config_t const * p_channel_config,
  257. ant_bpwr_disp_config_t const * p_disp_config);
  258. /**@brief Function for initializing the ANT Bicycle Power Sensor profile instance.
  259. *
  260. * @param[in] p_profile Pointer to the profile instance.
  261. * @param[in] p_channel_config Pointer to the ANT channel configuration structure.
  262. * @param[in] p_sens_config Pointer to the Bicycle Power Sensor configuration structure.
  263. *
  264. * @retval NRF_SUCCESS If initialization was successful. Otherwise, an error code is returned.
  265. */
  266. ret_code_t ant_bpwr_sens_init(ant_bpwr_profile_t * p_profile,
  267. ant_channel_config_t const * p_channel_config,
  268. ant_bpwr_sens_config_t const * p_sens_config);
  269. /**@brief Function for opening the profile instance channel for ANT BPWR Display.
  270. *
  271. * Before calling this function, pages should be configured.
  272. *
  273. * @param[in] p_profile Pointer to the profile instance.
  274. *
  275. * @retval NRF_SUCCESS If the channel was successfully opened. Otherwise, an error code is returned.
  276. */
  277. ret_code_t ant_bpwr_disp_open(ant_bpwr_profile_t * p_profile);
  278. /**@brief Function for opening the profile instance channel for ANT BPWR Sensor.
  279. *
  280. * Before calling this function, pages should be configured.
  281. *
  282. * @param[in] p_profile Pointer to the profile instance.
  283. *
  284. * @retval NRF_SUCCESS If the channel was successfully opened. Otherwise, an error code is returned.
  285. */
  286. ret_code_t ant_bpwr_sens_open(ant_bpwr_profile_t * p_profile);
  287. /** @name Functions: Sensor calibration API
  288. * @{
  289. */
  290. /** @brief Function for initializing the response for a calibration request.
  291. *
  292. * This function should be used to signal the status of the calibration procedure to the ANT profile layer .
  293. *
  294. * @param[in] p_profile Pointer to the profile instance.
  295. */
  296. void ant_bpwr_calib_response(ant_bpwr_profile_t * p_profile);
  297. /** @} */
  298. /**@brief Function for handling the Sensor ANT events.
  299. *
  300. * @details This function handles all events from the ANT stack that are of interest to the Bicycle Power Display profile.
  301. *
  302. * @param[in] p_ant_evt Event received from the ANT stack.
  303. * @param[in] p_context Pointer to the profile instance.
  304. */
  305. void ant_bpwr_sens_evt_handler(ant_evt_t * p_ant_evt, void * p_context);
  306. /**@brief Function for handling the Display ANT events.
  307. *
  308. * @details This function handles all events from the ANT stack that are of interest to the Bicycle Power Display profile.
  309. *
  310. * @param[in] p_ant_evt Event received from the ANT stack.
  311. * @param[in] p_context Pointer to the profile instance.
  312. */
  313. void ant_bpwr_disp_evt_handler(ant_evt_t * p_ant_evt, void * p_context);
  314. /** @name Functions: Display calibration API
  315. * @{
  316. */
  317. /**@brief Function for initializing the calibration request process from the Bicycle Power Display side.
  318. *
  319. * @details This function requests a transfer to the Sensor and starts watching for the calibration response.
  320. * If a calibration response has already been requested, the function ignores the new request and returns NRF_SUCCESS.
  321. *
  322. * @param [in] p_profile Pointer to the profile instance.
  323. * @param [in] p_page_1 Pointer to the prepared page 1.
  324. *
  325. * @return Values returned by the @ref sd_ant_acknowledge_message_tx SVC callback.
  326. */
  327. uint32_t ant_bpwr_calib_request(ant_bpwr_profile_t * p_profile, ant_bpwr_page1_data_t * p_page_1);
  328. /**
  329. * @}
  330. */
  331. /**
  332. * @}
  333. */
  334. #ifdef __cplusplus
  335. }
  336. #endif
  337. #endif // ANT_BICYCLE_POWER_H__