ams_client.h

Go to the documentation of this file.

/*
 * Copyright (c) 2021 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
 */
 
#ifndef BT_AMS_CLIENT_H_
#define BT_AMS_CLIENT_H_
 
#include <zephyr/bluetooth/gatt.h>
#include <zephyr/bluetooth/conn.h>
#include <bluetooth/gatt_dm.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define BT_UUID_AMS_VAL \
        BT_UUID_128_ENCODE(0x89d3502b, 0x0f36, 0x433a, 0x8ef4, 0xc502ad55f8dc)
 
#define BT_UUID_AMS_REMOTE_COMMAND_VAL                                     \
        BT_UUID_128_ENCODE(0x9b3c81d8, 0x57b1, 0x4a8a, 0xb8df, 0x0e56f7ca51c2)
 
#define BT_UUID_AMS_ENTITY_UPDATE_VAL                                           \
        BT_UUID_128_ENCODE(0x2f7cabce, 0x808d, 0x411f, 0x9a0c, 0xbb92ba96c102)
 
#define BT_UUID_AMS_ENTITY_ATTRIBUTE_VAL                                             \
        BT_UUID_128_ENCODE(0xc6b2f38c, 0x23ab, 0x46d8, 0xa6ab, 0xa3a870bbd5d7)
 
#define BT_UUID_AMS BT_UUID_DECLARE_128(BT_UUID_AMS_VAL)
#define BT_UUID_AMS_REMOTE_COMMAND                                       \
        BT_UUID_DECLARE_128(BT_UUID_AMS_REMOTE_COMMAND_VAL)
#define BT_UUID_AMS_ENTITY_UPDATE                                             \
        BT_UUID_DECLARE_128(BT_UUID_AMS_ENTITY_UPDATE_VAL)
#define BT_UUID_AMS_ENTITY_ATTRIBUTE BT_UUID_DECLARE_128(BT_UUID_AMS_ENTITY_ATTRIBUTE_VAL)
 
#define BT_AMS_EU_NOTIF_ENTITY_IDX 0
#define BT_AMS_EU_NOTIF_ATTRIBUTE_IDX 1
#define BT_AMS_EU_NOTIF_FLAGS_IDX 2
#define BT_AMS_EU_NOTIF_VALUE_IDX 3
 
#define BT_AMS_ENTITY_UPDATE_FLAG_TRUNCATED 0
 
#define BT_AMS_EU_CMD_ENTITY_IDX 0
#define BT_AMS_EU_CMD_ATTRIBUTE_IDX 1
#define BT_AMS_EU_CMD_ATTRIBUTE_COUNT_MAX 4
 
#define BT_AMS_EA_CMD_ENTITY_IDX 0
#define BT_AMS_EA_CMD_ATTRIBUTE_IDX 1
#define BT_AMS_EA_CMD_LEN 2
 
#define BT_ATT_ERR_AMS_MS_INVALID_STATE 0xA0
#define BT_ATT_ERR_AMS_MS_INVALID_COMMAND 0xA1
#define BT_ATT_ERR_AMS_MS_ABSENT_ATTRIBUTE 0xA2
 
enum bt_ams_remote_command_id {
        BT_AMS_REMOTE_COMMAND_ID_PLAY,
        BT_AMS_REMOTE_COMMAND_ID_PAUSE,
        BT_AMS_REMOTE_COMMAND_ID_TOGGLE_PLAY_PAUSE,
        BT_AMS_REMOTE_COMMAND_ID_NEXT_TRACK,
        BT_AMS_REMOTE_COMMAND_ID_PREVIOUS_TRACK,
        BT_AMS_REMOTE_COMMAND_ID_VOLUME_UP,
        BT_AMS_REMOTE_COMMAND_ID_VOLUME_DOWN,
        BT_AMS_REMOTE_COMMAND_ID_ADVANCE_REPEAT_MODE,
        BT_AMS_REMOTE_COMMAND_ID_ADVANCE_SHUFFLE_MODE,
        BT_AMS_REMOTE_COMMAND_ID_SKIP_FORWARD,
        BT_AMS_REMOTE_COMMAND_ID_SKIP_BACKWARD,
        BT_AMS_REMOTE_COMMAND_ID_LIKE_TRACK,
        BT_AMS_REMOTE_COMMAND_ID_DISLIKE_TRACK,
        BT_AMS_REMOTE_COMMAND_ID_BOOKMARK_TRACK
};
 
enum bt_ams_entity_id {
        BT_AMS_ENTITY_ID_PLAYER,
        BT_AMS_ENTITY_ID_QUEUE,
        BT_AMS_ENTITY_ID_TRACK
};
 
enum bt_ams_player_attribute_id {
        BT_AMS_PLAYER_ATTRIBUTE_ID_NAME,
        BT_AMS_PLAYER_ATTRIBUTE_ID_PLAYBACK_INFO,
        BT_AMS_PLAYER_ATTRIBUTE_ID_VOLUME
};
 
enum bt_ams_queue_attribute_id {
        BT_AMS_QUEUE_ATTRIBUTE_ID_INDEX,
        BT_AMS_QUEUE_ATTRIBUTE_ID_COUNT,
        BT_AMS_QUEUE_ATTRIBUTE_ID_SHUFFLE_MODE,
        BT_AMS_QUEUE_ATTRIBUTE_ID_REPEAT_MODE
};
 
enum bt_ams_shuffle_mode {
        BT_AMS_SHUFFLE_MODE_OFF,
        BT_AMS_SHUFFLE_MODE_ONE,
        BT_AMS_SHUFFLE_MODE_ALL
};
 
enum bt_ams_repeat_mode {
        BT_AMS_REPEAT_MODE_OFF,
        BT_AMS_REPEAT_MODE_ONE,
        BT_AMS_REPEAT_MODE_ALL
};
 
enum bt_ams_track_attribute_id {
        BT_AMS_TRACK_ATTRIBUTE_ID_ARTIST,
        BT_AMS_TRACK_ATTRIBUTE_ID_ALBUM,
        BT_AMS_TRACK_ATTRIBUTE_ID_TITLE,
        BT_AMS_TRACK_ATTRIBUTE_ID_DURATION
};
 
struct bt_ams_entity_attribute {
        enum bt_ams_entity_id entity;
 
        union {
                enum bt_ams_player_attribute_id player;
                enum bt_ams_queue_attribute_id queue;
                enum bt_ams_track_attribute_id track;
        } attribute;
};
 
struct bt_ams_entity_attribute_list {
        enum bt_ams_entity_id entity;
 
        union {
                const enum bt_ams_player_attribute_id *player;
                const enum bt_ams_queue_attribute_id *queue;
                const enum bt_ams_track_attribute_id *track;
        } attribute;
 
        size_t attribute_count;
};
 
struct bt_ams_entity_update_notif {
        struct bt_ams_entity_attribute ent_attr;
 
        uint8_t flags;
 
        const uint8_t *data;
 
        size_t len;
};
 
struct bt_ams_client;
 
typedef void (*bt_ams_remote_command_notify_cb)(
                                struct bt_ams_client *ams_c,
                                const uint8_t *data,
                                size_t len);
 
typedef void (*bt_ams_entity_update_notify_cb)(
                                struct bt_ams_client *ams_c,
                                const struct bt_ams_entity_update_notif *notif,
                                int err);
 
typedef void (*bt_ams_write_cb)(struct bt_ams_client *ams_c,
                                uint8_t err);
 
typedef void (*bt_ams_read_cb)(struct bt_ams_client *ams_c,
                               uint8_t err, const uint8_t *data, size_t len);
 
struct bt_ams_client {
        struct bt_conn *conn;
 
        struct bt_ams_remote_command_characteristic {
                uint16_t handle;
 
                uint16_t handle_ccc;
 
                struct bt_gatt_subscribe_params notif_params;
 
                bt_ams_remote_command_notify_cb notify_cb;
 
                struct bt_gatt_write_params write_params;
 
                bt_ams_write_cb write_cb;
 
                uint8_t data;
        } remote_command;
 
        struct bt_ams_entity_update_characteristic {
                uint16_t handle;
 
                uint16_t handle_ccc;
 
                struct bt_gatt_subscribe_params notif_params;
 
                bt_ams_entity_update_notify_cb notify_cb;
 
                struct bt_gatt_write_params write_params;
 
                bt_ams_write_cb write_cb;
 
                uint8_t data[BT_AMS_EU_CMD_ATTRIBUTE_COUNT_MAX + 1];
        } entity_update;
 
        struct bt_ams_entity_attribute_characteristic {
                uint16_t handle;
 
                struct bt_gatt_write_params write_params;
 
                bt_ams_write_cb write_cb;
 
                uint8_t data[BT_AMS_EA_CMD_LEN];
 
                struct bt_gatt_read_params read_params;
 
                bt_ams_read_cb read_cb;
        } entity_attribute;
 
        atomic_t state;
};
 
int bt_ams_client_init(struct bt_ams_client *ams_c);
 
int bt_ams_handles_assign(struct bt_gatt_dm *dm,
                          struct bt_ams_client *ams_c);
 
int bt_ams_subscribe_remote_command(struct bt_ams_client *ams_c,
                                    bt_ams_remote_command_notify_cb func);
 
int bt_ams_unsubscribe_remote_command(struct bt_ams_client *ams_c);
 
int bt_ams_subscribe_entity_update(struct bt_ams_client *ams_c,
                                   bt_ams_entity_update_notify_cb func);
 
int bt_ams_unsubscribe_entity_update(struct bt_ams_client *ams_c);
 
int bt_ams_write_remote_command(struct bt_ams_client *ams_c,
                                enum bt_ams_remote_command_id command,
                                bt_ams_write_cb func);
 
int bt_ams_write_entity_update(struct bt_ams_client *ams_c,
                               const struct bt_ams_entity_attribute_list *ent_attr_list,
                               bt_ams_write_cb func);
 
int bt_ams_write_entity_attribute(struct bt_ams_client *ams_c,
                                  const struct bt_ams_entity_attribute *ent_attr,
                                  bt_ams_write_cb func);
 
int bt_ams_read_entity_attribute(struct bt_ams_client *ams_c,
                                 bt_ams_read_cb func);
 
#ifdef __cplusplus
}
#endif
 
#endif /* BT_AMS_CLIENT_H_ */