Tmc9660DriveObservability.h File Reference

TMC9660 telemetry snapshots, fault decoding and parameter-image apply for MotorController. More...

#include <algorithm>
#include <array>
#include <cstddef>
#include <cstdint>
#include <span>
#include "bsp_bind/VortexBoardBind.h"
#include "core/hf-core-drivers/external/hf-tmc9660-driver/inc/tmc9660.hpp"

Include dependency graph for Tmc9660DriveObservability.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	vortex::motor::ParamAccess
	One axis-parameter access in a batch (MCU- and transport-neutral copy of the driver's type). More...
struct	vortex::motor::MotorTelemetrySnapshot
	Caller-owned snapshot, refreshed in place by MotorController::ReadTelemetry(). More...
struct	vortex::motor::MotorDriveDiagnostics
	The four TMC9660 status words, decoded (design §1.5). Raw words are kept for anything not named. More...
struct	vortex::motor::ParamWrite
	One entry of a parameter image (design §4.1, the TMC image). More...
struct	vortex::motor::ApplyOptions
	How ApplyParameterImage() works. More...
struct	vortex::motor::ApplyResult
	What ApplyParameterImage() did. More...

Namespaces
namespace	vortex
namespace	vortex::motor
namespace	vortex::motor::detail

Typedefs
using	vortex::motor::Param = tmc9660::tmcl::Parameters
using	vortex::motor::ReplyCode = tmc9660::tmcl::ReplyCode

Enumerations
enum class	vortex::motor::TelemetryField : uint8_t {   vortex::motor::ActualPosition = 0 , vortex::motor::ActualVelocity , vortex::motor::TorqueFluxActual , vortex::motor::GeneralStatus ,   vortex::motor::GeneralErrors , vortex::motor::GateDriverErrors , vortex::motor::AdcStatus , vortex::motor::SupplyVoltage ,   vortex::motor::ChipTemperature , vortex::motor::ExternalTemperature , vortex::motor::TotalMotorCurrent , vortex::motor::RampVelocity ,   vortex::motor::RampPosition , vortex::motor::VoltageDqActual , vortex::motor::Iit1Sum , vortex::motor::Iit2Sum ,   vortex::motor::Count }
	The telemetry signals a snapshot carries (design §1.3, tiers C/F/S). More...
enum class	vortex::motor::TelemetrySet : uint8_t { vortex::motor::Cyclic = 0 , vortex::motor::Status , vortex::motor::Full }
	Which signals one ReadTelemetry() call fetches. More...
enum class	vortex::motor::DriveSeverity : uint8_t { vortex::motor::Ok = 0 , vortex::motor::Warning , vortex::motor::Fault }
	How serious the decoded status words are. More...

Functions
template<typename Driver , bool kWrite>
size_t	vortex::motor::detail::RunBatch (Driver &driver, std::span< ParamAccess > items) noexcept
template<typename Driver >
size_t	vortex::motor::BatchRead (Driver &driver, std::span< ParamAccess > items) noexcept
	Read a batch (GAP, pipelined).
template<typename Driver >
size_t	vortex::motor::BatchWrite (Driver &driver, std::span< ParamAccess > items) noexcept
	Write a batch (SAP, pipelined; SAP is idempotent).
constexpr uint32_t	vortex::motor::TelemetryRequestMask (TelemetrySet set, uint32_t next_sequence) noexcept
	Fields a set asks for, given the snapshot's next sequence number (Cyclic alternates 299/300).
template<typename Driver >
size_t	vortex::motor::ReadTelemetry (Driver &driver, TelemetrySet set, MotorTelemetrySnapshot &snap) noexcept
	Refresh snap from one pipelined batch.
MotorDriveDiagnostics	vortex::motor::DecodeDriveStatus (uint32_t status, uint32_t gen_err, uint32_t gdrv, uint32_t adc) noexcept
	Decode the four status words into named conditions and a severity.
template<typename Driver >
bool	vortex::motor::ReadDriveDiagnostics (Driver &driver, MotorDriveDiagnostics &out) noexcept
	Read the four status words in one batch and decode them.
template<typename Driver >
bool	vortex::motor::ClearLatchedFlags (Driver &driver, uint32_t general_errors, uint32_t gate_driver_errors, uint32_t adc_status) noexcept
	Clear latched (write-1-to-clear) bits of the error words in one batch.
template<typename Driver , typename Pred >
void	vortex::motor::detail::ApplyPhase (Driver &driver, std::span< const ParamWrite > image, ApplyOptions opt, Pred take, ApplyResult &r) noexcept
	Apply the image entries selected by take, in image order, kBatchChunk at a time.
template<typename Driver >
ApplyResult	vortex::motor::ApplyParameterImage (Driver &driver, std::span< const ParamWrite > image, ApplyOptions opt) noexcept
	Apply a parameter image: MOTOR_TYPE first, then the rest in image order.

Variables
constexpr size_t	vortex::motor::kBatchChunk = 16
	Elements per pipelined chunk (bounds the stack buffer; the driver chunks again internally).
constexpr size_t	vortex::motor::kTelemetryFieldCount = static_cast<size_t>(TelemetryField::Count)
constexpr std::array< Param, kTelemetryFieldCount >	vortex::motor::kTelemetryParam
	TMC9660 parameter behind each telemetry field.

Detailed Description

TMC9660 telemetry snapshots, fault decoding and parameter-image apply for MotorController.

The hooks the drive-observability design (hardfoc-vortex-v1 docs/design/drive-observability.md) needs from the HAL, independent of any protocol stack:

• Batch access. Every read and write goes through the driver's pipelined TMCL batch API (readParameters() / writeParameters()): on SPI, N accesses cost N + 1 datagrams instead of 2N (design §1.8).
• Telemetry snapshots (§1.3, §2.2, §2.3): a caller-owned MotorTelemetrySnapshot is refreshed in place from one batch. Every field remembers the sequence number of its last good read, so a consumer can tell its age; a failed access leaves the old value and does not move its stamp. The cyclic set is the design's fixed slots: position and velocity actual, packed Iq/Id (331), status (289), and the general / gate-driver error words alternating (299 / 300).
• Fault decoding (§1.5): the four status words become named conditions and a severity.
• Configuration (§4.3–§4.5): a parameter image is applied with MOTOR_TYPE first (the chip rejects most SAPs until it is set), optionally only where the chip differs (differential apply), and optionally read back and compared (verify).

Everything here is templated on the driver type (Tmc9660Handler::SpiDriver or UartDriver) and is called by MotorController inside Tmc9660Handler::visitDriver(), so the handler mutex is held. Units are the chip's raw units; the SI conversions given are those the design marks as solid. The packed 331/332 values are unscaled until calibrated (§1.4).

Ownership: value types and free functions. Thread safety: none of its own (callers hold the handler lock). No allocation: batches are chunked through a fixed stack buffer. MCU-free.