Skip to main content

Touch Portal API and SDK for Python

Project description

Touch Portal API and SDK for Python

Easy way to build plugins for Touch Portal using Python.


The latest release can be found on PyPi. Simply run:

pip install TouchPortal-API

Alternatively, download/clone the source code from this repository and either:

  • pip install <path_to_source>
  • python <path_to_source>/ install
  • or place the /TouchPortalAPI folder and its contents from here into your plugin project's folder.


  • Python v3.8 or higher.
  • Additional Python modules pyee and requests (dependencies are automatically installed during setup, if necessary).
  • This Python API supports Touch Portal API version 3.0, as used in Touch Portal V2.3+.
  • Almost all the features from TP API (SDK 6.0 TP V 3.0.11) are fully implemented and tested with real plugins.


The API and SDK are documented in the code using common Python conventions.

Generated documentation is published at


A working plugin example is included in our repository which demonstrates usage of the API and SDK. Check the examples folder.

Basic Usage Example

Make a folder in %appdata%/TouchPortal/plugins/ or for Mac it would be in Document/TouchPortal/plugins called ExamplePlugin and make a file there called and paste this JSON data into that file:

  "sdk": 3,
  "version": 100,
  "name": "Example Plugin",
  "id": "ExamplePlugin",
  "categories": [
      "id": "Main",
      "name": "Example Plugin",
      "actions": [
          "id": "ExampleAction",
          "name": "This is an Example Action",
          "prefix": "plugin",
          "type": "communicate",
          "tryInline": true,
          "format": "Print({$ExampleTextData$})",
          "data": [
              "id": "ExampleTextData",
              "type": "text",
              "label": "text",
              "default": "Hello World"
      "states": [
          "id": "ExampleState",
          "type": "text",
          "desc": "Example State",
          "default": "None"

Restart Touch Portal and you should see your plugin. Now create a new file named with the following Python script. Note that the plugin, action, and state IDs used in the script correspond to the ones specified in the JSON.

import TouchPortalAPI as TP

# Setup callbacks and connection
TPClient = TP.Client("ExamplePlugin")

# This event handler will run once when the client connects to Touch Portal
@TPClient.on(TP.TYPES.onConnect) # Or replace TYPES.onConnect with 'info'
def onStart(data):
    print("Connected!", data)
    # Update a state value in TouchPortal
    TPClient.stateUpdate("ExampleState", "Connected!")

# Action handlers, called when user activates one of this plugin's actions in Touch Portal.
@TPClient.on(TP.TYPES.onAction) # Or 'action'
def onAction(data):
    # do something based on the action ID and the data value
    if data['actionId'] == "ExampleAction":
      # get the value from the action data (a string the user specified)
      action_value = getActionDataValue(data.get('data'), 'ExampleTextData')
      # We can also update our ExampleStates with the Action Value
      TPClient.stateUpdate("ExampleStates", action_value)

# Shutdown handler, called when Touch Portal wants to stop your plugin.
@TPClient.on(TP.TYPES.onShutDown) # or 'closePlugin'
def onShutdown(data):
    print("Got Shutdown Message! Shutting Down the Plugin!")
    # Terminates the connection and returns from connect()

# After callback setup like we did then we can connect.
# Note that `connect()` blocks further execution until
# `disconnect()` is called in an event handler, or an
# internal error occurs.

You should now be able to run this script from a command line (terminal) and it will interact with Touch Portal. To try it out, create a new button on a TP page which uses this plugin's "ExampleAction" action.

Change Log

1.7.9 (8/28/2022)

1.7.8 (8/27/2022)
- Added ADDITIONAL_TPPSDK_ARGS for additional tppsdk args
- Fixed in tppbuild it will add empty folder at root of the zip

1.7.7 (7/8/2022)
- Updated example in examples folder

1.7.6 (7/8/2022)
- Merged [#24](

1.7.5 (7/2/2022)
- Fixed typo where It can't generate states
- when generating doc `(click to expand)` is now smaller

1.7.4 (6/26/2022)
- Fixed doc gen and Python struct gen `format` and `readOnly` is not required key. so It will ignore this.

1.7.3 (6/26/2022)
(All this fixes is for doc generator)
- in ToC shows each category
- changed from Sliders to Connectors
- Made it so if theres more than one category for action/state/event/connector it will not show first detail open (Only if theres only 1)
- Instead of showing category Id now it will show category name instead.

1.7.2 (6/25/2022)
- Improved efficiency of generating Python struct
- Fixed Tools.convertImage_to_base64() (not all web image containing `content-type` header)
- and many more fixes from first review [pull #24](

1.7.1 (6/24/2022)
- Introduced tppdoc
- Introduced convert to Python struct

1.7 (6/4/2022)
- Updated pdoc
- Added logging 
- Added tppBuild

1.6.3 (5/27/2022)
- Added shortId
- sdk_spec updated to support parentGroup and new version of SDK

1.6.2 (1/14/2022)
- removed extra _ from connectorUpdate

1.6.1 (1/10/2022)
- Fixed connectorUpdate method
  - connectorValue needs to be a string
  - connectorId provided prefix eg "pc_yourpluginid_"

1.6 (8/26/2021)
- Notification (
  - Added notificationOptionClicked events to class TYPES
  - Added showNotification() method
- Connector can be used as silder (
  - Added connectorChange events to class TYPES
  - Added connectorUpdate method
- Client and Tools classes can now be imported separately as submodules.
- Added and updated lots of API documentation in code using Python "docstrings."
  - Reference docs now published at

1.5 (7/28/2021)
- Added tppsdk (Allows you to create within your code.)

1.4 (7/12/2021)
- Removed Socket Object from callback (v1.3 or older required to remove `client` from callback.)
- Added updateStatesOnBroadcast (automatically send all states on Broadcast message.)

1.3 (6/12/2021)
Pull requests from [#5]( and [#6](
- Minor cleanups
- Refactor Client to use selectors and non-blocking sockets.
- Sync with PyPi version.
- Optimize validations and key safety
- Added createStateMany()
- Added removeStateMany()

1.2 (4/12/2021)
- Added isActionBeingHeld(actionId) returns True or False

1.1.1 (3/24/2021)

Fix: fixed the readme for typo's
Fix: keywords
Fix: updateStates now only updates when value changed
Fix: createState now update the state if it already exists
Fix: updateSetting now only updates when value has changed

1.1.0 (3/23/2021)
- Fixed some typos

1.0 (3/23/2021)
# Feautres
- Easy to use
- createState
- removeState
- choice Update
- choice Update Specific
- setting Update
- state Update
- State Update Many
- Converting image to base64
- Update check

Touch Portal API documentation

Bugs and Suggestions

Please report any problems using GitHub Issues and feel free to use the Discussion feature as well.


Feel free to suggest a pull request for new features, improvements, or documentation. If you are not sure how to proceed with something, please start an Issue or Discussion at the GitHub repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

TouchPortal API-1.7.9.tar.gz (53.4 kB view hashes)

Uploaded source

Built Distribution

TouchPortal_API-1.7.9-py3-none-any.whl (58.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page