The panel's half of the SUPPLY link page (0x2A, protocol 4.3 to 4.13): what is written to it, in what order, and what a read of it means for the supply the screen shows. More...

#include <stdbool.h>
#include <stdint.h>
#include "link_pages.h"
#include "supply.h"

Data Structures
struct	supply_wiring_t
	Where the PD mini is wired, as SETUP INTERFACES has it. More...
struct	supply_link_t
	The panel's state of the SUPPLY link page. More...
struct	supply_link_follow_t
	Where the PD mini's wiring stood when last followed: the edit count and the wiring word the settings publish. More...

Macros
#define	SUPPLY_CAPS_PDMINI { 1.0f, 20.0f, 0.01f, 0.05f, 3.0f, 0.01f }
	The PD mini's own range, as the screen's caps: 1 to 20V and 0.05 to 3A from the vendor's page, in 10mV and 10mA steps.
#define	SUPPLY_LINK_STALE_MS 1500u
	A reading older than this is not the supply answering: longer than one exchange's 1000ms timeout, so one lost frame is not a supply gone, and about the 3 failed transactions the IOmcu's driver takes.
#define	SUPPLY_LINK_BLIND_MS (2u * SUPPLY_LINK_STALE_MS)
	A reading count that has stood this long is a supply no trip can watch: 2 x SUPPLY_LINK_STALE_MS, so the readings have been marked not valid (ok 0) for a further 1500ms (supply_link_blind()).
#define	SUPPLY_LINK_READ_MS 100u
	How often the page is read while the supply is in use.
#define	SUPPLY_LINK_BAUD_AUTO 7u
	The baud setting that asks the IOmcu to find the rate (4.4).
#define	SUPPLY_LINK_NO_ANSWER (-1)
	What came of a write or a read: ACK or DATA, a NACK's reason, or none.
#define	SUPPLY_LINK_ACK 0

Enumerations
enum	{ SUPPLY_LINK_EV_WIRING_REFUSED = 0x01 , SUPPLY_LINK_EV_ON_REFUSED = 0x02 , SUPPLY_LINK_EV_ON_LOST = 0x04 , SUPPLY_LINK_EV_STUCK = 0x08 , SUPPLY_LINK_EV_SET_STUCK = 0x10 , SUPPLY_LINK_EV_TRIPPED = 0x20 , SUPPLY_LINK_EV_BAUD_FOUND = 0x40 , SUPPLY_LINK_EV_SAGGED = 0x80 , SUPPLY_LINK_EV_WIRING_LIVE = 0x100 }
	Things the caller tells the operator about, each once. More...
enum	supply_link_write_t { SUPPLY_LINK_W_NONE = 0 , SUPPLY_LINK_W_OFF , SUPPLY_LINK_W_WIRING , SUPPLY_LINK_W_COMMAND , SUPPLY_LINK_W_RESET }
	The writes the supply link asks for next.

Functions
void	supply_link_init (supply_link_t *s)
	Sets up the supply link state.
void	supply_link_lost (supply_link_t *s)
	The link went or came back: nothing on the page is known, and the panel's ON, if it had one, is over.
void	supply_link_wire (supply_link_t s, const supply_wiring_t w)
	The wiring the settings name now.
void	supply_link_command (supply_link_t *s, bool on, uint16_t mv, uint16_t ma)
	What the output is to be; set points clamped to the page's 1000 to 20000mV and 50 to 3000mA.
void	supply_link_reset (supply_link_t *s)
	Restart the PD mini (protocol 4.4): written once the page's output is off and its wiring written, after any OFF owed.
supply_link_write_t	supply_link_next (supply_link_t s, uint8_t off, uint8_t n, uint16_t regs)
	The next write owed, or SUPPLY_LINK_W_NONE.
void	supply_link_written (supply_link_t *s, int result)
	How the write supply_link_next() gave went: SUPPLY_LINK_ACK, a NACK reason, or SUPPLY_LINK_NO_ANSWER.
bool	supply_link_settled (const supply_link_t *s)
	Whether nothing is owed: the page holds the command asked and the wiring, or the wiring was refused.
bool	supply_link_event_stands (const supply_link_t *s, uint16_t ev)
	Whether what `ev`, one SUPPLY_LINK_EV_* bit, says still holds now.
bool	supply_link_read_due (const supply_link_t *s, uint32_t now_ms)
	Whether a read of the page is due at `now_ms`.
void	supply_link_read (supply_link_t s, const uint16_t regs, uint32_t now_ms)
	The whole page as read at `now_ms`, or `regs` NULL for a read that was not answered.
void	supply_link_state (const supply_link_t s, uint32_t now_ms, supply_state_t st)
	The supply as the page last said, into `st:` readings, set points read back from the module, the mode – OFF while the module reads its output off – the module's reading count (SAMPLES, the IOmcu's count of output readings the module answered) and the time of the page read that first showed that count, and online only for a page read younger than SUPPLY_LINK_STALE_MS from a module the page drives.
bool	supply_link_blind (const supply_link_t *s, uint32_t now_ms)
	Whether the module's readings have stopped at `now_ms:` a page has been read and its reading count (SAMPLES) has not moved for SUPPLY_LINK_BLIND_MS or more, counted on the 32-bit millisecond clock across its wrap.
bool	supply_link_adopted (supply_link_t s, bool on, uint16_t mv, uint16_t ma)
	The command a programming port left on the page, once: true with `on`, `mv` and `ma` filled when the page's command was taken as the one asked since the last call.
uint16_t	supply_link_events (supply_link_t *s)
	The events since the last call, SUPPLY_LINK_EV_*, and cleared.
void	supply_link_sag (const supply_link_t s, uint16_t vin_mv, uint16_t *set_mv)
	The input and the set point in mV that SUPPLY_LINK_EV_SAGGED was read with: the page's VIN_MV and SET_MV_RB on the read that first showed FLAGS bit 10.
bool	supply_link_wiring_moved (supply_link_follow_t *f, unsigned edits, unsigned word)
	Whether the PD mini's wiring has moved since it was last followed.
bool	supply_link_held_pins (const supply_link_t s, int tx, int *rx)
	The PD mini's pins the page holds by its last read, as the IOmcu reserves them (supply_page_pins()): TX and RX while ENABLE is on, -1 and -1 while it is off.
bool	supply_link_port_held (const supply_link_t *s)
	Whether the last read of the page had LINK_SP_PORT set: a programming port holds the supply, and the page takes an OFF of the panel's and no other change of OUTPUT, SET_MV or SET_MA.

Detailed Description

The panel's half of the SUPPLY link page (0x2A, protocol 4.3 to 4.13): what is written to it, in what order, and what a read of it means for the supply the screen shows.

The IOmcu drives the PD mini; the panel asks. Two things are written: the wiring (ENABLE to BAUD, from SETUP INTERFACES) and the command (OUTPUT to SET_MA, from the SUPPLY screen). The order is fixed:

an OFF, alone in OUTPUT, before anything else owed, and first of all while what the page holds is not known;
the wiring, only with OUTPUT 0 on the page and FLAGS bit 6 clear, as the page refuses it otherwise;
the command: ON and the set points in one frame.

A refused wiring is not written again until the settings change. A wiring acknowledged is taken as the page's only once a read shows the page holding it: a 4.5 IOmcu holds a change while a module has answered until a state read of it shows the output off (FLAGS bit 8), and refuses it when that read shows it on or fails (bit 9), which is taken as a refusal and said as one (SUPPLY_LINK_EV_WIRING_LIVE). Nothing else is written while it waits. A read that shows the page holding other than what was written – an IOmcu that restarted between two polls, or one that switched the output off when the heartbeat stopped – makes everything owed again, and an ON the page no longer holds is lost.

A programming port commands the supply too (protocol 4.13, FLAGS bit 11, LINK_SP_PORT). A read with the bit set, and the first read after it, that shows OUTPUT, SET_MV or SET_MA other than written is the port's doing: the page's values become what is asked, nothing is written back and no ON is reported lost. supply_link_adopted() hands them to the caller, whose own copy of the command has to follow. What the caller asks next with supply_link_command() is written as ever; the page refuses it while the port holds the supply unless it is an OFF. A refusal of set points for an output that is on is judged by the next read: with the bit set the page's values are adopted as above and the output stays on, without it the ON is refused as ever. Nothing is written between the refusal and that read except an OFF asked for.

Pure C, no link of its own: the caller makes each exchange and reports how it went. Control task only.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Things the caller tells the operator about, each once.

Enumerator
SUPPLY_LINK_EV_WIRING_REFUSED	the pins or baud refused
SUPPLY_LINK_EV_ON_REFUSED	an ON refused: no output
SUPPLY_LINK_EV_ON_LOST	the page let an ON go
SUPPLY_LINK_EV_STUCK	would not switch
SUPPLY_LINK_EV_SET_STUCK	set points would not take
SUPPLY_LINK_EV_TRIPPED	the module switched it off
SUPPLY_LINK_EV_BAUD_FOUND	AUTO found the module's rate
SUPPLY_LINK_EV_SAGGED	switched off: input sagged
SUPPLY_LINK_EV_WIRING_LIVE	wiring refused: output may be on (4.5)

Function Documentation

◆ supply_link_adopted()

bool supply_link_adopted	(	supply_link_t *	s,
		bool *	on,
		uint16_t *	mv,
		uint16_t *	ma )

The command a programming port left on the page, once: true with on, mv and ma filled when the page's command was taken as the one asked since the last call.

The caller's own copy of the command follows it; a copy left as it was is written again at the caller's next supply_link_command().

Parameters

s	The link state.
on	Receives the output state the page holds.
mv	Receives the set point voltage, in mV.
ma	Receives the set point current, in mA.

Returns: true when the page took the command asked since the last call.

◆ supply_link_blind()

bool supply_link_blind	(	const supply_link_t *	s,
		uint32_t	now_ms )

Whether the module's readings have stopped at now_ms: a page has been read and its reading count (SAMPLES) has not moved for SUPPLY_LINK_BLIND_MS or more, counted on the 32-bit millisecond clock across its wrap.

The page may still answer and the module read ONLINE: a display read that fails while the other reads answer. No operator trip acts on such readings, so the caller switches an output that is on off and says why. False before the first page read.

Parameters

s	The link state.
now_ms	The time, in ms.

Returns: true when the page has been read and the last read is at least SUPPLY_LINK_BLIND_MS old.

◆ supply_link_command()

void supply_link_command	(	supply_link_t *	s,
		bool	on,
		uint16_t	mv,
		uint16_t	ma )

What the output is to be; set points clamped to the page's 1000 to 20000mV and 50 to 3000mA.

Parameters

s	The link state.
on	true to switch the output on.
mv	The set point voltage, in mV.
ma	The set point current, in mA.

◆ supply_link_event_stands()

bool supply_link_event_stands	(	const supply_link_t *	s,
		uint16_t	ev )

Whether what ev, one SUPPLY_LINK_EV_* bit, says still holds now.

A refused wiring – SUPPLY_LINK_EV_WIRING_REFUSED or _WIRING_LIVE – until a read shows the page holding the wiring the settings ask: pins stepped back to ones the page takes end it with the first read that shows them held. With no IOmcu answering it stands. True for every other event. The caller takes back an alert it showed for a refused wiring once this is false.

Parameters

s	The link state.
ev	One SUPPLY_LINK_EV_* bit.

Returns: true while the cause of the event holds.

◆ supply_link_events()

uint16_t supply_link_events ( supply_link_t * s )

The events since the last call, SUPPLY_LINK_EV_*, and cleared.

Parameters

s	The link state.

Returns: The events since the last call, as SUPPLY_LINK_EV_* bits.

◆ supply_link_held_pins()

bool supply_link_held_pins	(	const supply_link_t *	s,
		int *	tx,
		int *	rx )

The PD mini's pins the page holds by its last read, as the IOmcu reserves them (supply_page_pins()): TX and RX while ENABLE is on, -1 and -1 while it is off.

False, both -1, before the first read since the link came up; a refused wiring leaves the page's old one, and that is what is read. tx and rx may be NULL.

Parameters

s	The link state.
tx	Receives the TX pin, or -1; may be NULL.
rx	Receives the RX pin, or -1; may be NULL.

Returns: false before the first read since the link came up.

◆ supply_link_init()

void supply_link_init ( supply_link_t * s )

Sets up the supply link state.

Parameters

s	The link state to set up.

◆ supply_link_lost()

void supply_link_lost ( supply_link_t * s )

The link went or came back: nothing on the page is known, and the panel's ON, if it had one, is over.

Parameters

s	The link state.

◆ supply_link_next()

supply_link_write_t supply_link_next	(	supply_link_t *	s,
		uint8_t *	off,
		uint8_t *	n,
		uint16_t *	regs )

The next write owed, or SUPPLY_LINK_W_NONE.

off and n say where on the page and how many registers, regs what; the caller writes them and reports with supply_link_written().

Parameters

s	The link state.
off	Receives the page offset of the write.
n	Receives the number of registers.
regs	Receives the register values.

Returns: The write owed, or SUPPLY_LINK_W_NONE.

◆ supply_link_port_held()

bool supply_link_port_held ( const supply_link_t * s )

Whether the last read of the page had LINK_SP_PORT set: a programming port holds the supply, and the page takes an OFF of the panel's and no other change of OUTPUT, SET_MV or SET_MA.

The KST page holds it for its whole session; from protocol 4.29 the HITEC page holds it from its OPEN to its CLOSE. False before the first read since the link came up.

Parameters

s	The link state.

Returns: true while held.

◆ supply_link_read()

void supply_link_read	(	supply_link_t *	s,
		const uint16_t *	regs,
		uint32_t	now_ms )

The whole page as read at now_ms, or regs NULL for a read that was not answered.

Parameters

s	The link state.
regs	The page as read, or NULL for a read not answered.
now_ms	The time, in ms.

◆ supply_link_read_due()

bool supply_link_read_due	(	const supply_link_t *	s,
		uint32_t	now_ms )

Whether a read of the page is due at now_ms.

Parameters

s	The link state.
now_ms	The time, in ms.

Returns: true when a read of the page is due.

◆ supply_link_reset()

void supply_link_reset ( supply_link_t * s )

Restart the PD mini (protocol 4.4): written once the page's output is off and its wiring written, after any OFF owed.

Parameters

s	The link state.

◆ supply_link_sag()

void supply_link_sag	(	const supply_link_t *	s,
		uint16_t *	vin_mv,
		uint16_t *	set_mv )

The input and the set point in mV that SUPPLY_LINK_EV_SAGGED was read with: the page's VIN_MV and SET_MV_RB on the read that first showed FLAGS bit 10.

An input reading taken between the IOmcu's cut and that read replaces the one that cut.

Parameters

s	The link state.
vin_mv	Receives the input voltage, in mV.
set_mv	Receives the set point, in mV.

◆ supply_link_settled()

bool supply_link_settled ( const supply_link_t * s )

Whether nothing is owed: the page holds the command asked and the wiring, or the wiring was refused.

Parameters

s	The link state.

Returns: true when nothing is owed.

◆ supply_link_state()

void supply_link_state	(	const supply_link_t *	s,
		uint32_t	now_ms,
		supply_state_t *	st )

The supply as the page last said, into st: readings, set points read back from the module, the mode – OFF while the module reads its output off – the module's reading count (SAMPLES, the IOmcu's count of output readings the module answered) and the time of the page read that first showed that count, and online only for a page read younger than SUPPLY_LINK_STALE_MS from a module the page drives.

The readings are marked valid (ok) only while the count moved within the last SUPPLY_LINK_STALE_MS; behind a count that stands still they stay as the last ones with ok 0. Left as they are: output, which is what the panel asked, and the run's extremes, totals and trip.

Parameters

s	The link state.
now_ms	The time, in ms.
st	Receives the supply state.

◆ supply_link_wire()

void supply_link_wire	(	supply_link_t *	s,
		const supply_wiring_t *	w )

The wiring the settings name now.

Parameters

s	The link state.
w	The wiring the settings name.

◆ supply_link_wiring_moved()

bool supply_link_wiring_moved	(	supply_link_follow_t *	f,
		unsigned	edits,
		unsigned	word )

Whether the PD mini's wiring has moved since it was last followed.

Parameters

f	The followed wiring state, updated.
edits	The edit count now.
word	The wiring word now.

Returns: true when the edit count or the wiring word has moved since the last call.

◆ supply_link_written()

void supply_link_written	(	supply_link_t *	s,
		int	result )

How the write supply_link_next() gave went: SUPPLY_LINK_ACK, a NACK reason, or SUPPLY_LINK_NO_ANSWER.

Parameters

s	The link state.
result	The result: an acknowledgement, a NACK's reason or SUPPLY_LINK_NO_ANSWER.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ supply_link_adopted()

◆ supply_link_blind()

◆ supply_link_command()

◆ supply_link_event_stands()

◆ supply_link_events()

◆ supply_link_held_pins()

◆ supply_link_init()

◆ supply_link_lost()

◆ supply_link_next()

◆ supply_link_port_held()

◆ supply_link_read()

◆ supply_link_read_due()

◆ supply_link_reset()

◆ supply_link_sag()

◆ supply_link_settled()

◆ supply_link_state()

◆ supply_link_wire()

◆ supply_link_wiring_moved()

◆ supply_link_written()