490 lines
12 KiB
Markdown
490 lines
12 KiB
Markdown
# LED 屏管理系统技术文档
|
||
|
||
## 一、项目概述
|
||
|
||
本项目是基于 Onbon Bx06 系列 LED 控制器开发的 LED 屏管理系统，实现了 LED 屏的自动连接、内容绘制、定时刷新和状态监控等功能。
|
||
|
||
## 二、核心依赖
|
||
|
||
### Maven 依赖配置
|
||
项目使用 Onbon Bx06 系列 SDK，主要依赖包括：
|
||
|
||
```xml
|
||
<!-- Bx06 核心 SDK -->
|
||
<dependency>
|
||
<groupId>bx06</groupId>
|
||
<artifactId>bx06</artifactId>
|
||
<version>0.6.5-SNAPSHOT</version>
|
||
</dependency>
|
||
|
||
<!-- Bx06 消息处理 -->
|
||
<dependency>
|
||
<groupId>bx06.message</groupId>
|
||
<artifactId>bx06.message</artifactId>
|
||
<version>0.6.5-SNAPSHOT</version>
|
||
</dependency>
|
||
|
||
<!-- 通信相关 -->
|
||
<dependency>
|
||
<groupId>uia-comm</groupId>
|
||
<artifactId>uia-comm</artifactId>
|
||
<version>0.5.3-SNAPSHOT</version>
|
||
</dependency>
|
||
|
||
<!-- 其他依赖：jaxb、rxtx、simple-xml、slf4j 等 -->
|
||
```
|
||
|
||
## 三、核心架构
|
||
|
||
### 3.1 主要服务类
|
||
|
||
| 类名 | 职责 | 文件路径 |
|
||
|------|------|----------|
|
||
| LedServerService | LED 服务器管理，启动/停止/监控 | service/LedServerService.java |
|
||
| LedDrawService | LED 内容绘制和屏幕连接管理 | service/LedDrawService.java |
|
||
| LedServerListener | LED 屏连接/断开事件监听 | listener/LedServerListener.java |
|
||
| LedScreenServiceImpl | LED 屏配置管理和数据服务 | service/impl/LedScreenServiceImpl.java |
|
||
| LedController | REST API 接口 | controller/LedController.java |
|
||
| LedConfig | 配置类，启用定时任务 | config/LedConfig.java |
|
||
| LedProperties | 配置属性管理 | config/LedProperties.java |
|
||
|
||
### 3.2 工具类
|
||
|
||
| 类名 | 职责 |
|
||
|------|------|
|
||
| UniLedDrawer | LED 屏内容绘制工具（类型1） |
|
||
| Uni2LedDrawer | LED 屏内容绘制工具（类型2） |
|
||
| LedFileUtils | LED 文件操作工具 |
|
||
| LedContentUpdater | LED 内容更新工具 |
|
||
|
||
## 四、Onbon 接口使用详解
|
||
|
||
### 4.1 环境初始化接口
|
||
|
||
#### Bx6GEnv.initial()
|
||
```java
|
||
// 初始化 Bx6G 环境
|
||
Bx6GEnv.initial(ledProperties.getEnvTimeout());
|
||
```
|
||
- **功能**：初始化 Onbon Bx06 SDK 环境
|
||
- **参数**：超时时间（毫秒）
|
||
- **使用位置**：LedServerService.initializeServer()
|
||
|
||
### 4.2 服务器管理接口
|
||
|
||
#### Bx6GServer
|
||
```java
|
||
// 创建服务器实例
|
||
Bx6GServer server = new Bx6GServer("LED_Server", PORT, new Bx6E());
|
||
|
||
// 启动服务器
|
||
boolean started = server.start();
|
||
|
||
// 停止服务器
|
||
server.stop();
|
||
|
||
// 添加监听器
|
||
server.addListener(ledServerListener);
|
||
```
|
||
- **功能**：创建和管理 LED 服务器
|
||
- **参数**：
|
||
- 服务器名称
|
||
- 监听端口（默认 3801）
|
||
- 控制器类型（Bx6E/Bx6M/Bx6Q）
|
||
- **使用位置**：LedServerService
|
||
|
||
#### 控制器系列类
|
||
```java
|
||
import onbon.bx06.series.Bx6E;
|
||
import onbon.bx06.series.Bx6M;
|
||
import onbon.bx06.series.Bx6Q;
|
||
```
|
||
- **功能**：定义支持的控制器类型
|
||
- **使用位置**：LedServerService.getServerByType()
|
||
|
||
### 4.3 屏幕操作接口
|
||
|
||
#### Bx6GScreen
|
||
```java
|
||
// Ping 测试
|
||
Bx6GScreen.Result<?> result = screen.ping();
|
||
|
||
// 检查控制器状态
|
||
screen.checkControllerStatus();
|
||
|
||
// 检查固件版本
|
||
screen.checkFirmware();
|
||
|
||
// 读取控制器 ID
|
||
screen.readControllerId();
|
||
|
||
// 写入节目
|
||
screen.writeProgram(programFile);
|
||
|
||
// 获取屏幕配置
|
||
Bx6GScreenProfile profile = screen.getProfile();
|
||
```
|
||
- **功能**：LED 屏幕操作接口
|
||
- **使用位置**：LedDrawService, LedServerListener
|
||
|
||
### 4.4 节目文件接口
|
||
|
||
#### ProgramBxFile
|
||
```java
|
||
// 创建节目文件
|
||
ProgramBxFile programFile = new ProgramBxFile("P000", profile);
|
||
|
||
// 添加区域
|
||
programFile.addArea(area);
|
||
```
|
||
- **功能**：创建和管理节目文件
|
||
- **参数**：
|
||
- 节目名称
|
||
- 屏幕配置文件（Bx6GScreenProfile）
|
||
- **使用位置**：LedDrawService.createProgramByControllerType()
|
||
|
||
### 4.5 显示区域接口
|
||
|
||
#### TextCaptionBxArea（文本区域）
|
||
```java
|
||
// 创建文本区域
|
||
TextCaptionBxArea area = new TextCaptionBxArea(x, y, width, height, profile);
|
||
|
||
// 添加页面
|
||
area.addPage(textPage);
|
||
area.addPage(imagePage);
|
||
```
|
||
- **功能**：创建文本和图片显示区域
|
||
- **参数**：x坐标, y坐标, 宽度, 高度, 屏幕配置
|
||
- **使用位置**：LedDrawService.createBx6MProgram()
|
||
|
||
#### DateTimeBxArea（日期时间区域）
|
||
```java
|
||
// 创建日期时间区域
|
||
DateTimeBxArea timeBxArea = new DateTimeBxArea(0, height-16, width, 16, profile);
|
||
|
||
// 设置样式
|
||
timeBxArea.setMultiline(false);
|
||
timeBxArea.setDateStyle(DateStyle.YYYY_MM_DD_3);
|
||
timeBxArea.setTimeStyle(TimeStyle.HH_MM_SS_1);
|
||
timeBxArea.setWeekStyle(WeekStyle.CHINESE);
|
||
```
|
||
- **功能**：创建日期时间显示区域
|
||
- **样式选项**：
|
||
- DateStyle: YYYY_MM_DD_3 等多种日期格式
|
||
- TimeStyle: HH_MM_SS_1 等多种时间格式
|
||
- WeekStyle: CHINESE（中文）等星期格式
|
||
- **使用位置**：LedDrawService.createBx6MProgram()
|
||
|
||
### 4.6 页面接口
|
||
|
||
#### TextBxPage（文本页）
|
||
```java
|
||
// 创建文本页
|
||
TextBxPage textPage = new TextBxPage(text, new Font("宋体", Font.PLAIN, 12));
|
||
|
||
// 设置颜色
|
||
textPage.setForeground(Color.WHITE);
|
||
textPage.setBackground(Color.BLACK);
|
||
```
|
||
- **功能**：创建文本显示页面
|
||
- **参数**：文本内容, 字体
|
||
- **使用位置**：LedDrawService.createBx6MProgram()
|
||
|
||
#### ImageFileBxPage（图片页）
|
||
```java
|
||
// 创建图片页
|
||
ImageFileBxPage imagePage = new ImageFileBxPage(imagePath);
|
||
```
|
||
- **功能**：创建图片显示页面
|
||
- **参数**：图片文件路径
|
||
- **使用位置**：LedDrawService.createBx6MProgram()
|
||
|
||
### 4.7 服务器监听接口
|
||
|
||
#### Bx6GServerListener
|
||
```java
|
||
public class LedServerListener implements Bx6GServerListener {
|
||
@Override
|
||
public void connected(String socketId, String netId, Bx6GScreen screen) {
|
||
// LED 屏连接成功处理
|
||
}
|
||
|
||
@Override
|
||
public void disconnected(String socketId, String netId, Bx6GScreen screen) {
|
||
// LED 屏断开连接处理
|
||
}
|
||
}
|
||
```
|
||
- **功能**：监听 LED 屏的连接和断开事件
|
||
- **回调方法**：
|
||
- connected(): 屏幕连接时触发
|
||
- disconnected(): 屏幕断开时触发
|
||
- **使用位置**：LedServerListener
|
||
|
||
### 4.8 屏幕配置接口
|
||
|
||
#### Bx6GScreenProfile
|
||
```java
|
||
// 从屏幕获取配置
|
||
Bx6GScreenProfile profile = screen.getProfile();
|
||
|
||
// 使用配置创建区域
|
||
TextCaptionBxArea area = new TextCaptionBxArea(x, y, width, height, profile);
|
||
```
|
||
- **功能**：LED 屏幕配置文件
|
||
- **使用位置**：LedDrawService.createProgramByControllerType()
|
||
|
||
## 五、系统流程
|
||
|
||
### 5.1 服务器启动流程
|
||
|
||
```
|
||
1. 应用启动
|
||
↓
|
||
2. LedServerService.initializeServer() (@PostConstruct)
|
||
↓
|
||
3. 初始化 Bx6G 环境
|
||
Bx6GEnv.initial(envTimeout)
|
||
↓
|
||
4. 创建 LED 服务器
|
||
new Bx6GServer("LED_Server", PORT, new Bx6E())
|
||
↓
|
||
5. 添加监听器
|
||
server.addListener(ledServerListener)
|
||
↓
|
||
6. 启动服务器
|
||
server.start()
|
||
↓
|
||
7. 服务器监听端口 3801，等待 LED 屏连接
|
||
```
|
||
|
||
### 5.2 LED 屏连接流程
|
||
|
||
```
|
||
1. LED 屏主动连接到服务器（端口 3801）
|
||
↓
|
||
2. Bx6GServerListener.connected() 触发
|
||
↓
|
||
3. 清理旧连接（如果存在）
|
||
ledDrawService.removeConnectedScreen(netId)
|
||
↓
|
||
4. 更新数据库状态为在线
|
||
ledScreen.setOnline(true)
|
||
ledScreenService.updateLedScreen(ledScreen)
|
||
↓
|
||
5. 添加到连接管理器
|
||
ledDrawService.addConnectedScreen(netId, screen)
|
||
↓
|
||
6. 执行设备状态检查
|
||
- screen.ping()
|
||
- screen.checkControllerStatus()
|
||
- screen.checkFirmware()
|
||
- screen.readControllerId()
|
||
```
|
||
|
||
### 5.3 LED 内容绘制流程
|
||
|
||
```
|
||
1. 触发绘制请求
|
||
↓
|
||
2. drawLedScreenContent(ledScreen)
|
||
↓
|
||
3. 从连接管理器获取屏幕对象
|
||
Bx6GScreen screen = connectedScreens.get(deviceSn)
|
||
↓
|
||
4. 获取屏幕配置
|
||
Bx6GScreenProfile profile = screen.getProfile()
|
||
↓
|
||
5. 创建节目文件
|
||
ProgramBxFile programFile = new ProgramBxFile("P000", profile)
|
||
↓
|
||
6. 创建显示区域
|
||
a) 头部文本区域 (0, 0, width, 16)
|
||
- 创建 TextCaptionBxArea
|
||
- 添加 TextBxPage（标题）
|
||
|
||
b) 中间图片区域 (0, 17, width, height-32)
|
||
- 创建 TextCaptionBxArea
|
||
- 添加多个 ImageFileBxPage（图片列表）
|
||
|
||
c) 底部时间区域 (0, height-16, width, 16)
|
||
- 创建 DateTimeBxArea
|
||
- 设置日期/时间/星期样式
|
||
↓
|
||
7. 将区域添加到节目文件
|
||
programFile.addArea(area)
|
||
↓
|
||
8. 发送节目到 LED 屏
|
||
screen.writeProgram(programFile)
|
||
```
|
||
|
||
### 5.4 定时检测流程
|
||
|
||
#### 服务器状态检测（每30秒）
|
||
```
|
||
@Scheduled(fixedRate = 30000)
|
||
checkServerStatus()
|
||
↓
|
||
检查服务器是否运行
|
||
↓
|
||
如果未运行，尝试重启
|
||
- server.start()
|
||
- 失败则重新创建服务器实例
|
||
```
|
||
|
||
#### 设备在线状态检测（每30秒）
|
||
```
|
||
@Scheduled(fixedRate = 30000)
|
||
checkConnectedDevicesStatus()
|
||
↓
|
||
遍历所有已连接设备
|
||
↓
|
||
对每个设备执行 ping 测试
|
||
screen.ping()
|
||
↓
|
||
如果 ping 失败
|
||
- 从连接管理器移除
|
||
- 更新数据库状态为离线
|
||
```
|
||
|
||
### 5.5 LED 屏断开流程
|
||
|
||
```
|
||
1. LED 屏断开连接
|
||
↓
|
||
2. Bx6GServerListener.disconnected() 触发
|
||
↓
|
||
3. 更新数据库状态为离线
|
||
ledScreen.setOnline(false)
|
||
ledScreenService.updateLedScreen(ledScreen)
|
||
↓
|
||
4. 从连接管理器移除
|
||
ledDrawService.removeConnectedScreen(netId)
|
||
```
|
||
|
||
## 六、配置说明
|
||
|
||
### 6.1 application.yml 配置
|
||
|
||
```yaml
|
||
led:
|
||
server-host: localhost
|
||
server-port: 3801
|
||
refresh-interval: 30 # 刷新间隔（秒）
|
||
enabled: true
|
||
max-connection-retries: 3
|
||
connection-timeout: 5000 # 连接超时（毫秒）
|
||
response-timeout: 10000 # 响应超时（毫秒）
|
||
env-timeout: 30000 # 环境初始化超时（毫秒）
|
||
save-path: /Users/haha/code/leddata/ # LED 图片保存路径
|
||
```
|
||
|
||
### 6.2 屏幕布局说明
|
||
|
||
LED 屏内容分为三个区域：
|
||
|
||
| 区域 | 位置 | 尺寸 | 内容 |
|
||
|------|------|------|------|
|
||
| 头部区域 | (0, 0) | width × 16 | 标题文本 |
|
||
| 中间区域 | (0, 17) | width × (height-32) | 图片列表 |
|
||
| 底部区域 | (0, height-16) | width × 16 | 日期时间 |
|
||
|
||
## 七、数据库表结构
|
||
|
||
### SysLedscreen 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| deviceSn | String | 设备序列号（Net ID） |
|
||
| title | String | LED 屏标题 |
|
||
| width | Integer | 屏幕宽度 |
|
||
| height | Integer | 屏幕高度 |
|
||
| projectId | Long | 项目 ID |
|
||
| workareaId | Long | 工区 ID |
|
||
| drawType | Integer | 绘制类型（1/2） |
|
||
| online | Boolean | 在线状态 |
|
||
| enabled | Long | 是否启用 |
|
||
| isDel | Long | 是否删除 |
|
||
|
||
## 八、API 接口
|
||
|
||
### 8.1 获取服务器状态
|
||
```
|
||
GET /led/status?projectId={projectId}
|
||
```
|
||
返回：服务器运行状态和已连接屏幕数量
|
||
|
||
### 8.2 获取所有 LED 屏信息
|
||
```
|
||
GET /led/screens?projectId={projectId}
|
||
```
|
||
返回：LED 屏列表
|
||
|
||
### 8.3 获取特定 LED 屏信息
|
||
```
|
||
GET /led/screens/{netId}
|
||
```
|
||
返回：指定 LED 屏信息
|
||
|
||
### 8.4 手动刷新 LED 屏
|
||
```
|
||
POST /led/screens/{netId}/refresh
|
||
```
|
||
返回：刷新结果
|
||
|
||
### 8.5 更新 LED 屏配置
|
||
```
|
||
PUT /led/screens
|
||
Body: SysLedscreen
|
||
```
|
||
返回：更新结果
|
||
|
||
## 九、注意事项
|
||
|
||
1. **端口占用**：确保端口 3801 未被其他程序占用
|
||
2. **文件路径**：LED 图片保存路径需要有读写权限
|
||
3. **网络连接**：LED 屏需要能够访问服务器 IP 和端口
|
||
4. **定时任务**：确保 Spring Scheduling 已启用（@EnableScheduling）
|
||
5. **线程安全**：使用 ConcurrentHashMap 管理连接，确保线程安全
|
||
6. **异常处理**：所有 Onbon 接口调用都应包含异常处理
|
||
7. **资源释放**：应用停止时正确关闭服务器（@PreDestroy）
|
||
|
||
## 十、常见问题
|
||
|
||
### 10.1 服务器启动失败
|
||
- 检查端口 3801 是否被占用
|
||
- 检查 Bx6G 环境初始化是否成功
|
||
- 查看日志中的错误信息
|
||
|
||
### 10.2 LED 屏无法连接
|
||
- 检查网络连接
|
||
- 检查 LED 屏的 IP 配置
|
||
- 检查防火墙设置
|
||
- 确认 LED 屏的设备序列号正确
|
||
|
||
### 10.3 内容显示异常
|
||
- 检查图片路径是否正确
|
||
- 检查图片格式是否支持
|
||
- 检查屏幕尺寸配置是否正确
|
||
- 查看绘制日志
|
||
|
||
## 十一、技术栈
|
||
|
||
- **后端框架**：Spring Boot
|
||
- **LED SDK**：Onbon Bx06 0.6.5-SNAPSHOT
|
||
- **数据库**：MySQL（通过 MyBatis）
|
||
- **定时任务**：Spring Scheduling
|
||
- **日志**：SLF4J + Logback
|
||
- **工具库**：Hutool
|
||
|
||
## 十二、版本信息
|
||
|
||
- SDK 版本：bx06-0.6.5-SNAPSHOT
|
||
- Java 版本：1.8
|
||
- Spring Boot 版本：3.6.2
|
||
|
||
---
|
||
|
||
文档生成时间：2026-03-23
|