Analog I/O

analogRead(), analogWrite() (PWM) and their settings, plus averaging, millivolts, differential, several pins at once and fixed-rate bursts on every analog pin. More...

Functions
void	analogReadResolution (int bits)
	Sets the number of bits analogRead() returns, for every analog pin.
void	analogWriteResolution (int bits)
	Sets the range analogWrite() takes, for every pin.
void	analogWriteFrequency (uint32_t hz)
	Sets the PWM frequency used by later analogWrite() calls.
void	analogReadAveraging (uint8_t samples)
	Sets how many samples are averaged for each analog result, on every analog pin.
uint32_t	analogFullScaleMillivolts (pin_size_t pin)
	Voltage that reads as full scale on an analog pin.
uint32_t	analogReadMillivolts (pin_size_t pin)
	Reads an analog pin as a voltage, whatever its ADC and full scale.
int32_t	analogReadDifferentialMillivolts (pin_size_t plus, pin_size_t minus)
	Voltage between two analog pins, plus minus minus.
bool	analogReadMultiple (const pin_size_t *pins, uint8_t count, uint16_t *results)
	Reads several analog pins as close together in time as possible.
uint32_t	analogReadBurst (pin_size_t pin, uint16_t *buffer, size_t count, uint32_t sample_rate_hz)
	Samples one analog pin at a fixed rate into an array, and waits until it is full.
uint32_t	analogStartBurst (pin_size_t pin, uint16_t *buffer, size_t count, uint32_t sample_rate_hz)
	Starts a burst like analogReadBurst(), but returns at once; the samples are taken in the background.
bool	analogBurstDone ()
	Whether the burst started by analogStartBurst() has finished.
void	analogStopBurst ()
	Stops the burst started by analogStartBurst() before it has finished.
int	analogRead (pin_size_t pinNumber)
	Reads the voltage on an analog pin.
void	analogReference (uint8_t mode)
	Does nothing: the references are fixed on Phyduino boards.
void	analogWrite (pin_size_t pinNumber, int value)
	Outputs a PWM signal: a square wave whose duty cycle sets the average voltage.

Detailed Description

analogRead(), analogWrite() (PWM) and their settings, plus averaging, millivolts, differential, several pins at once and fixed-rate bursts on every analog pin.

A0-A2 use the RP2040 ADC (0-3.3 V); A3-A5 use the on-board MAX11635 ADC (0-2.048 V). Every function here works on all six, so a sketch does not need to know which ADC a pin uses. analogWrite() is PWM and works on every pin except A3-A5. Examples: File → Examples → Phyduino.

Function Documentation

analogBurstDone()

bool analogBurstDone

(

)

Whether the burst started by analogStartBurst() has finished.

Returns

true once every sample is in the buffer (and when no burst was started).

Examples

AnalogBurstBackground.ino.

analogFullScaleMillivolts()

uint32_t analogFullScaleMillivolts

(

pin_size_t

pin

)

Voltage that reads as full scale on an analog pin.

Parameters

pin	Analog pin (A0-A5).

Returns

Full scale in mV: 3300 for A0-A2 and 2048 for A3-A5 on the Phyduino Pico. 0 for a pin that is not analog.

Examples

AnalogBurstBackground.ino, AnalogMillivolts.ino, and AnalogReadMultiple.ino.

analogRead()

int analogRead

(

pin_size_t

pinNumber

)

Reads the voltage on an analog pin.

Pin	ADC	Full scale
A0-A2	RP2040 ADC	3.3 V
A3-A5	On-board MAX11635 (max11635::read())	2.048 V

Both are 12-bit ADCs. The result is scaled to analogReadResolution(), 10 bits (0-1023) by default as on an Uno.

Parameters

pinNumber

A0-A5.

Returns

0 to 2^bits - 1, where bits is the analogReadResolution() setting. 0 for a pin that is not analog.

Note

Use the names A0-A5. analogRead(0) reads D0, which is not an analog pin, and returns 0; on an Uno it would read A0.

Full scale differs between A0-A2 and A3-A5, so the same reading means a different voltage. At 10 bits: volts = reading * 3.3 / 1023 on A0-A2, and reading * 2.048 / 1023 on A3-A5.

Examples

AnalogAveraging.ino.

analogReadAveraging()

void analogReadAveraging

(

uint8_t

samples

)

Sets how many samples are averaged for each analog result, on every analog pin.

Applies to analogRead(), analogReadMillivolts(), analogReadMultiple() and analogReadDifferentialMillivolts(); not to bursts. The external ADC (A3-A5 on the Phyduino Pico) averages in hardware; the RP2040 ADC (A0-A2) takes the samples one after another (about 2 µs each) and averages them.

Parameters

samples

1 (the default, no averaging), 4, 8, 16 or 32. Other values use the next lower one (e.g. 10 gives 8).

Examples

AnalogAveraging.ino, and AnalogDifferential.ino.

analogReadBurst()

uint32_t analogReadBurst	(	pin_size_t	pin,
		uint16_t *	buffer,
		size_t	count,
		uint32_t	sample_rate_hz )

Samples one analog pin at a fixed rate into an array, and waits until it is full.

The samples are taken by the hardware at evenly spaced times; the sketch only waits. Averaging is not applied. Rates:

Pins (Phyduino Pico)	Highest rate	How
A0-A2 (RP2040 ADC)	500000 Hz	ADC timer and DMA; rates below 733 Hz use a timer interrupt
A3-A5 (MAX11635)	300000 Hz	Timer interrupt up to 20000 Hz; above that, the ADC clocked by SPI with DMA

The rate actually used can differ slightly from the one asked for (the hardware divides a fixed clock); it is returned.

Parameters

pin	Analog pin (A0-A5).
buffer	Array for the samples, in analogRead() units.
count	Number of samples.
sample_rate_hz	Samples per second, 1 up to the highest rate above.

Returns

Rate used in Hz, or 0 if the arguments are invalid or a burst is already running.

Examples

AnalogBurst.ino.

analogReadDifferentialMillivolts()

int32_t analogReadDifferentialMillivolts	(	pin_size_t	plus,
		pin_size_t	minus )

Voltage between two analog pins, plus minus minus.

On the Phyduino Pico, A3 with A4 (either way round) is a true differential measurement: the external ADC samples both pins at the same instant, so noise common to both cancels. It covers ±1024 mV in 0.5 mV steps; a larger difference is measured as two separate readings instead.

Any other pair is computed from two readings taken one after the other (a few µs apart), so it is not simultaneous: fine for slow signals, not for removing fast common noise.

Parameters

plus	Analog pin (A0-A5).
minus	Analog pin (A0-A5).

Returns

plus - minus in mV, negative if minus is higher. 0 if either pin is not analog.

Examples

AnalogDifferential.ino.

analogReadMillivolts()

uint32_t analogReadMillivolts

(

pin_size_t

pin

)

Reads an analog pin as a voltage, whatever its ADC and full scale.

Uses the full 12 bits, whatever analogReadResolution() is set to, and the analogReadAveraging() setting.

Parameters

pin	Analog pin (A0-A5).

Returns

Voltage in mV; 0 for a pin that is not analog.

Examples

AnalogMillivolts.ino, CmsisRtos2Threads.ino, and FreeRtosQueue.ino.

analogReadMultiple()

bool analogReadMultiple	(	const pin_size_t *	pins,
		uint8_t	count,
		uint16_t *	results )

Reads several analog pins as close together in time as possible.

Pins on the external ADC are converted in one scan, a few µs apart; pins on the RP2040 ADC follow each other about 2 µs apart. The two ADCs are read one after the other, not at the same time.

Parameters

pins	Analog pins, in any order; a pin may appear more than once.
count	Number of pins.
results	Array of count values, in the same order as pins, in analogRead() units (see analogReadResolution()).

Returns

false if a pin is not analog (its result is 0).

Examples

AnalogReadMultiple.ino.

analogReadResolution()

void analogReadResolution

(

int

bits

)

Sets the number of bits analogRead() returns, for every analog pin.

Parameters

bits	1-12; the default is 10 (0-1023). Other values are ignored.

Examples

AnalogAveraging.ino, AnalogBurst.ino, AnalogBurstBackground.ino, and AnalogReadMultiple.ino.

analogReference()

void analogReference

(

uint8_t

mode

)

Does nothing: the references are fixed on Phyduino boards.

A0-A2 use the 3.3 V supply; A3-A5 use the 2.048 V LM4040 reference (U7) on the AREF pin.

Parameters

mode

Ignored.

analogStartBurst()

uint32_t analogStartBurst	(	pin_size_t	pin,
		uint16_t *	buffer,
		size_t	count,
		uint32_t	sample_rate_hz )

Starts a burst like analogReadBurst(), but returns at once; the samples are taken in the background.

Check analogBurstDone() before using buffer. Only one burst runs at a time. While it runs, other reads of an analog pin on the same ADC wait until it has finished.

Parameters

pin	Analog pin (A0-A5).
buffer	Array for the samples; must stay valid until the burst is done.
count	Number of samples.
sample_rate_hz	Samples per second (see analogReadBurst()).

Returns

Rate used in Hz, or 0 if the arguments are invalid or a burst is already running.

Examples

AnalogBurstBackground.ino.

analogStopBurst()

void analogStopBurst

(

)

Stops the burst started by analogStartBurst() before it has finished.

Sampling stops at once and the ADC is free again for analogRead() and the other analog functions. The buffer's contents are then not valid: some samples may be missing and the rest are not converted to analogReadResolution(). Afterwards analogBurstDone() returns true and a new burst can be started. Does nothing if no burst is running.

analogWrite()

void analogWrite	(	pin_size_t	pinNumber,
		int	value )

Outputs a PWM signal: a square wave whose duty cycle sets the average voltage.

Unlike an Uno, every pin except A3-A5 can do PWM. The defaults match an Uno: 8 bits (0-255) at 1000 Hz; see analogWriteResolution() and analogWriteFrequency(). Call it again to change the duty cycle; pinMode() stops it.

The RP2040 has 8 PWM "slices". The pins on a slice share one frequency, set by the last analogWrite() or tone() on any of them. Pins on the same channel also share the duty cycle: both output what was last written to either.

Slice	Channel A	Channel B
0	D1, D8	D0, D9
2		LED_BUILTIN
3	D2	D3
4	D4, SDA	D5, SCL
5	D6, A0	D11, A1
6	D12, A2	D10
7	D13	D7

Parameters

pinNumber	Arduino pin. A3-A5 and numbers out of range are ignored.
value	0 (always LOW) to 2^bits - 1 (always HIGH), where bits is the analogWriteResolution() setting. Values outside the range are clamped.

analogWriteFrequency()

void analogWriteFrequency

(

uint32_t

hz

)

Sets the PWM frequency used by later analogWrite() calls.

Pins on the same PWM slice share one frequency, set by the last analogWrite() or tone() on any of them (table under analogWrite()).

Parameters

hz	Frequency in Hz; the default is 1000. 0 is ignored. The lowest is about 8 Hz at the default 133 MHz CPU speed (lower values run at that).

analogWriteResolution()

void analogWriteResolution

(

int

bits

)

Sets the range analogWrite() takes, for every pin.

Parameters

bits	1-16; the default is 8 (0-255). Other values are ignored.