{"id":21744418,"url":"https://github.com/killerboss2019/touchportal-api","last_synced_at":"2025-04-13T05:11:56.575Z","repository":{"id":37626078,"uuid":"350859921","full_name":"KillerBOSS2019/TouchPortal-API","owner":"KillerBOSS2019","description":"This is a SDK for https://www.touch-portal.com/api/ easy to use","archived":false,"fork":false,"pushed_at":"2024-06-07T04:28:54.000Z","size":852,"stargazers_count":15,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-26T22:03:36.745Z","etag":null,"topics":["api","easy-to-use","intergration","plugin","python","sdk-python","touchportal"],"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/KillerBOSS2019.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2021-03-23T21:17:05.000Z","updated_at":"2024-08-23T09:52:29.000Z","dependencies_parsed_at":"2023-01-22T23:00:08.029Z","dependency_job_id":"67be3f63-fdaf-4728-99c0-e66655b95b6b","html_url":"https://github.com/KillerBOSS2019/TouchPortal-API","commit_stats":{"total_commits":149,"total_committers":6,"mean_commits":"24.833333333333332","dds":0.5302013422818792,"last_synced_commit":"7f7b069c03316f3cc1475b60141380dbf7012f63"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerBOSS2019%2FTouchPortal-API","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerBOSS2019%2FTouchPortal-API/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerBOSS2019%2FTouchPortal-API/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KillerBOSS2019%2FTouchPortal-API/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KillerBOSS2019","download_url":"https://codeload.github.com/KillerBOSS2019/TouchPortal-API/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665744,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api","easy-to-use","intergration","plugin","python","sdk-python","touchportal"],"created_at":"2024-11-26T07:11:30.652Z","updated_at":"2025-04-13T05:11:56.555Z","avatar_url":"https://github.com/KillerBOSS2019.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Touch Portal API and SDK for Python\nEasy way to build plugins for [Touch Portal](https://touch-portal.com) using Python.\n\n## Installation\nThe latest release can be found on [PyPi](https://pypi.org/project/TouchPortal-API/). Simply run:\n\n`pip install TouchPortal-API`\n\nAlternatively, download/clone the source code from this repository and either:\n- `pip install \u003cpath_to_source\u003e`\n- `python \u003cpath_to_source\u003e/setup.py install`\n- or place the `/TouchPortalAPI` folder and its contents from here into your plugin project's folder.\n\n### Requires\n- Python v3.8 or higher.\n- Additional Python modules `pyee` and `requests` (dependencies are automatically installed during setup, if necessary).\n- This Python API supports Touch Portal API version 3.0, as used in Touch Portal V2.3+.\n- Almost all the features from TP API (SDK 6.0 TP V 3.0.11) are fully implemented and tested with real plugins.\n\n\n## Documentation\n\nThe API and SDK are documented in the code using common Python conventions.\n\nGenerated documentation is published at https://KillerBOSS2019.github.io/TouchPortal-API/\n\n\n## Examples\n\nA working plugin example is included in our repository which demonstrates usage of the API and SDK.\nCheck the [examples folder](https://github.com/KillerBOSS2019/TouchPortal-API/tree/main/examples).\n\n### Basic Usage Example\n\nMake a folder in `%appdata%/TouchPortal/plugins/` or for Mac it would be in `Document/TouchPortal/plugins` called `ExamplePlugin`\nand make a file there called `entry.tp` and paste this JSON data into that file:\n\n```json\n{\n  \"sdk\": 3,\n  \"version\": 100,\n  \"name\": \"Example Plugin\",\n  \"id\": \"ExamplePlugin\",\n  \"categories\": [\n    {\n      \"id\": \"Main\",\n      \"name\": \"Example Plugin\",\n      \"actions\": [\n        {\n          \"id\": \"ExampleAction\",\n          \"name\": \"This is an Example Action\",\n          \"prefix\": \"plugin\",\n          \"type\": \"communicate\",\n          \"tryInline\": true,\n          \"format\": \"Print({$ExampleTextData$})\",\n          \"data\": [\n            {\n              \"id\": \"ExampleTextData\",\n              \"type\": \"text\",\n              \"label\": \"text\",\n              \"default\": \"Hello World\"\n            }\n          ]\n        }\n      ],\n      \"states\": [\n        {\n          \"id\": \"ExampleState\",\n          \"type\": \"text\",\n          \"desc\": \"Example State\",\n          \"default\": \"None\"\n        }\n      ]\n    }\n  ]\n}\n```\n\nRestart Touch Portal and you should see your plugin.\nNow create a new file named `plugin.py` with the following\nPython script. Note that the plugin, action, and state IDs\nused in the script correspond to the ones specified in the\n`entry.tp` JSON.\n\n```python\nimport TouchPortalAPI as TP\n\n# Setup callbacks and connection\nTPClient = TP.Client(\"ExamplePlugin\")\n\n# This event handler will run once when the client connects to Touch Portal\n@TPClient.on(TP.TYPES.onConnect) # Or replace TYPES.onConnect with 'info'\ndef onStart(data):\n    print(\"Connected!\", data)\n    # Update a state value in TouchPortal\n    TPClient.stateUpdate(\"ExampleState\", \"Connected!\")\n\n# Action handlers, called when user activates one of this plugin's actions in Touch Portal.\n@TPClient.on(TP.TYPES.onAction) # Or 'action'\ndef onAction(data):\n    print(data)\n    # do something based on the action ID and the data value\n    if data['actionId'] == \"ExampleAction\":\n      # get the value from the action data (a string the user specified)\n      action_value = getActionDataValue(data.get('data'), 'ExampleTextData')\n      print(action_value)\n      # We can also update our ExampleStates with the Action Value\n      TPClient.stateUpdate(\"ExampleStates\", action_value)\n\n# Shutdown handler, called when Touch Portal wants to stop your plugin.\n@TPClient.on(TP.TYPES.onShutDown) # or 'closePlugin'\ndef onShutdown(data):\n    print(\"Got Shutdown Message! Shutting Down the Plugin!\")\n    # Terminates the connection and returns from connect()\n    TPClient.disconnect()\n\n# After callback setup like we did then we can connect.\n# Note that `connect()` blocks further execution until\n# `disconnect()` is called in an event handler, or an\n# internal error occurs.\nTPClient.connect()\n```\n\nYou should now be able to run this script from a command line (terminal)\nand it will interact with Touch Portal. To try it out, create a new button\non a TP page which uses this plugin's \"ExampleAction\" action.\n\n\n## Change Log\n\n```\n1.7.10 (8/12/2023)\n-------------------\n- Fixed typo `ADDITIONAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`\n- Fixed tppdoc error when importing py file\n- tppbuild optional args is not required to be included in build file.\n- Removed some unused imports\n- Added \"image/webp\" format to convertImage_to_base64()\n- TpToPy.py action data and state key starts at 1 instead of 0\n\n\n1.7.9 (8/28/2022)\n-------------------\n- Typo `ADDITINAL_TPPSDK_ARGS` changed to `ADDITIONAL_TPPSDK_ARGS`\n\n1.7.8 (8/27/2022)\n-------------------\n- Added ADDITIONAL_TPPSDK_ARGS for additional tppsdk args\n- Fixed in tppbuild it will add empty folder at root of the zip\n\n1.7.7 (7/8/2022)\n-------------------\n- Updated example in examples folder\n\n1.7.6 (7/8/2022)\n-------------------\n- Merged [#24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)\n\n1.7.5 (7/2/2022)\n-------------------\n- Fixed typo where It can't generate states\n- when generating doc `(click to expand)` is now smaller\n\n1.7.4 (6/26/2022)\n-------------------\n- Fixed doc gen and Python struct gen `format` and `readOnly` is not required key. so It will ignore this.\n\n1.7.3 (6/26/2022)\n-------------------\n(All this fixes is for doc generator)\n- in ToC shows each category\n- changed from Sliders to Connectors\n- 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)\n- Instead of showing category Id now it will show category name instead.\n\n1.7.2 (6/25/2022)\n-------------------\n- Improved efficiency of generating Python struct\n- Fixed Tools.convertImage_to_base64() (not all web image containing `content-type` header)\n- and many more fixes from first review [pull #24](https://github.com/KillerBOSS2019/TouchPortal-API/pull/24)\n\n1.7.1 (6/24/2022)\n-------------------\n- Introduced tppdoc\n- Introduced convert entry.tp to Python struct\n\n1.7 (6/4/2022)\n-------------------\n- Updated pdoc\n- Added logging \n- Added tppBuild\n\n1.6.3 (5/27/2022)\n-------------------\n- Added shortId\n- sdk_spec updated to support parentGroup and new version of SDK\n\n1.6.2 (1/14/2022)\n-------------------\n- removed extra _ from connectorUpdate\n\n1.6.1 (1/10/2022)\n-------------------\n- Fixed connectorUpdate method\n  - connectorValue needs to be a string\n  - connectorId provided prefix eg \"pc_yourpluginid_\"\n\n1.6 (8/26/2021)\n-------------------\n- Notification (https://www.touch-portal.com/api/index.php?section=notifications)\n  - Added notificationOptionClicked events to class TYPES\n  - Added showNotification() method\n- Connector can be used as silder (https://www.touch-portal.com/api/index.php?section=connectors)\n  - Added connectorChange events to class TYPES\n  - Added connectorUpdate method\n- Client and Tools classes can now be imported separately as submodules.\n- Added and updated lots of API documentation in code using Python \"docstrings.\"\n  - Reference docs now published at https://KillerBOSS2019.github.io/TouchPortal-API/\n\n\n1.5 (7/28/2021)\n-------------------\n- Added tppsdk (Allows you to create entry.tp within your code.)\n\n1.4 (7/12/2021)\n-------------------\n- Removed Socket Object from callback (v1.3 or older required to remove `client` from callback.)\n- Added updateStatesOnBroadcast (automatically send all states on Broadcast message.)\n\n1.3 (6/12/2021)\n-------------------\nPull requests from [#5](https://github.com/KillerBOSS2019/TouchPortal-API/pull/5) and [#6](https://github.com/KillerBOSS2019/TouchPortal-API/pull/6)\n- Minor cleanups\n- Refactor Client to use selectors and non-blocking sockets.\n- Sync __init__.py with PyPi version.\n- Optimize validations and key safety\n- Added createStateMany()\n- Added removeStateMany()\n\n1.2 (4/12/2021)\n-------------------\n- Added isActionBeingHeld(actionId) returns True or False\n\n1.1.1 (3/24/2021)\n-------------------\nFixes\n\nFix: fixed the readme for typo's\nFix: keywords\nFix: updateStates now only updates when value changed\nFix: createState now update the state if it already exists\nFix: updateSetting now only updates when value has changed\n\n1.1.0 (3/23/2021)\n-------------------\n- Fixed some typos\n\n1.0 (3/23/2021)\n-------------------\n# Feautres\n- Easy to use\n- createState\n- removeState\n- choice Update\n- choice Update Specific\n- setting Update\n- state Update\n- State Update Many\n- Converting image to base64\n- Update check\n```\n\n## Touch Portal API documentation\nhttps://www.touch-portal.com/api\n\n## Bugs and Suggestions\nPlease report any problems using GitHub [Issues](https://github.com/KillerBOSS2019/TouchPortal-API/issues)\nand feel free to use the [Discussion](https://github.com/KillerBOSS2019/TouchPortal-API/discussions)\nfeature as well.\n\n## Contribute\nFeel free to suggest a pull request for new features, improvements, or documentation.\nIf you are not sure how to proceed with something, please start an Issue or Discussion\nat the GitHub repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillerboss2019%2Ftouchportal-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkillerboss2019%2Ftouchportal-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkillerboss2019%2Ftouchportal-api/lists"}