ADC

Analog-to-Digital Converter (ADC) interface for hardware platforms. More...

Collaboration diagram for ADC:

Typedefs
typedef struct hw_adc_t	hw_adc_t
	Opaque ADC handle.
typedef bool(*	hw_adc_dma_callback_t) (hw_adc_t *adc, uint16_t *buf, size_t count, void *userdata)
	DMA read completion callback. More...

Lifecycle
hw_adc_t *	hw_adc_init_pin (hw_gpio_t *gpio)
	Initialize an ADC handle for a specific GPIO pin. More...
hw_adc_t *	hw_adc_init_temperature (void)
	Initialize an ADC handle for the internal temperature sensor channel. More...
void	hw_adc_deinit (hw_adc_t *adc)
	Finalize and release an ADC handle. More...
uint8_t	hw_adc_count (void)
	Get the total number of available ADC channels. More...
uint8_t	hw_adc_gpio_channel (uint8_t pin)
	Get the ADC channel number for a GPIO pin on bank 0. More...
uint8_t	hw_adc_gpio_pin (uint8_t channel)
	Get the GPIO pin number for an ADC channel. More...

Methods
uint16_t	hw_adc_read_12 (hw_adc_t *adc, uint16_t num_samples)
	Read the current value from an ADC channel as a 12-bit value. More...
uint16_t	hw_adc_read_16 (hw_adc_t *adc, uint16_t num_samples)
	Read the current value from an ADC channel as a 16-bit value. More...
float	hw_adc_read_voltage (hw_adc_t *adc, uint16_t num_samples)
	Read the current value from an ADC channel as a voltage. More...
float	hw_adc_read_temperature (hw_adc_t *adc, uint16_t num_samples)
	Read the current value from an ADC channel as a temperature. More...
bool	hw_adc_read_dma (hw_adc_t *adc, uint16_t *buf, size_t count, size_t partitions, hw_adc_dma_callback_t callback, void *userdata)
	Start an asynchronous, DMA-driven read of raw samples. More...

Detailed Description

Analog-to-Digital Converter (ADC) interface for hardware platforms.

This module provides functions to initialize and read from ADC peripherals.

Typedef Documentation

hw_adc_dma_callback_t

typedef bool(* hw_adc_dma_callback_t) (hw_adc_t *adc, uint16_t *buf, size_t count, void *userdata)

DMA read completion callback.

Parameters

adc	ADC handle the transfer was started on.
buf	Pointer to the partition of hw_adc_read_dma()'s buffer that was just filled with raw samples - not necessarily the start of the buffer passed to hw_adc_read_dma(), see partitions there.
count	Number of samples written to buf.
userdata	User-defined data pointer passed to hw_adc_read_dma().

Return values

true	Continue: start capturing into the next partition.
false	Stop; no further partitions are captured.

Called synchronously from the DMA-complete interrupt on systems with a real DMA controller (e.g. Pico) - the system does not start capturing the next partition until this returns, so it must return immediately. Don't process buf here: instead hand it off asynchronously (e.g. by posting an event naming this partition) to be read out elsewhere, then return. The system cycles through partitions round-robin, so once handed off, that consumer has until the other partitions - 1 have each been filled once more before this memory is overwritten again.

Definition at line 48 of file adc.h.

Function Documentation

hw_adc_count()

uint8_t hw_adc_count

(

void

)

Get the total number of available ADC channels.

Returns

Number of ADC channels available on the current platform.

The returned count includes both GPIO-mappable ADC channels and any internal ADC channels exposed by the system. For example, on Pico platforms this includes the internal temperature sensor channel.

hw_adc_deinit()

void hw_adc_deinit

(

hw_adc_t *

adc

)

Finalize and release an ADC handle.

Parameters

adc	ADC handle.

hw_adc_gpio_channel()

uint8_t hw_adc_gpio_channel

(

uint8_t

pin

)

Get the ADC channel number for a GPIO pin on bank 0.

Parameters

pin	GPIO pin number.

Returns

Channel number, or 0xFF if the pin is not ADC-capable.

hw_adc_gpio_pin()

uint8_t hw_adc_gpio_pin

(

uint8_t

channel

)

Get the GPIO pin number for an ADC channel.

Parameters

channel

ADC channel number.

Returns

GPIO pin number, or 0xFF if the channel has no GPIO mapping.

Channels that are valid ADC inputs but are not backed by a GPIO pin, such as internal temperature-sensor channels, return 0xFF here.

hw_adc_init_pin()

hw_adc_t* hw_adc_init_pin

(

hw_gpio_t *

gpio

)

Initialize an ADC handle for a specific GPIO pin.

Parameters

gpio	GPIO handle configured for ADC-capable pin access.

Returns

ADC handle or NULL on failure.

hw_adc_init_temperature()

hw_adc_t* hw_adc_init_temperature

(

void

)

Initialize an ADC handle for the internal temperature sensor channel.

Returns

ADC handle or NULL on failure.

The internal temperature sensor channel is not associated with a GPIO pin.

hw_adc_read_12()

uint16_t hw_adc_read_12	(	hw_adc_t *	adc,
		uint16_t	num_samples
	)

Read the current value from an ADC channel as a 12-bit value.

Parameters

adc	ADC handle.
num_samples	Number of conversions to average. 0 or 1 takes a single, immediate reading; higher values sample the ADC FIFO that many times and return the mean, which reduces noise at the cost of latency. Systems may clamp this to an implementation-defined maximum to bound how long the call can block.

Returns

Raw value in the 0-4095 range.

hw_adc_read_16()

uint16_t hw_adc_read_16	(	hw_adc_t *	adc,
		uint16_t	num_samples
	)

Read the current value from an ADC channel as a 16-bit value.

Parameters

adc	ADC handle.
num_samples	Number of conversions to average. See hw_adc_read_12().

Returns

Raw value in the 0-65535 range.

hw_adc_read_dma()

bool hw_adc_read_dma	(	hw_adc_t *	adc,
		uint16_t *	buf,
		size_t	count,
		size_t	partitions,
		hw_adc_dma_callback_t	callback,
		void *	userdata
	)

Start an asynchronous, DMA-driven read of raw samples.

Parameters

adc	ADC handle.
buf	Buffer to fill with raw samples, sized for count * partitions samples. Must remain valid for as long as callback keeps returning true.
count	Number of samples per partition.
partitions	Number of equal-sized partitions to split buf into, filled round-robin. callback (see hw_adc_dma_callback_t) must return immediately - it should hand a completed partition off asynchronously rather than process it inline - so partitions of 2 or more gives whatever actually reads out the data time to do so before that memory is reused, which matters given the ADC's own FIFO is only a handful of samples deep and drops conversions once full.
callback	Called each time a partition finishes filling; its return value decides whether capturing continues. See hw_adc_dma_callback_t.
userdata	User-defined data pointer passed to callback.

Return values

true	The transfer was started; callback will be invoked after each partition, until it returns false.
false	DMA-driven reads aren't set up/supported on this platform, partitions is less than 2, or another transfer is already in progress on this handle - callback is not invoked.

Not available on every system: DMA-driven ADC reads require a real DMA controller wired to the ADC's FIFO (e.g. Pico), so host systems with no ADC hardware at all always return false here.

hw_adc_read_temperature()

float hw_adc_read_temperature	(	hw_adc_t *	adc,
		uint16_t	num_samples
	)

Read the current value from an ADC channel as a temperature.

Parameters

adc	ADC handle configured for temperature sensing.
num_samples	Number of conversions to average. See hw_adc_read_12().

Returns

Temperature value in degrees Celsius.

hw_adc_read_voltage()

float hw_adc_read_voltage	(	hw_adc_t *	adc,
		uint16_t	num_samples
	)

Read the current value from an ADC channel as a voltage.

Parameters

adc	ADC handle.
num_samples	Number of conversions to average. See hw_adc_read_12().

Returns

Voltage value in volts.