The PD mini. More...

#include "pdmini_int.h"
#include <string.h>

Functions
void	pdmini_init (pdmini_t d, const pdmini_io_t io, uint32_t now_ms)
	Set up a driver with nothing asked and nothing known.
static uint16_t	clamp16 (uint16_t v, uint16_t lo, uint16_t hi)
	Clamp a value into a range.
void	pdmini_want (pdmini_t *d, bool output, uint16_t set_mv, uint16_t set_ma)
	What the output is to be.
void	pdmini_restored (pdmini_t *d)
	Attached to a module whose state is not known – wiring restored after a restart, or newly given: it may be on. pdmini_may_be_on() says so until a state read shows it off, or until PDMINI_ABSENT_TRIES WHO_AM_I in a row go unanswered by a byte.
void	pdmini_reset (pdmini_t *d)
	Restart the module with SYSTEM_RESET: sent once it has answered, its output reads off and nothing else waits; it is then asked who it is again, PDMINI_IDENTIFY_MS on.
void	pdmini_want_off (pdmini_t *d)
	The output off, and no set points asked: the module's are left as they are until pdmini_want() names some.
void	pdmini_check_off (pdmini_t *d)
	A state read sent from now on, ahead of the other readings: the answer is in pdmini_checked().
pdmini_check_t	pdmini_checked (const pdmini_t *d)
	The answer to the last pdmini_check_off().
const pdmini_status_t *	pdmini_status (const pdmini_t *d)
	The driver's status, read back from the module.
bool	pdmini_may_be_on (const pdmini_t *d)
	Whether the output is on or may be: it reads on, an ON waits to be sent or confirmed or went out unsettled, an OFF is owed to a module that went quiet with it on, or a module that has answered is not read off now.
void	pdmini_start (pdmini_t d, uint32_t now, const uint8_t req, size_t n, bool write)
	Starts the transaction `req` of `n` bytes and its CRC8: attaches the pins and enters PD_ATTACH.
void	pdmini_read1 (pdmini_t *d, uint32_t now, uint8_t cmd)
	Starts the one-byte read `cmd`.
void	pdmini_finish (pdmini_t *d, uint32_t now, bool ok)
	Ends the transaction under way, `ok` when its reply was taken (a write: when its bytes left), and enters PD_GAP.
static bool	holds (const uint8_t p, size_t n, const char s)
	Whether `n` bytes at `p` hold `s`.
uint16_t	pdmini_cap_mv (uint32_t vin_mv)
	The highest voltage set point written for an input of vin_mv, as read.
uint16_t	pdmini_target_mv (const pdmini_t *d)
	The voltage set point the module is given for the one asked.
bool	pdmini_under_line (const pdmini_t *d)
	Whether the input last read lies under the set point read back and PDMINI_HEADROOM_MV.
void	pdmini_sag_hold (pdmini_t *d)
	The output switched off for the input, or its ON not written, and held off until an OFF is asked.
static void	sag_check (pdmini_t *d)
	An input reading, against a live output's set point: under it and the headroom on PDMINI_SAG_READS readings in a row, the output is switched off and held off until an OFF is asked.
static void	learn_on (pdmini_t *d)
	Learn the OUTPUT_EN argument that means on from a seen output.
static bool	take_reply (pdmini_t *d, uint32_t now)
	Act on a whole reply for the command under way.
void	pdmini_rx (pdmini_t *d, uint8_t byte, uint32_t now_ms)
	A byte from the module.

Detailed Description

The PD mini.

See pdmini.h.

SPDX-License-Identifier: MIT

Function Documentation

◆ clamp16()

uint16_t clamp16	(	uint16_t	v,
		uint16_t	lo,
		uint16_t	hi )

static

Clamp a value into a range.

Parameters

v	Value to clamp.
lo	Lowest value returned.
hi	Highest value returned.

Returns: v limited to [lo, hi].

◆ holds()

bool holds	(	const uint8_t *	p,
		size_t	n,
		const char *	s )

static

Whether n bytes at p hold s.

Parameters

p	Bytes to search.
n	Number of bytes in `p`.
s	Nul-terminated string to find.

Returns: true when s occurs in p.

◆ learn_on()

void learn_on ( pdmini_t * d )

static

Learn the OUTPUT_EN argument that means on from a seen output.

Parameters

d	Driver state.

◆ pdmini_cap_mv()

uint16_t pdmini_cap_mv ( uint32_t vin_mv )

The highest voltage set point written for an input of vin_mv, as read.

vin_mv - PDMINI_CAP_MV rounded down to 10mV, at least PDMINI_V_MIN_MV (an input under PDMINI_V_MIN_MV + PDMINI_CAP_MV, 1700mV, gets the 1000mV floor, and one under 1500mV is held off), at most PDMINI_V_MAX_MV. The caller treats an input not known as PDMINI_V_MAX_MV.

Parameters

vin_mv Input voltage as read, in mV.

Returns: The highest voltage set point for that input, in mV.

◆ pdmini_check_off()

void pdmini_check_off ( pdmini_t * d )

A state read sent from now on, ahead of the other readings: the answer is in pdmini_checked().

It waits for the transaction under way and for an OFF owed, so at most about two transactions, 1210ms.

Parameters

d	Driver state.

◆ pdmini_checked()

pdmini_check_t pdmini_checked ( const pdmini_t * d )

The answer to the last pdmini_check_off().

Parameters

d	Driver state.

Returns: The state of the check.

◆ pdmini_finish()

void pdmini_finish	(	pdmini_t *	d,
		uint32_t	now,
		bool	ok )

Ends the transaction under way, ok when its reply was taken (a write: when its bytes left), and enters PD_GAP.

Parameters

d	Driver state.
now	Current time, in milliseconds.
ok	true when its reply was taken (a write: when its bytes left).

◆ pdmini_init()

void pdmini_init	(	pdmini_t *	d,
		const pdmini_io_t *	io,
		uint32_t	now_ms )

Set up a driver with nothing asked and nothing known.

Parameters

d	Driver state to initialise.
io	Hardware callbacks; copied.
now_ms	Current time, in milliseconds.

◆ pdmini_may_be_on()

bool pdmini_may_be_on ( const pdmini_t * d )

Whether the output is on or may be: it reads on, an ON waits to be sent or confirmed or went out unsettled, an OFF is owed to a module that went quiet with it on, or a module that has answered is not read off now.

Its wiring is not to be taken from under it while this holds.

Parameters

d	Driver state.

Returns: true while the output is, or may be, on.

◆ pdmini_read1()

void pdmini_read1	(	pdmini_t *	d,
		uint32_t	now,
		uint8_t	cmd )

Starts the one-byte read cmd.

Parameters

d	Driver state.
now	Current time, in milliseconds.
cmd	Command byte to read.

◆ pdmini_reset()

void pdmini_reset ( pdmini_t * d )

Restart the module with SYSTEM_RESET: sent once it has answered, its output reads off and nothing else waits; it is then asked who it is again, PDMINI_IDENTIFY_MS on.

Parameters

d	Driver state.

◆ pdmini_restored()

void pdmini_restored ( pdmini_t * d )

Attached to a module whose state is not known – wiring restored after a restart, or newly given: it may be on. pdmini_may_be_on() says so until a state read shows it off, or until PDMINI_ABSENT_TRIES WHO_AM_I in a row go unanswered by a byte.

Parameters

d	Driver state.

◆ pdmini_rx()

void pdmini_rx	(	pdmini_t *	d,
		uint8_t	byte,
		uint32_t	now_ms )

A byte from the module.

Parameters

d	Driver state.
byte	Received byte.
now_ms	Current time, in milliseconds.

◆ pdmini_sag_hold()

void pdmini_sag_hold ( pdmini_t * d )

The output switched off for the input, or its ON not written, and held off until an OFF is asked.

Parameters

d	Driver state.

◆ pdmini_start()

void pdmini_start	(	pdmini_t *	d,
		uint32_t	now,
		const uint8_t *	req,
		size_t	n,
		bool	write )

Starts the transaction req of n bytes and its CRC8: attaches the pins and enters PD_ATTACH.

write is true for a write.

Parameters

d	Driver state.
now	Current time, in milliseconds.
req	Request bytes, without the CRC8.
n	Number of bytes in `req`.
write	true for a write, which has no reply.

◆ pdmini_status()

const pdmini_status_t * pdmini_status ( const pdmini_t * d )

The driver's status, read back from the module.

Parameters

d	Driver state.

Returns: Pointer to the status inside d.

◆ pdmini_target_mv()

uint16_t pdmini_target_mv ( const pdmini_t * d )

The voltage set point the module is given for the one asked.

Parameters

d	Driver state.

Returns: Voltage in mV.

◆ pdmini_under_line()

bool pdmini_under_line ( const pdmini_t * d )

Whether the input last read lies under the set point read back and PDMINI_HEADROOM_MV.

Parameters

d	Driver state.

Returns: true when the input is under the line.

◆ pdmini_want()

void pdmini_want	(	pdmini_t *	d,
		bool	output,
		uint16_t	set_mv,
		uint16_t	set_ma )

What the output is to be.

Set points are clamped to the module's range; switching off is the first thing done whatever else is waiting. An output switched off because its set points would not take stays off, whatever is asked, until an OFF is asked – and so does one the module switched off by itself while ON was asked (st.tripped), and one switched off for a sagging input (st.sagged).

Parameters

d	Driver state.
output	true to ask for the output on.
set_mv	Voltage set point, in mV.
set_ma	Current set point, in mA.

◆ pdmini_want_off()

void pdmini_want_off ( pdmini_t * d )

The output off, and no set points asked: the module's are left as they are until pdmini_want() names some.

Parameters

d	Driver state.

◆ sag_check()

void sag_check ( pdmini_t * d )

static

An input reading, against a live output's set point: under it and the headroom on PDMINI_SAG_READS readings in a row, the output is switched off and held off until an OFF is asked.

Only an output read on with ON asked and a set point read back; a reading at or over the line, or an output not live, starts the count again. A failed read is no reading and leaves the count as it is.

◆ take_reply()

bool take_reply	(	pdmini_t *	d,
		uint32_t	now )

static

Act on a whole reply for the command under way.

Parameters

d	Driver state; the reply is in `d->rx`.
now	Current time, in milliseconds.

Returns: true when the reply is taken; false when it cannot be the module's answer and the transaction fails.

Functions

Detailed Description

Function Documentation

◆ clamp16()

◆ holds()

◆ learn_on()

◆ pdmini_cap_mv()

◆ pdmini_check_off()

◆ pdmini_checked()

◆ pdmini_finish()

◆ pdmini_init()

◆ pdmini_may_be_on()

◆ pdmini_read1()

◆ pdmini_reset()

◆ pdmini_restored()

◆ pdmini_rx()

◆ pdmini_sag_hold()

◆ pdmini_start()

◆ pdmini_status()

◆ pdmini_target_mv()

◆ pdmini_under_line()

◆ pdmini_want()

◆ pdmini_want_off()

◆ sag_check()

◆ take_reply()