TMC2209 Python Library

A Python library to configure and communicate with the TMC2209 stepper motor driver via UART. This library enables reading and writing to the TMC2209 registers, configuring microstepping, and setting driver parameters.

Features

• Read and write registers of TMC2209
• Configure driver settings (e.g., current, voltage, microsteps)
• UART communication with TMC2209
• Register-level access and control

Installation

This library depends on pyserial for UART communication. Install the required dependencies using:

pip install pyserial

To install the library

pip install TMC2209_PY

Before usage

Please read the datasheet of TMC2209 to understand the registers and their bits

Usage

1. Initialize UART Communication

First, create a UART instance to establish serial communication.

from uart import UART

uart = UART(port="/dev/ttyS0")  # Use appropriate port

2. Configure the TMC2209 Driver

Create an instance of TMC2209Configure to control the stepper motor.

from TMC2209 import TMC2209Configure

tmc = TMC2209Configure(uart=uart, MS1=17, MS2=27, EN=22, node_address=0x00)

3. Initialize and Configure the Driver

To set up the motor driver:

tmc.initialize()

You can use this function to make sure that the connections are correct

4. Reading and Writing Registers

1. Writing to a Register

To write to a register, follow these steps:

1. Set or reset the desired bits.
2. Send the updated register values.

Syntax:

tmcModel.<RegisterName>.<BitName> = <Value>  # Set the bit in the register
tmcModel.write_<RegisterName>()  # Write the updated register value

Example:

tmc.gconf.shaft = 1 # Setting the shaft bit in GCONF register to reverse the direction
tmc.write_GCONF()  # Writes GCONF register settings

2. Reading a Register

To read the value of a register, follow these steps:

1. Call the corresponding read_<RegisterName>() function.
2. Store the returned value in a variable.

Syntax:

<variable_name> = tmc.read_<RegisterName>()  # Read the register value

Example:

gstat_value = tmc.read_GSTAT()
print(f"GSTAT Register Value: {gstat_value}")

5. Closing the UART Connection

uart.close()

Full Example Code

Below is a complete example that:

• Initializes the UART connection.
• Configures the TMC2209 driver.
• Writes to the VACTUAL register to move the motor.
• Reads a register value.
• Closes the UART connection when done.

from uart import UART
from TMC2209 import TMC2209Configure

# Initialize UART communication
uart = UART(port="/dev/ttyS0")

# Configure the TMC2209 driver
tmc = TMC2209Configure(uart=uart, MS1=17, MS2=27, EN=22, node_address=0x00)

# Initialize the driver settings
tmc.initialize()

# Example: Writing 1000 to VACTUAL register in order to move the motor
tmc.vactual.VACTUAL = 1000
tmc.write_VACTUAL()

# Read a register value
gstat_value = tmc.read_GSTAT()
print(f"GSTAT Register Value: {gstat_value}")

# Close the UART connection when done
uart.close()

Note: The MS1 and MS2 pins in the uart interface determine the node address of the TMC2209 driver. If your node address is different from 0x00, ensure that you correctly set the digital values of MS1 and MS2.

TMC2209 Single-Wire UART hardware setup

The TMC2209 uses a single-wire UART interface for communication — meaning both Tx and Rx share the same line. Some microcontrollers or SBCs (like the Jetson Nano) don’t natively support this mode, so you’ll need a small hardware hack to make it work.

Below is a simple circuit that combines Tx and Rx into a single UART line (named pdn_UART) compatible with the TMC2209:

Circuit Breakdown:

• Tx: From your microcontroller/SBC (e.g., Jetson Nano).
• R2 (1kΩ): Limits current flowing into the combined line.
• R3 (4.7kΩ): Pull-up resistor to keep the line idle high at 3.3V.
• D2 (1N4007): Diode ensures that the Rx pin only sees data intended for it — enforcing directionality.
• Rx: Connects back to your UART receive pin.

---

Why This Matters

The TMC2209 expects UART communication on its PDN pin, which is bidirectional over one wire. This circuit merges TX and RX into a single line (pdn_UART) so it can talk to the driver without UART bus contention or logic issues.

This setup was tested and verified with Jetson Nano using 3.3V logic levels. It should work similarly on other boards — just ensure you match logic levels.

---

Extending the Library

The library is designed to be hardware-agnostic so it works on multiple platforms like Jetson Nano, Raspberry Pi, and other SBCs. You can extend it by subclassing TMC2209Configure to add your own methods for custom behavior.

License

This project is licensed under the MIT License - see the LICENSE file for details.