Skip to content

Bootloader

What bootloaderInit() does, which BootloaderConfig fields matter, and why nothing else works until it succeeds.

Why Bootloader Initialization is Required

The TMC9660 operates in two modes: - Bootloader Mode: Configuration and firmware update - Parameter Mode: Motor control operation

Motor control will NOT work until the bootloader is properly initialized and the device transitions to Parameter Mode.

Critical Configuration

tmc9660::BootloaderConfig cfg{};

// ⚠️ CRITICAL: Must set boot mode to Parameter
cfg.boot.boot_mode = tmc9660::bootcfg::BootMode::Parameter;

// Start motor control after configuration
cfg.boot.start_motor_control = true;

// SPI configuration
cfg.spiComm.boot_spi_iface = tmc9660::bootcfg::SPIInterface::IFACE0;

// UART configuration (if using UART)
cfg.uart.baud_rate = tmc9660::bootcfg::BaudRate::BR115200;
cfg.uart.tx_pin = tmc9660::bootcfg::UartTxPin::GPIO6;
cfg.uart.rx_pin = tmc9660::bootcfg::UartRxPin::GPIO7;

// Clock configuration
cfg.clock.use_external = tmc9660::bootcfg::ClockSource::Internal;

// Initialize bootloader
auto result = driver.bootloaderInit(&cfg);
if (result != tmc9660::TMC9660::BootloaderInitResult::Success) {
    // Handle failure - motor control will not work!
    return -1;
}

Command Ordering (CRITICAL)

When START_MOTOR_CONTROL = 1 is written, the bootloader EXITS IMMEDIATELY!

WRONG: Writing START_MOTOR_CONTROL early

// WRONG! Bootloader exits after this write
cfg.boot.start_motor_control = true;  // Written first
// ... other configs ...
// ❌ These configs fail because bootloader already exited!

CORRECT: Writing START_MOTOR_CONTROL last

The bootloaderInit() method automatically writes START_MOTOR_CONTROL = 1 LAST, after all other configurations. This is the correct order.

Initialization Sequence

  1. Hardware Reset (if performReset=true)
  2. Assert RST pin for 100ms
  3. Release RST pin

  4. Wait 100ms for stabilization

  5. Mode Detection

  6. Check if device is in bootloader or parameter mode

  7. If in parameter mode and config provided, reinitialize

  8. Configuration

  9. Write all bootloader settings

  10. LAST: Write START_MOTOR_CONTROL = 1 (if enabled)

  11. Motor Control Startup (if start_motor_control=true)

  12. Consume SESSION_START
  13. Verify TMCL communication

OTP vs Runtime Configuration

OTP Configuration (Production)

When START_MOTOR_CONTROL = 1 is burned into OTP: - ✅ Autonomous operation (no host needed) - ✅ Fastest startup - ❌ Cannot reconfigure without hardware reset - ❌ Bootloader commands not accepted after power-up

Runtime Configuration (Development)

When START_MOTOR_CONTROL = 1 is written at runtime: - ✅ Flexible configuration during development - ✅ Can test different settings - ⚠️ Requires host to send configuration - ⚠️ Longer startup time

Common Issues

Bootloader Initialization Fails

  1. Check Hardware Reset
  2. Verify RST pin toggling

  3. Wait at least 100ms after reset

  4. Verify Communication

  5. Check SPI/UART wiring
  6. Verify CS pin (SPI) or TX/RX pins (UART)

  7. Confirm clock speed ≤ 4 MHz (SPI)

  8. Check Configuration

  9. Must set boot_mode = Parameter
  10. Verify all required settings are provided

No Reply from Bootloader

  1. Check Pin Connections
  2. Verify TX/RX pins not swapped (UART)

  3. Verify MOSI/MISO not swapped (SPI)

  4. Verify Protocol

  5. Check CRC/checksum calculation

  6. Confirm frame format

  7. Check Timing

  8. Add delays between commands
  9. Respect SPI delayed reply timing

Best Practices

  1. Always Initialize Bootloader First 

    // This MUST be done before any motor control
auto result = driver.bootloaderInit(&cfg);

  2. Use Complete Configuration 

    // Set all required fields
cfg.boot.boot_mode = tmc9660::bootcfg::BootMode::Parameter;
cfg.boot.start_motor_control = true;

  3. Handle Errors 

    if (result != tmc9660::TMC9660::BootloaderInitResult::Success) {
    // Motor control will not work without successful initialization
    return false;
}

  4. Verify Communication After Init 

    // Test that TMCL communication works
auto version = driver.bootloaderGetVersion();
if (!version.has_value()) {
    // Communication failed
}

Bootloader Commands Quick Reference

Command Codes

Code Command Description
0x00 GET_INFO Get bootloader info
0x08 GET_BANK Get current bank
0x09 SET_BANK Select memory bank
0x0A GET_ADDRESS Get current address
0x0B SET_ADDRESS Set memory address
0x0C READ_32 Read 32-bit data
0x0D READ_32_INC Read 32-bit + increment
0x0E READ_16 Read 16-bit data
0x0F READ_16_INC Read 16-bit + increment
0x10 READ_8 Read 8-bit data
0x11 READ_8_INC Read 8-bit + increment
0x12 WRITE_32 Write 32-bit value
0x13 WRITE_32_INC Write 32-bit + increment
0x14 WRITE_16 Write 16-bit value
0x15 WRITE_16_INC Write 16-bit + increment
0x16 WRITE_8 Write 8-bit value
0x17 WRITE_8_INC Write 8-bit + increment
0x1D NO_OP No operation (get reply)
0x1E OTP_LOAD Load OTP page
0x1F OTP_BURN Burn OTP page

Status Codes

Code Name Description
0 OK Command executed successfully
1 CMD_NOT_FOUND Invalid command number
3 INVALID_ADDR Invalid memory address
4 INVALID_VALUE Invalid request value
14 INVALID_BANK Invalid memory bank
15 BUSY Bootloader busy (SPI only)
17 MEM_UNCONFIGURED External memory not configured
18 OTP_ERROR OTP command failed
19 SESSION_START First SPI datagram after power-on (SPI only)
20 CMD_NOT_AVAILABLE Command not available
21 BOOTLOADER_RESUMED Returned to bootloader from motor control (SPI only)

Memory Banks

Bank Name Description
0 RAM Internal SRAM
1 OTP One-time programmable memory
2 SPI Flash External SPI flash memory
3 I2C EEPROM External I2C EEPROM
4 Reserved Reserved for future use
5 CONFIG Configuration memory bank

Next Steps