API Reference

The public API is generated from the headers in include/.

Device API

Public API for the ADS1299 ESP-IDF driver.

The driver controls a Texas Instruments ADS1299 analog front-end over SPI. Applications own SPI bus initialization. The driver owns the ADS1299 SPI device handle, GPIO setup, and continuous acquisition resources.

Typedefs

typedef void (*ads1299_chunk_cb_t)(const ads1299_chunk_t *chunk, void *ctx)

Called when a full continuous-acquisition chunk is ready.

The callback runs from the driver’s handler task, not from ISR context. Keep callback work short and hand samples to an application task if processing is expensive.

Param chunk:

[in] Completed chunk of parsed samples.

Param ctx:

[in] User context pointer from ads1299_continuous_config_t.

typedef void (*ads1299_error_cb_t)(esp_err_t err, void *ctx)

Called when the continuous-acquisition task sees a recoverable error.

Param err:

[in] ESP-IDF error code.

Param ctx:

[in] User context pointer from ads1299_continuous_config_t.

typedef struct ads1299_dma_ctx ads1299_dma_ctx_t

Opaque continuous-mode context.

Functions

ads1299_t ads1299_create(const ads1299_config_t *cfg)

Create an ADS1299 device handle from static configuration.

Parameters:

cfg – [in] Pointer to the device configuration.

Returns:

Initialized handle value. If cfg is NULL, the returned handle is zero-initialized and not ready for ads1299_init().

esp_err_t ads1299_init(ads1299_t *dev)

Initialize the ADS1299 device.

This configures GPIOs, adds the ADS1299 SPI device, creates the driver mutex, and runs the power-up sequence. The SPI bus must already be initialized by the application.

Parameters:

dev – [inout] Device handle created by ads1299_create().

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_deinit(ads1299_t *dev)

Deinitialize the ADS1299 device and free driver-owned resources.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_write_register(ads1299_t *dev, uint8_t reg, uint8_t value)

Write one ADS1299 register.

Parameters:

• dev – [inout] Device handle.

• reg – [in] Register address.

• value – [in] Register value to write.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_read_register(ads1299_t *dev, uint8_t reg, uint8_t *value)

Read one ADS1299 register.

Parameters:

• dev – [inout] Device handle.

• reg – [in] Register address.

• value – [out] Destination for the register value.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_write_registers(ads1299_t *dev, uint8_t start_reg, const uint8_t *data, size_t count)

Write a contiguous ADS1299 register range.

Parameters:

• dev – [inout] Device handle.

• start_reg – [in] First register address.

• data – [in] Values to write.

• count – [in] Number of register values in data.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_read_registers(ads1299_t *dev, uint8_t start_reg, uint8_t *data, size_t count)

Read a contiguous ADS1299 register range.

Parameters:

• dev – [inout] Device handle.

• start_reg – [in] First register address.

• data – [out] Destination buffer.

• count – [in] Number of register values to read.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_send_command(ads1299_t *dev, uint8_t command)

Send a raw ADS1299 SPI command byte.

Prefer named helper functions for common device-control commands.

Parameters:

• dev – [inout] Device handle.

• command – [in] ADS1299 command opcode.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_read_data(ads1299_t *dev, uint8_t *buffer)

Read one raw 27-byte ADS1299 frame.

Parameters:

• dev – [inout] Device handle.

• buffer – [out] Destination buffer of at least ADS1299_FRAME_SIZE bytes.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_read_sample(ads1299_t *dev, ads1299_sample_t *sample)

Read and parse one ADS1299 sample.

DRDY must already be low before this function is called.

Parameters:

• dev – [inout] Device handle.

• sample – [out] Parsed sample destination.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_start(ads1299_t *dev)

Assert the START pin.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_stop(ads1299_t *dev)

Deassert the START pin.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_reset_hardware(ads1299_t *dev)

Pulse the ADS1299 hardware RESET pin.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_reset_software(ads1299_t *dev)

Send the ADS1299 RESET command.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_standby(ads1299_t *dev)

Send the ADS1299 STANDBY command.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_wakeup(ads1299_t *dev)

Send the ADS1299 WAKEUP command.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_enable_continuous_read(ads1299_t *dev)

Enter ADS1299 continuous read mode.

This sends RDATAC and is required before ads1299_start_continuous().

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_disable_continuous_read(ads1299_t *dev)

Exit ADS1299 continuous read mode.

This sends SDATAC and is required before register writes.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_start_continuous(ads1299_t *dev, const ads1299_continuous_config_t *cfg)

Begin DMA-driven continuous acquisition.

The driver allocates DMA buffers and chunk storage, installs the DRDY ISR, starts a handler task, and calls on_chunk as chunks complete.

Parameters:

• dev – [inout] Device handle.

• cfg – [in] Continuous-acquisition configuration.

Returns:

ESP_OK on success, or an ESP-IDF error code.

esp_err_t ads1299_stop_continuous(ads1299_t *dev)

Stop continuous acquisition and free acquisition resources.

Parameters:

dev – [inout] Device handle.

Returns:

ESP_OK on success, or an ESP-IDF error code.

bool ads1299_is_running(const ads1299_t *dev)

Check whether continuous acquisition is active.

Parameters:

dev – [in] Device handle.

Returns:

true if continuous acquisition is active, false otherwise.

RingbufHandle_t ads1299_get_ring_buffer(const ads1299_t *dev)

Get the driver-owned FreeRTOS ring buffer handle.

The returned handle is owned by the driver. Applications must not delete it.

Parameters:

dev – [in] Device handle.

Returns:

Ring buffer handle, or NULL when continuous mode is inactive.

void ads1299_parse_frame(const uint8_t *raw, int64_t timestamp, ads1299_sample_t *out)

Parse a raw ADS1299 frame.

Parameters:

• raw – [in] Raw ADS1299 frame of ADS1299_FRAME_SIZE bytes.

• timestamp – [in] Timestamp to store in the parsed sample.

• out – [out] Parsed sample destination.

esp_err_t ads1299_set_channel_gain(ads1299_t *dev, uint8_t channel, ads1299_pga_gain_t gain)

Set the Programmable Gain Amplifier (PGA) gain for a specific ADS1299 channel.

This function performs a read-modify-write to the corresponding CHnSET register. It modifies only bits [6:4] and leaves the power-down and MUX settings intact.

Note

The ADS1299 must be in SDATAC (Stop Read Data Continuous) mode before calling this function.

Parameters:

• dev – [inout] Device handle.

• channel – [in] Channel number (1 to ADS1299_NUM_CHANNELS).

• gain – [in] Desired PGA gain setting (e.g., ADS1299_PGA_GAIN_24).

Returns:

ESP_OK on success, ESP_ERR_INVALID_ARG for bad channel index, or SPI transaction error codes.

esp_err_t ads1299_set_all_channels_gain(ads1299_t *dev, ads1299_pga_gain_t gain)

Set the Programmable Gain Amplifier (PGA) gain for all ADS1299 channels.

Useful for establishing a uniform baseline configuration during initialization.

Parameters:

• dev – [inout] Device handle.

• gain – [in] Desired PGA gain setting for all channels.

Returns:

ESP_OK on success, or the first SPI transaction error encountered.

uint32_t ads1299_sample_rate_to_hz(ads1299_sample_rate_t rate)

Convert an ADS1299 sample-rate enum to hertz.

Parameters:

rate – [in] ADS1299 sample-rate enum value.

Returns:

Sample rate in hertz, or 0 for an invalid value.

struct ads1299_sample_t

#include <ads1299.h>

One fully parsed sample from the ADS1299.

Channel values are sign-extended 24-bit ADC values in LSB units.

Public Members

uint8_t status[ADS1299_STATUS_BYTES]

Status bytes from the ADS1299 frame.

int32_t channels[ADS1299_NUM_CHANNELS]

Sign-extended channel samples.

int64_t timestamp_us

Timestamp captured at DRDY falling edge.

struct ads1299_chunk_t

#include <ads1299.h>

A chunk of parsed ADS1299 samples delivered by the driver.

The samples pointer references driver-managed storage and is valid only for the duration of the chunk callback. Copy samples that must outlive the callback.

Public Members

const ads1299_sample_t *samples

Pointer to the first sample in the chunk.

size_t n_samples

Number of samples in the chunk.

int64_t first_timestamp_us

Timestamp of the first sample.

int64_t last_timestamp_us

Timestamp of the last sample.

int64_t dropped_count

Total number of samples dropped by the driver.

int64_t overflow_count

Total number of ring or DMA overflows.

struct ads1299_config_t

#include <ads1299.h>

Static device configuration.

The application must initialize the SPI bus for spi_host before calling ads1299_init(). The driver calls spi_bus_add_device() and spi_bus_remove_device() internally.

Public Members

spi_host_device_t spi_host

SPI host, usually SPI2_HOST or SPI3_HOST.

gpio_num_t cs_pin

Chip select pin, active low.

gpio_num_t drdy_pin

Data-ready pin, active low falling edge.

gpio_num_t reset_pin

Hardware reset pin, active low.

gpio_num_t start_pin

Conversion start pin.

ads1299_sample_rate_t sample_rate

Initial ADS1299 output data rate.

struct ads1299_continuous_config_t

#include <ads1299.h>

Continuous-acquisition configuration.

Buffer sizing is derived from sample_rate and chunk_duration_ms. The caller does not manage DMA or chunk storage directly.

Public Members

ads1299_chunk_cb_t on_chunk

Required callback for completed chunks.

ads1299_error_cb_t on_error

Optional callback for recoverable errors.

void *ctx

User context passed to callbacks.

uint32_t chunk_duration_ms

Chunk length in milliseconds.

uint32_t ring_buffer_chunks

Chunk slots; 0 selects ADS1299_RING_BUF_SLOTS.

UBaseType_t task_priority

FreeRTOS priority for the handler task.

BaseType_t task_core

FreeRTOS core affinity for the handler task.

struct ads1299_chunkring_t

#include <ads1299.h>

Internal single-producer single-consumer chunk ring.

This type is exposed only because the public handle is stack-allocatable. Applications should not access it directly.

Public Members

ads1299_sample_t *buf

Flat array of capacity * chunk_samples entries.

uint32_t capacity

Total slot count; power of two and at least 2.

uint32_t chunk_samples

Samples per chunk slot.

uint32_t mask

capacity - 1, used for modulo indexing.

volatile uint32_t head

Next write slot index.

volatile uint32_t tail

Next read slot index.

struct ads1299_t

#include <ads1299.h>

ADS1299 device handle.

Initialize with ads1299_create(), then ads1299_init(). Fields are public only to allow stack allocation; applications should use the API functions for all operations.

Public Members

ads1299_config_t config

Static device configuration.

spi_device_handle_t spi_handle

ESP-IDF SPI device handle.

SemaphoreHandle_t mutex

Driver mutex.

bool initialized

True after successful initialization.

ads1299_dma_ctx_t *dma_ctx

Non-NULL while continuous acquisition is active.

Definitions

Public constants and enums for the ADS1299 ESP-IDF driver.

Defines

ADS1299_CLK_FREQ

ADS1299 internal clock frequency in hertz.

ADS1299_TICKS_TO_US(ticks)

Convert ADS1299 clock ticks to microseconds, rounded up.

ADS1299_T_CLK_US

One ADS1299 clock period in microseconds.

ADS1299_T_RESET

Hardware reset pulse timing in microseconds.

ADS1299_T_PULSE

START or RESET pulse timing in microseconds.

ADS1299_T_SDATAC

SDATAC command timing in microseconds.

ADS1299_T_RDATAC

RDATAC command timing in microseconds.

ADS1299_T_WAKEUP

WAKEUP command timing in microseconds.

ADS1299_T_CSSC

Chip-select setup timing in microseconds.

ADS1299_T_SCLK

SCLK timing in microseconds.

ADS1299_T_CSH

Chip-select hold timing in microseconds.

ADS1299_T_SCCS

SCLK-to-chip-select timing in microseconds.

ADS1299_T_SDECODE

Command decode timing in microseconds.

ADS1299_NUM_CHANNELS

Number of ADS1299 channels.

ADS1299_STATUS_BYTES

Number of status bytes at the start of each ADS1299 frame.

ADS1299_BYTES_PER_CHANNEL

Number of bytes per ADS1299 channel sample.

ADS1299_FRAME_SIZE

Total ADS1299 frame size in bytes.

ADS1299_DEFAULT_CHUNK_MS

Default DMA chunk duration in milliseconds.

At 250 SPS this yields 25 samples per chunk. Override with ads1299_continuous_config_t::chunk_duration_ms.

ADS1299_RING_BUF_SLOTS

Default number of chunk slots allocated for continuous acquisition.

ADS1299_CMD_WAKEUP

ADS1299 WAKEUP command opcode.

ADS1299_CMD_STANDBY

ADS1299 STANDBY command opcode.

ADS1299_CMD_RESET

ADS1299 RESET command opcode.

ADS1299_CMD_START

ADS1299 START command opcode.

ADS1299_CMD_STOP

ADS1299 STOP command opcode.

ADS1299_CMD_RDATAC

ADS1299 RDATAC command opcode.

ADS1299_CMD_SDATAC

ADS1299 SDATAC command opcode.

ADS1299_CMD_RDATA

ADS1299 RDATA command opcode.

ADS1299_CMD_RREG

ADS1299 RREG command base opcode; OR with the register address.

ADS1299_CMD_WREG

ADS1299 WREG command base opcode; OR with the register address.

ADS1299_REG_ID

ADS1299 ID register address.

ADS1299_REG_CONFIG1

ADS1299 CONFIG1 register address.

ADS1299_REG_CONFIG2

ADS1299 CONFIG2 register address.

ADS1299_REG_CONFIG3

ADS1299 CONFIG3 register address.

ADS1299_REG_LOFF

ADS1299 lead-off control register address.

ADS1299_REG_CH1SET

ADS1299 channel 1 settings register address.

ADS1299_REG_CH2SET

ADS1299 channel 2 settings register address.

ADS1299_REG_CH3SET

ADS1299 channel 3 settings register address.

ADS1299_REG_CH4SET

ADS1299 channel 4 settings register address.

ADS1299_REG_CH5SET

ADS1299 channel 5 settings register address.

ADS1299_REG_CH6SET

ADS1299 channel 6 settings register address.

ADS1299_REG_CH7SET

ADS1299 channel 7 settings register address.

ADS1299_REG_CH8SET

ADS1299 channel 8 settings register address.

ADS1299_REG_BIAS_SENSP

ADS1299 positive BIAS sense register address.

ADS1299_REG_BIAS_SENSN

ADS1299 negative BIAS sense register address.

ADS1299_REG_MISC1

ADS1299 SRB1 config register address.

ADS1299_MISC1_SRB1_ON

ADS1299_MISC1_SRB1_OFF

ADS1299_CONFIG3_BIAS_ON

ADS1299_CONFIG3_BIAS_OFF

Enums

enum ads1299_sample_rate_t

ADS1299 output data rates.

Values match CONFIG1 register bits [2:0].

Values:

enumerator ADS1299_DR_16kSPS

16000 samples per second.

enumerator ADS1299_DR_8kSPS

8000 samples per second.

enumerator ADS1299_DR_4kSPS

4000 samples per second.

enumerator ADS1299_DR_2kSPS

2000 samples per second.

enumerator ADS1299_DR_1kSPS

1000 samples per second.

enumerator ADS1299_DR_500SPS

500 samples per second.

enumerator ADS1299_DR_250SPS

250 samples per second.

enum ads1299_pga_gain_t

ADS1299 programmable gain amplifier settings.

Values match CHnSET register bits [6:4].

Values:

enumerator ADS1299_PGA_GAIN_1

Gain of 1.

enumerator ADS1299_PGA_GAIN_2

Gain of 2.

enumerator ADS1299_PGA_GAIN_4

Gain of 4.

enumerator ADS1299_PGA_GAIN_6

Gain of 6.

enumerator ADS1299_PGA_GAIN_8

Gain of 8.

enumerator ADS1299_PGA_GAIN_12

Gain of 12.

enumerator ADS1299_PGA_GAIN_24

Gain of 24.

enum ads1299_input_mux_t

ADS1299 channel input mux settings.

Values match CHnSET register bits [2:0].

Values:

enumerator ADS1299_INPUT_NORMAL

Normal electrode input.

enumerator ADS1299_INPUT_SHORTED

Shorted input for noise measurements.

enumerator ADS1299_INPUT_BIAS_MEAS

BIAS drive measurement input.

enumerator ADS1299_INPUT_MVDD

Supply voltage measurement input.

enumerator ADS1299_INPUT_TEMP

Internal temperature sensor input.

enumerator ADS1299_INPUT_TEST_SIGNAL

Internal test signal input.