nrf_twi_sensor.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314
  1. /**
  2. * Copyright (c) 2017 - 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. /**@file
  41. *
  42. * @defgroup nrf_twi_sensor TWI Sensor module.
  43. * @{
  44. * @ingroup app_common
  45. */
  46. #ifndef NRF_TWI_SENSOR_H
  47. #define NRF_TWI_SENSOR_H
  48. #include "nrf_twi_mngr.h"
  49. #include "nrf_balloc.h"
  50. #ifdef __cplusplus
  51. extern "C" {
  52. #endif
  53. /**
  54. * @brief Internal write operation buffer length.
  55. *
  56. * Defines how many bytes can be stored internally.
  57. * 16 bytes were selected so that nrf_twi_sensor_write_cmd_t size
  58. * matches nrf_twi_sensor_read_cmd_t size.
  59. */
  60. #define NRF_TWI_SENSOR_SEND_BUF_SIZE 16
  61. /**
  62. * @brief Register read callback prototype.
  63. *
  64. * @param[in] result Return error code from TWI manager and underlying drivers.
  65. * @param[in] p_register_data Pointer to register value.
  66. */
  67. typedef void (* nrf_twi_sensor_reg_cb_t)(ret_code_t result, void * p_register_data);
  68. /**
  69. * @brief Structure holding sensor instance
  70. */
  71. typedef struct
  72. {
  73. nrf_twi_mngr_t const * const p_twi_mngr;
  74. nrf_balloc_t const * const p_pool;
  75. } nrf_twi_sensor_t;
  76. /**
  77. * @brief Struct describing sensor read command.
  78. *
  79. * @note For internal use only.
  80. */
  81. typedef struct
  82. {
  83. uint8_t reg_address;
  84. nrf_twi_mngr_transfer_t transfers[2];
  85. nrf_twi_mngr_transaction_t transaction;
  86. nrf_twi_sensor_reg_cb_t user_cb;
  87. nrf_twi_sensor_t const * p_instance;
  88. } nrf_twi_sensor_read_cmd_t;
  89. /**
  90. * @brief Struct describing sensor write command.
  91. *
  92. * @note For internal use only.
  93. */
  94. typedef struct
  95. {
  96. uint8_t send_msg[NRF_TWI_SENSOR_SEND_BUF_SIZE];
  97. nrf_twi_mngr_transfer_t transfer;
  98. nrf_twi_mngr_transaction_t transaction;
  99. nrf_twi_sensor_t const * p_instance;
  100. } nrf_twi_sensor_write_cmd_t;
  101. /**
  102. * @brief Union for sensor commands. Needed in buffer definition.
  103. *
  104. * @note For internal use only.
  105. */
  106. typedef union
  107. {
  108. nrf_twi_sensor_read_cmd_t read;
  109. nrf_twi_sensor_write_cmd_t write;
  110. } nrf_twi_sensor_cmd_t;
  111. /**
  112. * @brief Macro creating common twi sensor instance.
  113. *
  114. * Data in structure is used for basic communication with sensors.
  115. * THere should be one instance per TWI bus.
  116. *
  117. * @param[in] twi_sensor_name TWI common sensor instance name.
  118. * @param[in] p_nrf_twi_mngr Pointer to TWI Manager instance. @ref NRF_TWI_MNGR_DEF
  119. * @param[in] msg_buff_size Size of buffer used in communication
  120. *
  121. * @note Buffer size should be less or equal to TWI manager queue size.
  122. * Minimum buffer size can be found after checking utilization of sensor buffer.
  123. */
  124. #define NRF_TWI_SENSOR_DEF(twi_sensor_name, p_nrf_twi_mngr, msg_buff_size) \
  125. NRF_BALLOC_DEF(CONCAT_2(twi_sensor_name,_pool), sizeof(nrf_twi_sensor_cmd_t), msg_buff_size);\
  126. static nrf_twi_sensor_t twi_sensor_name = \
  127. { \
  128. .p_twi_mngr = p_nrf_twi_mngr, \
  129. .p_pool = &CONCAT_2(twi_sensor_name,_pool) \
  130. }
  131. /**
  132. * @brief Macro for defining TWI manager read transfer.
  133. *
  134. * @note For internal use only.
  135. */
  136. #define NRF_TWI_SENSOR_READ(p_reg_addr, p_buffer, byte_cnt) \
  137. NRF_TWI_MNGR_WRITE(0x00, p_reg_addr, 1, NRF_TWI_MNGR_NO_STOP), \
  138. NRF_TWI_MNGR_READ (0x00, p_buffer, byte_cnt, 0)
  139. /**
  140. * @brief Macro for defining TWI manager write transfer.
  141. *
  142. * @note For internal use only.
  143. */
  144. #define NRF_TWI_SENSOR_WRITE(p_buffer, byte_cnt) \
  145. NRF_TWI_MNGR_WRITE(0x00, p_buffer, byte_cnt, 0)
  146. /**
  147. * @brief Macro for assigning sensor address to transfers.
  148. *
  149. * @param[in] _transfers Transfers array.
  150. * @param[in] _sensor_addr Desired sensor address.
  151. *
  152. * @note For internal use only.
  153. */
  154. #define NRF_TWI_SENSOR_ADDRESS_SET(_transfers, _sensor_addr) \
  155. for (uint8_t i = 0; i < ARRAY_SIZE(_transfers); i++) \
  156. { \
  157. if (i % 2 == 0) \
  158. { \
  159. transfers[i].operation = NRF_TWI_MNGR_WRITE_OP(_sensor_addr); \
  160. } \
  161. else \
  162. { \
  163. transfers[i].operation = NRF_TWI_MNGR_READ_OP(_sensor_addr); \
  164. } \
  165. }
  166. /**
  167. * @brief Macro for setting parameters in sensor register.
  168. *
  169. * @param[in,out] _register Register to be altered.
  170. * @param[in] _msk Parameter mask.
  171. * @param[in] _pos Parameter position.
  172. * @param[in] _val Parameter value to be set.
  173. */
  174. #define NRF_TWI_SENSOR_REG_SET(_register, _msk, _pos, _val) \
  175. _register &= ~(_msk); \
  176. _register |= ((_msk) & ((_val) << (_pos)))
  177. /**
  178. * @brief Macro for getting parameters from sensor register.
  179. *
  180. * @param[in] _register Register to be processed.
  181. * @param[in] _msk Parameter mask.
  182. * @param[in] _pos Parameter position.
  183. *
  184. * @note For usage with registers read using nrf_twi_sensor_register_read function.
  185. *
  186. * @return Parameter value
  187. */
  188. #define NRF_TWI_SENSOR_REG_VAL_GET(_register, _msk, _pos) \
  189. (((_register) & (_msk)) >> (_pos))
  190. /**
  191. * @brief Function for initialization of sensor common instance.
  192. *
  193. * @note TWI Manager should be initialized before @ref nrf_twi_mngr_init
  194. * @param[in] p_twi_sensor Pointer to sensor common instance.
  195. *
  196. * @return Error code from nrf_balloc @ref nrf_balloc_init
  197. */
  198. ret_code_t nrf_twi_sensor_init(nrf_twi_sensor_t * p_twi_sensor);
  199. /**
  200. * @brief Function for reading sensor register.
  201. *
  202. * @param[in] p_instance Pointer to sensor instance.
  203. * @param[in] sensor_addr Sensor address.
  204. * @param[in] reg_address Register address.
  205. * @param[in] user_cb User callback.
  206. * @param[out] p_data Pointer to data save location.
  207. * @param[in] length Number of bytes to read.
  208. *
  209. * @retval NRF_ERROR_NO_MEM If there is no memory in sensor buffer
  210. * @retval NRF_SUCCESS If the operation was successful.
  211. * @retval other Error code from TWI manager @ref nrf_twi_mngr_schedule.
  212. */
  213. ret_code_t nrf_twi_sensor_reg_read(nrf_twi_sensor_t const * p_instance,
  214. uint8_t sensor_addr,
  215. uint8_t reg_address,
  216. nrf_twi_sensor_reg_cb_t user_cb,
  217. uint8_t * p_data,
  218. uint8_t length);
  219. /**
  220. * @brief Function for writing to sensor.
  221. *
  222. * @param[in] p_instance Pointer to sensor instance.
  223. * @param[in] sensor_addr Sensor address.
  224. * @param[in] p_data Pointer to data to be written.
  225. * @param[in] length Number of bytes to write.
  226. * @param[in] copy_flag If true, p_data is copied into internal static buffer.
  227. *
  228. * @note Most of the time, to write to sensors register, first byte in p_data has to be
  229. * register address.
  230. *
  231. * @retval NRF_ERROR_NO_MEM If there is no memory in sensor buffer
  232. * @retval NRF_ERROR_INVALID_LENGTH If trying to copy more bytes than
  233. * NRF_TWI_SENSOR_SEND_BUF_SIZE.
  234. * @retval NRF_SUCCESS If the operation was successful.
  235. * @retval other Error code from TWI manager @ref nrf_twi_mngr_schedule.
  236. */
  237. ret_code_t nrf_twi_sensor_write(nrf_twi_sensor_t const * p_instance,
  238. uint8_t sensor_addr,
  239. uint8_t const * p_data,
  240. uint8_t length,
  241. bool copy_flag);
  242. /**
  243. * @brief Function for writing to sensor register.
  244. *
  245. * @param[in] p_instance Pointer to sensor instance.
  246. * @param[in] sensor_addr Sensor address.
  247. * @param[in] reg_address Register address.
  248. * @param[in] p_data Pointer to data to be written.
  249. * @param[in] length Number of bytes to write.
  250. *
  251. * @note Data is copied into internal buffer.
  252. * Length has to be less than NRF_TWI_SENSOR_SEND_BUF_SIZE.
  253. *
  254. * @retval NRF_ERROR_NO_MEM If there is no memory in sensor buffer
  255. * @retval NRF_ERROR_INVALID_LENGTH If trying to copy more bytes than
  256. * NRF_TWI_SENSOR_SEND_BUF_SIZE - 1.
  257. * One byte reserved for register address.
  258. * @retval NRF_SUCCESS If the operation was successful.
  259. * @retval other Error code from TWI manager @ref nrf_twi_mngr_schedule.
  260. */
  261. ret_code_t nrf_twi_sensor_reg_write(nrf_twi_sensor_t const * p_instance,
  262. uint8_t sensor_addr,
  263. uint8_t reg_address,
  264. uint8_t * p_data,
  265. uint8_t length);
  266. /**
  267. * @brief Function for getting maximum utilization of sensor buffer.
  268. *
  269. * @param[in] p_twi_sensor Pointer to sensor buffer.
  270. *
  271. * @return Maximum utilization.
  272. */
  273. __STATIC_INLINE uint8_t nrf_twi_sensor_max_util_get(nrf_twi_sensor_t const * p_twi_sensor);
  274. #ifndef SUPPRESS_INLINE_IMPLEMENTATION
  275. __STATIC_INLINE uint8_t nrf_twi_sensor_max_util_get(nrf_twi_sensor_t const * p_twi_sensor)
  276. {
  277. return nrf_balloc_max_utilization_get(p_twi_sensor->p_pool);
  278. }
  279. #endif //SUPPRESS_INLINE_IMPLEMENTATION
  280. #ifdef __cplusplus
  281. }
  282. #endif
  283. #endif // NRF_SENSOR_COMMON_H
  284. /** @} */