File bluespy.h¶

blueSPY C API

#include "stdbool.h"
#include "stdint.h"
#include <stddef.h>

Classes¶

Type	Name
struct	bluespy_audio_channel_t
struct	bluespy_audio_codec_decoded_format Describes the decoded audio format produced by a codec.
struct	bluespy_audio_codec_funcs Collection of function pointers exposed by a codec implementation.
struct	bluespy_audio_codec_info Describes the codec configuration for a given audio stream.
struct	bluespy_audio_codec_init_ret Return structure for the stream initialisation function.
struct	bluespy_audio_codec_lib_info Library-level information describing a codec implementation.
struct	bluespy_audiostream_id_span
struct	bluespy_bytes
struct	bluespy_capture_audiopod_options
struct	bluespy_capture_i2s_options
struct	bluespy_capture_options
struct	bluespy_cis_lc3_config
struct	bluespy_connection_id_span
struct	bluespy_custom_event
struct	bluespy_filter_file_options
struct	bluespy_key
struct	bluespy_latency_result
struct	bluespy_logic_change
struct	bluespy_multi_moreph_options
struct	bluespy_query_value

Public Types¶

Type	Name
enum	bluespy_audio_bias
typedef enum bluespy_audio_bias	bluespy_audio_bias
enum	bluespy_audio_channel
typedef enum bluespy_audio_channel	bluespy_audio_channel
typedef struct bluespy_audio_channel_t	bluespy_audio_channel_t
typedef struct bluespy_audio_codec_decoded_format	bluespy_audio_codec_decoded_format Describes the decoded audio format produced by a codec.
typedef void(*	bluespy_audio_codec_deinit_t Function-pointer type for the codec de-initialisation function.
typedef struct bluespy_audio_codec_funcs	bluespy_audio_codec_funcs Collection of function pointers exposed by a codec implementation.
typedef struct bluespy_audio_codec_info	bluespy_audio_codec_info Describes the codec configuration for a given audio stream.
typedef struct bluespy_audio_codec_init_ret	bluespy_audio_codec_init_ret Return structure for the stream initialisation function.
typedef bluespy_audio_codec_init_ret(*	bluespy_audio_codec_init_t Function pointer type for a codec's stream creation routine.
typedef struct bluespy_audio_codec_lib_info	bluespy_audio_codec_lib_info Library-level information describing a codec implementation.
typedef bluespy_audio_codec_lib_info(*	bluespy_audio_codec_lib_init_t Signature of the codec library initialisation function.
enum	bluespy_audio_connect
typedef enum bluespy_audio_connect	bluespy_audio_connect
typedef void(*	bluespy_audio_decode_t Function pointer type for the codec_decode function.
enum	bluespy_audio_sample_format Enum describing the data type of decoded audio samples.
typedef enum bluespy_audio_sample_format	bluespy_audio_sample_format Enum describing the data type of decoded audio samples.
typedef bluespy_id	bluespy_audiostream_id Identifier for an audio stream.
typedef struct bluespy_audiostream_id_span	bluespy_audiostream_id_span
typedef struct bluespy_bytes	bluespy_bytes
typedef struct bluespy_capture_audiopod_options	bluespy_capture_audiopod_options
typedef struct bluespy_capture_i2s_options	bluespy_capture_i2s_options
typedef struct bluespy_capture_options	bluespy_capture_options
typedef struct bluespy_cis_lc3_config	bluespy_cis_lc3_config
typedef void(*	bluespy_cleanup_t
enum	bluespy_codec_container Enumeration of transport/container types used to deliver codec data.
typedef enum bluespy_codec_container	bluespy_codec_container Enumeration of transport/container types used to deliver codec data.
typedef bluespy_id	bluespy_connection_id Identifier for a connection.
typedef struct bluespy_connection_id_span	bluespy_connection_id_span
typedef struct bluespy_custom_event	bluespy_custom_event
typedef bluespy_id	bluespy_device_id Identifier for a device.
enum	bluespy_error
typedef enum bluespy_error	bluespy_error
typedef bluespy_id	bluespy_event_id Identifier for an packet or higher layer event.
enum	bluespy_event_types
typedef enum bluespy_event_types	bluespy_event_types
typedef int32_t	bluespy_filter_file_id Indentifier for a capture file stored by the API itself. -1 means invalid Only use bluespy_filter_file_ids returned by the API After bluespy_load_file or bluespy_capture all previous ids are invalid.
typedef struct bluespy_filter_file_options	bluespy_filter_file_options
typedef uint64_t	bluespy_id General Identifier for an event, device, connection, or audiostream (queryable)
typedef struct bluespy_key	bluespy_key
typedef struct bluespy_latency_result	bluespy_latency_result
enum	bluespy_latency_status
typedef enum bluespy_latency_status	bluespy_latency_status
enum	bluespy_log_level Any value in [0, 255] can be used for logging.
typedef enum bluespy_log_level	bluespy_log_level Any value in [0, 255] can be used for logging.
typedef struct bluespy_logic_change	bluespy_logic_change
enum	bluespy_logic_rate
typedef enum bluespy_logic_rate	bluespy_logic_rate
typedef struct bluespy_multi_moreph_options	bluespy_multi_moreph_options
enum	bluespy_query_type
typedef enum bluespy_query_type	bluespy_query_type
typedef struct bluespy_query_value	bluespy_query_value
typedef int64_t	bluespy_time_point

Public Functions¶

Type	Name
BLUESPY_API void	bluespy_add_IRK (const unsigned char * key, uint64_t * addr, uint64_t n_addresses) Add an IRK.
BLUESPY_API void	bluespy_add_audio (const uint8_t * pcm_data, uint32_t pcm_data_len, bluespy_event_id source_id, uint32_t missing_samples) Function for delivering decoded PCM audio. Should only be called from inside the codec_decode function.
BLUESPY_API bluespy_error	bluespy_add_event (bluespy_custom_event * event) Adds a custom event to the bluespy event log.
BLUESPY_API bluespy_error	bluespy_add_link_key (const unsigned char * key, uint64_t addr0, uint64_t addr1) Add a link key for decryption.
BLUESPY_API bluespy_error	bluespy_add_log_message (bluespy_log_level level, const char * message, bluespy_time_point ts) Adds a log message into the file. Pass BLUESPY_TIME_INVALID to log at the present time.
BLUESPY_API bluespy_error	bluespy_add_to_filter_file (bluespy_filter_file_id file_id, bluespy_event_id event_id) Adds an event to a capture file.
BLUESPY_API void *	bluespy_allocate (size_t bytes, bluespy_cleanup_t cleanup) Allocates memory that bluespy will automatically clean up.
BLUESPY_API bluespy_error	bluespy_capture (const char * filename, bluespy_capture_options * opts) Start a capture.
BLUESPY_API bluespy_capture_audiopod_options *	bluespy_capture_audiopod_options_alloc () Create a bluespy_capture_audiopod_options struct.
BLUESPY_API bluespy_capture_i2s_options *	bluespy_capture_i2s_options_alloc () Create a bluespy_capture_i2s_options struct.
BLUESPY_API bluespy_capture_options *	bluespy_capture_options_alloc () Create a bluespy_capture_options struct.
BLUESPY_DEPRECATED_API void	bluespy_capture_options_delete (bluespy_capture_options * opts) Delete a bluespy_capture_options struct.
BLUESPY_API bluespy_error	bluespy_close_file () Close current file.
BLUESPY_API bluespy_error	bluespy_close_filter_file (bluespy_filter_file_id file_id) Close a capture file.
BLUESPY_API bluespy_error	bluespy_connect (uint32_t serial) Connect to Moreph.
BLUESPY_API bluespy_error	bluespy_connect_multiple (uint32_t * serial_data, uint64_t serial_size) Connect to multiple Morephs.
BLUESPY_API bluespy_filter_file_id	bluespy_create_filter_file (const char * filename, bluespy_filter_file_options * opts) Create a capture file.
BLUESPY_API void	bluespy_deinit () Clean up before program exits.
BLUESPY_API void	bluespy_delete (void * obj) Delete any of the following bluespy structs:
BLUESPY_API bluespy_error	bluespy_disconnect () Disconnect from Morephs.
BLUESPY_API const char *	bluespy_error_string (bluespy_error error) Get message for error.
BLUESPY_API bluespy_filter_file_options *	bluespy_filter_file_options_alloc () Create a bluespy_filter_file_options struct.
BLUESPY_API void	bluespy_filter_file_options_delete (bluespy_filter_file_options * opts) Delete a bluespy_filter_file_options struct.
BLUESPY_API bluespy_error	bluespy_free_keys (bluespy_key * keys, size_t count) Free the keys returned by bluespy_list_keys.
BLUESPY_API bluespy_audiostream_id_span	bluespy_get_audiostreams (bluespy_id id) Obtains the IDs of the audio streams which a device is creating or which are part of a connection.
BLUESPY_API bluespy_event_id	bluespy_get_baseband (uint32_t index) Get a baseband packet.
BLUESPY_API const bluespy_event_id *	bluespy_get_children (bluespy_event_id event, uint32_t * count) Get all lower layer packets.
BLUESPY_API bluespy_connection_id_span	bluespy_get_connections (bluespy_device_id dev_id) Obtains the IDs of the connections which a device is creating.
BLUESPY_API bluespy_device_id	bluespy_get_device_id (const char * addr) Obtains the Device ID from an address.
BLUESPY_API const char *	bluespy_get_filter_file_name (bluespy_filter_file_id id) Get file name from ID.
bluespy_audiostream_id	bluespy_get_first_audiostream_id () Get the first out of all available audio stream IDs. Used to iterate over all audio streams.
bluespy_connection_id	bluespy_get_first_connection_id () Get the first out of all available Connection IDs. Used to iterate over all connections.
bluespy_device_id	bluespy_get_first_device_id () Get the first out of all available Device IDs. Used to iterate over all devices.
BLUESPY_API uint32_t	bluespy_get_logic_at_time (bluespy_time_point ts) Get the logic state at a given time.
BLUESPY_API bluespy_audiostream_id	bluespy_get_next_audiostream_id (bluespy_audiostream_id id) Get the next audio stream ID after 'id'. Used to iterate over all audio streams.
BLUESPY_API bluespy_connection_id	bluespy_get_next_connection_id (bluespy_connection_id id) Get the next Connection ID after 'id'. Used to iterate over all connections.
BLUESPY_API bluespy_device_id	bluespy_get_next_device_id (bluespy_device_id id) Get the next Device ID after 'id'. Used to iterate over all devices.
BLUESPY_API bluespy_logic_change	bluespy_get_next_logic_change (bluespy_time_point ts, uint32_t mask) Get the next logic state after a given time.
BLUESPY_API bluespy_event_id	bluespy_get_parent (bluespy_event_id event) Get higher layer packets.
BLUESPY_API void	bluespy_init () Initialise bluespy, run once at start of program.
BLUESPY_API const char *	bluespy_latency_status_string (bluespy_latency_status status) Get message for latency status.
BLUESPY_API bluespy_error	bluespy_list_keys (bluespy_key ** keys, size_t * count) List keys from the security tab. Later, call bluespy_free_keys.
BLUESPY_API bluespy_error	bluespy_load_file (const char * filename) Load a capture.
BLUESPY_API bluespy_error	bluespy_mark_key_used (const char * key, size_t len) Mark an encryption key as used. Most useful in custom decoder where the custom decoder performs decryption. This will highlight the key green in the GUI and cause it to be included in the capture.
BLUESPY_API bluespy_latency_result	bluespy_measure_latency (bluespy_audio_channel_t channel0, bluespy_audio_channel_t channel1, bool include_pres_delay, bluespy_time_point ts) Measure the latency between two audio streams.
BLUESPY_API bluespy_error	bluespy_moreph_reboot (uint32_t serial) Reboot Moreph.
BLUESPY_API uint64_t	bluespy_morephs_connected (uint32_t ** serials) Lists the serial numbers of the connected morephs.
BLUESPY_API uint32_t	bluespy_packet_count (void) Number of baseband packets loaded.
BLUESPY_API bluespy_error	bluespy_play_to_audiopod_output (const char * filename, bool loop) Play audio file to Audiopod File Playback.
BLUESPY_API const char *	bluespy_print_time (bluespy_time_point ts) Prints the time in a hh:mm:ss.xxx format.
BLUESPY_API const char *	bluespy_query (bluespy_id event, const char * query) Query an event, device, connection, or audio stream.
BLUESPY_DEPRECATED_API int	bluespy_query_auto (bluespy_id event, const char * query, const char ** s, int64_t * i, bool * b) Query an event, device, connection, or audio stream.
BLUESPY_API bool	bluespy_query_bool (bluespy_id event, const char * query) Query an event, device, connection, or audio stream.
BLUESPY_API bluespy_bytes	bluespy_query_bytes (bluespy_id event, const char * query) Query an event, device, connection, or audio stream.
BLUESPY_API bluespy_query_value	bluespy_query_get (bluespy_id id, const char * query) Query an event, device, connection, or audio stream.
BLUESPY_API int64_t	bluespy_query_int (bluespy_id event, const char * query) Query an event, device, connection, or audio stream.
BLUESPY_API void	bluespy_register_event_callback (bluespy_event_types types, void()(bluespy_event_id) callback) Sets the callback for bluespy events.*
BLUESPY_API bluespy_error	bluespy_set_cis_lc3_config (bluespy_audiostream_id id, bluespy_cis_lc3_config * conf) Set the configuration of a CIS stream.
BLUESPY_API void	bluespy_start_gui () Start a GUI instance.
BLUESPY_API bluespy_error	bluespy_stop_audio () Stop the audio file in Audiopod File Playback.
BLUESPY_API bluespy_error	bluespy_stop_capture () Stop a capture.
BLUESPY_API bluespy_logic_change	bluespy_wait_until_next_logic_change (uint32_t mask, int64_t timeout, bluespy_time_point start_ts) Wait until any of the logic lines within the mask changes, and returns the result.

Macros¶

Type	Name
define	BLUESPY_API `\_\_attribute\_\_((visibility("default")))`
define	BLUESPY_AUDIO_API_VERSION `1` Defines the API version for blueSPY Audio Codec Interface.
define	BLUESPY_DEPRECATED_API `BLUESPY\_API`
define	BLUESPY_FILTER_FILE_ID_INVALID `(([bluespy\_filter\_file\_id](bluespy_8h.md#typedef-bluespy_filter_file_id))(-1))`
define	BLUESPY_HASATTR (attr) `(0)`
define	BLUESPY_ID_INVALID `(([bluespy\_id](bluespy_8h.md#typedef-bluespy_id))(-1))` Invalid value, used to represent N/A.
define	BLUESPY_TIME_INVALID `(INT64\_MAX)`

Public Types Documentation¶

enum bluespy_audio_bias¶

enum bluespy_audio_bias {
    BLUESPY_BIAS_OFF,
    BLUESPY_BIAS_LOW,
    BLUESPY_BIAS_MID,
    BLUESPY_BIAS_HIG,
    BLUESPY_BIAS_VDD
};

typedef bluespy_audio_bias¶

typedef enum bluespy_audio_bias bluespy_audio_bias;

enum bluespy_audio_channel¶

enum bluespy_audio_channel {
    BLUESPY_STEREO,
    BLUESPY_MONO_L,
    BLUESPY_MONO_R
};

typedef bluespy_audio_channel¶

typedef enum bluespy_audio_channel bluespy_audio_channel;

typedef bluespy_audio_channel_t¶

typedef struct bluespy_audio_channel_t bluespy_audio_channel_t;

typedef bluespy_audio_codec_decoded_format¶

Describes the decoded audio format produced by a codec.

typedef struct bluespy_audio_codec_decoded_format bluespy_audio_codec_decoded_format;

Each codec must report its decoded sample format as part of its initialisation return structure.

typedef bluespy_audio_codec_deinit_t¶

Function-pointer type for the codec de-initialisation function.

typedef void(* bluespy_audio_codec_deinit_t) (uintptr_t context);

Called when an audio stream ends so the codec can release state and resources.

Parameters:

context Opaque handle to the codec instance state to be freed. This pointer should be cast back to the internal state struct and freed.

typedef bluespy_audio_codec_funcs¶

Collection of function pointers exposed by a codec implementation.

typedef struct bluespy_audio_codec_funcs bluespy_audio_codec_funcs;

Each successfully initialised codec must provide at least a decode and a deinit function. Both pointers must be non-NULL.

typedef bluespy_audio_codec_info¶

Describes the codec configuration for a given audio stream.

typedef struct bluespy_audio_codec_info bluespy_audio_codec_info;

The configuration data pointed to by config points to container-specific payloads as obtained from signalling. The meaning depends on container:

BLUESPY_CODEC_AVDTP: config points to a full AVDTP_Service_Capabilities_Media_Codec_t structure (including its entire Media_Codec_Specific_Information block).
BLUESPY_CODEC_CIS: config points to the Codec_Specific_Configuration part of the ASE Control Point (typically from a Set Configuration command).
BLUESPY_CODEC_BIS: config points to the ACAD + AdvData fields of the Extended Advertising PDU payload. ACAD (Additional Controller Advertising Data) includes the BIG Info block. AdvData (Advertising Data) includes the BASE block.

In all cases, config_len bytes are valid.

Note:

Pointers are transient: valid only during the new_codec_stream() call. Implementations must copy data they need.

typedef bluespy_audio_codec_init_ret¶

Return structure for the stream initialisation function.

typedef struct bluespy_audio_codec_init_ret bluespy_audio_codec_init_ret;

Returned by new_codec_stream() to provide the negotiated PCM output format, function table, and any error information.

typedef bluespy_audio_codec_init_t¶

Function pointer type for a codec's stream creation routine.

typedef bluespy_audio_codec_init_ret(* bluespy_audio_codec_init_t) (bluespy_audiostream_id stream_id, const bluespy_audio_codec_info *info);

The host calls this when an audio stream is detected and needs decoding.

The codec should: * Verify that it supports the provided configuration. * Allocate and initialise decoder state for the stream. * Return the output format and function pointers.

Each codec must export a C-linkage symbol named new_codec_stream matching this signature:

extern "C"
bluespy_audio_codec_init_ret new_codec_stream(
    bluespy_audiostream_id stream_id,
    const bluespy_audio_codec_info* info);

Parameters:

stream_id Gives an ID that can be passed to query functions, if information about the stream is required that's not included in the codec info.
info Pointer to container-specific configuration data. The memory is valid only during this call; codecs must copy anything they need.

Returns:

On success (error == 0) the format and fns fields must contain valid values. On failure (error < 0) the codec must release any allocations and return immediately so that other codec implementations can be offered the same configuration.

Note:

Codecs that do not recognise or support the configuration should return error = -1 to allow fallback to alternative decoders.

typedef bluespy_audio_codec_lib_info¶

Library-level information describing a codec implementation.

typedef struct bluespy_audio_codec_lib_info bluespy_audio_codec_lib_info;

Each codec shared library (e.g. AAC, aptX) must expose an 'init()' function returning an instance of this structure. It identifies the codec library at runtime and provides a library version for compatibility checking.

typedef bluespy_audio_codec_lib_init_t¶

Signature of the codec library initialisation function.

typedef bluespy_audio_codec_lib_info(* bluespy_audio_codec_lib_init_t) (void);

Each codec library must export a C-linkage symbol named 'init()' matching this signature. It provides information about the library and its capabilities.

Returns:

A structure containing the codec libray information.

enum bluespy_audio_connect¶

enum bluespy_audio_connect {
    BLUESPY_NOAUDIO,
    BLUESPY_LINE,
    BLUESPY_JACK,
    BLUESPY_HEADSET,
    BLUESPY_COAX,
    BLUESPY_OPTICAL,
    BLUESPY_MIC,
    BLUESPY_I2S
};

typedef bluespy_audio_connect¶

typedef enum bluespy_audio_connect bluespy_audio_connect;

typedef bluespy_audio_decode_t¶

Function pointer type for the codec_decode function.

typedef void(* bluespy_audio_decode_t) (uintptr_t context, const uint8_t *payload, const uint32_t payload_len, bluespy_event_id event_id, uint64_t sequence_number);

Called once per encoded packet or frame to produce decoded PCM audio data.

Parameters:

context Opaque handle to the codec instance state. This is the value returned in bluespy_audio_codec_init_ret::context_handle during initialization.
payload Pointer to the encoded audio packet or frame.

For Classic (A2DP/AVDTP): This buffer represents the contents of a single L2CAP Service Data Unit (SDU) carrying an AVDTP media packet. This typically contains: * RTP header (12 bytes + 4 bytes per CSRC) * Optional codec-specific headers (e.g., LDAC sync byte 0xAA) * One or more codec frames

For LE Audio (CIS/BIS): Payload is one reconstructed ISOAL SDU.

Parameters:

payload_len Length of the encoded data in bytes.
event_id Capture event identifier for this SDU.
sequence_number 64-bit monotonic sequence assigned by the host.

enum bluespy_audio_sample_format¶

Enum describing the data type of decoded audio samples.

enum bluespy_audio_sample_format {
    BLUESPY_AUDIO_FORMAT_S16_LE = 0
};

typedef bluespy_audio_sample_format¶

Enum describing the data type of decoded audio samples.

typedef enum bluespy_audio_sample_format bluespy_audio_sample_format;

typedef bluespy_audiostream_id¶

Identifier for an audio stream.

typedef bluespy_id bluespy_audiostream_id;

BLUESPY_ID_INVALID means invalid. Audio stream IDs are ordered arbitrarily. Only use bluespy_audiostream_ids returned by the API. After bluespy_load_file or bluespy_capture all previous ids are invalid.

typedef bluespy_audiostream_id_span¶

typedef struct bluespy_audiostream_id_span bluespy_audiostream_id_span;

typedef bluespy_bytes¶

typedef struct bluespy_bytes bluespy_bytes;

typedef bluespy_capture_audiopod_options¶

typedef struct bluespy_capture_audiopod_options bluespy_capture_audiopod_options;

typedef bluespy_capture_i2s_options¶

typedef struct bluespy_capture_i2s_options bluespy_capture_i2s_options;

typedef bluespy_capture_options¶

typedef struct bluespy_capture_options bluespy_capture_options;

typedef bluespy_cis_lc3_config¶

typedef struct bluespy_cis_lc3_config bluespy_cis_lc3_config;

typedef bluespy_cleanup_t¶

typedef void(* bluespy_cleanup_t) (void *);

enum bluespy_codec_container¶

Enumeration of transport/container types used to deliver codec data.

enum bluespy_codec_container {
    BLUESPY_CODEC_AVDTP,
    BLUESPY_CODEC_CIS,
    BLUESPY_CODEC_BIS
};

This is used to differentiate between Classic (AVDTP/A2DP) and LE Audio (LEA) transports.

typedef bluespy_codec_container¶

Enumeration of transport/container types used to deliver codec data.

typedef enum bluespy_codec_container bluespy_codec_container;

This is used to differentiate between Classic (AVDTP/A2DP) and LE Audio (LEA) transports.

typedef bluespy_connection_id¶

Identifier for a connection.

typedef bluespy_id bluespy_connection_id;

BLUESPY_ID_INVALID means invalid. Connection IDs are ordered arbitrarily. Only use bluespy_connection_ids returned by the API. After bluespy_load_file or bluespy_capture all previous ids are invalid.

typedef bluespy_connection_id_span¶

typedef struct bluespy_connection_id_span bluespy_connection_id_span;

typedef bluespy_custom_event¶

typedef struct bluespy_custom_event bluespy_custom_event;

typedef bluespy_device_id¶

Identifier for a device.

typedef bluespy_id bluespy_device_id;

BLUESPY_ID_INVALID means invalid. Device IDs are ordered arbitrarily. Only use bluespy_device_ids returned by the API. After bluespy_load_file or bluespy_capture all previous ids are invalid.

enum bluespy_error¶

enum bluespy_error {
    BLUESPY_NO_ERROR = 0,
    BLUESPY_ERROR_NO_DEVICE,
    BLUESPY_ERROR_LICENCE,
    BLUESPY_ERROR_NO_FILE,
    BLUESPY_ERROR_CAPTURE_NOT_STARTED,
    BLUESPY_ERROR_INVALID_PACKET,
    BLUESPY_ERROR_INVALID_CAPTURE_OPTIONS,
    BLUESPY_ERROR_INVALID_CIS_CONFIG,
    BLUESPY_ERROR_AUDIOPOD_DISABLED,
    BLUESPY_ERROR_AUDIOPOD_OUTPUT_DISABLED,
    BLUESPY_ERROR_INVALID_PARAMETER,
    BLUESPY_ERROR_IUT_NOT_CONNECTED,
    BLUESPY_ERROR_INVALID_TCID,
    BLUESPY_ERROR_TESTCASE_FAILURE,
    BLUESPY_ERROR_ABORTED_TESTCASES,
    BLUESPY_ERROR_NOT_INITIALIZED
};

typedef bluespy_error¶

typedef enum bluespy_error bluespy_error;

typedef bluespy_event_id¶

Identifier for an packet or higher layer event.

typedef bluespy_id bluespy_event_id;

BLUESPY_ID_INVALID means invalid. Only use bluespy_event_ids returned by the API. After bluespy_load_file or bluespy_capture all previous ids are invalid.

enum bluespy_event_types¶

enum bluespy_event_types {
    bluespy_event_bt_baseband,
    bluespy_event_custom,
    bluespy_event_proprietary_1,
    bluespy_event_proprietary_2
};

typedef bluespy_event_types¶

typedef enum bluespy_event_types bluespy_event_types;

typedef bluespy_filter_file_id¶

Indentifier for a capture file stored by the API itself. -1 means invalid Only use bluespy_filter_file_ids returned by the API After bluespy_load_file or bluespy_capture all previous ids are invalid.

typedef int32_t bluespy_filter_file_id;

typedef bluespy_filter_file_options¶

typedef struct bluespy_filter_file_options bluespy_filter_file_options;

typedef bluespy_id¶

General Identifier for an event, device, connection, or audiostream (queryable)

typedef uint64_t bluespy_id;

BLUESPY_ID_INVALID means invalid. Only use bluespy_ids returned by the API. Functions accepting a bluespy_id can accept any bluespy_???_id. After bluespy_load_file or bluespy_capture all previous ids are invalid.

typedef bluespy_key¶

typedef struct bluespy_key bluespy_key;

typedef bluespy_latency_result¶

typedef struct bluespy_latency_result bluespy_latency_result;

enum bluespy_latency_status¶

enum bluespy_latency_status {
    BLUESPY_OK,
    BLUESPY_ZEROS,
    BLUESPY_NOT_ENOUGH_DATA,
    BLUESPY_ENERGY_THRESHOLD,
    BLUESPY_AMBIG_PEAK,
    BLUESPY_PERIODIC,
    BLUESPY_OTHER_ERROR
};

typedef bluespy_latency_status¶

typedef enum bluespy_latency_status bluespy_latency_status;

enum bluespy_log_level¶

Any value in [0, 255] can be used for logging.

enum bluespy_log_level {
    BLUESPY_LOG_PASS = 0x00,
    BLUESPY_LOG_WARN = 0x20,
    BLUESPY_LOG_INFO = 0x40,
    BLUESPY_LOG_DEBUG = 0x60,
    BLUESPY_LOG_ERROR = 0x80
};

Colour-coding will be applied in the GUI based on the top three bits, and the bottom 5 bits will be available as log.severity_level_subtype

typedef bluespy_log_level¶

Any value in [0, 255] can be used for logging.

typedef enum bluespy_log_level bluespy_log_level;

Colour-coding will be applied in the GUI based on the top three bits, and the bottom 5 bits will be available as log.severity_level_subtype

typedef bluespy_logic_change¶

typedef struct bluespy_logic_change bluespy_logic_change;

enum bluespy_logic_rate¶

enum bluespy_logic_rate {
    bluespy_logic_rate_high,
    bluespy_logic_rate_mid,
    bluespy_logic_rate_low
};

typedef bluespy_logic_rate¶

typedef enum bluespy_logic_rate bluespy_logic_rate;

typedef bluespy_multi_moreph_options¶

typedef struct bluespy_multi_moreph_options bluespy_multi_moreph_options;

enum bluespy_query_type¶

enum bluespy_query_type {
    bluespy_query_type_invalid = -1,
    bluespy_query_type_none = 0,
    bluespy_query_type_bool = 1,
    bluespy_query_type_int = 2,
    bluespy_query_type_string = 3,
    bluespy_query_type_bytes = 4,
    bluespy_query_type_double = 5,
    bluespy_query_type_id = 6
};

typedef bluespy_query_type¶

typedef enum bluespy_query_type bluespy_query_type;

typedef bluespy_query_value¶

typedef struct bluespy_query_value bluespy_query_value;

typedef bluespy_time_point¶

typedef int64_t bluespy_time_point;

The time in nanoseconds since the epoch 1970/01/01 00:00 UTC BLUESPY_TIME_INVALID (0x7fff'ffff'ffff'ffff) represents an invalid time point

Public Functions Documentation¶

function bluespy_add_IRK¶

Add an IRK.

BLUESPY_API void bluespy_add_IRK (
    const unsigned char * key,
    uint64_t * addr,
    uint64_t n_addresses
)

Parameters:

key - 16 bytes of binary
addr - Array of relevant Bluetooth addresses, can be empty. Set bit 48 == 1 for Random, == 0 for Public
n_addresses - Length of array

The key should be added before loading/capturing, or you should load again afterwards.

function bluespy_add_audio¶

Function for delivering decoded PCM audio. Should only be called from inside the codec_decode function.

BLUESPY_API void bluespy_add_audio (
    const uint8_t * pcm_data,
    uint32_t pcm_data_len,
    bluespy_event_id source_id,
    uint32_t missing_samples
)

Parameters:

pcm_data Pointer to decoded PCM data (S16 LE interleaved).
pcm_data_len Number of bytes at pcm_data.
source_id Identifier for the source SDU / packet, used by the host to correlate decoded audio with captured packets. Usually passed from codec_decode.
missing_samples Number of samples (per channel) lost immediately before this packet. Pass 0 if continuous or unknown.

function bluespy_add_event¶

Adds a custom event to the bluespy event log.

BLUESPY_API bluespy_error bluespy_add_event (
    bluespy_custom_event * event
)

Used to add custom events for things like custom protocols

function bluespy_add_link_key¶

Add a link key for decryption.

BLUESPY_API bluespy_error bluespy_add_link_key (
    const unsigned char * key,
    uint64_t addr0,
    uint64_t addr1
)

Parameters:

key - 16 bytes of binary
addr0 - Bluetooth address of first device, set to 0 if unknown
addr1 - Bluetooth address of second device, set to 0 if unknown

Returns:

Error code

The link key should be added before loading/capturing, or you should load again afterwards.

function bluespy_add_log_message¶

Adds a log message into the file. Pass BLUESPY_TIME_INVALID to log at the present time.

BLUESPY_API bluespy_error bluespy_add_log_message (
    bluespy_log_level level,
    const char * message,
    bluespy_time_point ts
)

Parameters:

level
message
ts

Returns:

Error code

function bluespy_add_to_filter_file¶

Adds an event to a capture file.

BLUESPY_API bluespy_error bluespy_add_to_filter_file (
    bluespy_filter_file_id file_id,
    bluespy_event_id event_id
)

Parameters:

file_id - File ID
event_id - Event ID

Returns:

Error code

function bluespy_allocate¶

Allocates memory that bluespy will automatically clean up.

BLUESPY_API void * bluespy_allocate (
    size_t bytes,
    bluespy_cleanup_t cleanup
)

Parameters:

bytes - The number of bytes to allocate
cleanup - Optional function to be called when the allocation is later deallocated. Usually NULL

This function should be primarily used in custom decoders to allocate memory for new events

function bluespy_capture¶

Start a capture.

BLUESPY_API bluespy_error bluespy_capture (
    const char * filename,
    bluespy_capture_options * opts
)

Parameters:

filename - UTF8 filename
opts - Capture options

Returns:

Error code

function bluespy_capture_audiopod_options_alloc¶

Create a bluespy_capture_audiopod_options struct.

BLUESPY_API bluespy_capture_audiopod_options * bluespy_capture_audiopod_options_alloc ()

Returns:

New struct

function bluespy_capture_i2s_options_alloc¶

Create a bluespy_capture_i2s_options struct.

BLUESPY_API bluespy_capture_i2s_options * bluespy_capture_i2s_options_alloc ()

Returns:

New struct

function bluespy_capture_options_alloc¶

Create a bluespy_capture_options struct.

BLUESPY_API bluespy_capture_options * bluespy_capture_options_alloc ()

Returns:

New struct

function bluespy_capture_options_delete¶

Delete a bluespy_capture_options struct.

BLUESPY_DEPRECATED_API void bluespy_capture_options_delete (
    bluespy_capture_options * opts
)

function bluespy_close_file¶

Close current file.

BLUESPY_API bluespy_error bluespy_close_file ()

Returns:

Error code

function bluespy_close_filter_file¶

Close a capture file.

BLUESPY_API bluespy_error bluespy_close_filter_file (
    bluespy_filter_file_id file_id
)

Parameters:

file_id - File ID

Returns:

Error code

function bluespy_connect¶

Connect to Moreph.

BLUESPY_API bluespy_error bluespy_connect (
    uint32_t serial
)

Parameters:

serial - Serial number of the Moreph

Returns:

Error code

Connect by serial number, or first found on USB if serial == -1

function bluespy_connect_multiple¶

Connect to multiple Morephs.

BLUESPY_API bluespy_error bluespy_connect_multiple (
    uint32_t * serial_data,
    uint64_t serial_size
)

Parameters:

serial_data - Serial numbers of the Morephs
serial_size - Number of Morephs to connect

Returns:

Error code

Connect by serial numbers

function bluespy_create_filter_file¶

Create a capture file.

BLUESPY_API bluespy_filter_file_id bluespy_create_filter_file (
    const char * filename,
    bluespy_filter_file_options * opts
)

Parameters:

filename - File name
opts - Filter File options

Returns:

ID of file

function bluespy_deinit¶

Clean up before program exits.

BLUESPY_API void bluespy_deinit ()

function bluespy_delete¶

Delete any of the following bluespy structs:

BLUESPY_API void bluespy_delete (
    void * obj
)

Parameters:

obj - Object to delete

function bluespy_disconnect¶

Disconnect from Morephs.

BLUESPY_API bluespy_error bluespy_disconnect ()

Returns:

Error code

function bluespy_error_string¶

Get message for error.

BLUESPY_API const char * bluespy_error_string (
    bluespy_error error
)

Parameters:

error

Returns:

Internal pointer to null terminated string (do not free)

function bluespy_filter_file_options_alloc¶

Create a bluespy_filter_file_options struct.

BLUESPY_API bluespy_filter_file_options * bluespy_filter_file_options_alloc ()

Returns:

New struct

function bluespy_filter_file_options_delete¶

Delete a bluespy_filter_file_options struct.

BLUESPY_API void bluespy_filter_file_options_delete (
    bluespy_filter_file_options * opts
)

function bluespy_free_keys¶

Free the keys returned by bluespy_list_keys.

BLUESPY_API bluespy_error bluespy_free_keys (
    bluespy_key * keys,
    size_t count
)

function bluespy_get_audiostreams¶

Obtains the IDs of the audio streams which a device is creating or which are part of a connection.

BLUESPY_API bluespy_audiostream_id_span bluespy_get_audiostreams (
    bluespy_id id
)

Parameters:

id - Bluespy ID

Returns:

An array of audio stream IDs

If id is device_id: Streams which a device is creating. If id is connection_id: Streams which are part of a connection. If id is BLUESPY_ID_INVALID: Streams not associated with any device, e.g. audiopod streams.

function bluespy_get_baseband¶

Get a baseband packet.

BLUESPY_API bluespy_event_id bluespy_get_baseband (
    uint32_t index
)

Parameters:

index - 0 <= index < bluespy_packet_count()

Returns:

Event ID

function bluespy_get_children¶

Get all lower layer packets.

BLUESPY_API const bluespy_event_id * bluespy_get_children (
    bluespy_event_id event,
    uint32_t * count
)

Parameters:

event
count - size of returned array

Returns:

Event ID array

Returned child array is only valid until next call, so take a copy Returned child array is null-terminated with BLUESPY_ID_INVALID

function bluespy_get_connections¶

Obtains the IDs of the connections which a device is creating.

BLUESPY_API bluespy_connection_id_span bluespy_get_connections (
    bluespy_device_id dev_id
)

Parameters:

dev_id - Device ID

Returns:

An array of Connection IDs

function bluespy_get_device_id¶

Obtains the Device ID from an address.

BLUESPY_API bluespy_device_id bluespy_get_device_id (
    const char * addr
)

Parameters:

addr - 6 bytes representing the address

Returns:

Device ID. BLUESPY_ID_INVALID = Unknown or Invalid address

function bluespy_get_filter_file_name¶

Get file name from ID.

BLUESPY_API const char * bluespy_get_filter_file_name (
    bluespy_filter_file_id id
)

Parameters:

id - File ID

Returns:

file name

function bluespy_get_first_audiostream_id¶

Get the first out of all available audio stream IDs. Used to iterate over all audio streams.

inline bluespy_audiostream_id bluespy_get_first_audiostream_id ()

Returns:

Audio stream ID

function bluespy_get_first_connection_id¶

Get the first out of all available Connection IDs. Used to iterate over all connections.

inline bluespy_connection_id bluespy_get_first_connection_id ()

Returns:

Connection ID

function bluespy_get_first_device_id¶

Get the first out of all available Device IDs. Used to iterate over all devices.

inline bluespy_device_id bluespy_get_first_device_id ()

Returns:

Device ID

function bluespy_get_logic_at_time¶

Get the logic state at a given time.

BLUESPY_API uint32_t bluespy_get_logic_at_time (
    bluespy_time_point ts
)

Parameters:

ts - timestamp

Returns:

Logic state mask

function bluespy_get_next_audiostream_id¶

Get the next audio stream ID after 'id'. Used to iterate over all audio streams.

BLUESPY_API bluespy_audiostream_id bluespy_get_next_audiostream_id (
    bluespy_audiostream_id id
)

Parameters:

id - Audio stream ID

Returns:

Audio stream ID

id = BLUESPY_ID_INVALID returns the first audio stream id. Returns BLUESPY_ID_INVALID if there are no audio streams remaining.

function bluespy_get_next_connection_id¶

Get the next Connection ID after 'id'. Used to iterate over all connections.

BLUESPY_API bluespy_connection_id bluespy_get_next_connection_id (
    bluespy_connection_id id
)

Parameters:

id - Connection ID

Returns:

Connection ID

id = BLUESPY_ID_INVALID returns the first connection id. Returns BLUESPY_ID_INVALID if there are no connections remaining.

function bluespy_get_next_device_id¶

Get the next Device ID after 'id'. Used to iterate over all devices.

BLUESPY_API bluespy_device_id bluespy_get_next_device_id (
    bluespy_device_id id
)

Parameters:

id - Device ID

Returns:

Device ID

id = BLUESPY_ID_INVALID returns the first device id. Returns BLUESPY_ID_INVALID if there are no devices remaining.

function bluespy_get_next_logic_change¶

Get the next logic state after a given time.

BLUESPY_API bluespy_logic_change bluespy_get_next_logic_change (
    bluespy_time_point ts,
    uint32_t mask
)

Parameters:

ts - timestamp
mask - logic mask for which lines to look at

Returns:

Logic state mask and time of the next change

function bluespy_get_parent¶

Get higher layer packets.

BLUESPY_API bluespy_event_id bluespy_get_parent (
    bluespy_event_id event
)

Parameters:

event

Returns:

Event ID

function bluespy_init¶

Initialise bluespy, run once at start of program.

BLUESPY_API void bluespy_init ()

function bluespy_latency_status_string¶

Get message for latency status.

BLUESPY_API const char * bluespy_latency_status_string (
    bluespy_latency_status status
)

Parameters:

status

Returns:

Internal pointer to null terminated string (do not free)

function bluespy_list_keys¶

List keys from the security tab. Later, call bluespy_free_keys.

BLUESPY_API bluespy_error bluespy_list_keys (
    bluespy_key ** keys,
    size_t * count
)

function bluespy_load_file¶

Load a capture.

BLUESPY_API bluespy_error bluespy_load_file (
    const char * filename
)

Parameters:

filename - UTF8 filename

Returns:

Error code

function bluespy_mark_key_used¶

Mark an encryption key as used. Most useful in custom decoder where the custom decoder performs decryption. This will highlight the key green in the GUI and cause it to be included in the capture.

BLUESPY_API bluespy_error bluespy_mark_key_used (
    const char * key,
    size_t len
)

function bluespy_measure_latency¶

Measure the latency between two audio streams.

BLUESPY_API bluespy_latency_result bluespy_measure_latency (
    bluespy_audio_channel_t channel0,
    bluespy_audio_channel_t channel1,
    bool include_pres_delay,
    bluespy_time_point ts
)

Parameters:

channel0 - Audio Channel
channel1 - Audio Channel
include_pres_delay - Whether to include presentation delay
ts - Time to measure at

Returns:

latency result

function bluespy_moreph_reboot¶

Reboot Moreph.

BLUESPY_API bluespy_error bluespy_moreph_reboot (
    uint32_t serial
)

Parameters:

serial - Serial number of the Moreph

Returns:

Error code

Reboot by serial number, or first found on if serial == -1 This function will cause the specified Moreph to disconnect - bluespy_connect needs to be called afterwards to talk to the Moreph again

function bluespy_morephs_connected¶

Lists the serial numbers of the connected morephs.

BLUESPY_API uint64_t bluespy_morephs_connected (
    uint32_t ** serials
)

Parameters:

serials - Pointer to array of serial numbers

Returns:

Returns the number of connected morephs

function bluespy_packet_count¶

Number of baseband packets loaded.

BLUESPY_API uint32_t bluespy_packet_count (
    void
)

Returns:

N

function bluespy_play_to_audiopod_output¶

Play audio file to Audiopod File Playback.

BLUESPY_API bluespy_error bluespy_play_to_audiopod_output (
    const char * filename,
    bool loop
)

Parameters:

filename - Audio file
loop - Whether to loop the file

Returns:

error

function bluespy_print_time¶

Prints the time in a hh:mm:ss.xxx format.

BLUESPY_API const char * bluespy_print_time (
    bluespy_time_point ts
)

Parameters:

ts

Returns:

Time string

function bluespy_query¶

Query an event, device, connection, or audio stream.

BLUESPY_API const char * bluespy_query (
    bluespy_id event,
    const char * query
)

Parameters:

event
query - query string to apply

Returns:

String result of a query

Returned value is valid until next call, so take a copy

function bluespy_query_auto¶

Query an event, device, connection, or audio stream.

BLUESPY_DEPRECATED_API int bluespy_query_auto (
    bluespy_id event,
    const char * query,
    const char ** s,
    int64_t * i,
    bool * b
)

Parameters:

event
query - query string to apply
s - return if string
i - return if int
b - return if bool

Returns:

0 = None, 1 = str, 2 = int, 3 = bool

Returned value is valid until next call, so take a copy

Use bluespy_query_get instead

function bluespy_query_bool¶

Query an event, device, connection, or audio stream.

BLUESPY_API bool bluespy_query_bool (
    bluespy_id event,
    const char * query
)

Parameters:

event
query - query string to apply

Returns:

Bool result of a query

function bluespy_query_bytes¶

Query an event, device, connection, or audio stream.

BLUESPY_API bluespy_bytes bluespy_query_bytes (
    bluespy_id event,
    const char * query
)

Parameters:

event
query - query string to apply

Returns:

Bytes result of a query

function bluespy_query_get¶

Query an event, device, connection, or audio stream.

BLUESPY_API bluespy_query_value bluespy_query_get (
    bluespy_id id,
    const char * query
)

Parameters:

event
query - query string to apply

Returns:

bluespy_query_value

Referenced str/bytes data is valid until next call, so take a copy

function bluespy_query_int¶

Query an event, device, connection, or audio stream.

BLUESPY_API int64_t bluespy_query_int (
    bluespy_id event,
    const char * query
)

Parameters:

event
query - query string to apply

Returns:

Integer result of a query

function bluespy_register_event_callback¶

Sets the callback for bluespy events.

BLUESPY_API void bluespy_register_event_callback (
    bluespy_event_types types,
    void(*)( bluespy_event_id ) callback
)

Parameters:

types - The types of events that the callback should be called for
callback - The callback function

Use this function to add a callback for processing custom protocols and other propietary features

function bluespy_set_cis_lc3_config¶

Set the configuration of a CIS stream.

BLUESPY_API bluespy_error bluespy_set_cis_lc3_config (
    bluespy_audiostream_id id,
    bluespy_cis_lc3_config * conf
)

Parameters:

id - Audio stream ID
conf - Pointer to CIS config

Returns:

error

function bluespy_start_gui¶

Start a GUI instance.

BLUESPY_API void bluespy_start_gui ()

The GUI exists in a background thread, this function returns immediately

function bluespy_stop_audio¶

Stop the audio file in Audiopod File Playback.

BLUESPY_API bluespy_error bluespy_stop_audio ()

Returns:

error

function bluespy_stop_capture¶

Stop a capture.

BLUESPY_API bluespy_error bluespy_stop_capture ()

Returns:

Error code

function bluespy_wait_until_next_logic_change¶

Wait until any of the logic lines within the mask changes, and returns the result.

BLUESPY_API bluespy_logic_change bluespy_wait_until_next_logic_change (
    uint32_t mask,
    int64_t timeout,
    bluespy_time_point start_ts
)

Parameters:

mask - logic mask for which lines to look at
timeout - maximum time to wait in ns
start_ts - time to wait from. -1 = wait from present

Returns:

Struct containing the new logic state, the logic lines which changed, and the time the change occured. Timeout - returns {0,0,current_time}

Macro Definition Documentation¶

define BLUESPY_API¶

#define BLUESPY_API `__attribute__((visibility("default")))`

define BLUESPY_AUDIO_API_VERSION¶

Defines the API version for blueSPY Audio Codec Interface.

#define BLUESPY_AUDIO_API_VERSION `1`

Codec shared libraries must set bluespy_audio_codec_lib_info::api_version to this value when returning from their init() function. This allows the host to verify compatibility between itself and the loaded codec library.

API version history: * Version 1: Initial release (supports AVDTP/A2DP, CIS, and BIS containers)

define BLUESPY_DEPRECATED_API¶

#define BLUESPY_DEPRECATED_API `BLUESPY_API`

define BLUESPY_FILTER_FILE_ID_INVALID¶

#define BLUESPY_FILTER_FILE_ID_INVALID `(( bluespy_filter_file_id )(-1))`

define BLUESPY_HASATTR¶

#define BLUESPY_HASATTR (
    attr
) `(0)`

define BLUESPY_ID_INVALID¶

Invalid value, used to represent N/A.

#define BLUESPY_ID_INVALID `(( bluespy_id )(-1))`

define BLUESPY_TIME_INVALID¶

#define BLUESPY_TIME_INVALID `(INT64_MAX)`

The documentation for this class was generated from the following file bluespy.h