first commit
This commit is contained in:
zhaohengze
243
poweroff_linux/串口关机文档.md
Normal file
243
poweroff_linux/串口关机文档.md
Normal file
@ -0,0 +1,243 @@
|
||||
# 串口关机控制器
|
||||
|
||||
通过串口接收指令触发 x86 Ubuntu 系统关机的程序。
|
||||
|
||||
## 功能概述
|
||||
|
||||
本程序持续监听指定的串口，当接收到特定的关机指令时，自动执行系统关机操作。适用于嵌入式 x86 Ubuntu 系统中需要通过外部设备（如 MCU/Arduino）控制关机的场景。
|
||||
|
||||
程序启动后会主动发送 `start` 握手指令，并每秒定时发送 `blive` 心跳包，用于告知对端设备本机处于在线状态。
|
||||
|
||||
## 主要特性
|
||||
|
||||
- 持续监听串口数据
|
||||
- 支持配置文件自定义串口参数
|
||||
- 自动重连机制（串口断开后每 5 秒重新连接）
|
||||
- 按行解析接收到的数据
|
||||
- 串口连接后发送 `start` 握手指令
|
||||
- 每秒定时发送 `blive` 心跳包
|
||||
- 执行系统关机命令
|
||||
|
||||
## 通信协议
|
||||
|
||||
### 本机发送（→ 对端）
|
||||
|
||||
| 指令 | 触发时机 | 说明 |
|
||||
|------|----------|------|
|
||||
| `start\r\n` | 串口连接成功后立即发送 | 握手指令，通知对端本机已就绪 |
|
||||
| `blive\r\n` | 每秒定时发送 | 心跳包，通知对端本机仍在运行 |
|
||||
| `ok\r\n` | 系统关机（poweroff）时发送 | 关机钩子脚本发送，通知对端本机即将关机 |
|
||||
|
||||
### 本机接收（← 对端）
|
||||
|
||||
| 指令 | 说明 |
|
||||
|------|------|
|
||||
| `shutdownWord`（配置项） | 收到后立即触发系统关机，默认为 `SHUTDOWN` |
|
||||
|
||||
## 配置说明
|
||||
|
||||
配置文件为 `config.json`，与可执行文件放在同一目录下，包含以下参数：
|
||||
|
||||
| 参数 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| port | string | 串口设备路径 | `/dev/ttyUSB0` |
|
||||
| baudRate | int | 串口波特率 | 115200 |
|
||||
| shutdownWord | string | 触发关机的指令文本 | `SHUTDOWN` |
|
||||
|
||||
### 串口设备路径
|
||||
|
||||
x86 Ubuntu 下常见的串口设备路径格式：
|
||||
|
||||
| 设备类型 | 路径格式 | 说明 |
|
||||
|----------|----------|------|
|
||||
| USB 转串口 | `/dev/ttyUSBx` | USB-RS232/USB-TTL 转接器（如 CH340、CP2102、FT232） |
|
||||
| USB CDC ACM | `/dev/ttyACMx` | USB 虚拟串口设备(使用USB时) |
|
||||
| 原生串口 | `/dev/ttySx` | 主板自带 RS232 串口（COM 口） |
|
||||
|
||||
> `x` 为设备编号，从 0 开始。可通过 `ls /dev/tty*` 或 `dmesg | grep tty` 查看系统中可用的串口设备。
|
||||
|
||||
### 配置示例
|
||||
使用 USB 转串口：
|
||||
```json
|
||||
{
|
||||
"port": "/dev/ttyUSB0",
|
||||
"baudRate": 115200,
|
||||
"shutdownWord": "SHUTDOWN"
|
||||
}
|
||||
```
|
||||
|
||||
使用 USB CDC：
|
||||
|
||||
```json
|
||||
{
|
||||
"port": "/dev/ttyACM0",
|
||||
"baudRate": 115200,
|
||||
"shutdownWord": "SHUTDOWN"
|
||||
}
|
||||
```
|
||||
|
||||
使用主板原生串口：
|
||||
|
||||
```json
|
||||
{
|
||||
"port": "/dev/ttyS0",
|
||||
"baudRate": 115200,
|
||||
"shutdownWord": "SHUTDOWN"
|
||||
}
|
||||
```
|
||||
|
||||
## 交叉编译
|
||||
|
||||
本程序在 Windows 上开发，需要交叉编译为 x86 Linux 可执行文件：
|
||||
|
||||
```bash
|
||||
set GOOS=linux
|
||||
set GOARCH=amd64
|
||||
set CGO_ENABLED=0
|
||||
go build -o shutdown shutdown.go
|
||||
```
|
||||
|
||||
PowerShell 环境：
|
||||
|
||||
```powershell
|
||||
$env:GOOS = "linux"
|
||||
$env:GOARCH = "amd64"
|
||||
$env:CGO_ENABLED = "0"
|
||||
go build -o shutdown shutdown.go
|
||||
```
|
||||
|
||||
编译产物 `shutdown` 为 Linux x86_64 可执行文件，需上传至目标 Ubuntu 系统运行。
|
||||
|
||||
## 部署与运行
|
||||
|
||||
### 方式一：使用安装脚本（推荐）
|
||||
|
||||
项目提供 `install.sh` 安装脚本，可自动完成串口选择、配置生成、服务安装等全部流程。
|
||||
|
||||
#### 上传项目到目标系统
|
||||
|
||||
```bash
|
||||
scp -r ./ user@<目标IP>:/home/user/shutdown/
|
||||
```
|
||||
|
||||
#### 运行安装脚本
|
||||
|
||||
```bash
|
||||
cd /home/user/shutdown
|
||||
sudo bash install.sh
|
||||
```
|
||||
|
||||
#### 安装流程
|
||||
|
||||
1. **选择串口** - 脚本自动扫描系统中的串口设备（`ttyUSB*`、`ttyACM*`、`ttyS*`），列出设备并标明类型，交互选择或手动输入路径
|
||||
2. **配置参数** - 可自定义波特率（默认 115200）和关机指令（默认 SHUTDOWN）
|
||||
3. **确认安装** - 显示完整配置供确认
|
||||
4. **自动编译** - 检测到 Go 环境则交叉编译，否则使用预编译二进制
|
||||
5. **安装文件** - 二进制和配置文件安装到 `/opt/ttyshutdown/`
|
||||
6. **关机钩子** - 生成 `/usr/lib/systemd/system-shutdown/send_signal.sh`，系统关机时通过串口发送 `ok\r\n` 通知对端
|
||||
7. **systemd 服务** - 生成并启用 `ttyshutdown.service`
|
||||
|
||||
#### 安装后管理
|
||||
|
||||
```bash
|
||||
# 查看服务状态
|
||||
systemctl status ttyshutdown
|
||||
|
||||
# 查看实时日志
|
||||
journalctl -u ttyshutdown -f
|
||||
|
||||
# 停止服务
|
||||
systemctl stop ttyshutdown
|
||||
|
||||
# 更换串口
|
||||
sudo bash change_port.sh
|
||||
|
||||
# 卸载
|
||||
sudo bash uninstall.sh
|
||||
```
|
||||
|
||||
### 更换串口
|
||||
|
||||
当需要更换串口设备时（如更换 USB 端口、更换转接器等），使用 `change_port.sh` 脚本可自动完成配置更新和服务重启。
|
||||
|
||||
```bash
|
||||
sudo bash change_port.sh
|
||||
```
|
||||
|
||||
#### 更换流程
|
||||
|
||||
1. **显示当前配置** - 展示当前串口设备、波特率、关机指令
|
||||
2. **选择新串口** - 自动扫描系统中可用串口，当前使用的串口会标注 `<-- 当前`，交互选择或手动输入新路径
|
||||
3. **可选修改参数** - 波特率和关机指令可直接回车保持不变，或输入新值修改
|
||||
4. **确认更改** - 显示新旧配置对比供确认
|
||||
5. **执行更改** - 同时更新 `config.json` 和 `send_signal.sh`，并自动重启 `ttyshutdown` 服务
|
||||
|
||||
> 脚本会同时更新 `config.json` 和 `send_signal.sh` 中的串口配置，确保两者一致。
|
||||
|
||||
### 方式二：手动部署
|
||||
|
||||
#### 1. 上传到目标系统
|
||||
|
||||
```bash
|
||||
scp shutdown config.json user@<目标IP>:/home/user/shutdown/
|
||||
```
|
||||
|
||||
#### 2. 添加执行权限
|
||||
|
||||
```bash
|
||||
chmod +x shutdown
|
||||
```
|
||||
|
||||
#### 3. 运行程序
|
||||
|
||||
```bash
|
||||
sudo ./shutdown
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 程序需要 root 权限才能执行系统关机命令
|
||||
2. 串口断开后会每 5 秒尝试重新连接
|
||||
3. 接收的数据以换行符（`\n` 或 `\r\n`）为单位进行解析
|
||||
4. 关机指令必须与配置文件中的 `shutdownWord` 完全匹配（区分大小写）
|
||||
5. 串口重连后 `start` 握手和 `blive` 心跳会自动重新启动
|
||||
6. 串口设备路径在设备重新插拔后可能变化（ttyUSB0 → ttyUSB1），建议使用 udev 规则绑定固定设备名
|
||||
7. 安装脚本会将选定的串口设备同时写入 `config.json` 和 `send_signal.sh`，确保两者一致
|
||||
|
||||
|
||||
## 日志输出
|
||||
|
||||
程序运行时会输出以下日志信息：
|
||||
|
||||
- 配置加载状态
|
||||
- 串口连接状态
|
||||
- `start` 握手指令发送状态
|
||||
- 接收到的数据内容
|
||||
- 关机指令触发和执行状态
|
||||
- 串口错误和重连状态
|
||||
|
||||
## 关机钩子
|
||||
|
||||
系统关机时，`/usr/lib/systemd/system-shutdown/send_signal.sh` 会被 systemd 调用，在系统执行 poweroff 前通过串口向对端发送 `ok\r\n`，通知对端本机即将关机。
|
||||
|
||||
该脚本由安装脚本自动生成，其中 `TTY_DEVICE` 与 `config.json` 中的 `port` 保持一致。
|
||||
|
||||
## 文件说明
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `shutdown.go` | 主程序源码 |
|
||||
| `config.json` | 串口配置文件（与二进制同目录） |
|
||||
| `send_signal.sh` | systemd 关机钩子脚本，安装到 `/usr/lib/systemd/system-shutdown/` |
|
||||
| `ttyshutdown.service` | systemd 服务单元文件 |
|
||||
| `install.sh` | 安装脚本 |
|
||||
| `uninstall.sh` | 卸载脚本 |
|
||||
| `change_port.sh` | 更换串口脚本 |
|
||||
|
||||
## 技术实现
|
||||
|
||||
- 编程语言：Go
|
||||
- 目标平台：x86 Ubuntu (linux/amd64)
|
||||
- 依赖库：`go.bug.st/serial`（串口通信）
|
||||
- 关机命令：`shutdown -h now`
|
||||
- 交叉编译：CGO_ENABLED=0 静态编译，无外部依赖
|
||||
Reference in New Issue
Block a user