ble_ots.h 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474
  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 ble_ots Object Transfer Service
  43. * @{
  44. * @ingroup ble_sdk_srv
  45. * @brief Object Transfer Service module
  46. *
  47. * @details This is the main module of the OTS service.
  48. */
  49. #ifndef BLE_OTS_H__
  50. #define BLE_OTS_H__
  51. #include <stdint.h>
  52. #include "ble_srv_common.h"
  53. #include "ble_date_time.h"
  54. #include "nrf_ble_gq.h"
  55. #ifdef __cplusplus
  56. extern "C" {
  57. #endif
  58. /**@brief Macro for defining a ble_ots instance.
  59. *
  60. * @param _name Name of the instance.
  61. * @hideinitializer
  62. */
  63. #define BLE_OTS_DEF(_name) \
  64. static ble_ots_t _name; \
  65. NRF_SDH_BLE_OBSERVER(_name ## _ble_obs, \
  66. BLE_OTS_BLE_OBSERVER_PRIO, \
  67. ble_ots_on_ble_evt, &_name) \
  68. #define NRF_BLE_OTS_SIZE_CHAR_LEN (2*sizeof(uint32_t))
  69. #define BLE_OTS_FEATURE_LEN (2*sizeof(uint32_t))
  70. #define BLE_OTS_NAME_MAX_SIZE 128
  71. #define BLE_OTS_MAX_OBJ_SIZE 1028
  72. #define BLE_OTS_INVALID_CID 0x0000 /**< Invalid connection ID. */
  73. #define BLE_OTS_PSM 0x0025
  74. #define BLE_OTS_MAX_OACP_SIZE 21
  75. #define BLE_OTS_WRITE_MODE_TRUNCATE (1 << 1)
  76. #define BLE_OTS_WRITE_MODE_NO_TRUNCATE 0
  77. // Forward declarations.
  78. typedef struct ble_ots_s ble_ots_t;
  79. typedef struct ble_ots_oacp_s ble_ots_oacp_t;
  80. typedef struct ble_ots_l2cap_s ble_ots_l2cap_t;
  81. /*------------------------------------------ BLE OTS OBJECT --------------------------------------*/
  82. /**@brief Properties of an Object Transfer Service object. */
  83. typedef union
  84. {
  85. struct
  86. {
  87. bool is_delete_permitted :1;
  88. bool is_execute_permitted :1;
  89. bool is_read_permitted :1;
  90. bool is_write_permitted :1;
  91. bool is_append_permitted :1;
  92. bool is_truncate_permitted:1; /**< When writing using truncate mode, and the written length is shorter than the object, the object size is decreased. */
  93. bool is_patch_permitted :1; /**< When patching, a part of the object is replaced. */
  94. bool is_marked :1;
  95. } decoded;
  96. uint32_t raw;
  97. } ble_ots_obj_properties_t;
  98. /**@brief A structure representing the object type. */
  99. typedef struct
  100. {
  101. uint8_t len; /**< The length of the object type in bytes. 2 and 16 are the only valid type lengths. */
  102. union
  103. {
  104. uint16_t type16;
  105. uint8_t type128[16];
  106. } param;
  107. } ble_ots_obj_type_t;
  108. /**@brief The structure representing one Object Transfer Service object. */
  109. typedef struct
  110. {
  111. uint8_t name[BLE_OTS_NAME_MAX_SIZE]; /**< The name of the object. If the name is "", the object will be invalidated on disconnect. */
  112. uint8_t data[BLE_OTS_MAX_OBJ_SIZE];
  113. uint32_t current_size;
  114. ble_ots_obj_type_t type;
  115. ble_ots_obj_properties_t properties;
  116. uint32_t alloc_len;
  117. bool is_valid; /**< States if the object will be shown in a list. */
  118. bool is_locked; /**< When an object is written or read, the object will be locked. */
  119. } ble_ots_object_t;
  120. /**@brief The definition of an event from the object characteristics. */
  121. typedef struct
  122. {
  123. enum
  124. {
  125. BLE_OTS_OBJECT_EVT_NAME_CHANGED,
  126. BLE_OTS_OBJECT_EVT_PROPERTIES_CHANGED,
  127. } type;
  128. union
  129. {
  130. ble_ots_object_t * p_object;
  131. } evt;
  132. } ble_ots_object_evt_t;
  133. /**@brief Initialization properties of the Object Transfer Service Object characteristics. */
  134. typedef struct
  135. {
  136. ble_ots_t * p_ots;
  137. security_req_t name_read_access;
  138. security_req_t name_write_access;
  139. security_req_t type_read_access;
  140. security_req_t size_read_access;
  141. security_req_t properties_read_access;
  142. security_req_t properties_write_access;
  143. } ble_ots_object_chars_init_t;
  144. /**@brief The structure holding the state of the OTS object characteristics. */
  145. typedef struct
  146. {
  147. ble_ots_t * p_ots;
  148. ble_gatts_char_handles_t obj_name_handles;
  149. ble_gatts_char_handles_t obj_type_handles;
  150. ble_gatts_char_handles_t obj_size_handles;
  151. ble_gatts_char_handles_t obj_properties_handles;
  152. } ble_ots_object_chars_t;
  153. /*------------------------------------------ BLE OTS L2CAP ---------------------------------------*/
  154. /**@brief L2cap event types. */
  155. typedef enum
  156. {
  157. BLE_OTS_L2CAP_EVT_CH_CONNECTED,
  158. BLE_OTS_L2CAP_EVT_CH_DISCONNECTED,
  159. BLE_OTS_L2CAP_EVT_SEND_COMPLETE,
  160. BLE_OTS_L2CAP_EVT_RECV_COMPLETE,
  161. } ble_ots_l2cap_evt_type_t;
  162. /**@brief l2cap event. */
  163. typedef struct
  164. {
  165. ble_ots_l2cap_evt_type_t type;
  166. struct
  167. {
  168. uint8_t * p_data;
  169. uint16_t len;
  170. } param;
  171. } ble_ots_l2cap_evt_t;
  172. /**@brief L2CAP event handler. */
  173. typedef void (*ble_ots_l2cap_evt_handler_t)(ble_ots_l2cap_t * p_ots_l2cap,
  174. ble_ots_l2cap_evt_t * p_evt);
  175. /**@brief The structure holding the l2cap connection oriented channels state. */
  176. struct ble_ots_l2cap_s
  177. {
  178. ble_ots_l2cap_evt_handler_t evt_handler;
  179. ble_ots_oacp_t * p_ots_oacp;
  180. enum
  181. {
  182. NOT_CONNECTED,
  183. CONNECTED,
  184. SENDING,
  185. RECEIVING
  186. } state;
  187. ble_data_t tx_transfer_buffer;
  188. ble_l2cap_ch_rx_params_t rx_params;
  189. ble_l2cap_ch_tx_params_t tx_params;
  190. uint16_t remaining_bytes; /**< The number of remaining bytes in the current transfer. */
  191. uint16_t transmitted_bytes;
  192. uint16_t received_bytes;
  193. uint16_t transfer_len; /**< The total number of bytes in the current transfer. */
  194. uint16_t local_cid; /**< Connection ID of the current connection. */
  195. uint16_t conn_mtu; /**< The maximum transmission unit, that is the number of packets that can be sent or received. */
  196. uint16_t conn_mps; /**< MPS defines the maximum payload size in bytes. */
  197. };
  198. /**@brief The initialization structure of the l2cap module. */
  199. typedef struct
  200. {
  201. ble_ots_oacp_t * p_ots_oacp;
  202. ble_ots_l2cap_evt_handler_t evt_handler;
  203. uint8_t * p_transfer_buffer; /**< The user must provide buffer for transfers. */
  204. uint16_t buffer_len; /**< Length of the transfer buffer. */
  205. } ble_ots_l2cap_init_t;
  206. /*------------------------------------------ BLE OTS OCAP ----------------------------------------*/
  207. /**< Types of Object Action Control Point Procedures. */
  208. typedef enum
  209. {
  210. BLE_OTS_OACP_PROC_CREATE = 0x01, //!< Create object.
  211. BLE_OTS_OACP_PROC_DELETE = 0x02, //!< Delete object.
  212. BLE_OTS_OACP_PROC_CALC_CHKSUM = 0x03, //!< Calculate Checksum.
  213. BLE_OTS_OACP_PROC_EXECUTE = 0x04, //!< Execute Object.
  214. BLE_OTS_OACP_PROC_READ = 0x05, //!< Read object.
  215. BLE_OTS_OACP_PROC_WRITE = 0x06, //!< Write object.
  216. BLE_OTS_OACP_PROC_ABORT = 0x07, //!< Abort object.
  217. BLE_OTS_OACP_PROC_RESP = 0x60 //!< Procedure response.
  218. } ble_ots_oacp_proc_type_t;
  219. /**< Object Action Control Point return codes. */
  220. typedef enum
  221. {
  222. BLE_OTS_OACP_RES_SUCCESS = 0x01, //!< Success.
  223. BLE_OTS_OACP_RES_OPCODE_NOT_SUP = 0x02, //!< Not supported
  224. BLE_OTS_OACP_RES_INV_PARAM = 0x03, //!< Invalid parameter
  225. BLE_OTS_OACP_RES_INSUFF_RES = 0x04, //!< Insufficient resources.
  226. BLE_OTS_OACP_RES_INV_OBJ = 0x05, //!< Invalid object.
  227. BLE_OTS_OACP_RES_CHAN_UNAVAIL = 0x06, //!< Channel unavailable.
  228. BLE_OTS_OACP_RES_UNSUP_TYPE = 0x07, //!< Unsupported procedure.
  229. BLE_OTS_OACP_RES_NOT_PERMITTED = 0x08, //!< Procedure not permitted.
  230. BLE_OTS_OACP_RES_OBJ_LOCKED = 0x09, //!< Object locked.
  231. BLE_OTS_OACP_RES_OPER_FAILED = 0x0A //!< Operation Failed.
  232. } ble_ots_oacp_res_code_t;
  233. /**< Object Action Control Point procedure definition. */
  234. typedef struct
  235. {
  236. ble_ots_oacp_proc_type_t type;
  237. union
  238. {
  239. struct
  240. {
  241. uint32_t size;
  242. ble_ots_obj_type_t * p_obj_type;
  243. } create_params;
  244. struct
  245. {
  246. uint32_t offset;
  247. uint32_t length;
  248. } checksum_params;
  249. struct
  250. {
  251. uint8_t cmd_data_len;
  252. uint8_t * p_cmd_data;
  253. } execute_params;
  254. struct
  255. {
  256. uint32_t offset;
  257. uint32_t length;
  258. } read_params;
  259. struct
  260. {
  261. uint32_t offset;
  262. uint32_t length;
  263. uint8_t write_mode;
  264. } write_params;
  265. } params;
  266. } ble_ots_oacp_proc_t;
  267. /**@brief Definition of an OACP event. */
  268. typedef struct
  269. {
  270. enum
  271. {
  272. BLE_OTS_OACP_EVT_EXECUTE,
  273. BLE_OTS_OACP_EVT_REQ_READ,
  274. BLE_OTS_OACP_EVT_INCREASE_ALLOC_LEN,
  275. BLE_OTS_OACP_EVT_REQ_WRITE,
  276. BLE_OTS_OACP_EVT_ABORT,
  277. } type;
  278. union
  279. {
  280. ble_ots_object_t * p_object;
  281. struct
  282. {
  283. uint8_t cmd_data_len;
  284. uint8_t * p_cmd_data;
  285. } execute_params;
  286. } evt;
  287. } ble_ots_oacp_evt_t;
  288. /**@brief OACP initialization properties. */
  289. typedef struct
  290. {
  291. ble_ots_t * p_ots;
  292. uint32_t on_create_obj_properties_raw; /**< The encoded properties of a newly created object.*/
  293. security_req_t write_access; /**< The write security level for the OACP. */
  294. security_req_t cccd_write_access; /**< The write security level for the OACP CCCD. */
  295. uint8_t * p_l2cap_buffer;
  296. uint16_t l2cap_buffer_len;
  297. } ble_ots_oacp_init_t;
  298. struct ble_ots_oacp_s
  299. {
  300. ble_ots_t * p_ots;
  301. uint32_t on_create_obj_properties_raw; /**< The encoded properties of a newly created object.*/
  302. ble_ots_l2cap_t ots_l2cap; /**< L2CAP connection oriented channel module. */
  303. ble_gatts_char_handles_t oacp_handles; /**< The characteristic handles of the OACP. */
  304. };
  305. /*------------------------------------------ BLE OTS ---------------------------------------------*/
  306. /**@brief The event type indicates which module the event is connected to.*/
  307. typedef enum
  308. {
  309. BLE_OTS_EVT_OACP,
  310. BLE_OTS_EVT_OBJECT,
  311. BLE_OTS_EVT_INDICATION_ENABLED,
  312. BLE_OTS_EVT_INDICATION_DISABLED,
  313. BLE_OTS_EVT_OBJECT_RECEIVED /**< If this event is received, data is now available in the current object.*/
  314. } ble_ots_evt_type_t;
  315. /**@brief This structure represents the state of the Object Transfer Service. */
  316. typedef struct
  317. {
  318. ble_ots_evt_type_t type;
  319. union
  320. {
  321. ble_ots_oacp_evt_t oacp_evt;
  322. ble_ots_object_evt_t object_evt;
  323. } evt; /**< Event data. */
  324. } ble_ots_evt_t;
  325. /**@brief OTS event handler. */
  326. typedef void (*ble_ots_evt_handler_t) (ble_ots_t * p_ots, ble_ots_evt_t * p_evt);
  327. /**@brief Structure for initializing the OTS. */
  328. typedef struct
  329. {
  330. ble_ots_evt_handler_t evt_handler;
  331. ble_srv_error_handler_t error_handler;
  332. ble_ots_object_t * p_object; /**< Pointer to the object. */
  333. security_req_t feature_char_read_access; /**< Read security level for the feature characteristic value. */
  334. ble_ots_object_chars_init_t object_chars_init; /**< The initialization structure of the object characteristics. */
  335. ble_ots_oacp_init_t oacp_init; /**< The initialization structure of the object action control point. */
  336. uint16_t rx_mps; /**< Size of L2CAP Rx MPS (must be at least BLE_L2CAP_MPS_MIN).*/
  337. uint16_t rx_mtu; /**< Size of L2CAP Rx MTU (must be at least BLE_L2CAP_MTU_MIN).*/
  338. nrf_ble_gq_t * p_gatt_queue; /**< Pointer to BLE GATT queue instance. */
  339. } ble_ots_init_t;
  340. struct ble_ots_s
  341. {
  342. uint16_t conn_handle; /**< Connection handle of service. */
  343. uint16_t service_handle; /**< THe service handle of OTS. */
  344. ble_ots_evt_handler_t evt_handler;
  345. ble_srv_error_handler_t error_handler;
  346. ble_gatts_char_handles_t feature_handles;
  347. ble_ots_object_chars_t object_chars; /**< The structure holding the object characteristics representation. */
  348. ble_ots_oacp_t oacp_chars; /**< The structure holding the object action control point characteristics representation. */
  349. ble_ots_object_t * p_current_object; /**< Pointer to the currently selected object. */
  350. nrf_ble_gq_t * p_gatt_queue; /**< Pointer to BLE GATT queue instance. */
  351. };
  352. /**@brief Function for initializing the Object Transfer Service.
  353. *
  354. * @param[out] p_ots Object Transfer Service structure. This structure will have to be supplied by
  355. * the application. It will be initialized by this function, and will later
  356. * be used to identify this particular service instance.
  357. * @param[in] p_ots_init Information needed to initialize the service.
  358. *
  359. * @return NRF_SUCCESS on successful initialization of service, otherwise an error code.
  360. */
  361. uint32_t ble_ots_init(ble_ots_t * p_ots, ble_ots_init_t * p_ots_init);
  362. /**@brief Function for handling the Application's BLE Stack events.
  363. *
  364. * @details Handles all events from the BLE stack of interest to the Object Transfer Service.
  365. *
  366. * @param[in] p_ble_evt Event received from the BLE stack.
  367. * @param[in] p_context Object Transfer Service structure.
  368. */
  369. void ble_ots_on_ble_evt(ble_evt_t const * p_ble_evt, void * p_context);
  370. /**@brief Function for setting the name of an object.
  371. *
  372. * @details If p_object is the current selected object, and the notifications is enabled, the client will be notified that the object has changed.
  373. * @note If the name of the object is "" on disconnection, the object will be invalidated.
  374. *
  375. * @param[in] p_ots_object_chars Object Transfer Service Object Characteristics structure.
  376. * @param[in] p_object Pointer to the object where the name will be changed.
  377. * @param[in] new_name The new name of the object.
  378. *
  379. * @return NRF_SUCCESS On success, otherwise an error code.
  380. */
  381. uint32_t ble_ots_object_set_name(ble_ots_object_chars_t * p_ots_object_chars,
  382. ble_ots_object_t * p_object,
  383. char const * new_name);
  384. /**@brief Function for setting the type of an object.
  385. *
  386. * @details If p_object is the current selected object, and the notifications is enabled, the client will be notified that the object has changed.
  387. * @param[in] p_ots_object_chars Object Transfer Service Object Characteristics structure.
  388. * @param[in] p_object Pointer to the object where the type will be changed.
  389. * @param[in] p_new_type Pointer to the new type of the object.
  390. *
  391. * @return NRF_SUCCESS On success, otherwise an error code.
  392. */
  393. uint32_t ble_ots_object_set_type(ble_ots_object_chars_t * p_ots_object_chars,
  394. ble_ots_object_t * p_object,
  395. ble_ots_obj_type_t * p_new_type);
  396. /**@brief Function for setting the current size of an object.
  397. *
  398. * @details If p_object is the current selected object, and the notifications is enabled, the client will be notified that the object has changed.
  399. * @note If the new current size is smaller than the current size, the object will be truncated.
  400. *
  401. * @param[in] p_ots_object_chars Object Transfer Service Object Characteristics structure.
  402. * @param[in] p_object Pointer to the object where the current size will be changed.
  403. * @param[in] new_current_size The new current size of the object.
  404. *
  405. * @return NRF_SUCCESS On success, otherwise an error code.
  406. */
  407. uint32_t ble_ots_object_set_current_size(ble_ots_object_chars_t * p_ots_object_chars,
  408. ble_ots_object_t * p_object,
  409. uint32_t new_current_size);
  410. /**@brief Function for setting the properties of an object.
  411. *
  412. * @details If p_object is the current selected object, and the notifications is enabled, the client will be notified that the object has changed.
  413. *
  414. * @param[in] p_ots_object_chars Object Transfer Service Object Characteristics structure.
  415. * @param[in] p_object Pointer to the object where the properties will be changed.
  416. * @param[in] p_new_properties The properties of the object.
  417. *
  418. * @return NRF_SUCCESS On success, otherwise an error code.
  419. */
  420. uint32_t ble_ots_object_set_properties(ble_ots_object_chars_t * p_ots_object_chars,
  421. ble_ots_object_t * p_object,
  422. ble_ots_obj_properties_t * p_new_properties);
  423. #endif // BLE_OTS_H__
  424. /** @} */