{"id":26236764,"url":"https://github.com/chr157i4n/pytmcstepper","last_synced_at":"2026-02-16T02:21:27.109Z","repository":{"id":41851226,"uuid":"327051012","full_name":"Chr157i4n/PyTmcStepper","owner":"Chr157i4n","description":"PyTmcStepper is a pure Python library for controlling Trinamic stepper drivers via UART or SPI on platforms like Raspberry Pi and MicroPython devices.","archived":false,"fork":false,"pushed_at":"2026-01-25T23:46:39.000Z","size":4866,"stargazers_count":97,"open_issues_count":2,"forks_count":30,"subscribers_count":10,"default_branch":"main","last_synced_at":"2026-01-26T06:22:19.844Z","etag":null,"topics":["circuitpython","driver","ft232h","micropython","pin","python","raspberry-pi","spi","stepper-motor","tmc2208","tmc2209","tmc2240","tmc5160","trinamic","uart"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Chr157i4n.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-01-05T16:09:48.000Z","updated_at":"2026-01-25T13:31:08.000Z","dependencies_parsed_at":"2023-09-30T15:15:50.055Z","dependency_job_id":"358bea2c-42f2-4a37-8e18-ae1c13d98248","html_url":"https://github.com/Chr157i4n/PyTmcStepper","commit_stats":{"total_commits":265,"total_committers":14,"mean_commits":"18.928571428571427","dds":"0.41132075471698115","last_synced_commit":"eb6c11b1672cfb1576cdf4ec482cfd556af7e831"},"previous_names":["chr157i4n/pytmcstepper","chr157i4n/tmc2209_raspberry_pi"],"tags_count":46,"template":false,"template_full_name":null,"purl":"pkg:github/Chr157i4n/PyTmcStepper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chr157i4n%2FPyTmcStepper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chr157i4n%2FPyTmcStepper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chr157i4n%2FPyTmcStepper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chr157i4n%2FPyTmcStepper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Chr157i4n","download_url":"https://codeload.github.com/Chr157i4n/PyTmcStepper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chr157i4n%2FPyTmcStepper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28978724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T12:13:08.691Z","status":"ssl_error","status_checked_at":"2026-02-01T12:13:08.356Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuitpython","driver","ft232h","micropython","pin","python","raspberry-pi","spi","stepper-motor","tmc2208","tmc2209","tmc2240","tmc5160","trinamic","uart"],"created_at":"2025-03-13T04:09:44.185Z","updated_at":"2026-02-01T13:01:10.956Z","avatar_url":"https://github.com/Chr157i4n.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyTmcStepper\n\n[![PyPI python version PyTmcStepper](https://badgen.net/pypi/python/PyTmcStepper)](https://pypi.org/project/PyTmcStepper)\n[![PyPI version PyTmcStepper](https://badgen.net/pypi/v/PyTmcStepper)](https://pypi.org/project/PyTmcStepper)\n[![PyPI downloads PyTmcStepper](https://img.shields.io/pypi/dm/PyTmcStepper)](https://pypi.org/project/PyTmcStepper)\n[![GitHub issues](https://img.shields.io/github/issues/Chr157i4n/PyTmcStepper.svg)](https://GitHub.com/Chr157i4n/PyTmcStepper/issues/)\n\n[![CI Pipeline](https://github.com/Chr157i4n/PyTmcStepper/actions/workflows/ci.yml/badge.svg)](https://github.com/Chr157i4n/PyTmcStepper/actions/workflows/ci.yml)\n[![Coverage badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Chr157i4n/PyTmcStepper/python-coverage-comment-action-data/endpoint.json)](https://htmlpreview.github.io/?https://github.com/Chr157i4n/PyTmcStepper/blob/python-coverage-comment-action-data/htmlcov/index.html)\n\n\\\n\\\nThis is a Python library to drive a stepper motor with a Trinamic stepper driver and a single board computer like a Raspberry Pi.\n\nThis code is still experimental, so use it at your own risk.\n\nThis library is programmed in pure Python. The performance of Python is not good enough to drive the motor with high speed.\nSo if you move the motor with high speed using this library the motor will lose steps.\n\nTested on a [Bigtreetech TMC2209 V1.2](https://github.com/bigtreetech/BIGTREETECH-Stepper-Motor-Driver/tree/master/TMC2209/V1.2) and [Bigtreetech TMC2209 V1.3](https://github.com/bigtreetech/BIGTREETECH-Stepper-Motor-Driver/tree/master/TMC2209/V1.3).\n\nIt has a rSense of 110 mOhm and it uses one Pin (PDN_UART) for UART RX and TX.\nSo the PDN_UART-Pin needs to be connected to the Raspberry Pis RX-Pin directly and to the TX-Pin with an 1kOhm resistor.\nYou can read more about this in the datasheet from Trinamic.\n\nBecause the TMC2209 uses one shared pin for transmit and receive in the UART communication line, the Raspberry Pi also receives what it sends.\nWell, the Pi receives 4 bytes from itself and 8 bytes from the driver. So the Pi receives a total of 12 bytes and only the last 8 are the reply, of which only 4 are data bytes.\n\nThe documentation of the TMC2209 can be found here:\n[TMC2209 - Datasheet](https://www.analog.com/media/en/technical-documentation/data-sheets/TMC2209_datasheet_rev1.09.pdf)\n\nThe code is also available on [PyPI](https://pypi.org/project/PyTmcStepper).\n\n## Installation (on Raspberry Pi)\n\n### Installation with PIP\n\n```shell\npip3 install PyTmcStepper\n```\n\n### Installation with GIT\n\n- clone this repo to your Raspberry Pi using\n\n    ```shell\n    git clone https://github.com/Chr157i4n/PyTmcStepper\n    cd PyTmcStepper\n    ```\n\n- (optional) install the lib to get proper syntax highlighting and start the demo scripts from every path\n\n    ```shell\n    pip3 install -e .\n    ```\n\n- install the required modules\n\n    ```shell\n    pip3 install RPi.GPIO pyserial\n    ```\n\n- enable the serial port in\n\n    ```shell\n    sudo raspi-config\n    ```\n\n### Board Support\n\nThe following table shows the supported boards and which libraries for GPIO access is being used for that board.\n\nLibrary     | Installation Parameter    | Boards\n----------- | ------------------------- | -----------\nRPi.GPIO    | raspberry_pi              | Pi4, Pi3 etc.\ngpiozero    | raspberry_pi5             | Pi5\nJetson.GPIO | nvidia_jetson             | Nvidia Jetson\nperiphery   | luckfox_pico              | Luckfox Pico\nOPi.GPIO    | orange_pi                 | Orange Pi\npyftdi      | ftdi                      | Windows/Linux\nmachine     | -                         | Pico, Pico2, ESP32, etc.\n\nThose libraries are needed for this library to work. You can either install the correct library yourself.\nYou can also install the needed GPIO library by specifying the Installation Parameter while installing this library:\n\n```shell\npip3 install PyTmcStepper[raspberry_pi, uart]\n```\n\n## Driver Support\n\nThe currently supported drivers are:\n\nDriver  | Interface\n--      | --\nTMC2208 | UART\nTMC2209 | UART\nTMC2240 | SPI/UART\nTMC5160 | SPI/UART\n\n## Submodules\n\nwith V0.7 the code for enabling the motor current output and the code for controlling the motion of the drivers\nis split into their own classes to be able to support the diverse methods.\n\n### EnableControl\n\nThe 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.\n\nEnableControl   | Class                                                                 | Driver    | Notes\n--              | --                                                                    | --        | --\nPin             | [TmcEnableControlPin](src/tmc_driver/enable_control/_tmc_ec_pin.py)   | all       | the EN Pin of the Driver needs to be connected to a GPIO of the Pi\nTOff            | [TmcEnableControlToff](src/tmc_driver/enable_control/_tmc_ec_toff.py) | all       | the EN Pin needs to be connected to GND.\u003cbr /\u003eOn the TMC2209 this enables current Output on Startup!\u003cbr /\u003eOn the TMC2240 this works fine, because TOff is per default 0 (off).\n\n### MotionControl\n\nThe MotionControl module controls the motion of the motor. Before a movement the motor current output needs to be enabled by the [EnableControl](#enablecontrol) module.\n\nMotionControl   | Class                                                                                             | Driver    | Notes\n--              | --                                                                                                | --        | --\nSTEP/DIR        | [TmcMotionControlStepDir](src/tmc_driver/motion_control/_tmc_mc_step_dir.py)                      | all       | the STEP and DIR pin of the driver must each be connected to a GPIO of the Pi\nSTEP/REG        | [TmcMotionControlStepReg](src/tmc_driver/motion_control/_tmc_mc_step_reg.py)                      | all       | only the STEP pin needs to be connected to a GPIO of the Pi.\u003cbr /\u003eThe direction is controlled via the Register.\nVACTUAL         | [TmcMotionControlVActual](src/tmc_driver/motion_control/_tmc_mc_vactual.py)                       | 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.\nSTEP_PWM/DIR    | [TmcMotionControlStepPwmDir](src/tmc_driver/motion_control/_tmc_mc_step_pwm_dir.py)               | 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).\u003cbr /\u003eSTEP must be connected to a PWM-capable pin for this purpose\nRAMP_GENERATOR  | [TmcMotionControlIntRampGenerator](src/tmc_driver/motion_control/_tmc_mc_int_ramp_generator.py)   | TMC5160   | the SD_Mode Pin needs to be LOW for this to work. This is not possible on all TMC5160-Boards easily.\n\nFurther methods of controlling the motion of a motor could be:\n\n- via a µC which controlls the Motor\n- highperformance Step/Dir Library written in a compiled language (C/C++)\n\n### Com\n\nCom             | Class                                                     | Driver    | Notes\n--              | --                                                        | --        | --\nUART            | [TmcComUart](src/tmc_driver/com/_tmc_com_uart.py)         | all       | Communication via UART (RX, TX). See [Wiring](#uart)\u003cbr /\u003e[pyserial](https://pypi.org/project/pyserial) needs to be installed\nSPI             | [TmcComSpi](src/tmc_driver/com/_tmc_com_spi.py)           | TMC2240   | Communication via SPI (MOSI, MISO, CLK, CS). See [Wiring](#spi)\u003cbr /\u003e[spidev](https://pypi.org/project/spidev) needs to be installed\nSPI over FT232H | [TmcComSpiFtdi](src/tmc_driver/com/_tmc_com_spi_ftdi.py)  | TMC2240   | Communication via SPI using a FT232H. This can be used on any OS.\u003cbr /\u003e[pyftdi](https://pypi.org/project/pyftdi) needs to be installed\n\n## Wiring\n\n![wiring diagram](docs/images/wiring_tmc2209_rpi4.png)\n\nPin TMC | Color     | connect to                    | Function\n--      | --        | --                            | --\nVDD     |           | 3,3V of Raspberry Pi          | recommended, for forcing the TMC to use 3,3V logic level\nGND     | BLACK     | GND of Raspberry Pi           | GND for VDD and Signals\nVM      | RED       | 12V or 24V of power supply    | power for the motor\nGND     | BLACK     | GND of power supply           | power for the motor\nEN      | RED       | GPIO21 of Raspberry Pi        | enable the motor output\nSTEP    | GREEN     | GPIO16 of Raspberry Pi        | moves the motor one step per pulse\nDIR     | WHITE     | GPIO20 of Raspberry Pi        | set the direction of the motor\nDIAG    | ORANGE    | GPIO26 of Raspberry Pi        | optional, for StallGuard\n\nThe GPIO pins can be specific when initiating the class.\nIf 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.\n\n### UART\n\nPin TMC                     | Color     | connect to            | Function\n--                          | --        | --                    | --\nTX or PDN_UART with 1kOhm   | YELLOW    | TX of Raspberry Pi    | send data to TMC via UART\nRX or PDN_UART directly     | YELLOW    | RX of Raspberry Pi    | receive data from TMC via UART\n\n### SPI\n\nPin TMC | Color | connect to                        | Function\n--      | --    | --                                | --\nMOSI    |       | MOSI                              | Data from Pi to TMC\nMISO    |       | MOSI                              | Data from TMC to Pi\nSPI-CLK |       | CLK                               | Clock for SPI\nCS      |       | SPI CE0 (for the demo scripts)    | Chipselect (2nd parameter of TmcComSpi \"spi_dev\")\n\n## Demo scripts\n\nYou can run the demo scripts files from the main directory with\n\n```shell\npython3 -m demo.demo_script_01_uart_connection\n```\n\n### [demo_script_01_uart_connection.py](demo/demo_script_01_uart_connection.py)\n\nThis only communicates with the TMC driver over UART. It should set some settings in the driver and then outputs the settings.\nWhen it outputs ```TMC2209: UART Communication Error```, you need to check the UART-connection.\n\n### [demo_script_02_pin_connection.py](demo/demo_script_02_pin_connection.py)\n\nThis script enables the raspberry GPIO output for the dir, en and step pin and then checks the TMC driver register,\nwhether the driver sees them as HIGH or LOW. Because the enabled pin is activated for a short time, the motor current ouput\nwill be also activated in this script for a short time.\nThis script should output:\nPin DIR:        OK\nPin STEP:       OK\nPin EN:         OK\nif not, check the connection of the pin.\n\n### [demo_script_03_basic_movement.py](demo/demo_script_03_basic_movement.py)\n\nThis script shows the different functions available to move the motors.\nThe motor is moved 4 times one revolution back and forth.\n\n### [demo_script_04_stallguard.py](demo/demo_script_04_stallguard.py)\n\nIn this script the stallguard feature of the TMC2209 is being setup.\nA funtion will be called, if the driver detects a stall. The function stops the current movement.\nThe motor will be moved 10 revolutions. If the movement is finished unhindered, the script outputs ```Movement finished successfully```.\nIf you block the motor with pliers or something similar, the the motor will stop and the script outputs ```StallGuard!``` and ```Movement was not completed```\n\n### [demo_script_05_vactual.py](demo/demo_script_05_vactual.py)\n\nVACTUAL 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.\n\n### [demo_script_06_multiple_drivers.py](demo/demo_script_06_multiple_drivers.py)\n\nMultiple drivers can be addressed via UART by setting different addresses with the MS1 and MS2 pins.\nSimultaneous movement of multiple motors can be done with threaded movement.\nWhen using SPI different Drivers are accessed via the Chip Select pin.\n\n### [demo_script_07_threads.py](demo/demo_script_07_threads.py)\n\nIn 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.\n\n### [demo_script_08_log_to_file.py](demo/demo_script_08_log_to_file.py)\n\nThis 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.\n\n\\\n\\\nFor me these baudrates worked fine: 19200, 38400, 57600, 115200, 230400, 460800, 576000.\n\nIf the TMC2209 driver is connected to the Vmotor, the internal voltage regulator will create the Vio for the chip.\nSo you don't need to connect anything to the Vio pin of the driver.\n\n### Micropython\n\nThe lib is also compatible with MicroPython. For using it with Micropython the VSCode addon [MicroPico](https://marketplace.visualstudio.com/items?itemName=paulober.pico-w-go) is used. Use the Upload Project function to upload the src folder and the needed lib folder.\n\nthe needed libs, which are not builtin in Micropython are:\n\nLib         | available on MIP\n--          | --\nabc         | yes\nenum        | no\nthreading   | yes\ntypes       | yes\n\nYou can also use MicroPico to run the demo script by opening one and then pressing Run on the bottom left corner\n\n## Usage\n\nThe library currently uses functions to access the TMC registers, but Python properties for internal getters/setters.\n\n```python\nfrom tmc_driver import Tmc2209, TmcEnableControlPin, TmcMotionControlStepDir\nfrom tmc_driver.com import TmcComUart\n\ntmc = Tmc2209(TmcEnableControlPin(21), TmcMotionControlStepDir(16, 20), TmcComUart(\"/dev/serial0\"))\n\ntmc.set_direction_reg(False)\ntmc.set_current_rms(300)\ntmc.set_interpolation(True)\ntmc.set_spreadcycle(False)\ntmc.set_microstepping_resolution(2)\ntmc.set_internal_rsense(False)\n\ntmc.acceleration_fullstep = 1000\ntmc.max_speed_fullstep = 250\n\ntmc.set_motor_enabled(True)\n\ntmc.run_to_position_steps(400)\ntmc.run_to_position_steps(0)\n\ntmc.set_motor_enabled(False)\n```\n\nspecial register access:\n\n```python\nfrom tmc_driver import Tmc2209, TmcEnableControlPin, TmcMotionControlStepDir\nfrom tmc_driver.com import TmcComUart\n\ntmc = Tmc2209(TmcEnableControlPin(21), TmcMotionControlStepDir(16, 20), TmcComUart(\"/dev/serial0\"))\n\ntmc.chopconf.read()         # read register from the driver\nprint(tmc.chopconf.intpol)  # print current interpolation setting\ntmc.chopconf.intpol = True  # enable interpolation\ntmc.chopconf.write()        # write register to the driver\n```\n\n## Troubleshoot\n\nIf you have questions please check out the [Wiki](https://github.com/Chr157i4n/PyTmcStepper/wiki) and the other issues.\n\nIf you encounter any problems, feel free to open an issue (ENG/GER).\nPlease don't send any E-Mails to me. Pls use Github, so that i don't need to answer the same question multiple times.\nI reserve the right not to answer E-Mails.\n\nProblem                                                                                 | Solution\n--                                                                                      | --\nFileNotFoundError: [Errno 2] No such file or directory: '/dev/serial0'                  | depending on your Raspberry Pi version, you need to enable the Serial Port \u003cbr /\u003e run `sudo raspi-config` in your terminal. \u003cbr /\u003e there go to '3 Interface Options' -\u003e 'P3 Serial Port' \u003cbr /\u003e Would you like a login shell to be accessible over serial? No \u003cbr /\u003e Would you like the serial port hardware to be enabled? Yes \u003cbr /\u003e Finish and then reboot\nPermissionError: [Errno 13] \u003cbr /\u003e Permission denied: '/dev/serial0'                    | you need to give the permission to acces the Serial Port to your current user \u003cbr /\u003e You may need to add your user (pi) to the dialout group with `sudo usermod -a -G dialout pi` and then relog. \u003cbr /\u003e If that does not work, make sure that your user has read/write permissions on the dev file `/dev/serial0` by calling `sudo chmod 660 /dev/serial0`.\n\"TMC2209: UART Communication Error\"                                                     | You can use the 'debug_script_01_uart_connection' script to get a better reading on the received bytes and troubleshoot your problem\n\"TMC2209: UART Communication Error: 0 data bytes \\| 4 total bytes\"                      | only 4 total bytes received indicates, that the Raspberry Pi receives its own data, but nothing from the TMC driver. This happens if RX and TX are connected properly, but the TMC driver has no power\n\"TMC2209: UART Communication Error: 0 data bytes \\| 0 total bytes\"                      | 0 total bytes received indicates, a problem with your wiring or your Raspberry Pi. This happens if TX is not connected\n\"TMC2209: UART Communication Error: 4 data bytes \\| 12 total bytes\"                     | this indicates, the Raspberry Pi received only zeroes. This happens if only RX is connected and TX not\n\"the Raspberry Pi received only the sended bits\" or\u003cbr /\u003e inconsistent received bits    | Make sure the UART ist properly connected to the TMC driver and the driver is powered and working. \u003cbr /\u003e Make sure login shell (console) over serial is disabled.\n\n![wiring photo](docs/images/wiring_photo.jpg)\n\n## Acknowledgements\n\nThe code to run the stepper motor is based on the code of the [AccelStepper Library from Mike McCauley](http://www.airspayce.com/mikem/arduino/AccelStepper).\n\nThe code for the UART communication is based on this [code from troxel](https://github.com/troxel/TMC_UART).\n\nFor the implementation of Python-stdlib for micropython [micropython-lib](https://github.com/micropython/micropython-lib)\n\nMy goal is to make a library, that can run a stepper motor with a TMC2209 stepper driver and can write the setting in the register of the TMC2209, entirely in Python.\nThe main focus for this are Test setups, as Python is not fast enough for high motor speeds.\n\n## Feedback/Contributing\n\nIf you encounter any problem, feel free to open an issue on the Github [issue page](https://github.com/Chr157i4n/PyTmcStepper/issues).\nFeedback will keep this project growing and I encourage all suggestions.\nFeel free to submit a pull request on the dev branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchr157i4n%2Fpytmcstepper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchr157i4n%2Fpytmcstepper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchr157i4n%2Fpytmcstepper/lists"}