|
TMC9660 Driver 0.1.0
API reference
|
Driver for one TMC9660 on a platform port. More...
#include <tmc9660.hpp>
Public Member Functions | |
| TMC9660 (Port &port, const Config &config={}) noexcept | |
| Bind the driver to a port and store the configuration. No I/O, cannot fail. | |
| TMC9660 (const TMC9660 &)=delete | |
| One driver object per chip. | |
| TMC9660 & | operator= (const TMC9660 &)=delete |
| One driver object per chip. | |
Lifecycle | |
| Result< void > | EnsureInitialized () noexcept |
Start the driver, once: bus up, optional hardware reset, identity check in Config::mode. | |
| Result< void > | Deinitialize () noexcept |
| Switch the gate driver off and mark the driver uninitialised. The chip is left as it is. | |
| bool | IsInitialized () const noexcept |
| Mode | GetMode () const noexcept |
| uint8_t | LastStatus () const noexcept |
| LastReply | GetLastReply () const noexcept |
| The last parameter-mode reply, as the chip sent it (no bus traffic). | |
| const Config & | GetConfig () const noexcept |
| Result< void > | Service () noexcept |
| Poll the things that need no request: FAULTN when the port reads it, and in parameter mode a read of GENERAL_ERROR_FLAGS that also keeps the heartbeat alive. | |
Safety | |
| Result< void > | DisableDrive () noexcept |
| Switch the gate driver off. Never refused: whatever the mode, state or earlier error, every step is attempted, the DRV_EN pin first. | |
| Result< void > | EnableDrive (uint8_t commutation_mode) noexcept |
| Energise the gate driver in parameter mode, after the start-up guards. | |
| Result< void > | MotorStop () noexcept |
| Stop the motor (MST). Parameter mode. Sent before a UART resync, and once more (after the resync) when the first attempt fails. | |
Bootloader | |
| Result< uint32_t > | BlGetInfo (BlInfo info) noexcept |
| GET_INFO. | |
| Result< uint32_t > | BlRead32 (Bank bank, uint32_t address) noexcept |
| Read a 32-bit word of a bootloader memory bank. | |
| Result< void > | BlWrite32 (Bank bank, uint32_t address, uint32_t value) noexcept |
| Write a 32-bit word of an external memory bank (SPI flash or I2C EEPROM). | |
| Result< BootConfig > | BlReadConfig () noexcept |
| Read the 64-byte configuration memory. | |
| Result< void > | BlWriteConfig (const BootConfig &config, const BlWriteOptions &options={}) noexcept |
| Write a configuration and verify it. | |
| Result< void > | BlStartApplication (BootMode target) noexcept |
Read the configuration, set BOOT_MODE and START_MOTOR_CTRL and write it (BlWriteConfig). | |
| Result< bool > | BlMemoryStatus (Bank bank, MemQuery query) noexcept |
| Ask about an external memory. | |
| Result< void > | BlEraseFlashSector (uint32_t address, bool allow_partition_table=false) noexcept |
Erase one 4 KiB sector of the SPI flash (SECTOR_ERASE 0x20). Refused unless the flash is configured and connected, and refused for sector 0, which holds the partition descriptor, unless allow_partition_table. | |
| Result< void > | BlOtpLoad () noexcept |
| OTP_LOAD: load the OTP configuration. (OTP_BURN is not exposed: it is permanent.) | |
Parameter mode | |
| Result< uint32_t > | GetChipId () noexcept |
| GetInfo type 0: the chip ID. | |
| Result< uint32_t > | GetVersion () noexcept |
| GetInfo type 1: the version word. | |
| Result< int64_t > | GetParam (Param param, uint8_t motor=0) noexcept |
| GAP: read an axis parameter. | |
| Result< uint32_t > | ReadRawParam (uint16_t type, uint8_t motor=0) noexcept |
| Single-shot raw read: one GAP with a parameter number taken as given (not looked up in the table, so a number the table does not know can be read). Nothing is written to the chip, so this cannot energise anything. | |
| Result< void > | SetParam (Param param, int64_t value, uint8_t motor=0) noexcept |
| SAP: write an axis parameter, after checking access, range and coded set against Table 57. | |
| Result< void > | ClearFlags (Param flags, uint32_t mask) noexcept |
| SAP of a flag word: write 1 to the bits to clear. | |
| Result< void > | StoreParams () noexcept |
| STAP: store all storable parameters to the external memory. | |
| Result< void > | FactoryDefault (bool confirm) noexcept |
| FactoryDefault: clears the settings stored in the external memory. | |
| Result< int64_t > | GetGlobal (GlobalBank bank, uint16_t number) noexcept |
| GGP. | |
| Result< void > | SetGlobal (GlobalBank bank, uint16_t number, int64_t value) noexcept |
| SGP, checked against Tables 61 to 63. | |
| Result< void > | SetTargetTorque (int32_t value) noexcept |
| SetParam of TARGET_TORQUE. | |
| Result< void > | SetTargetVelocity (int32_t value) noexcept |
| SetParam of TARGET_VELOCITY. | |
| Result< void > | SetTargetPosition (int32_t value) noexcept |
| SetParam of TARGET_POSITION. | |
| Result< int32_t > | ReferenceSearchCommand (ReferenceSearch action) noexcept |
| RFS. | |
| Result< void > | SetIo (uint8_t pin, bool high) noexcept |
| SIO: set a digital output. | |
| Result< int32_t > | GetIo (uint8_t pin, bool analog) noexcept |
| GIO. | |
| Result< int32_t > | RamDebug (RamDebugType type, uint8_t motor_bank, int32_t value) noexcept |
| RAMDebug command. | |
| Result< void > | ScriptRun (bool from_address, uint32_t address) noexcept |
ApplRun: run the script. The chip executes what is in its script memory, a script stored earlier or one that was not downloaded through this driver included, and the driver cannot see it: such a script may set COMMUTATION_MODE without EnableDrive()'s guards (see docs/safety.md). Only ScriptDownload() screens what it loads. | |
| Result< void > | ScriptStop () noexcept |
| ApplStop. | |
| Result< void > | ScriptStep () noexcept |
| ApplStep. | |
| Result< void > | ScriptReset () noexcept |
| ApplReset. | |
| Result< int32_t > | ScriptStatus () noexcept |
| GetStatus of the script. | |
| Result< uint32_t > | ScriptReadMem (uint32_t address) noexcept |
ReadMem: the script instruction word at address. | |
| Result< void > | ScriptDownload (std::span< const TmclInstruction > script) noexcept |
Download a script: DownloadStart, every instruction (each acknowledged with CMD_LOADED), DownloadEnd. DownloadEnd is sent even when an instruction failed. The chip executes scripts on its own. The one way a script of this driver could energise the stage, setting COMMUTATION_MODE (SAP of parameter 4 with a non-zero value, or AAP of it, whose value is the accumulator), is Refused before anything is sent; nothing else a script does is analysed. | |
| Result< void > | PowerDown (PowerDownTime time) noexcept |
| Put the chip into the power-down state for a time (global parameter 11). The gate driver is switched off first; the chip restarts afterwards, so the driver becomes uninitialised. | |
| Result< void > | ReturnToBootloader () noexcept |
| Return to the bootloader (Boot command). The gate driver is switched off and COMMUTATION_MODE is read back as 0 first (erratum 3); then Boot is sent; then the bootloader's chip ID is checked. | |
| Result< void > | DisableSpi1Slave () noexcept |
| Erratum 5 workaround: disable the SPI1 slave (op 146, type 4, bank 9, value 0). Only call it when the host is not connected to SPI1. | |
Register mode | |
| Result< uint32_t > | ReadReg (RegAddr addr) noexcept |
| Read a register of the register map. | |
| Result< void > | WriteReg (RegAddr addr, uint32_t value) noexcept |
Write a register. Refused (nothing sent): read-only registers (InvalidArgument) and any write that sets a bit that energises the gate driver (MCC_GDRV_HW and MCC_PWM_CONFIG enable bits): use GateDriverStart(). | |
| Result< void > | UpdateReg (RegAddr addr, uint32_t mask, uint32_t value) noexcept |
Read-modify-write of the bits in mask; the mask must lie within the register's writable bits. | |
| template<typename F > | |
| Result< uint32_t > | ReadField (RegAddr addr) noexcept |
| The value of one field. | |
| template<typename F > | |
| Result< void > | WriteField (RegAddr addr, uint32_t value) noexcept |
| Set one field. | |
| Result< uint32_t > | RegRamDebug (uint8_t subcommand, uint8_t index, bool write, uint32_t value) noexcept |
| RAMDebug access in register mode. | |
| Result< void > | GateDriverStart (const GateDriverRegConfig &config) noexcept |
| Energise the gate driver in register mode, in the order of the register manual, with the guards complete before the first energising write: the sequence sets up PWM, gate-driver configuration, timing and break-before- make, clears the status, reads MCC_GDRV_STATUS and MCC_GDRV_FAULT and stops on any latched bit, asserts DRV_EN and only then writes MCC_GDRV_HW and the run value of CHOP. The result is read back; a mismatch switches the gate driver off again. | |
Driver for one TMC9660 on a platform port.
Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, optional reset, identity check in the mode the chip is expected to be in), use, optionally Deinitialize() (the gate driver is switched off). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded, and again after the driver has seen a reset.
The chip speaks one of three protocols (Mode); a call that belongs to another mode returns Error::WrongMode and sends nothing. Every call validates its arguments against the datasheet tables before it sends a byte (Error::InvalidArgument, nothing sent).
Optional port hooks, found at compile time:
void DelayUs(uint32_t us) noexcept: the SPI reply gap, reset and boot waits. Without it: compile error, the waits are required.bool GpioSet(CtrlPin, GpioSignal) noexcept: RSTN (hardware reset), DRV_EN, WAKE. Without it: no hardware reset, and EnableDrive() assumes DRV_EN is wired high.bool GpioGet(CtrlPin, bool& high) noexcept: FAULTN, for boot completion and Service(). Without it: boot completion is waited for by time.void Log(LogLevel, const char* message) noexcept: one line per lifecycle event or failure. Without it: nothing is logged.A hook declared with the wrong signature is a compile error.
| Port | Your class derived from SpiInterface<Port> or UartInterface<Port>, not both. |
|
inlineexplicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | What EnsureInitialized() will apply; checked there, before any I/O. |
|
noexcept |
Erase one 4 KiB sector of the SPI flash (SECTOR_ERASE 0x20). Refused unless the flash is configured and connected, and refused for sector 0, which holds the partition descriptor, unless allow_partition_table.
| address | The first address of the sector: a multiple of 4096 below 2^24 (the flash takes a 24-bit address); anything else is InvalidArgument and nothing is sent. |
| allow_partition_table | Allow sector 0 (the partition descriptor). |
Ok, Refused, InvalidArgument, Busy, bus errors.
|
noexcept |
GET_INFO.
| info | The selector. |
|
noexcept |
Ask about an external memory.
| bank | SpiFlash or I2cEeprom. |
| query | What to ask. |
|
noexcept |
OTP_LOAD: load the OTP configuration. (OTP_BURN is not exposed: it is permanent.)
Ok, WrongMode, the transport errors.
|
noexcept |
Read a 32-bit word of a bootloader memory bank.
| bank | The bank. |
| address | Byte address (a multiple of 4). |
InvalidArgument for a misaligned address.
|
noexcept |
Read the 64-byte configuration memory.
|
noexcept |
Read the configuration, set BOOT_MODE and START_MOTOR_CTRL and write it (BlWriteConfig).
| target | Register or Parameter; the reserved values are Refused. |
BlWriteConfig.
|
noexcept |
Write a 32-bit word of an external memory bank (SPI flash or I2C EEPROM).
| bank | SpiFlash or I2cEeprom: the OTP bank is never written (Refused), the configuration memory has its own call (BlWriteConfig, Refused). |
| address | Byte address (a multiple of 4). |
| value | The word. |
Ok, InvalidArgument, Refused, WrongMode, the bus errors.
|
noexcept |
Write a configuration and verify it.
Refused before anything is written when config.CheckStart() fails (the application would start with a reserved BOOT_MODE or a clock other than 40 MHz) or when the LDO word changes without options.allow_ldo_change. Only the words that differ are written; the clock word with one 32-bit write; the BOOT_MODE word last. A write of the BOOT_MODE word with START_MOTOR_CTRL set starts the application (A24): the driver switches to the new mode and waits up to Config::boot_timeout_ms for its chip ID. If the start write fails other than by a bootloader error status, the start is followed all the same. End states on failure: the application is adopted (Ok); the bootloader still answers, so the driver stays in it, initialised, and returns the error; or the driver is left uninitialised in the application's mode, so a stop reaches it.
| config | The configuration. |
| options | Permissions for changes that affect the board. |
Ok, Refused, VerifyFailed, Timeout, DeviceIdMismatch, the bus errors.
|
noexcept |
SAP of a flag word: write 1 to the bits to clear.
| flags | One of the flag parameters. |
| mask | The bits to clear. |
Ok, InvalidArgument (not a flag parameter, nothing sent), the transport errors.
|
noexcept |
Switch the gate driver off and mark the driver uninitialised. The chip is left as it is.
The stop is sent whether or not the driver is initialised: after a reported reset (UnexpectedReset) the DRV_EN pin is still high and the chip may run an application of its own, so this call drops the pin and sends the stop frames then too (DisableDrive()).
|
noexcept |
Switch the gate driver off. Never refused: whatever the mode, state or earlier error, every step is attempted, the DRV_EN pin first.
Parameter mode writes COMMUTATION_MODE = 0, once more after any failure (a reported reset, a lost frame, a stale or late UART reply; the repeat resynchronises the line first), and without a DRV_EN hook then makes sure IDLE_MOTOR_PWM_BEHAVIOR is 1; register mode writes zero to MCC_GDRV_HW and MCC_PWM_CONFIG, always both, and reads both back: VerifyFailed when an energising bit is still set (a stop the chip did not apply, for example under the wrong register SPI layout, A3). In bootloader mode nothing needs switching off: with a DRV_EN hook the pin drop is the stop; without one the stop is Ok only when the bootloader still answers its chip type. BUSY, an error status or a seen reset are the bootloader answering: the error is returned, no application stop is sent and the mode stays. Any other failure may be an unseen restart into an application: the driver sends the stop of the application that BOOT_MODE names (read at adoption, before anything was written, so it is the OTP value; or by the last BlReadConfig()), else of Config::mode, becomes uninitialised in that protocol and returns the error; with no proved protocol and no hook it is NotInitialized.
Ok when every step worked.
|
noexcept |
Erratum 5 workaround: disable the SPI1 slave (op 146, type 4, bank 9, value 0). Only call it when the host is not connected to SPI1.
Ok, WrongMode, the transport errors.
|
noexcept |
Energise the gate driver in parameter mode, after the start-up guards.
Guards, in order, all before DRV_EN or COMMUTATION_MODE is touched: mode is Parameter, commutation_mode is 1 to 8, GENERAL_ERROR_FLAGS and GDRV_ERROR_FLAGS read zero. Then DRV_EN is asserted (when the port drives it) and COMMUTATION_MODE written; if that write fails (the chip may still have run it) the full stop of DisableDrive() follows, so a failed call leaves the drive stopped also without a DRV_EN hook.
| commutation_mode | COMMUTATION_MODE value, 1 to 8. |
Ok; InvalidArgument; NotInitialized; WrongMode; DeviceFault (a flag is latched: read and clear it); the bus errors.
|
noexcept |
Start the driver, once: bus up, optional hardware reset, identity check in Config::mode.
|
noexcept |
FactoryDefault: clears the settings stored in the external memory.
| confirm | Must be true: the call is Refused otherwise. COMMUTATION_MODE must be 0, else Refused. |
Ok, Refused (nothing changed), the transport errors.
|
noexcept |
Energise the gate driver in register mode, in the order of the register manual, with the guards complete before the first energising write: the sequence sets up PWM, gate-driver configuration, timing and break-before- make, clears the status, reads MCC_GDRV_STATUS and MCC_GDRV_FAULT and stops on any latched bit, asserts DRV_EN and only then writes MCC_GDRV_HW and the run value of CHOP. The result is read back; a mismatch switches the gate driver off again.
| config | The words. |
Ok, InvalidArgument (bits outside the registers' writable bits), DeviceFault, VerifyFailed, WrongMode, the bus errors.
|
noexcept |
GetInfo type 0: the chip ID.
WrongMode outside parameter mode, the transport errors.
|
inlinenoexcept |
|
noexcept |
GGP.
| bank | 0, 2 or 3. |
| number | The parameter number. |
|
noexcept |
GIO.
| pin | Port number 0 to 18. |
| analog | true: the analog value (bank 1). |
|
inlinenoexcept |
The last parameter-mode reply, as the chip sent it (no bus traffic).
|
inlinenoexcept |
Config::mode until a start or a mode change proves another one; a failed start keeps the last one proved (the stop uses it).
|
noexcept |
GAP: read an axis parameter.
| param | The parameter. |
| motor | The axis, 0. |
InvalidArgument for a write-only parameter or a motor above 15.
|
noexcept |
GetInfo type 1: the version word.
WrongMode outside parameter mode, the transport errors.
|
inlinenoexcept |
EnsureInitialized() succeeded and until a reset is detected or Deinitialize() runs.
|
inlinenoexcept |
BlStatus or a TmclStatus value.
|
noexcept |
Stop the motor (MST). Parameter mode. Sent before a UART resync, and once more (after the resync) when the first attempt fails.
Ok or the error of the repeat.
|
noexcept |
Put the chip into the power-down state for a time (global parameter 11). The gate driver is switched off first; the chip restarts afterwards, so the driver becomes uninitialised.
| time | Duration. |
Ok, InvalidArgument (nothing sent), the transport errors.
|
noexcept |
RAMDebug command.
| type | Table 16 type. |
| motor_bank | The motor/bank field. |
| value | The value. |
InvalidArgument (nothing sent), the transport errors.
|
inlinenoexcept |
The value of one field.
| F | A fields::<REGISTER>::<FIELD> type. |
| addr | The register that holds the field. |
ReadReg().
|
noexcept |
Single-shot raw read: one GAP with a parameter number taken as given (not looked up in the table, so a number the table does not know can be read). Nothing is written to the chip, so this cannot energise anything.
| type | The 12-bit parameter number. |
| motor | The axis, 0. |
InvalidArgument (nothing sent) for a number above 0xFFF or a motor above 15, WrongMode outside parameter mode.
|
noexcept |
Read a register of the register map.
| addr | The register. |
InvalidArgument for an address the map does not list; Unsupported when the offset does not fit the SPI layout (ambiguity A3).
|
noexcept |
RFS.
| action | Start, stop or status. |
Status).
|
noexcept |
RAMDebug access in register mode.
| subcommand | RAMDebug subcommand 0 to 15. |
| index | Index (5 or 6 bits, Quirks::ram_debug_index_bits). |
| write | true to write. |
| value | The data. |
InvalidArgument (nothing sent), the transport errors.
|
noexcept |
Return to the bootloader (Boot command). The gate driver is switched off and COMMUTATION_MODE is read back as 0 first (erratum 3); then Boot is sent; then the bootloader's chip ID is checked.
Ok, Refused (the system is not off), the transport errors.
|
noexcept |
Download a script: DownloadStart, every instruction (each acknowledged with CMD_LOADED), DownloadEnd. DownloadEnd is sent even when an instruction failed. The chip executes scripts on its own. The one way a script of this driver could energise the stage, setting COMMUTATION_MODE (SAP of parameter 4 with a non-zero value, or AAP of it, whose value is the accumulator), is Refused before anything is sent; nothing else a script does is analysed.
| script | The instructions; at most 255, each one a script-capable command. |
Ok, InvalidArgument or Refused (nothing sent), the error of the first failing instruction.
|
noexcept |
ReadMem: the script instruction word at address.
| address | The word address. |
WrongMode, the transport errors.
|
noexcept |
ApplReset.
Ok, WrongMode, the transport errors.
|
noexcept |
ApplRun: run the script. The chip executes what is in its script memory, a script stored earlier or one that was not downloaded through this driver included, and the driver cannot see it: such a script may set COMMUTATION_MODE without EnableDrive()'s guards (see docs/safety.md). Only ScriptDownload() screens what it loads.
| from_address | true: start at address. |
| address | The start address. |
Ok, WrongMode, UnexpectedReset, the transport errors.
|
noexcept |
GetStatus of the script.
WrongMode, the transport errors.
|
noexcept |
ApplStep.
Ok, WrongMode, the transport errors.
|
noexcept |
ApplStop.
Ok, WrongMode, the transport errors.
|
noexcept |
Poll the things that need no request: FAULTN when the port reads it, and in parameter mode a read of GENERAL_ERROR_FLAGS that also keeps the heartbeat alive.
Ok; UnexpectedReset when Config::faultn_is_reset and FAULTN is low outside the bootloader, or when the flag word shows WATCHDOG_EVENT that was clear at the start (a watchdog reset; a reset that leaves no flag is found by the canary or FIRST_CMD instead).
|
noexcept |
SGP, checked against Tables 61 to 63.
| bank | The bank. |
| number | The parameter number in the bank. |
| value | The value, checked against the table. |
Ok, InvalidArgument (nothing sent), Nack, the transport errors.
|
noexcept |
SIO: set a digital output.
| pin | Port number 0 to 18. |
| high | The level. |
Ok, InvalidArgument (nothing sent), the transport errors.
|
noexcept |
SAP: write an axis parameter, after checking access, range and coded set against Table 57.
Refused: COMMUTATION_MODE other than 0 (use EnableDrive()), and MOTOR_TYPE while COMMUTATION_MODE is not 0.
| param | The parameter. |
| value | The value, checked against the table. |
| motor | The axis, 0. |
Ok, InvalidArgument (nothing sent), Refused, Nack, the transport errors.
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
|
noexcept |
STAP: store all storable parameters to the external memory.
Ok, WrongMode, Nack, the transport errors.
|
noexcept |
Read-modify-write of the bits in mask; the mask must lie within the register's writable bits.
| addr | The register. |
| mask | The bits to change. |
| value | The new value of those bits. |
WriteReg(); InvalidArgument for a mask outside the writable bits.
|
inlinenoexcept |
Set one field.
| F | A fields::<REGISTER>::<FIELD> type. |
| addr | The register that holds the field. |
| value | The new field value; InvalidArgument when it does not fit. |
UpdateReg().
|
noexcept |
Write a register. Refused (nothing sent): read-only registers (InvalidArgument) and any write that sets a bit that energises the gate driver (MCC_GDRV_HW and MCC_PWM_CONFIG enable bits): use GateDriverStart().
| addr | The register. |
| value | The new value. |
Ok, InvalidArgument, Refused, UnexpectedReset, the transport errors.