Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tuya/tuya-connector
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.
https://github.com/tuya/tuya-connector
connector iot openapi rest-api rest-client restful retrofit retrofit-starter retrofit2 retrofit2-starter tuya tuya-api tuya-cloud tuya-smart
Last synced: 7 days ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/tuya/tuya-connector
- Owner: tuya
- License: apache-2.0
- Created: 2021-05-04T06:35:38.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-05T02:10:56.000Z (3 months ago)
- Last Synced: 2025-01-08T00:11:27.064Z (14 days ago)
- Topics: connector, iot, openapi, rest-api, rest-client, restful, retrofit, retrofit-starter, retrofit2, retrofit2-starter, tuya, tuya-api, tuya-cloud, tuya-smart
- Language: Java
- Homepage:
- Size: 346 KB
- Stars: 62
- Watchers: 16
- Forks: 33
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[English](README.md) | [中文版](README_zh.md)
[](https://github.com/tuya/tuya-connector/blob/master/LICENSE 'License')
`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.
#### [demo vedio](https://www.youtube.com/watch?v=pEGg-n43UhI)
## Quick start
### Integrate Spring Boot
```xml
com.tuya
tuya-spring-boot-starter
#{latest.version}
tuya-maven
https://maven-other.tuya.com/repository/maven-public/
```
#### Configuration
```properties
# ClientId & SecretKey generated on the Tuya Cloud Development Platform
connector.ak=***
connector.sk=***
```
region configuration
```properties
# region configuration(default region is China if without configuration)
# more details, please check: com.tuya.connector.open.common.constant.TuyaRegion)
connector.region=CN
```
#### Usage
##### **Call OpenAPI operations**
1. Create the `Connector` interface, which is the mapping class of OpenAPI.
```java
public interface DeviceConnector {
/**
* query device info by device_id
* @param deviceId
* @return
*/
@GET("/v1.0/devices/{device_id}")
Device getById(@Path("device_id") String deviceId);
}
```
2. Set `@ConnectorScan` for the class of the Spring Boot application. You can set `@EnableMessaging` to enable the message subscription capability.
> 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.
```java
@ConnectorScan(basePackages = "com.xxx.connectors")
@EnableMessaging
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
```
3. The `Connector` interface will be scanned and injected into the Spring container.
```java
@Service
public class DeviceService {
@Autowired
private DeviceConnector device;
public Device getById(String deviceId) {
return device.getById(deviceId);
}
}
```
##### **Subscribe to message events**
```java
/**
* device status data report event
*/
@EventListener
public void statusReportMessage(StatusReportMessage event) {
log.info("### StatusReport event happened, eventInfo: {}", event);
}
```
## How it works: implement extensions based on the [connector](https://github.com/tuya/connector) framework.
### Extension points of OpenAPI
- ErrorProcessor
You 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`.
> **The extended `ErrorProcessor` must be injected into the Spring container to take effect.**
- ContextManager
The `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.
- TokenManager
`TuyaTokenManager` is the default token management mechanism and implements the `TokenManager` interface in the `connector` framework. The token information is cached on the premises.
> **To manage the token on the premises, you can extend `TokenManager` and inject it into the Spring container.**
- HeaderProcessor
`TuyaHeaderProcessor` implements the processing logic of the header for OpenAPI operations, including the required attribute values and signatures.
### Extension points of messages
- MessageDispatcher
`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.
- MessageEvent
You 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.
| **Message event** | **BizCode** | **Description** |
| --- | --- | --- |
| StatusReportMessage | statusReport | Report data to the cloud. |
| OnlineMessage | online | A device is online. |
| OfflineMessage | offline | A device is offline. |
| NameUpdateMessage | nameUpdate | Modify the device name. |
| DpNameUpdateMessage | dpNameUpdate | Modify the name of a data point. |
| DeleteMessage | delete | Remove a device. |
| BindUserMessage | bindUser | Bind the device to a user account. |
| UpgradeStatusMessage | upgradeStatus | The update status. |
| AutomationExternalActionMessage | automationExternalAction | Automate an external action. |
| SceneExecuteMessage | sceneExecute | Execute a scene. |