ots.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020-2022 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_
 
#include <stdbool.h>
#include <stdint.h>
 
#include <sys/types.h>
 
#include <zephyr/sys/byteorder.h>
#include <zephyr/sys/util.h>
#include <zephyr/sys/crc.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/bluetooth/gatt.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define BT_OTS_OBJ_ID_SIZE 6
 
#define BT_OTS_OBJ_ID_MIN 0x000000000100ULL
 
#define BT_OTS_OBJ_ID_MAX 0xFFFFFFFFFFFFULL
 
#define OTS_OBJ_ID_DIR_LIST 0x000000000000ULL
 
#define BT_OTS_OBJ_ID_MASK BIT64_MASK(48)
 
#define BT_OTS_OBJ_ID_STR_LEN 15
 
struct bt_ots_obj_type {
        union {
                /* Used to indicate UUID type */
                struct bt_uuid uuid;
 
                /* 16-bit UUID value */
                struct bt_uuid_16 uuid_16;
 
                /* 128-bit UUID value */
                struct bt_uuid_128 uuid_128;
        };
};
 
enum {
        BT_OTS_OBJ_PROP_DELETE    = 0,
 
        BT_OTS_OBJ_PROP_EXECUTE   = 1,
 
        BT_OTS_OBJ_PROP_READ      = 2,
 
        BT_OTS_OBJ_PROP_WRITE     = 3,
 
        BT_OTS_OBJ_PROP_APPEND    = 4,
 
        BT_OTS_OBJ_PROP_TRUNCATE  = 5,
 
        BT_OTS_OBJ_PROP_PATCH     = 6,
 
        BT_OTS_OBJ_PROP_MARKED    = 7,
};
 
#define BT_OTS_OBJ_SET_PROP_DELETE(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_DELETE, 1)
 
#define BT_OTS_OBJ_SET_PROP_EXECUTE(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_EXECUTE, 1)
 
#define BT_OTS_OBJ_SET_PROP_READ(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_READ, 1)
 
#define BT_OTS_OBJ_SET_PROP_WRITE(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_WRITE, 1)
 
#define BT_OTS_OBJ_SET_PROP_APPEND(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_APPEND, 1)
 
#define BT_OTS_OBJ_SET_PROP_TRUNCATE(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_TRUNCATE, 1)
 
#define BT_OTS_OBJ_SET_PROP_PATCH(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_PATCH, 1)
 
#define BT_OTS_OBJ_SET_PROP_MARKED(prop) \
        WRITE_BIT(prop, BT_OTS_OBJ_PROP_MARKED, 1)
 
#define BT_OTS_OBJ_GET_PROP_DELETE(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_DELETE))
 
#define BT_OTS_OBJ_GET_PROP_EXECUTE(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_EXECUTE))
 
#define BT_OTS_OBJ_GET_PROP_READ(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_READ))
 
#define BT_OTS_OBJ_GET_PROP_WRITE(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_WRITE))
 
#define BT_OTS_OBJ_GET_PROP_APPEND(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_APPEND))
 
#define BT_OTS_OBJ_GET_PROP_TRUNCATE(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_TRUNCATE))
 
#define BT_OTS_OBJ_GET_PROP_PATCH(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_PATCH))
 
#define BT_OTS_OBJ_GET_PROP_MARKED(prop) \
        ((prop) & BIT(BT_OTS_OBJ_PROP_MARKED))
 
struct bt_ots_obj_size {
        uint32_t cur;
 
        uint32_t alloc;
} __packed;
 
enum {
        BT_OTS_OACP_FEAT_CREATE     = 0,
 
        BT_OTS_OACP_FEAT_DELETE     = 1,
 
        BT_OTS_OACP_FEAT_CHECKSUM   = 2,
 
        BT_OTS_OACP_FEAT_EXECUTE    = 3,
 
        BT_OTS_OACP_FEAT_READ       = 4,
 
        BT_OTS_OACP_FEAT_WRITE      = 5,
 
        BT_OTS_OACP_FEAT_APPEND     = 6,
 
        BT_OTS_OACP_FEAT_TRUNCATE   = 7,
 
        BT_OTS_OACP_FEAT_PATCH      = 8,
 
        BT_OTS_OACP_FEAT_ABORT      = 9,
};
 
/*
 * @enum bt_ots_oacp_write_op_mode
 * @brief Mode Parameter for OACP Write Op Code.
 */
enum bt_ots_oacp_write_op_mode {
        BT_OTS_OACP_WRITE_OP_MODE_NONE = 0,
        BT_OTS_OACP_WRITE_OP_MODE_TRUNCATE = BIT(1),
};
 
#define BT_OTS_OACP_SET_FEAT_CREATE(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_CREATE, 1)
 
#define BT_OTS_OACP_SET_FEAT_DELETE(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_DELETE, 1)
 
#define BT_OTS_OACP_SET_FEAT_CHECKSUM(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_CHECKSUM, 1)
 
#define BT_OTS_OACP_SET_FEAT_EXECUTE(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_EXECUTE, 1)
 
#define BT_OTS_OACP_SET_FEAT_READ(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_READ, 1)
 
#define BT_OTS_OACP_SET_FEAT_WRITE(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_WRITE, 1)
 
#define BT_OTS_OACP_SET_FEAT_APPEND(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_APPEND, 1)
 
#define BT_OTS_OACP_SET_FEAT_TRUNCATE(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_TRUNCATE, 1)
 
#define BT_OTS_OACP_SET_FEAT_PATCH(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_PATCH, 1)
 
#define BT_OTS_OACP_SET_FEAT_ABORT(feat) \
        WRITE_BIT(feat, BT_OTS_OACP_FEAT_ABORT, 1)
 
#define BT_OTS_OACP_GET_FEAT_CREATE(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_CREATE))
 
#define BT_OTS_OACP_GET_FEAT_DELETE(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_DELETE))
 
#define BT_OTS_OACP_GET_FEAT_CHECKSUM(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_CHECKSUM))
 
#define BT_OTS_OACP_GET_FEAT_EXECUTE(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_EXECUTE))
 
#define BT_OTS_OACP_GET_FEAT_READ(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_READ))
 
#define BT_OTS_OACP_GET_FEAT_WRITE(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_WRITE))
 
#define BT_OTS_OACP_GET_FEAT_APPEND(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_APPEND))
 
#define BT_OTS_OACP_GET_FEAT_TRUNCATE(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_TRUNCATE))
 
#define BT_OTS_OACP_GET_FEAT_PATCH(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_PATCH))
 
#define BT_OTS_OACP_GET_FEAT_ABORT(feat) \
        ((feat) & BIT(BT_OTS_OACP_FEAT_ABORT))
 
enum {
        BT_OTS_OLCP_FEAT_GO_TO      = 0,
 
        BT_OTS_OLCP_FEAT_ORDER      = 1,
 
        BT_OTS_OLCP_FEAT_NUM_REQ    = 2,
 
        BT_OTS_OLCP_FEAT_CLEAR      = 3,
};
 
#define BT_OTS_OLCP_SET_FEAT_GO_TO(feat) \
        WRITE_BIT(feat, BT_OTS_OLCP_FEAT_GO_TO, 1)
 
#define BT_OTS_OLCP_SET_FEAT_ORDER(feat) \
        WRITE_BIT(feat, BT_OTS_OLCP_FEAT_ORDER, 1)
 
#define BT_OTS_OLCP_SET_FEAT_NUM_REQ(feat) \
        WRITE_BIT(feat, BT_OTS_OLCP_FEAT_NUM_REQ, 1)
 
#define BT_OTS_OLCP_SET_FEAT_CLEAR(feat) \
        WRITE_BIT(feat, BT_OTS_OLCP_FEAT_CLEAR, 1)
 
#define BT_OTS_OLCP_GET_FEAT_GO_TO(feat) \
        ((feat) & BIT(BT_OTS_OLCP_FEAT_GO_TO))
 
#define BT_OTS_OLCP_GET_FEAT_ORDER(feat) \
        ((feat) & BIT(BT_OTS_OLCP_FEAT_ORDER))
 
#define BT_OTS_OLCP_GET_FEAT_NUM_REQ(feat) \
        ((feat) & BIT(BT_OTS_OLCP_FEAT_NUM_REQ))
 
#define BT_OTS_OLCP_GET_FEAT_CLEAR(feat) \
        ((feat) & BIT(BT_OTS_OLCP_FEAT_CLEAR))
 
struct bt_ots_feat {
        /* OACP Features */
        uint32_t oacp;
 
        /* OLCP Features */
        uint32_t olcp;
} __packed;
 
enum {
        BT_OTS_METADATA_REQ_NAME                        = BIT(0),
        BT_OTS_METADATA_REQ_TYPE                        = BIT(1),
        BT_OTS_METADATA_REQ_SIZE                        = BIT(2),
        BT_OTS_METADATA_REQ_CREATED                     = BIT(3),
        BT_OTS_METADATA_REQ_MODIFIED                    = BIT(4),
        BT_OTS_METADATA_REQ_ID                          = BIT(5),
        BT_OTS_METADATA_REQ_PROPS                       = BIT(6),
        BT_OTS_METADATA_REQ_ALL                         = 0x7F,
};
 
struct bt_ots_date_time {
        uint16_t year;
        uint8_t month;
        uint8_t day;
        uint8_t hours;
        uint8_t minutes;
        uint8_t seconds;
};
#define BT_OTS_DATE_TIME_FIELD_SIZE 7
 
struct bt_ots_obj_metadata {
 
#if defined(CONFIG_BT_OTS)
        char                           *name;
#endif /* CONFIG_BT_OTS */
 
#if defined(CONFIG_BT_OTS_CLIENT)
        /* TODO: Unify client/server name */
        char                           name_c[CONFIG_BT_OTS_OBJ_MAX_NAME_LEN + 1];
#endif /* CONFIG_BT_OTS_CLIENT */
 
        struct bt_ots_obj_type         type;
 
        struct bt_ots_obj_size         size;
 
#if defined(CONFIG_BT_OTS_CLIENT)
        struct bt_ots_date_time        first_created;
 
        struct bt_ots_date_time        modified;
 
        uint64_t                       id;
#endif /* CONFIG_BT_OTS_CLIENT */
 
        uint32_t                       props;
};
 
struct bt_ots;
 
struct bt_ots_obj_add_param {
        uint32_t size;
 
        struct bt_ots_obj_type type;
};
 
struct bt_ots_obj_created_desc {
        char *name;
 
        struct bt_ots_obj_size size;
 
        uint32_t props;
};
 
struct bt_ots_cb {
        int (*obj_created)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id,
                           const struct bt_ots_obj_add_param *add_param,
                           struct bt_ots_obj_created_desc *created_desc);
 
        int (*obj_deleted)(struct bt_ots *ots, struct bt_conn *conn,
                           uint64_t id);
 
        void (*obj_selected)(struct bt_ots *ots, struct bt_conn *conn,
                             uint64_t id);
 
        ssize_t (*obj_read)(struct bt_ots *ots, struct bt_conn *conn,
                           uint64_t id, void **data, size_t len,
                           off_t offset);
 
        ssize_t (*obj_write)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id,
                             const void *data, size_t len, off_t offset,
                             size_t rem);
 
        void (*obj_name_written)(struct bt_ots *ots, struct bt_conn *conn,
                                 uint64_t id, const char *cur_name, const char *new_name);
 
        int (*obj_cal_checksum)(struct bt_ots *ots, struct bt_conn *conn, uint64_t id,
                                off_t offset, size_t len, void **data);
};
 
struct bt_ots_init_param {
        /* OTS features */
        struct bt_ots_feat features;
 
        /* Callbacks */
        struct bt_ots_cb *cb;
};
 
int bt_ots_obj_add(struct bt_ots *ots, const struct bt_ots_obj_add_param *param);
 
int bt_ots_obj_delete(struct bt_ots *ots, uint64_t id);
 
void *bt_ots_svc_decl_get(struct bt_ots *ots);
 
int bt_ots_init(struct bt_ots *ots, struct bt_ots_init_param *ots_init);
 
struct bt_ots *bt_ots_free_instance_get(void);
 
#define BT_OTS_STOP                       0
#define BT_OTS_CONTINUE                   1
 
/* TODO: Merge server and client instance as opaque type */
struct bt_ots_client {
        uint16_t start_handle;
        uint16_t end_handle;
        uint16_t feature_handle;
        uint16_t obj_name_handle;
        uint16_t obj_type_handle;
        uint16_t obj_size_handle;
        uint16_t obj_properties_handle;
        uint16_t obj_created_handle;
        uint16_t obj_modified_handle;
        uint16_t obj_id_handle;
        uint16_t oacp_handle;
        uint16_t olcp_handle;
 
        struct bt_gatt_subscribe_params oacp_sub_params;
        struct bt_gatt_discover_params oacp_sub_disc_params;
        struct bt_gatt_subscribe_params olcp_sub_params;
        struct bt_gatt_discover_params olcp_sub_disc_params;
 
        struct bt_gatt_write_params write_params;
        struct bt_gatt_read_params read_proc;
        struct bt_ots_client_cb *cb;
 
        struct bt_ots_feat features;
 
        struct bt_ots_obj_metadata cur_object;
};
 
struct bt_ots_client_cb {
        void (*obj_selected)(struct bt_ots_client *ots_inst,
                             struct bt_conn *conn, int err);
 
 
        int (*obj_data_read)(struct bt_ots_client *ots_inst,
                             struct bt_conn *conn, uint32_t offset,
                             uint32_t len, uint8_t *data_p, bool is_complete);
 
        void (*obj_metadata_read)(struct bt_ots_client *ots_inst,
                                  struct bt_conn *conn, int err,
                                  uint8_t metadata_read);
 
        void (*obj_data_written)(struct bt_ots_client *ots_inst,
                                 struct bt_conn *conn, size_t len);
 
        void (*obj_checksum_calculated)(struct bt_ots_client *ots_inst, struct bt_conn *conn,
                                        int err, uint32_t checksum);
};
 
int bt_ots_client_register(struct bt_ots_client *ots_inst);
 
int bt_ots_client_unregister(uint8_t index);
 
uint8_t bt_ots_client_indicate_handler(struct bt_conn *conn,
                                       struct bt_gatt_subscribe_params *params,
                                       const void *data, uint16_t length);
 
int bt_ots_client_read_feature(struct bt_ots_client *otc_inst,
                               struct bt_conn *conn);
 
int bt_ots_client_select_id(struct bt_ots_client *otc_inst,
                            struct bt_conn *conn,
                            uint64_t obj_id);
 
int bt_ots_client_select_first(struct bt_ots_client *otc_inst,
                               struct bt_conn *conn);
 
int bt_ots_client_select_last(struct bt_ots_client *otc_inst,
                              struct bt_conn *conn);
 
int bt_ots_client_select_next(struct bt_ots_client *otc_inst,
                              struct bt_conn *conn);
 
int bt_ots_client_select_prev(struct bt_ots_client *otc_inst,
                              struct bt_conn *conn);
 
int bt_ots_client_read_object_metadata(struct bt_ots_client *otc_inst,
                                       struct bt_conn *conn,
                                       uint8_t metadata);
 
int bt_ots_client_read_object_data(struct bt_ots_client *otc_inst,
                                   struct bt_conn *conn);
 
int bt_ots_client_write_object_data(struct bt_ots_client *otc_inst, struct bt_conn *conn,
                                    const void *buf, size_t len, off_t offset,
                                    enum bt_ots_oacp_write_op_mode mode);
 
int bt_ots_client_get_object_checksum(struct bt_ots_client *otc_inst, struct bt_conn *conn,
                                      off_t offset, size_t len);
 
typedef int (*bt_ots_client_dirlisting_cb)(struct bt_ots_obj_metadata *meta);
 
int bt_ots_client_decode_dirlisting(uint8_t *data, uint16_t length,
                                    bt_ots_client_dirlisting_cb cb);
 
static inline int bt_ots_obj_id_to_str(uint64_t obj_id, char *str, size_t len)
{
        uint8_t id[6];
 
        sys_put_le48(obj_id, id);
 
        return snprintk(str, len, "0x%02X%02X%02X%02X%02X%02X",
                        id[5], id[4], id[3], id[2], id[1], id[0]);
}
 
void bt_ots_metadata_display(struct bt_ots_obj_metadata *metadata,
                             uint16_t count);
 
#if defined(CONFIG_BT_OTS_OACP_CHECKSUM_SUPPORT)
static inline uint32_t bt_ots_client_calc_checksum(const uint8_t *data, size_t len)
{
        return crc32_ieee(data, len);
}
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_SERVICES_OTS_H_ */