The SUPPLY link page. More...

#include "supply_page.h"
#include <stddef.h>
#include <string.h>
#include "link_msg.h"

Functions
uint32_t	supply_page_baud (uint16_t setting)
	The baud rate of a UART setting.
void	supply_page_init (supply_page_t *p)
	Clears the page to its start: BAUD 1 (19200), BAUD_FOUND AUTO, the scan at 1.
bool	supply_page_enabled (const supply_page_t *p)
	Whether the page drives a supply, and on which pins.
uint8_t	supply_page_tx (const supply_page_t *p)
	The TX pin register, as a GPIO number.
uint8_t	supply_page_rx (const supply_page_t *p)
	The RX pin register, as a GPIO number.
uint64_t	supply_page_pins (const supply_page_t *p)
	The pins it holds, as a reservation mask; 0 while not enabled.
static bool	pin_free (const supply_page_t p, const outputs_t o, uint16_t pin)
	Whether `pin` may carry the supply: in the bank, not reserved unless it is one this page already holds, and no output's.
static uint16_t	wire_flags (const supply_page_t *p)
	FLAGS bits 8, 9 and 11, kept whether or not a driver runs.
static void	wire_publish (supply_page_t *p)
	Bits 8, 9 and 11 onto the page as they change, not at the next step: a read between the two must not show a refusal already cleared, or no wait.
static uint8_t	page_write (supply_page_t p, uint8_t off, uint8_t n, const uint16_t in, const outputs_t *o, bool beat_alive, bool checked)
	A write, judged whole; `checked` for the wiring a state read cleared, which does not wait again.
uint8_t	supply_page_write (supply_page_t p, uint8_t off, uint8_t n, const uint16_t in, const outputs_t *o, bool beat_alive)
	A write, validated whole before any of it is stored.
void	supply_page_follow (supply_page_t p, const pdmini_t drv)
	What the driver says now, straight before a write is judged: FLAGS bit 6 (the output on or maybe on) and whether its module has answered.
bool	supply_page_wire_ready (const supply_page_t p, uint16_t regs)
	The wiring change whose state read showed the output off, into `regs` (ENABLE to BAUD): true while one is SUPPLY_WIRE_READY.
void	supply_page_wire_refuse (supply_page_t *p)
	The ready wiring could not be put in force after it was written (no UART for its pins): refused, FLAGS bit 9, as a refused read is.
uint8_t	supply_page_wire_write (supply_page_t p, const outputs_t o)
	The ready wiring written: judged whole as a link write is, against the driver's state as supply_page_follow() last took it, without waiting again. 0, or the NACK reason, which refuses it (FLAGS bit 9).
static void	wire_step (supply_page_t p, pdmini_t drv)
	The wiring change waiting, followed: its read asked of `drv`, and its answer taken.
uint8_t	supply_page_rate (supply_page_t p, const pdmini_t drv)
	The rate the UART is to run at now, 0 to 6.
uint32_t	supply_page_uart_baud (const supply_page_t *p)
	The baud the UART is to be opened at now.
uint8_t	supply_page_slots_check (const supply_page_t p, const uint16_t slots)
	LINK_NACK_BAD_VALUE for an OUTPUTS page (`slots`, LINK_OS_COUNT registers) that binds a slot to a pin the supply holds; 0 otherwise.
void	supply_page_read (const supply_page_t p, uint8_t off, uint8_t n, uint16_t out)
	Copies registers of the SUPPLY page.
void	supply_page_step (supply_page_t p, bool beat_alive, pdmini_t drv)
	One pass: the output off without a heartbeat, what the driver is to do, and what it last said into the read-only registers.
void	supply_page_port_view (const supply_page_t p, supply_port_view_t out)
	The page as of the last supply_page_step(), for a programming port.
bool	supply_page_port_set (supply_page_t *p, bool on, uint16_t mv, uint16_t ma, bool beat_alive)
	A programming port's request, in place of a link write of OUTPUT to SET_MA.
void	supply_page_port_frame (supply_page_t *p, bool frame_out, uint32_t now_ms)
	Whether a programming port has a frame on the wire, and the clock, once a pass before supply_page_step().
void	supply_page_hold (supply_page_t *p, bool held)
	Whether a programming port holds the command registers (FLAGS bit 11, LINK_SP_PORT).

Detailed Description

The SUPPLY link page.

See supply_page.h.

SPDX-License-Identifier: MIT

Function Documentation

◆ page_write()

uint8_t page_write	(	supply_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in,
		const outputs_t *	o,
		bool	beat_alive,
		bool	checked )

static

A write, judged whole; checked for the wiring a state read cleared, which does not wait again.

Parameters

p	The page state.
off	First register, 0 to LINK_SP_COUNT - 1.
n	Number of registers to write.
in	The `n` new register values.
o	The outputs bank.
beat_alive	Whether the panel's heartbeat is live.
checked	true when a state read of the driver has just cleared the wiring, so a wiring change does not wait again.

Returns: 0 when taken, or a NACK reason as supply_page_write() gives it.

◆ pin_free()

bool pin_free	(	const supply_page_t *	p,
		const outputs_t *	o,
		uint16_t	pin )

static

Whether pin may carry the supply: in the bank, not reserved unless it is one this page already holds, and no output's.

Parameters

p	The page state, for the pins it already holds.
o	The outputs bank.
pin	GPIO number to judge.

Returns: true when the pin may be taken, false otherwise.

◆ supply_page_baud()

uint32_t supply_page_baud ( uint16_t setting )

The baud rate of a UART setting.

Parameters

setting UART setting, 0 to SUPPLY_BAUD_COUNT - 1.

Returns: 9600, 19200, 38400, 57600, 115200, 230400 or 460800 for settings 0 to 6; 0 for a setting of 7 or more, including SUPPLY_BAUD_AUTO.

◆ supply_page_enabled()

bool supply_page_enabled ( const supply_page_t * p )

Whether the page drives a supply, and on which pins.

Parameters

p	The page state.

Returns: true when ENABLE is not 0, false otherwise or for NULL.

◆ supply_page_follow()

void supply_page_follow	(	supply_page_t *	p,
		const pdmini_t *	drv )

What the driver says now, straight before a write is judged: FLAGS bit 6 (the output on or maybe on) and whether its module has answered.

drv NULL for no driver: nothing answered, nothing on. supply_page_step() does the same every pass.

Parameters

p	The page state, updated.
drv	The PD mini driver, or NULL.

◆ supply_page_hold()

void supply_page_hold	(	supply_page_t *	p,
		bool	held )

Whether a programming port holds the command registers (FLAGS bit 11, LINK_SP_PORT).

While it does, supply_page_write() takes an OFF, which leaves SET_MV and SET_MA as they are whatever the write names, and refuses every other write of OUTPUT to SET_MA that changes one of the three with LINK_NACK_BAD_VALUE: the panel can switch the supply off, and cannot switch it on or move a set point under the servo.

Parameters

p	The page state. Nothing is done when NULL.
held	true while the programming port holds the registers.

◆ supply_page_init()

void supply_page_init ( supply_page_t * p )

Clears the page to its start: BAUD 1 (19200), BAUD_FOUND AUTO, the scan at 1.

Nothing is done when p is NULL.

Parameters

p	The page state, overwritten.

◆ supply_page_pins()

uint64_t supply_page_pins ( const supply_page_t * p )

The pins it holds, as a reservation mask; 0 while not enabled.

Parameters

p	The page state.

Returns: Bits for the TX and RX pins, 0 when not enabled or for NULL.

◆ supply_page_port_frame()

void supply_page_port_frame	(	supply_page_t *	p,
		bool	frame_out,
		uint32_t	now_ms )

Whether a programming port has a frame on the wire, and the clock, once a pass before supply_page_step().

An OFF taken while one is – written by the panel or forced by a lost heartbeat – reaches the driver when the frame has ended, SUPPLY_PAGE_OFF_WAIT_MS after it was asked at the latest. OUTPUT reads 0 from the moment it is asked.

Parameters

p	The page state. Nothing is done when NULL.
frame_out	true while a frame is on the wire.
now_ms	Current time in milliseconds.

◆ supply_page_port_set()

bool supply_page_port_set	(	supply_page_t *	p,
		bool	on,
		uint16_t	mv,
		uint16_t	ma,
		bool	beat_alive )

A programming port's request, in place of a link write of OUTPUT to SET_MA.

Off is always taken and leaves the set points. On is refused (false, nothing changed) without a live heartbeat, while the supply is not wired or a wiring change waits, for set points outside the module's range, and for a voltage above SET_MV while OUTPUT is 1: the voltage of an output that is on is not raised here.

Parameters

p	The page state.
on	true for ON, false for OFF.
mv	Set voltage in millivolts, for ON.
ma	Set current in milliamps, for ON.
beat_alive	Whether the panel's heartbeat is live.

Returns: true when taken. false for NULL, an ON that is refused (see above), otherwise true for an OFF.

◆ supply_page_port_view()

void supply_page_port_view	(	const supply_page_t *	p,
		supply_port_view_t *	out )

The page as of the last supply_page_step(), for a programming port.

Parameters

p	The page state.
out	Receives the view. Zeroed first; nothing else is done when `p` is NULL. Nothing is done when `out` is NULL.

◆ supply_page_rate()

uint8_t supply_page_rate	(	supply_page_t *	p,
		const pdmini_t *	drv )

The rate the UART is to run at now, 0 to 6.

The setting itself, or under AUTO the one being tried: the next after every WHO_AM_I drv reports without a valid answer, until a module has answered once, from when the rate holds. Publishes it in BAUD_FOUND – 7 while AUTO has found none. drv NULL leaves the scan where it is.

Parameters

p	The page state. BAUD_FOUND is updated.
drv	The PD mini driver, or NULL.

Returns: The setting, 0 to 6. 1 for a NULL p.

◆ supply_page_read()

void supply_page_read	(	const supply_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

Copies registers of the SUPPLY page.

Nothing is done when p or out is NULL, or when off and n reach past LINK_SP_COUNT.

Parameters

p	The page state, not changed.
off	First register, 0 to LINK_SP_COUNT - 1.
n	Number of registers to copy.
out	Receives the `n` register values.

◆ supply_page_rx()

uint8_t supply_page_rx ( const supply_page_t * p )

The RX pin register, as a GPIO number.

Parameters

p	The page state.

Returns: The pin, 0 for NULL.

◆ supply_page_slots_check()

uint8_t supply_page_slots_check	(	const supply_page_t *	p,
		const uint16_t *	slots )

LINK_NACK_BAD_VALUE for an OUTPUTS page (slots, LINK_OS_COUNT registers) that binds a slot to a pin the supply holds; 0 otherwise.

Checked before the page is stored, so no binding is kept that the bank would leave unbound – and that a restart, with the supply not yet wired, would drive on the module's pin.

Parameters

p	The page state.
slots	The OUTPUTS page, LINK_OS_COUNT registers.

Returns: LINK_NACK_BAD_VALUE for a NULL slots or a slot with a driver on a pin in supply_page_pins(), 0 otherwise.

◆ supply_page_step()

void supply_page_step	(	supply_page_t *	p,
		bool	beat_alive,
		pdmini_t *	drv )

One pass: the output off without a heartbeat, what the driver is to do, and what it last said into the read-only registers.

drv may be NULL while no supply is wired. A wiring change waiting asks the driver for its state read and follows the answer: off makes it SUPPLY_WIRE_READY, anything else refuses it (FLAGS bit 9). With no driver it is ready: nothing is attached to the module to switch it off.

Parameters

p	The page state. Nothing is done when NULL.
beat_alive	Whether the panel's heartbeat is live.
drv	The PD mini driver, or NULL.

◆ supply_page_tx()

uint8_t supply_page_tx ( const supply_page_t * p )

The TX pin register, as a GPIO number.

Parameters

p	The page state.

Returns: The pin, 0 for NULL.

◆ supply_page_uart_baud()

uint32_t supply_page_uart_baud ( const supply_page_t * p )

The baud the UART is to be opened at now.

Parameters

p	The page state.

Returns: supply_page_baud() of the rate from supply_page_rate()'s rules, or 0 for NULL.

◆ supply_page_wire_ready()

bool supply_page_wire_ready	(	const supply_page_t *	p,
		uint16_t *	regs )

The wiring change whose state read showed the output off, into regs (ENABLE to BAUD): true while one is SUPPLY_WIRE_READY.

The caller writes it with supply_page_wire_write() in the same pass.

Parameters

p	The page state.
regs	Receives the four wiring registers, ENABLE to BAUD. Not written when false is returned.

Returns: true when a change is ready and regs is filled, false otherwise or for NULL.

◆ supply_page_wire_refuse()

void supply_page_wire_refuse ( supply_page_t * p )

The ready wiring could not be put in force after it was written (no UART for its pins): refused, FLAGS bit 9, as a refused read is.

Parameters

p	The page state. Nothing is done when NULL.

◆ supply_page_wire_write()

uint8_t supply_page_wire_write	(	supply_page_t *	p,
		const outputs_t *	o )

The ready wiring written: judged whole as a link write is, against the driver's state as supply_page_follow() last took it, without waiting again. 0, or the NACK reason, which refuses it (FLAGS bit 9).

Parameters

p	The page state.
o	The outputs bank, for the pins.

Returns: 0 when written. LINK_NACK_BAD_VALUE when no change is ready, or the refusal of the page write otherwise.

◆ supply_page_write()

uint8_t supply_page_write	(	supply_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in,
		const outputs_t *	o,
		bool	beat_alive )

A write, validated whole before any of it is stored.

Refused: off the page (BAD_RANGE); a read-only register (READ_ONLY); a wiring change while the output is asked on or may be on, a pin past the bank, reserved, bound to an output or the other pin, a baud setting past 7 (AUTO), an ON without the supply enabled or without its set points in the same frame, a set point above the module's range, an ON while a wiring change waits, a wiring change that waits in the same frame as OUTPUT to SET_MA (BAD_VALUE); an ON without a live heartbeat (NOT_ARMED).

A wiring change that passes, while the driver's module has answered (supply_page_follow()), is acknowledged and not yet taken: it waits (SUPPLY_WIRE_WAIT, FLAGS bit 8) for a state read the next supply_page_step() asks of the driver. Another change replaces it and is read for again; a write of the wiring in force drops it.

Parameters

p	The page state, changed only when the write is taken.
off	First register, 0 to LINK_SP_COUNT - 1.
n	Number of registers to write. 0 is taken with no change.
in	The `n` new register values.
o	The outputs bank, for the pins a wiring change takes.
beat_alive	Whether the panel's heartbeat is live.

Returns: 0 when taken, or when the write waits for a state read. The NACK reason otherwise: LINK_NACK_BAD_RANGE, LINK_NACK_READ_ONLY, LINK_NACK_BAD_VALUE or LINK_NACK_NOT_ARMED, as listed above.

◆ wire_flags()

uint16_t wire_flags ( const supply_page_t * p )

static

FLAGS bits 8, 9 and 11, kept whether or not a driver runs.

Parameters

p	The page state.

Returns: LINK_SP_PORT when held, LINK_SP_WIRE_WAIT while a change waits, LINK_SP_WIRE_REFUSED after a refusal; the bits that are set.

◆ wire_publish()

void wire_publish ( supply_page_t * p )

static

Bits 8, 9 and 11 onto the page as they change, not at the next step: a read between the two must not show a refusal already cleared, or no wait.

Parameters

p	The page state. Only those three FLAGS bits are replaced.

◆ wire_step()

void wire_step	(	supply_page_t *	p,
		pdmini_t *	drv )

static

The wiring change waiting, followed: its read asked of drv, and its answer taken.

Parameters

p	The page state.
drv	The PD mini driver, or NULL.

Functions

Detailed Description

Function Documentation

◆ page_write()

◆ pin_free()

◆ supply_page_baud()

◆ supply_page_enabled()

◆ supply_page_follow()

◆ supply_page_hold()

◆ supply_page_init()

◆ supply_page_pins()

◆ supply_page_port_frame()

◆ supply_page_port_set()

◆ supply_page_port_view()

◆ supply_page_rate()

◆ supply_page_read()

◆ supply_page_rx()

◆ supply_page_slots_check()

◆ supply_page_step()

◆ supply_page_tx()

◆ supply_page_uart_baud()

◆ supply_page_wire_ready()

◆ supply_page_wire_refuse()

◆ supply_page_wire_write()

◆ supply_page_write()

◆ wire_flags()

◆ wire_publish()

◆ wire_step()