> For the complete documentation index, see [llms.txt](https://delta-robotics.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://delta-robotics.gitbook.io/docs/software/thermoflex-python-api.md).
# ThermoFlex™ Python API
Install the ThermoFlex Python API with pip, then flex your first artificial muscle using the quickstart script and its required cleanup call
Welcome to the brains of the operation. The **ThermoFlex Python API** is your Python interface to the ThermoFlex artificial muscle system. It lets you command contractions, read sensors, and coordinate motion across your Delta Robotics hardware over a single USB connection.
The library is open source. If you want to go deeper, fork it, or see what kind of code we write after midnight, the source lives on [GitHub](https://github.com/Delta-Robotics-Inc/ThermoFlex-Python-API).
## Requirements
You need three things before you install.
* **Python.** The package requires Python 3.8 or newer. Delta recommends Python 3.12 or newer for the smoothest experience.
* **pip.** Python's package installer ships with modern Python builds. It pulls in the dependencies (`pyserial`, `protobuf`, and `pandas`) for you.
* **A TF Node Controller.** Connect it to your computer over USB. The library talks to it at 115200 baud and finds it by its USB signature.
{% hint style="info" %}
Working inside a virtual environment such as `venv` or `conda`? Activate it before you install, so the package lands in the right place.
{% endhint %}
## Install the API
Install the `thermoflex` package with pip.
```bash
pip install thermoflex
```
pip downloads the package and its dependencies. When it finishes, you can import `thermoflex` in any script or notebook.
Install manually or from source (for developers)
To work from a specific release or contribute to the library, clone the repository and install the `python-serial` folder.
```bash
git clone https://github.com/Delta-Robotics-Inc/ThermoFlex-Python-API
cd ThermoFlex-Python-API
pip install ./python-serial # standard install from source
pip install --editable ./python-serial # editable install for development
```
An editable install reflects your local source changes in the installed package, which is what you want while developing.
## Quickstart
This script discovers a node, attaches a muscle to port M1, drives it, and shuts down cleanly. It follows the canonical `muscle-simple` example from the repository.
{% hint style="danger" %}
The muscle heats its wire to contract, and the Mk.1 Muscle has no built-in overheat cutoff. Keep the run short, watch the muscle, and be ready to cut power if it gets too hot. The values below assume a TF Mk.1 Muscle on a 12 V supply.
{% endhint %}
{% code title="first\_flex.py" %}
```python
import thermoflex as tf
import time
node = tf.get_usb_node() # Discover the first node over USB
muscle = tf.Muscle(_port=0) # 0 = M1, 1 = M2
node.attachMuscle(muscle, 0) # Attach the muscle to port 0
muscle.setMode("percent") # Command as a fraction of full drive
muscle.setSetpoint("percent", 0.5) # Drive to 50 percent
muscle.setEnable(True)
time.sleep(2)
muscle.setSetpoint("percent", 0.1) # Ramp down to 10 percent
time.sleep(2)
node.disableAll() # Stop driving the muscle
time.sleep(0.1) # Let the disable command flush
tf.endAll() # Required: close ports and stop threads
```
{% endcode %}
On a successful run, the library reports the node it found and its firmware status. Expect output close to this, then watch the muscle contract and relax:
```
Found node on USB bus at port COM4
Node 0.0.1: Firmware v1.1.2 is compatible
```
{% hint style="warning" %}
Always finish with `tf.endAll()`. It disables every muscle, stops the background threads, and closes the serial port. Skip it and the port can stay locked, blocking your next run.
{% endhint %}
## Firmware compatibility
{% hint style="info" %}
The library expects TF Node Controller firmware between **1.1.1** and **1.1.2**. On discovery it checks the node's firmware and prints a warning if the version is older or newer than this window. If you see that warning, see [Firmware updates](/docs/software/firmware-updates.md).
{% endhint %}
## Common failures
No nodes found on available USB ports
`tf.get_usb_node()` raises a `TimeoutError` and `tf.discover()` raises an `ImportError` when no node answers. Check that the TF Node Controller is powered and connected over USB, and that no other program (such as a serial monitor) holds the port. On Linux, add your user to the `dialout` group and log back in.
The muscle does not move
Confirm you called `setEnable(True)` after setting the mode and setpoint, and that the muscle is attached to the correct port (0 for M1, 1 for M2). A setpoint of `0.0` in percent mode holds the muscle at rest.
The port is busy on the next run
This usually means the previous script did not call `tf.endAll()`. Close the Python process, unplug and replug the controller if needed, and add `tf.endAll()` to the end of every script.
## Related pages
* [API reference](/docs/software/thermoflex-python-api/api-reference.md): every function, class, and control mode
* [First time flexing your muscles](/docs/tutorials/thermoflex/getting-started-with-our-evaluation-kit/first-time-flexing-your-muscles.md): the guided eval-kit tutorial
* [Firmware updates](/docs/software/firmware-updates.md): keep the TF Node Controller in the supported range
* [Uninstall ThermoFlex API](/docs/tutorials/thermoflex/uninstall-thermoflex-api.md): remove the package
* [TF Node Controller](/docs/hardware/thermoflex/tf-node-controller.md): the hardware the API drives
***
### Need help?
If you run into trouble with setup, a bug, or a feature request, reach out.
* Email Kevin at
* Or open an issue on [GitHub](https://github.com/Delta-Robotics-Inc/ThermoFlex-Python-API/issues)