docs: 说明书指令参考精简为exe界面涉及指令, 修复表格长文本截断

- 指令参考仅保留界面按钮对应的para与lora fc, 其余指令改为在线帮助提示
- 删除lpcfg/laser/sig等扩展操作指南章节, 恢复原有章节结构
- 表格单元格改为Paragraph自动换行, 修复超宽内容被截断的问题
- 补充界面细节: 串口参数固定8/N/1, 清空日志按钮, 升级自动切9600与超时保护

generate_manual.py

@@ -65,20 +65,20 @@ style_step = ParagraphStyle("Step", parent=style_body, leftIndent=20)
 style_warning = ParagraphStyle("Warning", parent=style_body, textColor=C_RED, fontName="SimHei")
 style_q = ParagraphStyle("Q", fontName="SimHei", fontSize=11, leading=20, spaceBefore=10, spaceAfter=2)
 style_a = ParagraphStyle("A", fontName="SimSun", fontSize=11, leading=20, leftIndent=20, spaceAfter=6)
+style_th = ParagraphStyle("TH", fontName="SimHei", fontSize=11, leading=15, textColor=white)
+style_td = ParagraphStyle("TD", fontName="SimSun", fontSize=10, leading=14)
 
 def make_table(headers, rows, col_widths=None):
-    data = [headers] + rows
+    # 单元格统一用 Paragraph 包装，超宽内容自动换行（字符串单元格会被截断）
+    from xml.sax.saxutils import escape as _esc
+    data = [[Paragraph(_esc(str(headers[0])), style_th)] + [Paragraph(_esc(str(c)), style_td) for c in headers[1:]]]
+    for r in rows:
+        data.append([Paragraph(_esc(str(c)), style_td) for c in r])
     if col_widths is None:
         col_widths = [doc.width / len(headers)] * len(headers)
     t = Table(data, colWidths=col_widths, repeatRows=1)
     style_cmds = [
         ("BACKGROUND", (0, 0), (-1, 0), C_HEADER_BG),
-        ("TEXTCOLOR", (0, 0), (-1, 0), C_HEADER_FG),
-        ("FONTNAME", (0, 0), (-1, 0), "SimHei"),
-        ("FONTSIZE", (0, 0), (-1, 0), 11),
-        ("FONTNAME", (0, 1), (-1, -1), "SimSun"),
-        ("FONTSIZE", (0, 1), (-1, -1), 10),
-        ("ALIGN", (0, 0), (-1, -1), "LEFT"),
         ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
         ("GRID", (0, 0), (-1, -1), 0.5, HexColor("#CCCCCC")),
         ("TOPPADDING", (0, 0), (-1, -1), 4),
@@ -156,7 +156,7 @@ features = [
     "波特率支持修改（内置2400~115200常用波特率，也可手动输入）",
     "查看设备低功耗配置参数（采集间隔、上报时间、紧急上报间隔/时长）",
     "注册状态自动转换为\"已注册/未注册\"显示",
-    "通过通用串口升级协议（V1.1）实现设备固件升级",
+    "通过通用串口升级协议（V1.1）实现设备固件升级，支持进度显示与断口复用",
     "支持发送自定义AT指令",
     "通讯日志实时显示，方便调试",
 ]
@@ -222,12 +222,12 @@ story.append(Paragraph("位于界面顶部，用于选择和配置串口连接
 story.append(make_table(
     ["项目", "说明", "默认值"],
     [
-        ["串口选择", "下拉框选择可用串口，点击\"刷新\"按钮可重新扫描", "自动选择第一个"],
+        ["串口选择", "下拉框选择可用串口（显示端口描述，同名端口自动追加COM号区分），点击\"刷新\"按钮可重新扫描", "自动选择第一个"],
-        ["波特率", "串口通信速率，可编辑下拉框，内置常用波特率，也可手动输入", "9600 bps"],
+        ["波特率", "串口通信速率，可编辑下拉框，内置2400/4800/9600/19200/38400/57600/115200，也可手动输入", "9600 bps"],
-        ["数据位", "每帧数据位数", "8"],
+        ["数据位", "固定为8，与设备通信协议一致（界面仅显示，不可修改）", "8"],
-        ["停止位", "停止位位数", "1"],
+        ["停止位", "固定为1，与设备通信协议一致（界面仅显示，不可修改）", "1"],
-        ["校验", "奇偶校验方式", "None（无校验）"],
+        ["校验", "固定为无校验，与设备通信协议一致（界面仅显示，不可修改）", "None（无校验）"],
-        ["打开/关闭串口", "按钮切换串口连接状态", "—"],
+        ["打开/关闭串口", "按钮切换串口连接状态；连接成功后串口下拉框锁定，关闭后恢复可选", "—"],
     ],
     col_widths=[3.5*cm, 8.5*cm, 4*cm]
 ))
@@ -268,21 +268,29 @@ story.append(make_table(
 ))
 
 story.append(Paragraph("4.4  低功耗配置区域", style_h2))
-story.append(Paragraph("显示设备的低功耗运行参数：", style_body))
+story.append(Paragraph("显示设备的低功耗运行参数（由para指令返回的LpCfg字段解析而来）：", style_body))
 story.append(make_table(
-    ["参数名称", "说明"],
+    ["参数名称", "说明", "取值范围"],
     [
-        ["CI（采集间隔）", "传感器数据采集的时间间隔，单位：秒"],
+        ["CI（采集间隔）", "传感器数据采集的时间间隔", "30~7200秒"],
-        ["RI（上报时间）", "数据上报到网关的时间间隔，单位：分钟/时"],
+        ["RI（上报时间）", "数据上报到网关的时间间隔", "5~720分钟"],
-        ["EI（紧急上报间隔）", "紧急状态下数据上报的时间间隔，单位：分钟/时"],
+        ["EI（紧急上报间隔）", "紧急状态下数据上报的时间间隔", "1~5分钟"],
-        ["ET（紧急上报时长）", "紧急上报模式持续时间，单位：分钟/时"],
+        ["ET（紧急上报时长）", "紧急上报模式持续时间", "10~120分钟"],
     ],
-    col_widths=[5*cm, 11*cm]
+    col_widths=[4.5*cm, 7.5*cm, 4*cm]
+))
+story.append(Spacer(1, 6))
+story.append(Paragraph(
+    "显示格式说明：CI以\"秒\"显示；RI/EI/ET以\"分钟\"显示，当数值≥60分钟时自动换算为\"X时X分钟\"格式（例如90分钟显示为\"1时30分钟\"）。",
+    style_body
 ))
 
 story.append(Paragraph("4.5  通讯日志区域", style_h2))
 story.append(Paragraph("界面底部，分为左右两部分：", style_body))
-story.append(Paragraph("日志窗口：实时显示串口通讯内容。不同类型信息用不同颜色区分：", style_body))
+story.append(Paragraph(
+    "日志窗口：深色背景，实时显示串口通讯内容。不同类型信息用不同颜色区分：",
+    style_body
+))
 story.append(make_table(
     ["颜色", "含义"],
     [
@@ -294,7 +302,11 @@ story.append(make_table(
     col_widths=[4*cm, 12*cm]
 ))
 story.append(Spacer(1, 6))
-story.append(Paragraph("自定义指令：右侧面板可输入自定义AT指令，点击\"发送\"或按Enter键发送。", style_body))
+story.append(Paragraph(
+    "清空日志：点击日志窗口下方的\"清空日志\"按钮可清除当前全部日志内容，便于新一轮操作的观察。",
+    style_body
+))
+story.append(Paragraph("自定义指令：右侧面板可输入自定义指令，点击\"发送\"或按Enter键发送，发送成功后输入框自动清空。", style_body))
 
 # 5 操作指南
 story.append(Paragraph("5  操作指南", style_h1))
@@ -337,27 +349,32 @@ story.append(Paragraph(
 ))
 
 story.append(Paragraph("5.4  设备升级", style_h2))
-story.append(Paragraph("设备升级用于通过通用串口升级协议对设备固件进行升级。升级期间请保持设备供电正常。", style_body))
+story.append(Paragraph("设备升级用于通过通用串口升级协议（V1.1）对设备固件进行升级。升级期间请保持设备供电正常。", style_body))
 steps = [
     "确认串口已成功连接。",
     "点击\"参数配置\"区域中的\"设备升级\"按钮，打开设备升级对话框。",
-    "在对话框中选择要更新的固件文件（.bin），并确认设备MAC地址（默认自动填充本机MAC）。",
+    "在对话框中点击\"浏览\"选择要更新的固件文件（.bin），并确认设备MAC地址（默认自动填充para查询到的本机MAC；格式为6字节横线分隔，例如 09-00-01-7F-FF-FF）。",
-    "点击\"开始升级\"按钮，软件通过协议下发固件并向设备逐包传输。",
+    "点击\"开始升级\"按钮，软件复用当前串口连接并自动切换至9600bps升级波特率，向设备下发固件信息（包数、大小、CRC32校验值）。",
-    "弹出进度条显示传输进度；升级日志显示握手/下发/完成等过程信息。",
+    "设备校验通过后逐包请求数据，软件按请求逐包下发固件；进度条显示\"n/m 包\"传输进度，升级日志显示握手/下发/完成等过程信息。",
-    "升级完成后可在同一对话框再次点击\"开始升级\"重复升级，无需关闭重开。",
+    "升级完成后串口自动恢复原波特率，可在同一对话框再次点击\"开始升级\"重复升级，无需关闭重开。",
 ]
 for i, s in enumerate(steps, 1):
     story.append(step(i, s))
+story.append(Spacer(1, 6))
 story.append(Paragraph(
-    "注意：升级过程中请勿断开串口或断电，否则可能导致设备无法正常启动。",
+    "注意：升级过程中请勿断开串口或断电，否则可能导致设备无法正常启动。若设备长时间无响应（约10秒），升级将自动停止并提示未完成，可检查接线后重试。",
     style_warning
 ))
+story.append(Paragraph(
+    "提示：升级期间设备输出的调试信息会以\"[设备]\"前缀转发到主界面通讯日志，可用于排查升级失败原因。",
+    style_body
+))
 
 story.append(Paragraph("5.5  发送自定义指令", style_h2))
 steps = [
     "确认串口已成功连接。",
     "在通讯日志区域右侧的\"自定义指令\"输入框中输入AT指令。",
-    "点击\"发送\"按钮或按Enter键发送。",
+    "点击\"发送\"按钮或按Enter键发送，发送成功后输入框自动清空。",
     "通讯日志中将显示发送的指令和设备的回应。",
 ]
 for i, s in enumerate(steps, 1):
@@ -365,18 +382,20 @@ for i, s in enumerate(steps, 1):
 
 # 6 指令参考
 story.append(Paragraph("6  指令参考", style_h1))
-story.append(Paragraph("软件内置以下AT指令：", style_body))
+story.append(Paragraph("软件界面涉及的指令如下：", style_body))
 story.append(make_table(
-    ["指令", "功能", "示例"],
+    ["指令", "功能", "对应操作"],
     [
-        ["para", "查询设备全部参数", "para"],
+        ["para", "查询设备全部参数", "点击\"查询当前配置(para)\"按钮"],
-        ["lora fc <频率值>", "设置Lora信道频率（单位Hz）", "lora fc " + FC_EXAMPLE],
+        ["lora fc <频率值>", "设置Lora信道频率（单位Hz）", "在\"Lora 参数\"下拉框中选择频率后点击\"发送\"，范围" + FC_RANGE + "；示例：lora fc " + FC_EXAMPLE],
-        ["（自定义指令）", "在自定义指令输入框中输入任意指令", "—"],
     ],
-    col_widths=[5*cm, 6*cm, 5*cm]
+    col_widths=[4.5*cm, 5.5*cm, 6*cm]
 ))
 story.append(Spacer(1, 6))
-story.append(Paragraph("说明：指令以回车换行（\\r\\n）结尾自动发送，无需手动添加。", style_body))
+story.append(Paragraph(
+    "说明：指令以回车换行（\\r\\n）结尾自动发送，无需手动添加。此外，可在自定义指令框中手动输入设备支持的其他指令，发送\"<指令> ?\"可查看该指令的在线帮助。",
+    style_body
+))
 
 # 7 常见问题
 story.append(Paragraph("7  常见问题与故障排除", style_h1))
@@ -413,6 +432,11 @@ qa_items = [
      "2. 确认固件文件为正确的.bin文件；\n"
      "3. 确认串口连接正常、设备供电稳定；\n"
      "4. 查看通讯日志中的设备调试信息辅助排查。"),
+    ("升级进度长时间停留/中途停止",
+     "1. 软件在约10秒未收到设备响应时会自动停止升级，属正常保护机制；\n"
+     "2. 检查RS485接线是否松动、设备供电是否稳定；\n"
+     "3. 关闭升级对话框后重新打开重试；\n"
+     "4. 若多次失败，查看主界面通讯日志中\"[设备]\"前缀的调试信息定位原因。"),
 ]
 for q, a in qa_items:
     story.append(Paragraph("Q: " + q, style_q))