{"id":19858247,"url":"https://github.com/tuya/tuya-connector","last_synced_at":"2025-04-06T03:07:17.181Z","repository":{"id":37392510,"uuid":"364162351","full_name":"tuya/tuya-connector","owner":"tuya","description":"tuya-connector helps you efficiently create cloud development projects regarding the OpenAPI or message subscription capabilities. You can put all the focus on business logic without taking care of server-side programming nor relational databases.","archived":false,"fork":false,"pushed_at":"2025-01-17T09:30:09.000Z","size":357,"stargazers_count":64,"open_issues_count":15,"forks_count":33,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-03-30T02:05:07.935Z","etag":null,"topics":["connector","iot","openapi","rest-api","rest-client","restful","retrofit","retrofit-starter","retrofit2","retrofit2-starter","tuya","tuya-api","tuya-cloud","tuya-smart"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tuya.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2021-05-04T06:35:38.000Z","updated_at":"2025-03-10T23:49:53.000Z","dependencies_parsed_at":"2023-02-15T10:31:40.365Z","dependency_job_id":"16977c6e-06f0-45d4-b901-4a04c4293a81","html_url":"https://github.com/tuya/tuya-connector","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Ftuya-connector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Ftuya-connector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Ftuya-connector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuya%2Ftuya-connector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuya","download_url":"https://codeload.github.com/tuya/tuya-connector/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"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":["connector","iot","openapi","rest-api","rest-client","restful","retrofit","retrofit-starter","retrofit2","retrofit2-starter","tuya","tuya-api","tuya-cloud","tuya-smart"],"created_at":"2024-11-12T14:22:18.397Z","updated_at":"2025-04-06T03:07:17.156Z","avatar_url":"https://github.com/tuya.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[English](README.md) | [中文版](README_zh.md)\n\n[![License: Apache 2](https://img.shields.io/badge/license-Apache%202-green)](https://github.com/tuya/tuya-connector/blob/master/LICENSE 'License')\n![Version: 1.0.0](https://img.shields.io/badge/version-1.0.0-blue)\n\n`tuya-connector` helps you efficiently create cloud development projects regarding the OpenAPI or message subscription capabilities. You can put all the focus on business logic without taking care of server-side programming nor relational databases.\n\n\n#### [demo vedio](https://www.youtube.com/watch?v=pEGg-n43UhI)\n\n## Quick start\n### Integrate Spring Boot\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.tuya\u003c/groupId\u003e\n  \u003cartifactId\u003etuya-spring-boot-starter\u003c/artifactId\u003e\n  \u003cversion\u003e#{latest.version}\u003c/version\u003e\n\u003c/dependency\u003e\n\n\u003c!-- Specify the Maven repository URL --\u003e\n\u003crepository\u003e\n    \u003cid\u003etuya-maven\u003c/id\u003e\n    \u003curl\u003ehttps://maven-other.tuya.com/repository/maven-public/\u003c/url\u003e\n\u003c/repository\u003e\n```\n\n#### Configuration\n```properties\n# ClientId \u0026 SecretKey generated on the Tuya Cloud Development Platform\nconnector.ak=***\nconnector.sk=***\n```\nregion configuration\n```properties\n# region configuration(default region is China if without configuration)\n# more details, please check: com.tuya.connector.open.common.constant.TuyaRegion)\nconnector.region=CN\n```\n#### Usage\n##### **Call OpenAPI operations**\n\n1. Create the `Connector` interface, which is the mapping class of OpenAPI.\n```java\npublic interface DeviceConnector {\n    /**\n     * query device info by device_id\n     * @param deviceId\n     * @return\n     */\n    @GET(\"/v1.0/devices/{device_id}\")\n    Device getById(@Path(\"device_id\") String deviceId);\n}\n```\n\n2. Set `@ConnectorScan` for the class of the Spring Boot application. You can set `@EnableMessaging` to enable the message subscription capability.\n\u003e Note: Since the connector SDK relies on the reflection mechanism, and starting from JDK 9, a modularization mechanism has been introduced. Therefore, when starting, you need to add the parameters `--add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED` to avoid potential errors.\n```java\n@ConnectorScan(basePackages = \"com.xxx.connectors\")\n@EnableMessaging\n@SpringBootApplication\npublic class DemoApplication {\n    public static void main(String[] args) {\n        SpringApplication.run(DemoApplication.class, args);\n    }\n}\n```\n\n3. The `Connector` interface will be scanned and injected into the Spring container.\n```java\n@Service\npublic class DeviceService {\n    @Autowired\n    private DeviceConnector device;\n\n    public Device getById(String deviceId) {\n        return device.getById(deviceId);\n    }\n}\n```\n\n##### **Subscribe to message events**\n```java\n/**\n * device status data report event\n */\n@EventListener\npublic void statusReportMessage(StatusReportMessage event) {\n    log.info(\"### StatusReport event happened, eventInfo: {}\", event);\n}\n```\n\n## How it works: implement extensions based on the [connector](https://github.com/tuya/connector) framework.\n### Extension points of OpenAPI\n\n- ErrorProcessor\n\nYou can define the implementation class of `ErrorProcessor` to handle different error responses. For example, if a token expires, it can be automatically refreshed. The API operation will be tried again with the refreshed token. `TokenInvalidErrorProcessor` is the built-in implementation class of `ErrorProcessor`.\n\u003e **The extended `ErrorProcessor` must be injected into the Spring container to take effect.**\n\n\n- ContextManager\n\nThe `connector` framework supports `TuyaContextManager` on which the automatic token refreshing depends. `TuyaContextManager` can prepare the context before API operations, and manage information including data source connection, tokens, and multilingual text.\n\n- TokenManager\n\n`TuyaTokenManager` is the default token management mechanism and implements the `TokenManager` interface in the `connector` framework. The token information is cached on the premises.\n\u003e **To manage the token on the premises, you can extend `TokenManager` and inject it into the Spring container.**\n\n\n- HeaderProcessor\n\n`TuyaHeaderProcessor` implements the processing logic of the header for OpenAPI operations, including the required attribute values and signatures.\u003cbr /\u003e\n\n\n### Extension points of messages\n\n- MessageDispatcher\n\n`TuyaMessageDispatcher` implements `MessageDispatcher` interface for message dispatching in the `connector` framework. The dispatcher features message ordering and data decryption. It allows you to create specific message types and publish messages based on Spring's event mechanism.\u003cbr /\u003e\n\n- MessageEvent\n\nYou can add `ApplicationListener` to listen for required events. The `connector` framework includes all the Tuya's message event types. The message data contains ciphertext messages and plaintext messages.\n\n| **Message event** | **BizCode** | **Description** |\n| --- | --- | --- |\n| StatusReportMessage | statusReport | Report data to the cloud. |\n| OnlineMessage | online | A device is online. |\n| OfflineMessage | offline | A device is offline. |\n| NameUpdateMessage | nameUpdate | Modify the device name. |\n| DpNameUpdateMessage | dpNameUpdate | Modify the name of a data point. |\n| DeleteMessage | delete | Remove a device. |\n| BindUserMessage | bindUser | Bind the device to a user account. |\n| UpgradeStatusMessage | upgradeStatus | The update status. |\n| AutomationExternalActionMessage | automationExternalAction | Automate an external action. |\n| SceneExecuteMessage | sceneExecute | Execute a scene. |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuya%2Ftuya-connector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuya%2Ftuya-connector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuya%2Ftuya-connector/lists"}