# tp-protocol-sdk-java **Repository Path**: ThingsPanel/tp-protocol-sdk-java ## Basic Information - **Project Name**: tp-protocol-sdk-java - **Description**: No description available - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 3 - **Created**: 2025-05-30 - **Last Updated**: 2025-12-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # TP Protocol SDK Java ThingsPanel Protocol SDK for Java，用于快速开发ThingsPanel协议和服务插件的Java版本。 ## 功能特性 - 设备配置管理 - MQTT消息通信 - HTTP回调处理 - HTTP API客户端 - 设备动态认证 - 服务接入点管理 - 心跳机制 - 简单易用的API ## 快速开始 ### 完整客户端使用（推荐） ```java // 创建完整客户端（包含MQTT和API功能） TPClient client = new TPClient("tcp://localhost:1883", "http://localhost:8080") .setAuth("username", "password") .setClientId("my-plugin-001") .setServiceIdentifier("my-service"); // 连接（会自动发送心跳） if (client.connect()) { // 1. 设备动态认证 TPAPIClient.APIResponse> authResponse = client.deviceDynamicAuth("template-secret-123", "device-001"); // 2. 获取设备配置 TPAPIClient.APIResponse configResponse = client.getDeviceConfig("device-001", "voucher-123", "DEV001"); // 3. 发送设备数据 String data = "{\"temperature\":25.5,\"humidity\":60}"; client.sendData("my-service", "device-001", data); // 4. 订阅下行消息 client.subscribe("plugin/my-service/devices/+/commands"); // 5. 发送心跳 client.sendHeartbeat(); client.disconnect(); } ``` ### MQTT客户端使用 ```java // 创建客户端 TPClient client = new TPClient("tcp://localhost:1883") .setAuth("username", "password") .setClientId("my-device-001"); // 连接到服务器 if (client.connect()) { // 发送设备状态 client.sendStatus("device-001", "1"); // 发送设备数据 String data = "{\"temperature\":25.5,\"humidity\":60}"; client.sendData("my-service", "device-001", data); // 订阅主题 client.subscribe("plugin/my-service/#"); // 断开连接 client.disconnect(); } ``` ### HTTP回调处理器使用 ```java // 创建处理器 TPHandler handler = new TPHandler(); // 设置表单配置处理函数 handler.setFormConfigHandler((protocolType, deviceType, formType) -> { Map config = new HashMap<>(); List> fields = new ArrayList<>(); // 添加配置字段 Map field = new HashMap<>(); field.put("name", "host"); field.put("type", "string"); field.put("label", "服务器地址"); fields.add(field); config.put("fields", fields); return config; }); // 设置设备断开处理函数 handler.setDeviceDisconnectHandler((deviceId, voucher) -> { System.out.println("设备断开: " + deviceId); }); // 启动HTTP服务器 handler.start(8080); ``` ### 设备管理 ```java // 创建设备 Device device = new Device("device-001", "voucher-123", "DEV001", "sensor", "mqtt"); // 设置设备配置 Map config = new HashMap<>(); config.put("host", "192.168.1.100"); config.put("port", 1883); device.setConfig(config); // 创建子设备 SubDevice subDevice = new SubDevice("sub-001", "sub-voucher", "SUB001", "addr-001"); List subDevices = new ArrayList<>(); subDevices.add(subDevice); device.setSubDevices(subDevices); ``` ## API说明 ### TPClient (主客户端) #### 构造函数 - `TPClient(String mqttBroker)` - 创建MQTT客户端 - `TPClient(String mqttBroker, String apiBaseURL)` - 创建完整客户端（MQTT + API） #### 配置方法 - `setAuth(String username, String password)` - 设置MQTT认证信息 - `setClientId(String clientId)` - 设置客户端ID - `setServiceIdentifier(String serviceIdentifier)` - 设置服务标识符 #### MQTT功能 - `connect()` - 连接到MQTT服务器 - `sendStatus(String deviceId, String status)` - 发送设备状态 - `sendData(String serviceIdentifier, String deviceId, String data)` - 发送设备数据 - `subscribe(String topic)` - 订阅主题 - `disconnect()` - 断开连接 #### API功能 - `getDeviceConfig(String deviceId, String voucher, String deviceNumber)` - 获取设备配置 - `deviceDynamicAuth(String templateSecret, String deviceNumber)` - 设备动态认证 - `getServiceAccess()` - 获取服务接入点信息 - `sendHeartbeat()` - 发送心跳 ### TPAPIClient (API客户端) - `getDeviceConfig(DeviceConfigRequest)` - 获取设备配置 - `deviceDynamicAuth(DeviceDynamicAuthRequest)` - 设备动态认证 - `getServiceAccess(ServiceAccessRequest)` - 获取服务接入点 - `sendHeartbeat(HeartbeatRequest)` - 发送心跳 ### TPHandler (HTTP回调处理器) - `setFormConfigHandler(FormConfigHandler handler)` - 设置表单配置处理函数 - `setDeviceDisconnectHandler(DeviceDisconnectHandler handler)` - 设置设备断开处理函数 - `setNotificationHandler(NotificationHandler handler)` - 设置通知处理函数 - `start(int port)` - 启动HTTP服务器 ### HTTP回调接口 - `/api/v1/form/config` - 获取表单配置 - `/api/v1/device/disconnect` - 设备断开通知 - `/api/v1/plugin/notification` - 事件通知 - `/api/v1/plugin/device/list` - 获取设备列表 ### HTTP API接口 - `/api/v1/plugin/device/config` - 获取设备配置 - `/api/v1/device/auth` - 设备动态认证 - `/api/v1/plugin/service/access` - 获取服务接入点 - `/api/v1/plugin/heartbeat` - 发送心跳 ### MQTT主题 - `devices/status/{device_id}` - 设备状态上报 - `plugin/{服务标识符}/devices/{device_id}/datas` - 设备数据上报 - `plugin/{服务标识符}/#` - 订阅平台数据主题 ## 文件结构 ``` tp-protocol-sdk-java/ ├── Device.java - 设备信息类 ├── SubDevice.java - 子设备信息类 ├── TPClient.java - 主客户端（MQTT + API） ├── TPAPIClient.java - HTTP API客户端 ├── TPHandler.java - HTTP回调处理器 ├── Example.java - 使用示例 └── README.md - 说明文档 ``` ## 运行示例 ```bash # 编译所有Java文件 javac *.java # 运行完整示例 java Example ``` ## 功能对比 ### 与Go版本功能对比 | 功能 | Go版本 | Java版本 | 状态 | |------|--------|----------|------| | MQTT客户端 | ✅ | ✅ | 完整实现 | | HTTP回调处理 | ✅ | ✅ | 完整实现 | | 设备配置获取 | ✅ | ✅ | 完整实现 | | 设备动态认证 | ✅ | ✅ | 完整实现 | | 服务接入点管理 | ✅ | ✅ | 完整实现 | | 心跳机制 | ✅ | ✅ | 完整实现 | | 数据类型定义 | ✅ | ✅ | 完整实现 | ### 实现差异 1. **Go版本优势**： - 使用真实的MQTT库（Eclipse Paho） - 更完善的错误处理 - 更好的并发支持 2. **Java版本特点**： - 使用Java 11+ HttpClient - 面向对象设计 - 简化的API接口 - 更好的类型安全 ## 注意事项 1. 这是一个功能完整的SDK框架，包含了Go版本的所有主要功能 2. MQTT功能当前是模拟实现，生产环境需要集成真正的MQTT库（如Eclipse Paho） 3. HTTP服务器功能需要集成Servlet容器或Spring Boot 4. JSON解析当前是简化实现，建议使用Jackson或Gson 5. 生产环境使用时需要添加完善的错误处理、重连机制等 ## 依赖建议 实际使用时建议添加以下依赖： - **MQTT客户端**: Eclipse Paho MQTT Client - **HTTP服务器**: Spring Boot Starter Web - **JSON处理**: Jackson或Gson - **日志框架**: SLF4J + Logback ## License This project is licensed under the Apache 2.0