link_pages.h

Go to the documentation of this file.

#ifndef RCBENCH_LINK_PAGES_H
#define RCBENCH_LINK_PAGES_H
 
#include <stdbool.h>
 
#include "link_crc.h"
#include "link_msg.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef enum {
    LINK_PAGE_IDENTITY = 0x00, 
    LINK_PAGE_STATUS   = 0x01, 
    LINK_PAGE_CONTROL  = 0x10, 
    LINK_PAGE_LIMITS   = 0x11, 
    LINK_PAGE_FAILSAFE = 0x12, 
    LINK_PAGE_CHANNELS = 0x13, 
    LINK_PAGE_BENCH    = 0x20, 
    /*
     * 0x21 is reserved and not assigned.  A page number is part of the
     * contract between two firmwares flashed separately; a number that
     * changes meaning lets an old panel write into a page the IOmcu
     * interprets differently, and be acknowledged.
     */
    LINK_PAGE_OUTPUTS  = 0x22, 
    LINK_PAGE_CHAN_CFG = 0x23, 
    LINK_PAGE_CATALOGUE = 0x24, 
    LINK_PAGE_SHAPE     = 0x25, 
    LINK_PAGE_ARTWORK   = 0x26, 
    LINK_PAGE_ART_DATA  = 0x27, 
    LINK_PAGE_PADS      = 0x28, 
    LINK_PAGE_SERVO     = 0x29, 
    LINK_PAGE_SUPPLY    = 0x2A, 
    LINK_PAGE_SENSE     = 0x2B, 
    LINK_PAGE_SERVO_SENSE = 0x2C, 
    LINK_PAGE_TONE      = 0x2D, 
    LINK_PAGE_BIND_CFG  = 0x2E, 
    LINK_PAGE_BIND_OUT  = 0x2F, 
    LINK_PAGE_BIND      = 0x30, 
    LINK_PAGE_SERVO_WIN = 0x31, 
    LINK_PAGE_KST       = 0x32, 
    LINK_PAGE_PROG      = 0x33, 
    LINK_PAGE_HITEC     = 0x34, 
    LINK_PAGE_SENSE_MAP = 0x35, 
    LINK_PAGE_SENSE_LIMIT = 0x36, 
    LINK_PAGE_SENSE_WIN_A = 0x37, 
    LINK_PAGE_SENSE_WIN_B = 0x38, 
    /* Frozen: the same numbers, layout and meaning under every major. */
    LINK_PAGE_UPDATE_CTL  = 0xF0, 
    LINK_PAGE_UPDATE_DATA = 0xF1, 
} link_page_id_t;

#define LINK_PROTOCOL_MAJOR 4u
#define LINK_PROTOCOL_MINOR 29u

#define LINK_MINOR_BIND 10u
#define LINK_MINOR_SERVO_WIN 11u
#define LINK_MINOR_KST 12u
#define LINK_MINOR_PROG 13u
#define LINK_MINOR_KST_PLAN 14u
#define LINK_MINOR_KST_LEAVE 15u
#define LINK_MINOR_PULSE_FRAME 16u
#define LINK_MINOR_TONE_BUSY 17u
#define LINK_MINOR_ARM_ROLE 18u
#define LINK_MINOR_SERVO_TARGET_RATE 19u
#define LINK_MINOR_DRAWING 20u
#define LINK_MINOR_REFUSED 21u
#define LINK_MINOR_UPDATE 22u
#define LINK_MINOR_HITEC 23u
#define LINK_MINOR_HITEC_RX 24u
#define LINK_MINOR_SENSE_MAP 25u
#define LINK_MINOR_SENSE_LIMIT 27u

#define LINK_MINOR_PROG_FUNC 26u

#define LINK_MINOR_PROG_DSHOT 28u

#define LINK_MINOR_HITEC_HOLD 29u
 
/* ----------------------------------------------------------------- outputs */
 
/*
 * The three output pages.  Every output protocol has a proportion of travel
 * and a driver that renders it, so that is what the wire carries:
 *
 *   CHANNELS  what each output is asked for, and nothing else.  Hot: written
 *             many times a second, and the only page in the group that is.
 *   CHAN_CFG  what a channel is (throttle or surface), how fast it may move,
 *             and the pulse widths its ends correspond to.
 *   OUTPUTS   which driver renders which channels, on which pin, how often.
 *
 * Eight of each.  At four registers per slot, eight slots fit a page of
 * LINK_MAX_REGS registers; eight is also the number of servo outputs the
 * bench has and the number of channels PPM (pulse-position modulation)
 * carries.  A ninth slot needs a minor version and a second page.
 */
 
#define LINK_OUT_SLOTS     8u
#define LINK_OUT_CHANNELS  8u

#define LINK_CH_SPAN    1000u
 
/* --- what each output is asked for */
#define LINK_CH_COUNT   LINK_OUT_CHANNELS
 
/* --- what a channel is.  Four registers each, and a channel must be written
 *     whole: min and max are a pair, and a range half-applied is a range
 *     nothing is clamped against. */
enum {
    LINK_CC_ROLE    = 0, 
    LINK_CC_SLEW    = 1, 
    LINK_CC_MIN_US  = 2, 
    LINK_CC_MAX_US  = 3, 
    LINK_CC_STRIDE  = 4,
};
#define LINK_CC_COUNT  (LINK_OUT_CHANNELS * LINK_CC_STRIDE)

#define LINK_CC_SLEW_MAX 3000u
 
#define LINK_CC_ROLE_THROTTLE 0u
#define LINK_CC_ROLE_SURFACE  1u

#define LINK_CC_DEFAULT_MIN 1000u
#define LINK_CC_DEFAULT_MAX 2000u
#define LINK_CC_FLOOR_US     400u
#define LINK_CC_CEILING_US  2500u

#define LINK_CC_THROTTLE_GAP_US 100u
 
/* --- which driver drives what.  Four registers a slot, written whole for the
 *     same reason: a driver claimed on a pin the rest of the write has not
 *     arrived to name yet is a driver on the wrong pin. */
enum {
    LINK_OS_DRIVER  = 0, 
    LINK_OS_PIN     = 1, 
    /*
     * First channel and count in one register: the run of channels this slot
     * renders.  PPM is eight channels on one pin, so a slot cannot be assumed
     * to be one channel.
     */
    LINK_OS_RANGE   = 2, 
    LINK_OS_RATE_HZ = 3, 
    LINK_OS_STRIDE  = 4,
};
#define LINK_OS_COUNT  (LINK_OUT_SLOTS * LINK_OS_STRIDE)
 
/* --- the SERVO screen's page: the target's frame rate (protocol 4.1) and
 *     the sweep that drives it through a curve (4.2).
 *
 *     FRAME_HZ is the frame rate, in Hz, of the tester's target (PROG's
 *     LINK_PG_TARGET), or 0 for its own rate.  With the standard servo
 *     ports as target it is every PWM output whose first channel is a
 *     surface, 0 meaning each slot's own rate from the OUTPUTS page.  One
 *     register for all of them, so a write is whole: a servo screen that
 *     moved some surfaces to 560Hz and not their slice-mates would leave a
 *     slice asked for two rates.  A rate that would do that against the
 *     binding in force -- a surface and a throttle on one slice -- is
 *     refused with BAD_VALUE and nothing changes.  With a programming port
 *     as target (since 4.19) it is that port's pin alone, 0 meaning 50Hz;
 *     the slots run at their own rates.  A port pin that shares its PWM
 *     slice with another port's pin takes only 0 or 50 (BAD_VALUE).  Every
 *     port that is not the target runs at 50Hz, and a TARGET change sets
 *     FRAME_HZ to 0.  An IOmcu before 4.19 runs every surface and
 *     every port at FRAME_HZ, whatever the target.
 *
 *     SWEEP to SWEEP_DWELL_MS are a sweep (servo_sweep.h), four registers so
 *     a start fits one frame.  SWEEP is the curve, 0 stopped, 1 square,
 *     2 sine, 3 triangle; MHZ thousandths of a cycle a second, 50 to 5000;
 *     SPAN command units either side of the centre, 0 to 500; DWELL_MS the
 *     hold at each end, 0 to 5000.  A sweep needs the bench armed
 *     (NOT_ARMED) and stops after 500ms unwritten, on a disarm, or after
 *     SWEEP_MOVES ends (0 for no end), read back in SWEEP_DONE.
 *
 *     SWEEP = 4 (LINK_SV_HOLD), one register, holds every surface where
 *     its output is -- a sweep stopped part way, exactly where it got to,
 *     slew and all -- for as long as it is written, on the same 500ms and
 *     disarm rules.  A sweep that was running when the hold began keeps its
 *     phase: how far into the curve it was, so its point, its dwell and its
 *     movements reached.  One that had made its movements is held at the
 *     centre it ended on.  A write is judged against the page as a pass at
 *     the same moment leaves it: a sweep past its last movement, unwritten
 *     for 500ms or disarmed has ended, even before the pass that ends it.
 *
 *     SWEEP = 5 (LINK_SV_RESUME, since 4.6), one register, carries that
 *     sweep on from the kept phase.  The surfaces are commanded along the
 *     curve again at once and slew there from where they were held, at
 *     their own rate.  Refused with BAD_VALUE when no phase is kept -- no
 *     sweep was running when the hold began, or the hold has ended by a
 *     write of 0, a curve written over it, a disarm, 500ms unwritten or
 *     a restart -- and when
 *     SWEEP_MHZ, SPAN, DWELL_MS or MOVES no longer read what the paused
 *     sweep runs; NOT_ARMED on a disarmed bench.  A 4.5 IOmcu refuses
 *     5 with BAD_VALUE, as any curve not written whole.
 *
 *     Not kept: an IOmcu restart drives every slot at its own rate
 *     again, which is the binding's 50Hz for a servo, and runs no sweep. */
enum {
    LINK_SV_FRAME_HZ       = 0,
    LINK_SV_SWEEP          = 1,
    LINK_SV_SWEEP_MHZ      = 2,
    LINK_SV_SWEEP_SPAN     = 3,
    LINK_SV_SWEEP_DWELL_MS = 4,
    LINK_SV_SWEEP_MOVES    = 5,
    LINK_SV_SWEEP_DONE     = 6,   
    LINK_SV_COUNT          = 7,
};
#define LINK_SV_HOLD 4u
#define LINK_SV_RESUME 5u
 
/* --- the SUPPLY page (protocol 4.3): a WeAct PD Power Mini V1 Buck on a
 *     PIO UART the IOmcu runs on two of its pins (shared/bench/
 *     pdmini.h).
 *
 *     ENABLE to BAUD are its wiring, one frame: 1 to drive it, the GPIO the
 *     UART transmits on (to the module's DM) and receives on (its DP), and
 *     the module's UART Baudrate setting, 0 to 6 for 9600 to 460800 baud,
 *     or 7 (protocol 4.4) to find it: the UART steps to the next rate
 *     after every WHO_AM_I without a valid answer, until a module has
 *     answered once, and BAUD_FOUND says which rate is in use.
 *
 *     RESET, written alone as 1 with OUTPUT 0, restarts the module
 *     (SYSTEM_RESET) once it has answered and its output reads off; it
 *     reads 0.
 *     Refused with BAD_VALUE: a pin that is reserved, bound to an output or
 *     the other pin, a baud out of range, or any change while the output is
 *     asked on or may be on (FLAGS bit 6).  The pins it takes are no
 *     output's while it holds them.
 *
 *     Protocol 4.5: a change while a module has answered is acknowledged
 *     and waits, ENABLE to BAUD reading the wiring in force and FLAGS bit 8
 *     set, for a state read of the module sent after it -- at most about
 *     1.2s.  That read showing the output off takes it; on, or failed,
 *     refuses it: bit 8 clears and bit 9 sets until the next wiring write.
 *     Such a change comes alone, without OUTPUT to SET_MA, and an ON is
 *     refused with BAD_VALUE while one waits.
 *
 *     OUTPUT to SET_MA are what it is to do, one frame: 1 for the output
 *     on, the set points in mV and mA, clamped to the module's 1 to 20V
 *     and 0.05 to 3A.  An ON is refused with NOT_ARMED without a live
 *     heartbeat, and the output goes off when the heartbeat stops.
 *
 *     FLAGS onwards are read only, what the module last said: bit 0
 *     online, bit 1 output on, bits 3..2 the mode (0 normal, 1 constant
 *     current, 2 overcurrent), bit 4 an output that would not switch,
 *     bit 5 set points that would not take, bit 6 an output that is on or
 *     may be -- read on, an ON not yet confirmed, or an OFF owed to a
 *     module that stopped answering, bit 7 an output the module switched
 *     off by itself, held off until OUTPUT is written 0, bit 8 a wiring
 *     change waiting for its state read and bit 9 one refused by it
 *     (4.5), bit 10 an output switched off because its input read under
 *     the set point and 500mV on 2 input reads in a row, held off until
 *     OUTPUT is written 0 (4.5);
 *     the output's voltage and current, the set points read back from it,
 *     the input's state and voltage, and the counts of readings taken and
 *     of transactions that failed, modulo 65536.
 *
 *     The wiring is kept in the IOmcu's flash and driven at boot with
 *     the output off, so a module left on is switched off after a restart;
 *     the command is not kept. */
enum {
    LINK_SP_ENABLE    = 0,
    LINK_SP_TX_PIN    = 1,
    LINK_SP_RX_PIN    = 2,
    LINK_SP_BAUD      = 3,
    LINK_SP_OUTPUT    = 4,
    LINK_SP_SET_MV    = 5,
    LINK_SP_SET_MA    = 6,
    LINK_SP_FLAGS     = 7,   
    LINK_SP_V_MV      = 8,
    LINK_SP_I_MA      = 9,
    LINK_SP_SET_MV_RB = 10,
    LINK_SP_SET_MA_RB = 11,
    LINK_SP_IN_STATE  = 12,
    LINK_SP_VIN_MV    = 13,
    LINK_SP_SAMPLES   = 14,
    LINK_SP_ERRORS    = 15,
    LINK_SP_BAUD_FOUND = 16,  
    LINK_SP_RESET     = 17,   
    LINK_SP_COUNT     = 18,
};
#define LINK_SP_ONLINE  0x01u
#define LINK_SP_ON      0x02u
#define LINK_SP_MODE(f) (((f) >> 2) & 3u)
#define LINK_SP_STUCK   0x10u
#define LINK_SP_SET_STUCK 0x20u
#define LINK_SP_LIVE      0x40u
#define LINK_SP_TRIPPED   0x80u
#define LINK_SP_WIRE_WAIT    0x100u  
#define LINK_SP_WIRE_REFUSED 0x200u  
#define LINK_SP_SAGGED       0x400u  
#define LINK_SP_PORT         0x800u
 
/* --- the SENSE page (protocol 4.7): two I2C (Inter-Integrated Circuit)
 *     current monitors on one bus the IOmcu runs on two of its pins,
 *     a TI INA228 in the ESC's power path and a TI INA3221 on the servo
 *     rail.
 *
 *     ENABLE to KHZ are the bus, one frame: ENABLE bit 0 the INA228, bit 1
 *     the INA3221, bit 2 the AS5600 output encoder (protocol 4.9); the GPIO for SDA and the one for SCL; the clock, 400kHz
 *     and nothing else (LINK_SN_KHZ_BUS): the schedule's 1ms tick does not
 *     fit a slower bus.  The RP2350 has its I2C function at pin mod 4 -- 0 I2C0 SDA,
 *     1 I2C0 SCL, 2 I2C1 SDA, 3 I2C1 SCL -- so SDA is a GPIO whose number
 *     mod 4 is 0 or 2 and SCL is the one after it: one I2C block's pair.
 *
 *     I228_ADDR to register 7 are the INA228, one frame: its address, 0x40
 *     to 0x4F; its shunt in micro-ohms, 50 to 20000; the current its range
 *     is set for, in 0.1A, 1.0 to 300.0A, the bench's design maximum.
 *     That current chooses ADCRANGE only: 1
 *     while the shunt's voltage at it is at most 40.96mV, 0 up to
 *     163.84mV, and past that the write is refused.  CURRENT_LSB is the
 *     shunt ADC's step divided by the shunt at that range, so CURRENT and
 *     VSHUNT clip together, and SHUNT_CAL is 4096 at either range.  A
 *     shunt whose full scale at the chosen range passes 2000A is refused
 *     too: below 81.92 micro-ohms only ADCRANGE 1 is taken.  The rule is
 *     the driver's, ina228_calibrate() in shared/sense.
 *
 *     I3221_ADDR to register 11 are the INA3221, one frame: its address,
 *     0x40 to 0x43; its shunt in 0.1 milliohm, 50 to 10000 (5mOhm to
 *     1Ohm); the channels read, bits 0..2 for CH1 to CH3, at least one
 *     while the part is enabled.  The part's full scale is 163.8mV across
 *     the shunt: 1.638A at the DAOKAI module's 0.1Ohm, 32.76A at 5mOhm,
 *     which is the most SERVO_SENSE's signed mA carry.
 *
 *     Registers 7 and 11 are reserved: they read 0, and a write of anything
 *     else is refused with BAD_VALUE.  They keep each part's frame four
 *     registers long for a later minor to give them a meaning.
 *
 *     Refused with BAD_VALUE: a value out of its range, SDA and SCL not one
 *     I2C block's pair (link_sn_pins_pair()) whatever ENABLE holds, and
 *     while a part is enabled a pin past the bank, reserved, bound to an
 *     output or held by the SUPPLY page, the two parts on one address while
 *     both are enabled, and any change while the bank is armed -- the bus
 *     opened again stops the readings for some milliseconds mid-run.  One
 *     frame that is not a pair is taken: ENABLE 0 with SDA or SCL 0, which
 *     is how a panel writes pins that are not set.  The pins are no
 *     output's while a part is enabled.
 *
 *     FLAGS onwards are read only: FLAGS (link_sense_flag_t); PRESENT, bit
 *     n for address 0x40 + n answering the last scan; the ID the INA228
 *     gave (DEVICE_ID) and the one the INA3221 gave (die ID); transactions
 *     failed, modulo 65536; the INA228's die temperature in 0.1C, signed,
 *     and its DIAG_ALRT as read; its CHARGE in 0.01mAh, signed 32 bit, and
 *     its ENERGY in 0.01Wh, 32 bit, each low register first and counted
 *     since the run's arm; and the ESC's own telemetry voltage (10mV) and
 *     current (10mA), ESC_FLAGS bit 0 and bit 1 saying each is valid --
 *     here because BENCH carries the INA228's while it answers.
 *
 *     The output encoder (protocol 4.9) is an ams OSRAM AS5600 magnetic
 *     angle sensor on the same bus, at its fixed address 0x36, on the horn
 *     shaft of the servo under test.  ENABLE bit 2 turns it on and has no
 *     parameter of its own: the bus pins are the INA parts', and the angle
 *     comes back as the 12-bit count, 0 to 4095 for one turn (0.0879 degrees
 *     a count), with no centre applied -- the panel keeps that.  The
 *     IOmcu reads it at 500Hz.  A bit 2 written to a 4.8 or older
 *     IOmcu is not sent: the panel gates it on minor >= 9.
 *
 *     AS5600_FLAGS (link_sense_enc_flag_t) say whether it answers and what
 *     its magnet is doing.  AS5600_ANGLE is RAW ANGLE as last read, 0 until
 *     the first read of a set-up.  It is a position only while ENC_ONLINE,
 *     ENC_VALID and ENC_MD are all set: with MD clear the part sees no
 *     magnet and the count means nothing.  With ML or MH set beside MD the
 *     count is a position whose noise the datasheet does not specify.  AS5600_MAGNITUDE is the part's CORDIC
 *     (coordinate rotation digital computer) magnitude, read at 20Hz, 0
 *     until read; it is a measure of the field.  AS5600_SAMPLES counts the
 *     angle reads, modulo 65536: two reads of the page with the same count
 *     are one sample.  AS5600_STILL_MS is how long the angle has stayed
 *     within 12 counts (1.05 degrees) of an anchor -- the angle at the last
 *     time it left that band -- in milliseconds, saturating at 65535, 0 with
 *     no sample and 0 while MD is clear: without a magnet the count is not
 *     a position, and the anchor starts afresh when MD returns.  A move that ends at time t_end, read at time t_read, shows
 *     STILL_MS = t_read - t_end to within the 2ms sample interval, so the
 *     panel times the end of a move to the IOmcu's resolution
 *     whatever its own polling interval.
 *
 *     RESETS (register 31, protocol 4.11) counts the times a current
 *     monitor was found running on its power-on set-up and not the one
 *     written to it: the INA228 in the low byte, the INA3221 in the high
 *     byte, each modulo 256, since the set-up in force was taken.  The
 *     IOmcu reads the INA228's ADC_CONFIG and the INA3221's
 *     Configuration back every 40ms; a part found reset loses ONLINE and
 *     is set up again 1000ms on.  The count shows a reset that was found
 *     and repaired between two reads of FLAGS.  Before 4.11 the register
 *     is reserved and reads 0.
 *
 *     ENABLE to register 11 are kept in the IOmcu's flash beside the
 *     bindings and the supply's wiring, and the bus is opened at boot. */
enum {
    LINK_SN_ENABLE          = 0,
    LINK_SN_SDA_PIN         = 1,
    LINK_SN_SCL_PIN         = 2,
    LINK_SN_KHZ             = 3,
    LINK_SN_I228_ADDR       = 4,
    LINK_SN_I228_SHUNT_UOHM = 5,
    LINK_SN_I228_MAX_DA     = 6,
    LINK_SN_RESERVED_7      = 7,   
    LINK_SN_I3221_ADDR      = 8,
    LINK_SN_I3221_SHUNT_DMOHM = 9,
    LINK_SN_I3221_CHANNELS  = 10,
    LINK_SN_RESERVED_11     = 11,  
    LINK_SN_FLAGS           = 12,  
    LINK_SN_PRESENT         = 13,
    LINK_SN_I228_ID         = 14,
    LINK_SN_I3221_ID        = 15,
    LINK_SN_ERRORS          = 16,
    LINK_SN_I228_TEMP_DC    = 17,  
    LINK_SN_I228_DIAG       = 18,
    LINK_SN_I228_CHARGE_LO  = 19,  
    LINK_SN_I228_CHARGE_HI  = 20,
    LINK_SN_I228_ENERGY_LO  = 21,  
    LINK_SN_I228_ENERGY_HI  = 22,
    LINK_SN_ESC_VOLTAGE_CV  = 23,  
    LINK_SN_ESC_CURRENT_CA  = 24,  
    LINK_SN_ESC_FLAGS       = 25,
    LINK_SN_AS5600_FLAGS    = 26,  
    LINK_SN_AS5600_ANGLE    = 27,  
    LINK_SN_AS5600_MAGNITUDE = 28, 
    LINK_SN_AS5600_SAMPLES  = 29,  
    LINK_SN_AS5600_STILL_MS = 30,  
    LINK_SN_RESETS          = 31,  
    LINK_SN_COUNT           = 32,
};
#define LINK_SN_COUNT_V48 26u
#define LINK_SN_CONFIG_COUNT 12u

#define LINK_SN_EN_I228   0x01u
#define LINK_SN_EN_I3221  0x02u
#define LINK_SN_EN_AS5600 0x04u     
#define LINK_SN_EN_ALL    (LINK_SN_EN_I228 | LINK_SN_EN_I3221 | LINK_SN_EN_AS5600)
 
/* The ranges a write is held to. */
#define LINK_SN_KHZ_BUS          400u
#define LINK_SN_I228_ADDR_MIN    0x40u
#define LINK_SN_I228_ADDR_MAX    0x4Fu
#define LINK_SN_I228_UOHM_MIN      50u
#define LINK_SN_I228_UOHM_MAX   20000u
#define LINK_SN_I228_DA_MIN        10u
#define LINK_SN_I228_DA_MAX      3000u
#define LINK_SN_I3221_ADDR_MIN   0x40u
#define LINK_SN_I3221_ADDR_MAX   0x43u
#define LINK_SN_I3221_DMOHM_MIN    50u
#define LINK_SN_I3221_DMOHM_MAX 10000u
#define LINK_SN_I3221_CH_ALL     0x07u

static inline bool link_sn_pins_pair(unsigned sda, unsigned scl)
{
    return (sda % 2u) == 0u && scl == sda + 1u;
}

typedef enum {
    LINK_SN_I228_ONLINE    = 1u << 0, 
    LINK_SN_I228_ID_OK     = 1u << 1,
    LINK_SN_I228_ID_WRONG  = 1u << 2,
    LINK_SN_I228_CLIPPED   = 1u << 3,
    LINK_SN_I3221_ONLINE   = 1u << 4,
    LINK_SN_I3221_ID_OK    = 1u << 5,
    LINK_SN_I3221_ID_WRONG = 1u << 6,
    LINK_SN_BUS_OPEN       = 1u << 8, 
    LINK_SN_BUS_STUCK      = 1u << 9, 
} link_sense_flag_t;

#define LINK_SN_RESETS_I228(r)  ((uint8_t)((r) & 0xFFu))
#define LINK_SN_RESETS_I3221(r) ((uint8_t)(((r) >> 8) & 0xFFu))

typedef enum {
    LINK_SN_ENC_ONLINE = 1u << 0,
    LINK_SN_ENC_MD     = 1u << 1,
    LINK_SN_ENC_ML     = 1u << 2,
    LINK_SN_ENC_MH     = 1u << 3,
    LINK_SN_ENC_WRONG  = 1u << 4,
    LINK_SN_ENC_VALID  = 1u << 5,
} link_sense_enc_flag_t;

#define LINK_SN_ESC_VOLTAGE_OK 0x01u
#define LINK_SN_ESC_CURRENT_OK 0x02u
 
/* --- the SERVO_SENSE page (protocol 4.7): the INA3221's three channels,
 *     and a move timed on the IOmcu's clock.
 *
 *     Registers 0 to 11, four a channel from CH1: the mean and the highest
 *     current in mA, signed, and the mean and the lowest bus voltage in mV,
 *     at the load side of the shunt, over the last 50ms window.  WINDOW
 *     numbers the windows, modulo 65536; a read does not end one, so a
 *     reply lost on the link loses nothing.  CH_FLAGS bits 0..2 say a
 *     channel's window holds readings; bits 4..6 that one of them read the
 *     top of the range, 163.8mV across the shunt, which makes that
 *     channel's mean and highest current lower bounds and not values; bit 7
 *     the same of the capture's move.
 *
 *     CAP_ARM to CAP_BAND_MA are a capture, one frame: CAP_ARM with bit 7
 *     set, the INA3221 channel in bits 0..1 (1: CH2 and CH3 are refused,
 *     LINK_SS_CAP_CH) and in bits 8..10 the
 *     output channel (0 to 7) whose next changed command starts the timing;
 *     the holding level the move ends at in mA, signed, -32768 to 32767
 *     (protocol 4.11; before it 0 to 32767, and 32768 to 65535 refused):
 *     a holding level near 0A reads below zero by the part's offset; the
 *     distance from
 *     the level before the command that counts as movement, and the band
 *     around the holding level that counts as arrival, each 1 to 32767mA.
 *     An arm is the whole frame from CAP_ARM; an arm restarts a capture
 *     already running.  CAP_ARM written 0 disarms and is never refused,
 *     alone or at the head of the frame, whose other registers are then not
 *     stored.  Refused with BAD_VALUE: any other write that is not the
 *     whole frame, CAP_ARM bits outside the three fields, a value out of
 *     range, an INA3221 channel other than CH1 or one SENSE does not read,
 *     and an output channel
 *     that is not a surface rendered by a PWM slot; with NOT_ARMED on a
 *     disarmed bank.  A bank that stops driving ends a capture that has not
 *     finished: CAP_ARM reads 0 and CAP_STATE idle.
 *
 *     CAP_STATE onwards are read only: the state (link_cap_state_t);
 *     captures finished, modulo 65536; the time from the PWM frame that
 *     carries the new pulse to the movement and to the arrival, in 0.1ms,
 *     6553.5ms at most, resolved to CH1's 1ms sample interval; the
 *     highest and the mean filtered current of the move in mA, signed,
 *     over CAP_SAMPLES samples.  A capture ends arrived, at a stop, late
 *     (movement and no arrival within 3000ms plus the meter's lag),
 *     unseen (no movement in that time) or lost (the INA3221 stopped
 *     answering, or no PWM edge came within 3000ms of the arm).
 *
 *     Not kept: an IOmcu restart reads 0 throughout. */
enum {
    LINK_SS_CH_MEAN_MA  = 0,   
    LINK_SS_CH_MAX_MA   = 1,
    LINK_SS_CH_MEAN_MV  = 2,
    LINK_SS_CH_MIN_MV   = 3,
    LINK_SS_CH_STRIDE   = 4,
};
#define LINK_SS_CHANNELS 3u
enum {
    LINK_SS_WINDOW       = 12,
    LINK_SS_CH_FLAGS     = 13,
    LINK_SS_CAP_ARM      = 14,
    LINK_SS_CAP_HOLD_MA  = 15,
    LINK_SS_CAP_MOVE_MA  = 16,
    LINK_SS_CAP_BAND_MA  = 17,
    LINK_SS_CAP_STATE    = 18,  
    LINK_SS_CAP_SEQ      = 19,
    LINK_SS_CAP_MOVE_T   = 20,  
    LINK_SS_CAP_ARRIVE_T = 21,  
    LINK_SS_CAP_PEAK_MA  = 22,
    LINK_SS_CAP_MEAN_MA  = 23,
    LINK_SS_CAP_SAMPLES  = 24,
    LINK_SS_COUNT        = 25,
};
#define LINK_SS_CAP_FRAME 4u

#define LINK_SS_CH_VALID(ch)   ((uint16_t)(1u << ((unsigned)(ch) - 1u)))
#define LINK_SS_CH_CLIPPED(ch) ((uint16_t)(1u << ((unsigned)(ch) + 3u)))
#define LINK_SS_CAP_CLIPPED    0x80u

#define LINK_SS_ARM            0x80u
#define LINK_SS_ARM_OF(ch, out) \
    ((uint16_t)(LINK_SS_ARM | ((unsigned)(ch) & 0x03u) \
                | (((unsigned)(out) & 0x07u) << 8)))
#define LINK_SS_ARM_CH(r)      ((uint8_t)((r) & 0x03u))
#define LINK_SS_ARM_OUT(r)     ((uint8_t)(((r) >> 8) & 0x07u))
#define LINK_SS_ARM_BITS       0x0F83u
#define LINK_SS_ARM_PORT       0x0800u
#define LINK_SS_CAP_CH         1u

typedef enum {
    LINK_CAP_IDLE      = 0,
    LINK_CAP_ARMED     = 1, 
    LINK_CAP_WAIT_MOVE = 2, 
    LINK_CAP_MOVING    = 3,
    LINK_CAP_ARRIVED   = 4, 
    LINK_CAP_AT_STOP   = 5, 
    LINK_CAP_LATE      = 6, 
    LINK_CAP_UNSEEN    = 7, 
    LINK_CAP_LOST      = 8, 
} link_cap_state_t;
 
/* --- the SERVO_WIN page (protocol 4.11): the INA3221's CH1, the servo
 *     under test, as its last four 50ms windows.  Read only: every write
 *     is refused with READ_ONLY.
 *
 *     SERVO_SENSE shows the last window alone, so a host whose reads lie
 *     further apart than 50ms misses windows.  Here a host takes each
 *     window number once, and misses none while two of its reads lie at
 *     most 200ms apart.
 *
 *     WINDOW is the number of the newest complete window, modulo 65536,
 *     the number SERVO_SENSE's WINDOW shows.  FLAGS bit 0 (LINK_SW_HAVE)
 *     says a window has closed under the set-up in force, so WINDOW is a
 *     number; bit 7 (LINK_SW_CAP_CLIPPED) is SERVO_SENSE's capture bit.
 *     CAP_STATE and CAP_SEQ read as SERVO_SENSE's registers 18 and 19, so
 *     one read shows the windows and whether a capture has ended.
 *
 *     Then four entries of six registers, newest first: entry k, from
 *     register 4 + 6 k, is window number WINDOW - k.  Mean, highest and
 *     lowest current in mA, signed; mean and lowest bus voltage in mV, at
 *     the load side of the shunt; and the entry's flags.  The schedule
 *     reads CH1's current every 1ms and its bus voltage every 24ms: a
 *     window holds up to 50 current samples and 2 or 3 voltage samples.
 *
 *     An entry's flags: bit 15 (LINK_SW_E_CLOSED) a window closed with
 *     this number -- clear for a number the IOmcu skipped because
 *     its tick ran late by more than a window, and for a number before
 *     the first window, and the entry then reads 0 throughout; bit 8
 *     (LINK_SW_E_CURRENT) the window holds current samples; bit 9
 *     (LINK_SW_E_VOLTAGE) it holds voltage samples; bit 10
 *     (LINK_SW_E_CLIP_HI) a current sample read the top of the range,
 *     163.8mV across the shunt; bit 11 (LINK_SW_E_CLIP_LO) one read the
 *     bottom; bits 0..7 the number of samples that did, held at 255.
 *
 *     A clipped sample counts in an entry as the reading it is: the end
 *     of the range, 1.638A or -1.6384A on the 0.1Ohm shunt, in the
 *     mean, the highest and the lowest.  SERVO_SENSE's registers 0 to 11
 *     leave a clipped sample out of their figures, so the two pages
 *     differ for a window with a clipped sample, and only for such a
 *     window.
 *
 *     A window being filled when the INA3221 is found reset (SENSE's
 *     RESETS) is emptied: its entry is closed and holds no samples.
 *
 *     Not kept, and cleared by a SENSE set-up taken. */
enum {
    LINK_SW_WINDOW    = 0,
    LINK_SW_FLAGS     = 1,
    LINK_SW_CAP_STATE = 2,   
    LINK_SW_CAP_SEQ   = 3,
    LINK_SW_ENTRIES   = 4,   
    LINK_SW_COUNT     = 28,
};
#define LINK_SW_RING 4u
enum {
    LINK_SW_E_MEAN_MA = 0,   
    LINK_SW_E_MAX_MA  = 1,   
    LINK_SW_E_MIN_MA  = 2,   
    LINK_SW_E_MEAN_MV = 3,
    LINK_SW_E_MIN_MV  = 4,
    LINK_SW_E_FLAGS   = 5,
    LINK_SW_E_STRIDE  = 6,
};
#define LINK_SW_ENTRY(k, r) \
    ((unsigned)LINK_SW_ENTRIES + (unsigned)(k) * LINK_SW_E_STRIDE + (unsigned)(r))

#define LINK_SW_HAVE        0x01u
#define LINK_SW_CAP_CLIPPED 0x80u

#define LINK_SW_E_CLIPPED(f) ((uint8_t)((f) & 0xFFu))
#define LINK_SW_E_CLIPPED_MAX 255u
#define LINK_SW_E_CURRENT   0x0100u
#define LINK_SW_E_VOLTAGE   0x0200u
#define LINK_SW_E_CLIP_HI   0x0400u
#define LINK_SW_E_CLIP_LO   0x0800u
#define LINK_SW_E_CLOSED    0x8000u
 
/* --- the SENSE_MAP page (protocol 4.25): up to four INA3221 parts on the
 *     sensor bus, at 0x40 to 0x43, three channels each.  Channel c is
 *     part a's channel ch for c = 3 a + ch - 1, so 0 to 11.
 *
 *     ENABLE bit a: the part at 0x40 + a is fitted.  FAST: the channel
 *     read every 1ms, whose last four windows SERVO_WIN carries and
 *     on which SERVO_SENSE times a move; 0xFF (LINK_SM_FAST_NONE) none.
 *     SHUNT[c]: channel c's shunt in 0.1mOhm, 50 to 10000, 0 = the
 *     channel is off and never read.  WATCH[c]: what channel c measures,
 *     for the panel's screens and logs; the IOmcu keeps it and acts on
 *     nothing in it.
 *
 *     Registers 0 to 25 are kept in the IOmcu's flash.  A write lies
 *     within them: one that reaches register 26 is refused with
 *     READ_ONLY.  The registers written are merged into the map and the
 *     whole map judged; a map refused leaves every register as it was.
 *     Refused with BAD_VALUE: ENABLE above 15; FAST not 0xFF and past 11,
 *     on a part not fitted or on a channel whose SHUNT is 0; a SHUNT not 0
 *     outside 50 to 10000; a WATCH value outside the list below; a fitted
 *     part with all three SHUNT 0; a fitted part on the address of the
 *     INA228 while SENSE enables it; any change while the bank drives.
 *     A part not fitted keeps the values written for it, judged by range
 *     alone.
 *
 *     ID[a] (read only): the die ID part a answered at its last probe, 0
 *     before one.  FLAGS (read only): bit a part a online; bit 4 + a part
 *     a answered with another identity; bit 8 (LINK_SM_IN_FORCE) the map
 *     has been written and is kept; bit 9 (LINK_SM_DERIVED) it has never
 *     been written and is SENSE's one part (below).
 *
 *     SENSE and the map.  Until the map is first written it is derived
 *     from SENSE: ENABLE bit 1 fits the part at SENSE's I3221_ADDR, each
 *     channel in I3221_CHANNELS has SENSE's shunt, FAST is that part's
 *     CH1 when it is read, and nothing is watched.  Once written, SENSE's
 *     ENABLE bit 1 and registers 8 to 10 mirror the map: bit 1 set while
 *     a part is fitted; I3221_ADDR the mirror part -- FAST's part, or
 *     the lowest fitted part while FAST is 0xFF; I3221_SHUNT_DMOHM that
 *     part's CH1 shunt, or its first one not 0; I3221_CHANNELS its
 *     channels with a shunt.  A SENSE write that would change bit 1 or
 *     registers 8 to 10 is then refused with BAD_VALUE.  SERVO_SENSE's
 *     registers 0 to 11 are the mirror part's three channels, and a
 *     capture's channel 1 (LINK_SS_CAP_CH) is FAST. */
enum {
    LINK_SM_ENABLE   = 0,
    LINK_SM_FAST     = 1,
    LINK_SM_SHUNT_0  = 2,    
    LINK_SM_WATCH_0  = 14,   
    LINK_SM_KEPT     = 26,   
    LINK_SM_ID_0     = 26,   
    LINK_SM_FLAGS    = 30,
    LINK_SM_RESERVED_31 = 31,
    LINK_SM_COUNT    = 32,
};
#define LINK_SM_PARTS        4u
#define LINK_SM_CHANNELS    12u
#define LINK_SM_SHUNT(c)    ((unsigned)LINK_SM_SHUNT_0 + (unsigned)(c))
#define LINK_SM_WATCH(c)    ((unsigned)LINK_SM_WATCH_0 + (unsigned)(c))
#define LINK_SM_ID(a)       ((unsigned)LINK_SM_ID_0 + (unsigned)(a))
#define LINK_SM_FIT_ALL     0x000Fu
#define LINK_SM_FAST_NONE   0x00FFu
#define LINK_SM_DMOHM_MIN   50u
#define LINK_SM_DMOHM_MAX   10000u
#define LINK_SM_WATCH_NONE    0x00u
#define LINK_SM_WATCH_OUT(n)  (0x01u + (unsigned)(n))   
#define LINK_SM_WATCH_PORT(n) (0x10u + (unsigned)(n))   
#define LINK_SM_WATCH_SUPPLY  0x20u     
#define LINK_SM_ONLINE(a)    (1u << (unsigned)(a))
#define LINK_SM_ID_WRONG(a)  (1u << (4u + (unsigned)(a)))
#define LINK_SM_IN_FORCE     0x0100u
#define LINK_SM_DERIVED      0x0200u
 
/* --- the SENSE_WIN_A and SENSE_WIN_B pages (protocol 4.25): every
 *     channel's last complete 50ms window, channels 0 to 5 on A and 6 to
 *     11 on B.  Read only: every write is refused with READ_ONLY.
 *
 *     WINDOW is the window's number, SERVO_SENSE's WINDOW.  FLAGS: bit a
 *     part a online, on both pages; bit 8 (LINK_SX_HAVE) a window has
 *     closed under the set-up in force.  Then six entries of five
 *     registers, entry k from register 2 + 5 k the page's channel k: mean
 *     and highest current in mA, signed; mean and lowest bus voltage in
 *     mV; the entry's flags -- bit 0 current samples, bit 1 voltage
 *     samples, bit 2 a current sample at the top of the range, bit 3 one
 *     at the bottom.  A clipped sample is left out of the figures, as on
 *     SERVO_SENSE.  A channel off, or of a part not online, reads 0
 *     throughout.  Rates: FAST every 1ms; every other channel with a
 *     shunt in turn, one a 1ms tick (1000 / n Hz for n of them, 90.9Hz
 *     with 11); each bus voltage every 24ms.  Not kept. */
enum {
    LINK_SX_WINDOW   = 0,
    LINK_SX_FLAGS    = 1,
    LINK_SX_ENTRIES  = 2,
    LINK_SX_COUNT    = 32,
};
#define LINK_SX_PER_PAGE 6u
enum {
    LINK_SX_E_MEAN_MA = 0,   
    LINK_SX_E_MAX_MA  = 1,   
    LINK_SX_E_MEAN_MV = 2,
    LINK_SX_E_MIN_MV  = 3,
    LINK_SX_E_FLAGS   = 4,
    LINK_SX_E_STRIDE  = 5,
};
#define LINK_SX_E(k, r) \
    ((unsigned)LINK_SX_ENTRIES + (unsigned)(k) * LINK_SX_E_STRIDE + (unsigned)(r))
#define LINK_SX_HAVE        0x0100u
#define LINK_SX_E_CURRENT   0x0001u
#define LINK_SX_E_VOLTAGE   0x0002u
#define LINK_SX_E_CLIP_HI   0x0004u
#define LINK_SX_E_CLIP_LO   0x0008u
 
/* --- the SENSE_LIMIT page (protocol 4.27): a current limit for each of
 *     SENSE_MAP's 12 channels, and the windows that passed them.  An
 *     alert only: a limit passed stops nothing and drives nothing.
 *
 *     LIMIT_MA[c] (registers 0 to 11): channel c's limit in mA, 1 to
 *     32767; 0 = none.  Kept in the IOmcu's flash.  A write lies within
 *     them: one that reaches register 12 is refused with READ_ONLY, a
 *     value above 32767 with BAD_VALUE, and a refused write stores none
 *     of its registers.  Taken in any bank state.
 *
 *     Core 1 judges each channel's window once, as it closes
 *     (sense_window_over()): over when its highest current, in mA as
 *     SENSE_WIN shows it, is above the limit, or when a sample read the
 *     top of the range and that top, unrounded, is above the limit.  A
 *     negative current is never over, nor a channel off or of a part not
 *     online at the close.  Core 0 adds what core 1 counted at each
 *     snapshot, so no window is missed however late it takes one.
 *
 *     OVER (register 12, read only): bit c set when a window of channel c
 *     was over since the last read of this register.  A read that covers
 *     register 12 clears it after the reply is filled; a reply lost on
 *     the link loses those bits, which OVER_COUNT still counts.
 *     OVER_COUNT (register 13, read only): channel windows over, modulo
 *     65536, since the IOmcu started.  Registers 14 and 15 are reserved:
 *     they read 0. */
enum {
    LINK_SL_LIMIT_0    = 0,     
    LINK_SL_KEPT       = 12,    
    LINK_SL_OVER       = 12,
    LINK_SL_OVER_COUNT = 13,
    LINK_SL_COUNT      = 16,
};
#define LINK_SL_MA_MAX 32767u
 
/* --- the TONE page (protocol 4.8): the beeps of an ESC (electronic speed
 *     controller), heard on one motor phase.  One GPIO reads the phase
 *     through a series resistor and a zener clamp; a PIO (programmable
 *     input/output) state machine stamps its edges at 26.7ns, and
 *     protocols/phase_tap/tone.c turns them into beeps and their pitch.
 *
 *     ENABLE to F_MAX_HZ are one frame and SPLIT_PCT to register 7 the
 *     next.  ENABLE bit 0 runs the tap.  PIN is the GPIO.  F_MIN_HZ and
 *     F_MAX_HZ bound the tones heard: 50 to 2000Hz, and F_MIN_HZ + 1 to
 *     6900Hz (EVT_FREQ_DHZ holds 0.1Hz in 16 bits, to 6553.5Hz).
 *     SPLIT_PCT is how far a pitch moves, in percent, to start a new beep
 *     without a silence: 0 splits on silence only, 50 at most.  GAP_MS is
 *     the silence that ends a beep, 1 to 100ms and at least the period of
 *     F_MIN_HZ.  MIN_PERIODS is how many tone periods make a beep, 1 to
 *     64.  Register 7 reads 0 and takes only 0.
 *
 *     Refused with BAD_VALUE: a value out of its range, a combination the
 *     detector refuses (tone_init()), and, while the tap is enabled, a pin
 *     past the bank, one the board reserves, or an ADC (analog to digital
 *     converter) pin: GP26 to GP29 on the RP2350A and GP40 to GP47 on the
 *     RP2354B, rated IOVDD + 0.5V and not fault tolerant, and any pin on
 *     an IOmcu whose core 1 did not start at boot: no capture runs
 *     before a restart.  Refused with
 *     BUSY (since 4.17, BAD_VALUE before): while the tap is enabled, a pin
 *     bound to an output or held by the SENSE, SUPPLY or PROG page, and a
 *     capture the wiring cannot start for now -- core 1 in a pass, or no
 *     PIO state machine or DMA channel left.  Freed, the same write is
 *     taken.  The pin is no output's while the tap
 *     is enabled, and an OUTPUTS write that binds it is refused, as are a
 *     SENSE or SUPPLY write that takes it.  A change is taken armed or
 *     not: the tap is an input and drives nothing.
 *
 *     FLAGS onwards are read only: FLAGS (link_tone_flag_t); WINDOW, the
 *     detector's 8ms windows counted modulo 65536; WIN_FREQ_DHZ, the last
 *     window's tone in 0.1Hz, 0 with no tone; WIN_PERIODS, the periods in
 *     it.
 *
 *     The IOmcu keeps the last LINK_TN_RING beeps and numbers them
 *     from 1 to 65535, then from 1 again.  BEEP_HEAD is the newest number,
 *     0 before the first beep.  EVT_SEL names the beep that EVT_SEQ to
 *     EVT_FLAGS show.  It is the one writable register after register 7,
 *     it is not kept, and a read does not consume a beep, so a reply lost
 *     on the link loses nothing.  EVT_SEQ equals EVT_SEL while that beep is
 *     in the ring; when it has left the ring, or has not happened yet,
 *     EVT_SEQ and registers 15 to 21 read 0.  EVT_START_MS is the beep's
 *     first rise in ms since the capture started (ENABLE written 1, or PIN
 *     changed while enabled), 32 bit, low register first (49.7 days);
 *     EVT_LEN_DMS its length to its last edge in 0.1ms, to 6553.5ms;
 *     EVT_FREQ_DHZ its mean pitch in 0.1Hz; EVT_BURSTS its bursts, to
 *     65535; EVT_CARRIER_HHZ the carrier it was chopped at in 100Hz
 *     steps, 0 unchopped.  A length, pitch, burst count or carrier past its
 *     register reads as the largest it holds.  EVT_FLAGS bit 0: the beep
 *     began at a pitch change with no silence before it; bit 1: it ended
 *     at one.
 *     LOST counts beeps dropped, modulo 65536: the detector's queue full,
 *     or the hand-over between the cores full.  GLITCHES counts lows the
 *     detector ignored as shorter than 500ns, modulo 65536.  The
 *     capture's 8us hold-off removes every low shorter than 8us before
 *     the detector sees it, so the register reads 0 on the tap.
 *
 *     The capture starts when the tap is enabled or its pin changes, and
 *     then empties the ring; the numbers go on.  Registers 0 to 6 are kept
 *     in the IOmcu's flash beside the SENSE set-up, and the tap starts
 *     at boot.  Nothing else is kept.
 *
 *     While the tap is disabled the pin is an input with its pull-down on,
 *     so a wire connected to nothing reads low.  The panel's read at
 *     20Hz is registers 8 to 23: a request and 4 data frames. */
enum {
    LINK_TN_ENABLE       = 0,
    LINK_TN_PIN          = 1,
    LINK_TN_F_MIN_HZ     = 2,
    LINK_TN_F_MAX_HZ     = 3,
    LINK_TN_SPLIT_PCT    = 4,
    LINK_TN_GAP_MS       = 5,
    LINK_TN_MIN_PERIODS  = 6,
    LINK_TN_RESERVED_7   = 7,   
    LINK_TN_FLAGS        = 8,   
    LINK_TN_WINDOW       = 9,
    LINK_TN_WIN_FREQ_DHZ = 10,
    LINK_TN_WIN_PERIODS  = 11,
    LINK_TN_BEEP_HEAD    = 12,
    LINK_TN_EVT_SEL      = 13,  
    LINK_TN_EVT_SEQ      = 14,
    LINK_TN_EVT_START_LO = 15,  
    LINK_TN_EVT_START_HI = 16,
    LINK_TN_EVT_LEN_DMS  = 17,  
    LINK_TN_EVT_FREQ_DHZ = 18,  
    LINK_TN_EVT_BURSTS   = 19,
    LINK_TN_EVT_CARRIER_HHZ = 20, 
    LINK_TN_EVT_FLAGS    = 21,
    LINK_TN_LOST         = 22,
    LINK_TN_GLITCHES     = 23,
    LINK_TN_COUNT        = 24,
};
#define LINK_TN_CONFIG_COUNT 7u

#define LINK_TN_EN_TAP   0x01u

#define LINK_TN_F_MIN_LO       50u
#define LINK_TN_F_MIN_HI     2000u
#define LINK_TN_F_MAX_HI     6900u
#define LINK_TN_SPLIT_MAX      50u
#define LINK_TN_GAP_MS_MIN      1u
#define LINK_TN_GAP_MS_MAX    100u
#define LINK_TN_PERIODS_MIN     1u
#define LINK_TN_PERIODS_MAX    64u
#define LINK_TN_RING           64u

#define LINK_TN_DEFAULT_PIN        22u
#define LINK_TN_DEFAULT_F_MIN     400u
#define LINK_TN_DEFAULT_F_MAX    6500u
#define LINK_TN_DEFAULT_SPLIT       8u
#define LINK_TN_DEFAULT_GAP_MS      3u
#define LINK_TN_DEFAULT_PERIODS     3u

typedef enum {
    LINK_TN_RUNNING     = 1u << 0,
    LINK_TN_PIN_REFUSED = 1u << 1,
    LINK_TN_OVERRUN     = 1u << 2,
    LINK_TN_BEEP        = 1u << 3,
    LINK_TN_TONE        = 1u << 4,
} link_tone_flag_t;

#define LINK_TN_EVT_AFTER_CHANGE  0x01u
#define LINK_TN_EVT_BEFORE_CHANGE 0x02u
 
#define LINK_OS_RANGE_OF(first, count) \
    ((uint16_t)((((unsigned)(first) & 0xFFu) << 8) | ((unsigned)(count) & 0xFFu)))
#define LINK_OS_FIRST(range) ((uint8_t)((range) >> 8))
#define LINK_OS_CHANNELS(range) ((uint8_t)((range) & 0xFFu))

typedef enum {
    LINK_DRIVER_NONE        = 0,
    LINK_DRIVER_PWM         = 1,
    LINK_DRIVER_PPM         = 2,
    LINK_DRIVER_DSHOT       = 3,
    /*
     * Bidirectional DShot is its own driver rather than a flag on the one
     * above.  It inverts the line and the checksum, so an ESC (electronic
     * speed controller) set up for one protocol ignores the other entirely;
     * a slot that could be switched between them by a flag would look like
     * one output with a setting instead of two incompatible wires.
     */
    LINK_DRIVER_DSHOT_BIDIR = 4,
} link_out_driver_t;
 
/* -------------------------------------------------------------------- bind */

enum {
    LINK_BD_COMMIT = 0, 
    LINK_BD_COUNT  = 1,
};
 
/* ---------------------------------------------------------------- identity */
enum {
    LINK_ID_PROTOCOL_MAJOR = 0,
    LINK_ID_PROTOCOL_MINOR = 1,
    LINK_ID_FIRMWARE_MAJOR = 2,
    LINK_ID_FIRMWARE_MINOR = 3,
    LINK_ID_FIRMWARE_PATCH = 4,
    LINK_ID_HARDWARE       = 5, 
    LINK_ID_CAPABILITIES   = 6, 
    LINK_ID_COUNT          = 7,
};

typedef enum {
    LINK_CAP_ESC_DRIVE   = 1u << 0, 
    LINK_CAP_ESC_TELEM   = 1u << 1, 
    LINK_CAP_SERVO_PWM   = 1u << 2, 
    LINK_CAP_SERVO_SENSE = 1u << 3, 
    LINK_CAP_PACK_SENSE  = 1u << 4, 
    LINK_CAP_RECEIVER    = 1u << 5, 
    LINK_CAP_VIBRATION   = 1u << 6, 
    LINK_CAP_CELLS       = 1u << 7, 
    LINK_CAP_PROGRAM     = 1u << 8, 
} link_cap_t;
 
/* ------------------------------------------------------------------ status */
enum {
    LINK_ST_STATE      = 0, 
    LINK_ST_FAULTS     = 1, 
    LINK_ST_UPTIME_MS_LO = 2,
    LINK_ST_UPTIME_MS_HI = 3,
    LINK_ST_FRAMES_LO  = 4, 
    LINK_ST_FRAMES_HI  = 5, 
    LINK_ST_CRC_ERRORS = 6,
    LINK_ST_RESYNCS    = 7,
    LINK_ST_REFUSED_LO = 8,
    LINK_ST_REFUSED_HI = 9,
    LINK_ST_COUNT      = 10,
};
#define LINK_ST_COUNT_V420 8u

typedef enum {
    LINK_FAULT_NONE          = 0,
    LINK_FAULT_LINK_SILENT   = 1u << 0,
    LINK_FAULT_OVERCURRENT   = 1u << 1,
    LINK_FAULT_OVERTEMP      = 1u << 2,
    LINK_FAULT_STALL         = 1u << 3,
    LINK_FAULT_HEARTBEAT     = 1u << 4, 
    LINK_FAULT_VERSION       = 1u << 5, 
    LINK_FAULT_STORE_OFF     = 1u << 6,
} link_fault_t;

typedef enum {
    LINK_STATE_IDLE     = 0, 
    LINK_STATE_ARMED    = 1, 
    LINK_STATE_FAILSAFE = 2, 
} link_dev_state_t;
 
/* ------------------------------------------------------------------- bench */
enum {
    LINK_BN_VOLTAGE_CV   = 0,  
    LINK_BN_CURRENT_CA   = 1,  
    LINK_BN_POWER_W      = 2,  
    LINK_BN_RPM          = 3,
    LINK_BN_TEMP_ESC_DC  = 4,  
    LINK_BN_TEMP_MOT_DC  = 5,  
    LINK_BN_CHARGE_MAH   = 6,  
    LINK_BN_ENERGY_DWH   = 7,  
    LINK_BN_VOLT_MIN_CV  = 8,  
    LINK_BN_CURR_MAX_CA  = 9,
    LINK_BN_POWER_MAX_W  = 10,
    LINK_BN_RPM_MAX      = 11,
    LINK_BN_FLAGS        = 12, 
    LINK_BN_COUNT        = 13,
};

typedef enum {
    LINK_BN_VOLTAGE_OK = 1u << 0, 
    LINK_BN_CURRENT_OK = 1u << 1,
    LINK_BN_RPM_OK     = 1u << 2,
    LINK_BN_TEMP_OK    = 1u << 3,
    LINK_BN_TEMP_MOT_OK = 1u << 4,
    LINK_BN_SENSED     = 1u << 5,
    LINK_BN_TOTALS_OK  = 1u << 6,
    LINK_BN_SIMULATED  = 1u << 7,
} link_bench_flag_t;
 
/* --------------------------------------------------------------- catalogue */

#define LINK_CAT_PINS  32u
#define LINK_CAT_COUNT LINK_CAT_PINS

#define LINK_CAT_OF(gpio, pad, hold) \
    ((uint16_t)((((unsigned)(gpio) & 0x3Fu) << 10) \
                | (((unsigned)(pad) & 0x3Fu) << 4) \
                | ((unsigned)(hold) & 0x0Fu)))
#define LINK_CAT_GPIO(r) ((uint8_t)(((r) >> 10) & 0x3Fu))
#define LINK_CAT_PAD(r)  ((uint8_t)(((r) >> 4) & 0x3Fu))
#define LINK_CAT_HOLD(r) ((uint8_t)((r) & 0x0Fu))

typedef enum {
    LINK_PIN_FREE      = 0,  
    LINK_PIN_HEARTBEAT = 1,  
    LINK_PIN_CAN       = 2,  
    LINK_PIN_FLASH     = 3,
    LINK_PIN_DEBUG     = 4,
    LINK_PIN_SENSOR    = 5,
    LINK_PIN_OTHER     = 15, 
} link_pin_hold_t;
 
/* ------------------------------------------------------------------- shape */

enum {
    LINK_SH_WIDTH_CMM  = 0, 
    LINK_SH_HEIGHT_CMM = 1, 
    LINK_SH_LAYOUT     = 2, 
    LINK_SH_PITCH_CMM  = 3, 
    LINK_SH_INSET_CMM  = 4,
    LINK_SH_COUNT      = 5,
};
 
#define LINK_SH_LAYOUT_OF(corner, per_side) \
    ((uint16_t)((((unsigned)(corner) & 0xFFu) << 8) \
                | ((unsigned)(per_side) & 0xFFu)))
#define LINK_SH_CORNER(r)   ((uint8_t)(((r) >> 8) & 0xFFu))
#define LINK_SH_PER_SIDE(r) ((uint8_t)((r) & 0xFFu))

typedef enum {
    LINK_SH_BOTTOM_LEFT  = 0,
    LINK_SH_BOTTOM_RIGHT = 1,
    LINK_SH_TOP_LEFT     = 2,
    LINK_SH_TOP_RIGHT    = 3,
} link_shape_corner_t;
 
/* ----------------------------------------------------------------- artwork */

enum {
    LINK_AW_BLOCKS   = 0, 
    LINK_AW_WIDTH    = 1, 
    LINK_AW_HEIGHT   = 2, 
    LINK_AW_FORMAT   = 3, 
    LINK_AW_BYTES_LO = 4, 
    LINK_AW_BYTES_HI = 5,
    LINK_AW_CRC      = 6,
    LINK_AW_HASH_LO  = 7,
    LINK_AW_HASH_HI  = 8,
    LINK_AW_COUNT    = 9,
};

typedef enum {
    LINK_ART_NONE    = 0,
    LINK_ART_RGB565  = 1,
    LINK_ART_DRAWING = 2,
} link_art_format_t;

#define LINK_DRAW_VERSION      1u
#define LINK_DRAW_HEAD_BYTES   16u
#define LINK_DRAW_PAD_BYTES    8u
#define LINK_DRAW_SHAPE_BYTES  12u
#define LINK_DRAW_MAX_PADS     64u
#define LINK_DRAW_MAX_SHAPES   400u
#define LINK_DRAW_MAX_BYTES    (LINK_DRAW_HEAD_BYTES \
                                + LINK_DRAW_MAX_PADS * LINK_DRAW_PAD_BYTES \
                                + LINK_DRAW_MAX_SHAPES * LINK_DRAW_SHAPE_BYTES)
#define LINK_DRAW_PAD_GPIO     4u
#define LINK_DRAW_PAD_SQUARE   0x01u

typedef enum {
    LINK_DRAW_RECT  = 1,
    LINK_DRAW_RRECT = 2,
    LINK_DRAW_DISC  = 3,
    LINK_DRAW_LINE  = 4,
} link_draw_shape_kind_t;

enum {
    LINK_AD_BLOCK = 0,            
    LINK_AD_DATA  = 1,            
    LINK_AD_COUNT = LINK_MAX_REGS,
};
#define LINK_AD_WORDS ((unsigned)(LINK_AD_COUNT - LINK_AD_DATA))
#define LINK_AD_BYTES (LINK_AD_WORDS * 2u)
 
/* -------------------------------------------------------------------- pads */

#define LINK_PAD_SLOTS 32u
#define LINK_PAD_COUNT LINK_PAD_SLOTS

#define LINK_PAD_OF(pad, kind, dv) \
    ((uint16_t)((((unsigned)(pad) & 0x3Fu) << 10) \
                | (((unsigned)(kind) & 0x03u) << 8) \
                | ((unsigned)(dv) & 0xFFu)))
#define LINK_PAD_NUM(r)  ((uint8_t)(((r) >> 10) & 0x3Fu))
#define LINK_PAD_KIND(r) ((uint8_t)(((r) >> 8) & 0x03u))
#define LINK_PAD_DV(r)   ((uint8_t)((r) & 0xFFu))

typedef enum {
    LINK_PAD_NONE   = 0, 
    LINK_PAD_GROUND = 1, 
    LINK_PAD_POWER  = 2, 
    LINK_PAD_OTHER  = 3, 
} link_pad_kind_t;
 
/* --------------------------------------------------------------------- KST */
enum {
    LINK_KS_STATE = 0,   
    LINK_KS_SEQ   = 1,   
    LINK_KS_OP    = 2,   
    LINK_KS_RESULT = 3,  
    LINK_KS_FAIL  = 4,   
    LINK_KS_DIFF_LO = 5, 
    LINK_KS_DIFF_HI = 6, 
    LINK_KS_BAD_LO  = 7, 
    LINK_KS_BAD_HI  = 8,
    LINK_KS_FP_RULES = 9,    
    LINK_KS_FP_REGS_LO = 10, 
    LINK_KS_FP_REGS_HI = 11,
    LINK_KS_HALF_MIN_NS = 12, 
    LINK_KS_HALF_MAX_NS = 13,
    LINK_KS_DELAY_MIN_US = 14, 
    LINK_KS_DELAY_MAX_US = 15,
    LINK_KS_IMAGE = 16,  
    LINK_KS_COUNT = 32,
};

enum {
    LINK_KS_W_CMD = 0,   
    LINK_KS_W_SEQ = 1,   
    LINK_KS_W_KEY = 2,   
    LINK_KS_W_CRC = 3,   
    LINK_KS_W_IMAGE = 4, 
    LINK_KS_W_UNLOCK = 20,    
    LINK_KS_W_START_CRC = 24, 
    LINK_KS_W_VIEW = 25,      
    LINK_KS_W_SUPPLY_MV = 26, 
    LINK_KS_W_SUPPLY_MA = 27, 
    LINK_KS_W_LEAVE_MS = 28,  
    LINK_KS_W_COUNT = 29,
};

#define LINK_KS_W_CMD_FRAME 4u
#define LINK_KS_W_STAGED 21u
#define LINK_KS_IMAGE_REGS 16u

#define LINK_KST_WRITE_KEY 0x57A5u
 
#define LINK_KS_STATE_OF(r)   ((uint8_t)((r) & 0x7u))
#define LINK_KS_PORT_OF(r)    ((uint8_t)(((r) >> 12) & 0xFu))
#define LINK_KS_OP_OF(r)      ((uint8_t)(((r) >> 12) & 0xFu))
#define LINK_KS_FRAMES_OF(r)  ((uint16_t)((r) & 0xFFFu))
#define LINK_KS_W_CMD_CONFIRM 0x0080u
#define LINK_KS_W_CMD_PORT    0x0040u
#define LINK_KS_W_CMD_OF(op, port) \
    ((uint16_t)((unsigned)(op) | LINK_KS_W_CMD_PORT \
                | (((unsigned)(port) & 0xFu) << 8)))
#define LINK_KST_RESULT_SUPPLY 32u
#define LINK_KST_RESULT_NO_PATH 33u
#define LINK_KST_RESULT_TOO_COMPLEX 34u
#define LINK_KST_RESULT_PLANNING 35u

#define LINK_KST_LEAVE_MS_MAX 10000u
#define LINK_KST_LEAVE_MS_DEFAULT 100u

static inline uint16_t link_kst_crc(const uint16_t *regs, unsigned n)
{
    uint16_t crc = 0xFFFFu;
 
    for (unsigned i = 0; i < n; ++i) {
        const uint8_t b[2] = { (uint8_t)(regs[i] & 0xFFu),
                               (uint8_t)(regs[i] >> 8) };
        crc = link_crc(crc, b, sizeof(b));
    }
    return crc;
}

typedef enum {
    LINK_KST_PWM = 0,      
    LINK_KST_STOPPING = 1, 
    LINK_KST_LOW = 2,      
    LINK_KST_PROGRAMMING = 3, 
    LINK_KST_RAIL_OFF = 4, 
    LINK_KST_RAIL_WAIT = 5, 
    LINK_KST_LEAVING = 6,  
} link_kst_state_t;

enum {
    LINK_KS_F_BUSY      = 0x0008u, 
    LINK_KS_F_IN_MODE   = 0x0010u, 
    LINK_KS_F_MUST_READ = 0x0020u, 
    LINK_KS_F_IMAGE     = 0x0040u, 
    LINK_KS_F_BACKUP    = 0x0080u, 
    LINK_KS_F_FP_OK     = 0x0100u, 
    LINK_KS_F_LOCKED    = 0x0200u, 
    LINK_KS_F_RAIL      = 0x0400u, 
    LINK_KS_F_VIEW_BACKUP = 0x0800u, 
};

typedef enum {
    LINK_KST_OP_NONE = 0,     
    LINK_KST_OP_ENTER = 1,    
    LINK_KST_OP_READ_ALL = 2,
    LINK_KST_OP_WRITE = 3,    
    LINK_KST_OP_RESTORE = 4,  
    LINK_KST_OP_RELEASE = 5,  
    LINK_KST_OP_VERIFY = 6,   
    LINK_KST_OP_ABORT = 7,    
    LINK_KST_OP_POWER_CYCLED = 8, 
    LINK_KST_OP_REBOOT = 9,   
    LINK_KST_OP_LEAVE = 10,   
    LINK_KST_OP_COUNT
} link_kst_op_t;

typedef enum {
    LINK_KST_REF_NONE = 0,
    LINK_KST_REF_BUSY = 1,       
    LINK_KST_REF_PORT = 2,       
    LINK_KST_REF_UNSAFE = 5,     
    LINK_KST_REF_NOT_PROGRAMMING = 6, 
    LINK_KST_REF_NO_ENABLE = 7,  
    LINK_KST_REF_STAGED = 8,     
    LINK_KST_REF_START = 9,      
    LINK_KST_REF_MUST_READ = 10, 
    LINK_KST_REF_NO_IMAGE = 11,  
    LINK_KST_REF_PLAN_RULES = 12,   
    LINK_KST_REF_PLAN_R00 = 13,     
    LINK_KST_REF_PLAN_PAIRING = 14, 
    LINK_KST_REF_PLAN_NO_PATH = 15, 
    LINK_KST_REF_NO_PIN = 16,    
    LINK_KST_REF_SUPPLY_RANGE = 17, 
    LINK_KST_REF_NO_SUPPLY = 18, 
    LINK_KST_REF_LEAVE_MS = 19,  
    LINK_KST_REF_LOCKED = 20,    
    LINK_KST_REF_SUPPLY_LOW = 21, 
} link_kst_refusal_t;
 
/* -------------------------------------------------------------------- PROG */
enum {
    LINK_PG_COUNT  = 0,  
    LINK_PG_FLAGS  = 1,  
    LINK_PG_PWM    = 2,  
    LINK_PG_TARGET = 3,  
    LINK_PG_PORT0  = 4,
    LINK_PG_REGS_V424 = 24, 
    LINK_PG_FUNC0  = 24, 
    LINK_PG_REGS   = 28,
};
enum {
    LINK_PG_PIN    = 0,  
    LINK_PG_CMD    = 1,  
    LINK_PG_SLEW   = 2,  
    LINK_PG_MIN_US = 3,  
    LINK_PG_MAX_US = 4,  
    LINK_PG_STRIDE = 5,
};
typedef enum {
    LINK_PG_FN_SERVO_PWM = 0, 
    LINK_PG_FN_NONE      = 1, 
    LINK_PG_FN_DSHOT150  = 2, 
    LINK_PG_FN_DSHOT300  = 3, 
    LINK_PG_FN_DSHOT600  = 4, 
    LINK_PG_FN_COUNT     = 5,
} link_pg_func_t;

#define LINK_PG_FN_COUNT_V426 2u
#define LINK_PG_FN_IS_DSHOT(fn) \
    ((unsigned)(fn) - (unsigned)LINK_PG_FN_DSHOT150 \
     <= (unsigned)LINK_PG_FN_DSHOT600 - (unsigned)LINK_PG_FN_DSHOT150)

#define LINK_PG_FN_KBIT(fn) \
    ((unsigned)(fn) == (unsigned)LINK_PG_FN_DSHOT150 ? 150u \
     : (unsigned)(fn) == (unsigned)LINK_PG_FN_DSHOT300 ? 300u \
     : (unsigned)(fn) == (unsigned)LINK_PG_FN_DSHOT600 ? 600u : 0u)

#define LINK_PG_PORTS_MAX 4u
#define LINK_PG_PIN_NONE  0xFFFFu
#define LINK_PG_REG(port, r) \
    ((uint8_t)(LINK_PG_PORT0 + (unsigned)(port) * LINK_PG_STRIDE + (r)))
#define LINK_PG_FUNC(port) ((uint8_t)(LINK_PG_FUNC0 + (unsigned)(port)))
#define LINK_PG_F_BOUND(port)   ((uint16_t)(1u << (unsigned)(port)))
#define LINK_PG_F_PARKED(port)  ((uint16_t)(0x10u << (unsigned)(port)))
#define LINK_PG_F_REFUSED(port) ((uint16_t)(0x100u << (unsigned)(port)))
#define LINK_PG_F_DSHOT(port)   ((uint16_t)(0x1000u << (unsigned)(port)))
 
/* ------------------------------------------------------------------- HITEC */
enum {
    LINK_HT_STATE  = 0,  
    LINK_HT_SEQ    = 1,  
    LINK_HT_OP     = 2,  
    LINK_HT_RESULT = 3,  
    LINK_HT_CAP    = 4,  
    LINK_HT_DEC    = 5,  
    LINK_HT_VALUE  = 6,  
    LINK_HT_VIEW   = 7,  
    LINK_HT_BYTES  = 8,  
    LINK_HT_DATA   = 16, 
    LINK_HT_COUNT  = 32,
};

typedef enum {
    LINK_HITEC_VIEW_TIMES_LO = 0,
    LINK_HITEC_VIEW_TIMES_HI = 1,
    LINK_HITEC_VIEW_RUN = 2,
    LINK_HITEC_VIEW_COUNT
} link_hitec_view_t;

enum {
    LINK_HT_I_DELAY_LO = 16, 
    LINK_HT_I_DELAY_HI = 17,
    LINK_HT_I_LEAD_LO  = 18, 
    LINK_HT_I_LEAD_HI  = 19,
    LINK_HT_I_T_LO     = 20, 
    LINK_HT_I_T_HI     = 21,
    LINK_HT_I_SPAN_LO  = 22, 
    LINK_HT_I_SPAN_HI  = 23,
    LINK_HT_I_BIT_NS   = 24, 
    LINK_HT_I_LINE     = 25, 
    LINK_HT_I_PIN      = 26, 
    LINK_HT_I_WINDOW_LO = 27, 
    LINK_HT_I_WINDOW_HI = 28,
    LINK_HT_I_FRAMING  = 29, 
};

enum {
    LINK_HT_W_CMD  = 0,  
    LINK_HT_W_SEQ  = 1,  
    LINK_HT_W_KEY  = 2,  
    LINK_HT_W_CRC  = 3,  
    LINK_HT_W_LINE = 4,  
    LINK_HT_W_NTX  = 5,  
    LINK_HT_W_TX   = 6,  
    LINK_HT_W_LEAD_LO   = 10, 
    LINK_HT_W_LEAD_HI   = 11,
    LINK_HT_W_WINDOW_LO = 12, 
    LINK_HT_W_WINDOW_HI = 13,
    LINK_HT_W_RX   = 14, 
    LINK_HT_W_ANSWER = 15, 
    LINK_HT_W_LEVEL_LO = 16, 
    LINK_HT_W_LEVEL_HI = 17,
    LINK_HT_W_DECODE = 18,   
    LINK_HT_W_SUPPLY_MV = 19, 
    LINK_HT_W_SUPPLY_MA = 20, 
    LINK_HT_W_OFF_MS = 21,    
    LINK_HT_W_VIEW = 22,      
    LINK_HT_W_RX_MODE = 23,   
    LINK_HT_W_COUNT = 24,
};

typedef enum {
    LINK_HITEC_RX_PULL_UP = 0,
    LINK_HITEC_RX_PRECHARGE = 1,
    LINK_HITEC_RX_COUNT
} link_hitec_rx_t;

#define LINK_HT_LINE_PRECHARGE 0x0100u

#define LINK_HT_W_CMD_FRAME 4u
#define LINK_HT_W_STAGED 18u

#define LINK_HITEC_WRITE_KEY 0x48A5u
#define LINK_HITEC_SUPPLY_MIN_MV 4800u
#define LINK_HITEC_SUPPLY_MAX_MV 6000u
#define LINK_HITEC_OFF_MS_MAX 10000u
 
#define LINK_HT_STATE_OF(r) ((uint8_t)((r) & 0x7u))
#define LINK_HT_PORT_OF(r)  ((uint8_t)(((r) >> 12) & 0xFu))
#define LINK_HT_OP_OF(r)    ((uint8_t)(((r) >> 12) & 0xFu))
#define LINK_HT_W_CMD_OF(op, port) \
    ((uint16_t)((unsigned)(op) | (((unsigned)(port) & 0xFu) << 8)))
#define LINK_HT_LINE_OF(family, drive) \
    ((uint16_t)(((unsigned)(family) & 1u) | (((unsigned)(drive) & 1u) << 4)))

typedef enum {
    LINK_HITEC_FREE = 0,     
    LINK_HITEC_STOPPING = 1, 
    LINK_HITEC_OPEN = 2,     
    LINK_HITEC_BUSY = 3,     
    LINK_HITEC_POWER_OFF = 4, 
} link_hitec_state_t;

enum {
    LINK_HT_F_STOPPED = 0x0008u, 
    LINK_HT_F_RAIL    = 0x0010u, 
    LINK_HT_F_CAPTURE = 0x0020u, 
    LINK_HT_F_KEY     = 0x0040u, 
    LINK_HT_F_PRECHARGE = 0x0080u, 
};

enum {
    LINK_HT_CAP_FULL     = 0x0100u,
    LINK_HT_CAP_ANSWERED = 0x0200u,
    LINK_HT_CAP_OVERFLOW = 0x0400u,
    LINK_HT_CAP_ABORTED  = 0x0800u,
};

typedef enum {
    LINK_HITEC_DEC_NONE = 0,
    LINK_HITEC_DEC_C = 1,       
    LINK_HITEC_DEC_D = 2,       
    LINK_HITEC_DEC_LISTEN = 3,  
} link_hitec_dec_t;

typedef enum {
    LINK_HITEC_OP_NONE = 0,   
    LINK_HITEC_OP_OPEN = 1,   
    LINK_HITEC_OP_CLOSE = 2,  
    LINK_HITEC_OP_SEND = 3,   
    LINK_HITEC_OP_LISTEN = 4, 
    LINK_HITEC_OP_LEVEL = 5,  
    LINK_HITEC_OP_ABORT = 6,  
    LINK_HITEC_OP_POWER = 7,  
    LINK_HITEC_OP_CLEAR = 8,  
    LINK_HITEC_OP_COUNT
} link_hitec_op_t;

typedef enum {
    LINK_HITEC_RESULT_NONE = 0,    
    LINK_HITEC_RESULT_RUNNING = 1, 
    LINK_HITEC_RESULT_DONE = 2,    
    LINK_HITEC_RESULT_SUPPLY = 3,  
    LINK_HITEC_RESULT_START = 4,   
    LINK_HITEC_RESULT_NO_LINE = 5, 
    LINK_HITEC_RESULT_CUT = 6,     
} link_hitec_result_t;

#define LINK_HITEC_SUPPLY_MS 3000u

typedef enum {
    LINK_HITEC_REF_NONE = 0,
    LINK_HITEC_REF_BUSY = 1,      
    LINK_HITEC_REF_PORT = 2,      
    LINK_HITEC_REF_HELD = 3,      
    LINK_HITEC_REF_ARMED = 4,     
    LINK_HITEC_REF_UNSAFE = 5,    
    LINK_HITEC_REF_NOT_OPEN = 6,  
    LINK_HITEC_REF_NO_KEY = 7,    
    LINK_HITEC_REF_STAGED = 8,    
    LINK_HITEC_REF_STOPPED = 9,   
    LINK_HITEC_REF_NO_PIN = 10,   
    LINK_HITEC_REF_RANGE = 11,    
    LINK_HITEC_REF_SUPPLY_RANGE = 12, 
    LINK_HITEC_REF_NO_SUPPLY = 13, 
} link_hitec_refusal_t;
 
/* ----------------------------------------------------------------- control */
enum {
    LINK_CT_ARM        = 0, 
    LINK_CT_THROTTLE   = 1, 
    /*
     * The magnet count of the motor under test, so an electrical speed can
     * be turned into a mechanical one.  It is the one number bidirectional
     * DShot cannot carry: an ESC (electronic speed controller) reports
     * electrical periods and has no idea what it is bolted to.  Zero means
     * nobody has said, and rpm (revolutions per minute) is then not reported
     * rather than reported wrong.
     */
    LINK_CT_MOTOR_POLES = 2,
    LINK_CT_CLEAR      = 3, 
    LINK_CT_COUNT      = 4,
};

#define LINK_CT_ARM_FRAME 3u

#define LINK_POLES_MIN  2u
#define LINK_POLES_MAX 42u

#define LINK_CLEAR_MAGIC 0x5AFEu

#define LINK_ARM_ALL       0x0001u 
#define LINK_ARM_THROTTLE  0x0002u 
#define LINK_ARM_SURFACE   0x0004u 
#define LINK_ARM_ROLES     (LINK_ARM_THROTTLE | LINK_ARM_SURFACE)

#define LINK_THROTTLE_MAX 10000u
 
/* ----------------------------------------------------------------- update */

enum {
    LINK_UPD_VERSION     = 0,  
    LINK_UPD_STATE       = 1,  
    LINK_UPD_ERROR       = 2,  
    LINK_UPD_SLOT        = 3,  
    LINK_UPD_SLOT_SECTORS = 4, 
    LINK_UPD_NEXT_BLOCK  = 5,  
    LINK_UPD_SIZE_LO     = 6,  
    LINK_UPD_SIZE_HI     = 7,  
    LINK_UPD_CMD         = 8,  
    LINK_UPD_ARG0        = 9,
    LINK_UPD_ARG1        = 10,
    LINK_UPD_ARG2        = 11,
    LINK_UPD_DIGEST_OF   = 12, 
    /* 13 to 15 read 0. */
    LINK_UPD_DIGEST      = 16, 
    LINK_UPD_COUNT       = 32,
};

#define LINK_UPD_PROTOCOL 1u

#define LINK_UPD_BLOCK_BYTES 64u
#define LINK_UPD_DATA_COUNT  32u
#define LINK_UPD_SECTOR_BYTES 4096u
#define LINK_UPD_EXPECT_REGS 16u

#define LINK_UPD_SLOT_A      0x0000u
#define LINK_UPD_SLOT_B      0x0001u
#define LINK_UPD_SLOT_NONE   0x000Fu
#define LINK_UPD_SLOT_MASK   0x000Fu
#define LINK_UPD_SLOT_TRIAL  0x0100u
#define LINK_UPD_SLOT_OTHER  0x0200u

typedef enum {
    LINK_UPD_IDLE      = 0, 
    LINK_UPD_HASHING   = 1, 
    LINK_UPD_RECEIVING = 2, 
    LINK_UPD_RECEIVED  = 3, 
    LINK_UPD_VERIFYING = 4, 
    LINK_UPD_VERIFIED  = 5, 
    LINK_UPD_FAILED    = 6, 
    LINK_UPD_ACTIVATED = 7, 
} link_upd_state_t;

typedef enum {
    LINK_UPD_CMD_NONE         = 0,
    LINK_UPD_CMD_HASH_RUNNING = 1,
    LINK_UPD_CMD_BEGIN        = 2,
    LINK_UPD_CMD_COMMIT       = 3,
    LINK_UPD_CMD_FINISH       = 4,
    LINK_UPD_CMD_ACTIVATE     = 5,
    LINK_UPD_CMD_ABORT        = 6,
    LINK_UPD_CMD_BUY          = 7,
} link_upd_cmd_t;

typedef enum {
    LINK_UPD_ERR_NONE     = 0,
    LINK_UPD_ERR_NO_SLOTS = 1,  
    LINK_UPD_ERR_GATE     = 2,  
    LINK_UPD_ERR_SIZE     = 3,  
    LINK_UPD_ERR_ORDER    = 4,  
    LINK_UPD_ERR_CRC      = 5,  
    LINK_UPD_ERR_FLASH    = 6,  
    LINK_UPD_ERR_DIGEST   = 7,  
    LINK_UPD_ERR_STATE    = 8,  
    LINK_UPD_ERR_TRIAL    = 9,  
    LINK_UPD_ERR_LINK     = 10, 
    LINK_UPD_ERR_BUY      = 11, 
    LINK_UPD_ERR_COMMAND  = 12, 
} link_upd_err_t;

typedef enum {
    LINK_UPD_DIGEST_NONE    = 0,
    LINK_UPD_DIGEST_RUNNING = 1, 
    LINK_UPD_DIGEST_IMAGE   = 2, 
} link_upd_digest_t;
 
#ifdef __cplusplus
}
#endif
 
#endif /* RCBENCH_LINK_PAGES_H */