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
|