Getting started
pip3 install PyTmcStepperclone this repo to your Raspberry Pi using
git clone https://github.com/Chr157i4n/PyTmcStepperIf you use the Raspberry Pi OS you can enable the serial port in
sudo raspi-config
make sure that you disable the login shell over serial
Would you like a login shell to be accessible over serial? --> No
Would you like the serial port hardware to be enabled? --> Yes
For other OS, you must check yourself how to activate the serial interface.
In Order to gain access to the serial port on the Raspberry Pi OS, you must add your user to the dialout group:
sudo usermod -a -G dialout <your-user>You can check the permission on your serial port with
ls -lha /dev/serial0This should show a symbolic link to your actual serial port /dev/serial0 -> ttyS0
ls -lha /dev/ttyS0
It should show, that the dialout group has read/write access to the file. Otherwise you need to change the permissions on that file with chmod.
The following table shows the supported boards and which libraries for GPIO access is beeing used for that board.
| Library | Installation Parameter | Boards |
|---|---|---|
| RPi.GPIO | RASPBERRY_PI | Pi4, Pi3 etc. |
| gpiozero | RASPBERRY_PI5 | Pi5 |
| Jetson.GPIO | NVIDIA_JETSON | Nvidia Jetson |
| pheriphery | LUCKFOX_PICO | Luckfox Pico |
| OPi.GPIO | ORANGE_PI | Orange Pi |
Those libraries are needed for this library to work. You can either install the correct library yourself. You can also install the needed GPIO library by specifing the Installation Parameter while installing this library:
pip3 install PyTmcStepper[RASPBERRY_PI]The currently supported drivers are:
| Driver | Interface |
|---|---|
| TMC2208 | UART |
| TMC2209 | UART |
| TMC2240 | SPI/UART |
with V0.7 the code for enabling the motor current output and the code for controling the motion of the drivers is split into their own classes to be able to support the diverse methods.
The EnableControl module controls the motor current output. It has a function set_motor_enabled with one boolean parameter. This function is used to enable or disable the Motor current output.
| EnableControl | Class | Driver | Notes |
|---|---|---|---|
| Pin | TmcEnableControlPin | all | the EN Pin of the Driver needs to be connected to a GPIO of the Pi |
| TOff | TmcEnableControlToff | all | the EN Pin needs to be connected to GND. On the TMC2209 this enables current Output on Startup! On the TMC2240 this works fine, because TOff is per default 0 (off). |
The MotionControl module controls the motion of the motor. Before a movement the motor current output needs to be enabled by the EnableControl module.
| MotionControl | Class | Driver | Notes |
|---|---|---|---|
| STEP/DIR | TmcMotionControlStepDir | all | the STEP and DIR pin of the driver must each be connected to a GPIO of the Pi |
| STEP/REG | TmcMotionControlStepReg | all | only the STEP pin needs to be connected to a GPIO of the Pi. The direction is controlled via the Register. |
| VACTUAL | TmcMotionControlVActual | TMC220x | the Direction and Speed is controlled via Register. But VActual does only allow setting a speed and therefore cannot control positioning of the Motor. |
| STEP_PWM/DIR | TmcMotionControlStepPwmDir | all | In contrast to STEP/DIR, the step pin is controlled by PWM. This reduces the load on the CPU, but does not allow precise positioning (similar to the VACTUAL). STEP must be connected to a PWM-capable pin for this purpose |
Further methods of controlling the motion of a motor could be:
- using the built in Motion Controller of the TMC5130
- via a µC which controlls the Motor
- highperformance Step/Dir Library written in a compiled language (C/C++)
| Com | Class | Driver | Notes |
|---|---|---|---|
| UART | TmcComUart | all | Communication via UART (RX, TX). See Wiring pyserial needs to be installed |
| SPI | TmcComSpi | TMC2240 | Communication via SPI (MOSI, MISO, CLK, CS). See Wiring spidev needs to be installed |
| Pin TMC | Color | connect to | Function |
|---|---|---|---|
| VDD | 3,3V of Raspberry Pi | recommended, for forcing the TMC to use 3,3V logic level | |
| GND | BLACK | GND of Raspberry Pi | GND for VDD and Signals |
| VM | RED | 12V or 24V of power supply | power for the motor |
| GND | BLACK | GND of power supply | power for the motor |
| EN | RED | GPIO21 of Raspberry Pi | enable the motor output |
| STEP | GREEN | GPIO16 of Raspberry Pi | moves the motor one step per pulse |
| DIR | WHITE | GPIO20 of Raspberry Pi | set the direction of the motor |
| DIAG | ORANGE | GPIO26 of Raspberry Pi | optional, for StallGuard |
The GPIO pins can be specific when initiating the class. If you test this on a breadboard, make sure to cut off the bottomside of the pins (Vref and DIAG) next to the EN pin, so that they are not shorted trough the breadboard.
| Pin TMC | Color | connect to | Function |
|---|---|---|---|
| TX or PDN_UART with 1kOhm | YELLOW | TX of Raspberry Pi | send data to TMC via UART |
| RX or PDN_UART directly | YELLOW | RX of Raspberry Pi | receive data from TMC via UART |
| Pin TMC | Color | connect to | Function |
|---|---|---|---|
| MOSI | MOSI | Data from Pi to TMC | |
| MISO | MOSI | Data from TMC to Pi | |
| SPI-CLK | CLK | Clock for SPI | |
| CS | SPI CE0 (for the demo scripts) | Chipselect (2nd parameter of TmcComSpi "spi_dev") |
You can run the demo scripts files from the main directory with
python3 -m demo.demo_script_01_uart_connectionThis only communicates with the TMC driver over UART. It should set some settings in the driver and then outputs the settings.
When it outputs TMC2209: UART Communication Error, you need to check the UART-connection.
This script enables the raspberry GPIO output for the dir, en and step pin and then checks the TMC driver register, whether the driver sees them as HIGH or LOW. Because the enabled pin is activated for a short time, the motor current ouput will be also activated in this script for a short time. This script should output: Pin DIR: OK Pin STEP: OK Pin EN: OK if not, check the connection of the pin.
This script shows the different functions available to move the motors. The motor is moved 4 times one revolution back and forth.
In this script the stallguard feature of the TMC2209 is being setup.
A funtion will be called, if the driver detects a stall. The function stops the current movement.
The motor will be moved 10 revolutions. If the movement is finished unhindered, the script outputs Movement finished successfully.
If you block the motor with pliers or something similar, the the motor will stop and the script outputs StallGuard! and Movement was not completed
VACTUAL enables the motor to be moved via the COM interface (UART) without additional GPIOs. The motor speed is transmitted as a value in +-(2^23)-1 [µsteps / t] via the COM interface.
Multiple drivers can be addressed via UART by setting different addresses with the MS1 and MS2 pins. Simultaneous movement of multiple motors can be done with threaded movement. When using SPI different Drivers are accessed via the Chip Select pin.
In this script, the movement of a stepper with threads is shown. This can be used to do other task while moving a motor, or to move several motors simultaneous.
This script shows how you can alter the formatting of the TMC2209 log messages and redirect the log output to a file called tmc2209_log_file.log that will be created in the current directory.
For me these baudrates worked fine: 19200, 38400, 57600, 115200, 230400, 460800, 576000.
If the TMC2209 driver is connected to the Vmotor, the internal voltage regulator will create the Vio for the chip. So you don't need to connect anything to the Vio pin of the driver.
The library currently uses functions to access the TMC registers, but Python properties for internal getters/setters.
from tmc_driver.tmc_2209 import *
tmc = Tmc2209(TmcEnableControlPin(21), TmcMotionControlStepDir(16, 20), TmcComUart("/dev/serial0"))
tmc.set_direction_reg(False)
tmc.set_current(300)
tmc.set_interpolation(True)
tmc.set_spreadcycle(False)
tmc.set_microstepping_resolution(2)
tmc.set_internal_rsense(False)
tmc.acceleration_fullstep = 1000
tmc.max_speed_fullstep = 250
tmc.set_motor_enabled(True)
tmc.run_to_position_steps(400)
tmc.run_to_position_steps(0)
tmc.set_motor_enabled(False)