# sensor_ws

**Repository Path**: Huanzze/sensor_ws

## Basic Information

- **Project Name**: sensor_ws
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 传感器数据采集系统 - 用户手册

**树莓派传感器数据采集系统 | 运维部署指南**

支持 5 个传感器：太阳辐射 × 1 | 温湿度 × 2 | 粉尘 × 2

---

## 1. 快速开始

### 1.1 硬件连接

参考 ((20260415144818-ocvexod '2.3 接线说明'))小节，完成传感器实地连接。

### 1.2 软件配置

取下树莓派 TF 卡，使用读卡器插入另一台电脑。
![image](树莓派TF卡.png)

在文件管理器打开 TF 卡中的 `rootfs` 分区，如图示。
![image](文件管理器1.png)

1. 找到 `sensor_ws` 项目文件夹，默认为 `/home/ubuntu/sensor_ws`；
   ![image](文件管理器2.png)
2. 进入 WiFi 配置：`etc/sensor_ws/config/wifi_config.yaml`，根据需要修改 WiFi 配置；
   ![image](WiFi配置.png)
3. 进入 MQTT 配置：`src/sensor_driver/config/mqtt_bridge.yaml`，根据需要修改 MQTT 配置。
   ![image](MQTT配置.png)

完成修改并保存后，弹出 TF 卡，重新插入树莓派。

### 1.3 接通电源

使用随附 12v 充电头，插入充电接口。（切忌插错接口）

### 1.4 检验正常运行

确保 WiFi 网络已开启，树莓派会自动连接上已配置的网络。

在另一台连接相同网络的 Linux 电脑上，通过 `mosquitto_sub` 命令可以查看发布的 MQTT 话题数据。

```bash
sudo apt install mosquitto mosquitto_client
mosquitto_sub -h <配置的IP地址> -p <配置的端口号> -t /airs/environment/up/<配置的设备号，默认是213>
```

也可以通过 `ssh` 连接上树莓派，用户名 `ubuntu`，密码 `1`。

---

# 各组成部分简要介绍

## 2. 硬件组成

### 2.1 传感器清单

| 序号 | 传感器名称       | 类型  | Modbus 地址 | 测量参数           | 单位    |
| ------ | ------------------ | ------- | ------------- | -------------------- | --------- |
| 1    | 太阳辐射传感器   | RS485 | 0x01        | 辐射强度           | W/m²   |
| 2    | 温湿度传感器 1   | RS485 | 0x02        | 温度、湿度         | ℃、%RH |
| 3    | 温湿度传感器 2   | RS485 | 0x03        | 温度、湿度         | ℃、%RH |
| 4    | 激光粉尘传感器 1 | 串口  | -           | PM1.0、PM2.5、PM10 | μg/m³ |
| 5    | 激光粉尘传感器 2 | 串口  | -           | PM1.0、PM2.5、PM10 | μg/m³ |

### 2.2 端口映射表

| 系统端口 | 连接设备        | 通信参数  | 说明                              |
| ---------- | ----------------- | ----------- | ----------------------------------- |
| `/dev/ttyACM0`         | USB 转 485 模块 | 9600, 8N1 | 485 总线（太阳辐射 + 温湿度 ×2） |
| `/dev/ttyUSB0`         | 粉尘传感器 1    | 9600, 8N1 | ZH03B/ZH06                        |
| `/dev/ttyUSB1`         | 粉尘传感器 2    | 9600, 8N1 | ZH03B/ZH06                        |

### 2.3 接线说明

> ![image](接口说明.png)
>
> *着重注意区分 485 接口和串口接口所适配的传感器，不得混用！否则烧坏传感器。*
> ![image](接线说明.png)
> **485** 接口只支持**光电**传感器和**温湿度**传感器，**串口**接口只支持**粉尘**传感器。

- **太阳辐射传感器**：防水盒顶部，透光面朝上
- **温湿度传感器 1/2**：防水盒中部，485 总线串联
- **粉尘传感器 1/2**：防水盒侧面，激光口朝外，水平放置

### 2.4 供电要求（盒内已处理供电，只需外接 12vDC 供电）

| 设备       | 电压 | 电流      | 备注         |
| ------------ | ------ | ----------- | -------------- |
| 树莓派     | 5V   | ≥3A      | 转接板供电   |
| 传感器总线 | 12V  | ≥2A      | 输入直接供电 |
| 粉尘传感器 | 5V   | ≥0.5A/个 | 树莓派供电   |

> ⚠️ **警告**：严禁将 12V 电源接入树莓派 GPIO，会导致设备永久损坏！

---

## 3. 上电启动

### 3.1 上电前完整检查

| 检查项        | 检查内容                  | 合格标准         |
| --------------- | --------------------------- | ------------------ |
| □ 电源电压   | 用万用表测量 12V 电源输出 | 11.5V-12.5V      |
| □ 传感器接线 | 检查所有模块连接          | 无松动、正确位置 |
| □ 网络连接   | 检查网线/WiFi 配置        | 能 ping 通网关   |
| □ ROS 环境   | 确认 ROS Melodic 已安装   | `rosversion -d` 返回 melodic    |

### 3.2 上电要求

配套 12v DC 供电，直接接入即启动整套系统。

### 3.3 启动命令（手动启动，调试用）

```bash
# 1. 刷新环境
source ~/sensor_ws/devel/setup.bash

# 2. 启动 roscore（新终端窗口 1）
roscore

# 3. 启动 485 总线节点（新终端窗口 2）
rosrun sensor_driver multi_sensor_485_node.py

# 4. 启动粉尘传感器 1（新终端窗口 3）
rosrun sensor_driver dust_sensor_node.py

# 5. 启动粉尘传感器 2（新终端窗口 4）
rosrun sensor_driver dust_sensor_node_blue01.py

# 6. 启动 MQTT 桥接（新终端窗口 5）
rosrun sensor_driver mqtt_bridge_node.py
```

### 3.4 验证启动成功

```bash
# 1. 检查 ROS 节点是否运行
rosnode list
# 应看到：/mqtt_bridge, /multi_sensor_485_node, /dust_sensor_node (×2)

# 2. 检查话题是否有数据
rostopic hz /solar_radiation_01/data
rostopic hz /temp_humi_02/data
rostopic hz /dust_sensor/data
# 频率应稳定在 0.2-1 Hz

# 3. 查看实时数据
rostopic echo /solar_radiation_01/data -n 1
# 应看到类似：radiation: 856.3

# 4. 查看 mqtt 发布
mosquitto_sub -h localhost -p 1883 -t /airs/environment/up/213
```

---

## 4. 配置修改

### 4.1 MQTT 配置文件位置

配置文件路径：

```
sensor_ws/src/sensor_driver/config/mqtt_bridge.yaml
```

### 4.2 Broker 连接参数详解

```yaml
broker:
  host: "localhost"      # MQTT Broker 地址，修改为实际服务器 IP 或域名
  port: 1883             # MQTT 端口（1883: 非加密，8883: TLS 加密）
  keepalive: 60          # 心跳间隔（秒），超时未响应则断开重连
  username: "your_username"  # 认证用户名（如 Broker 需要认证，取消注释）
  password: "your_password"  # 认证密码（如 Broker 需要认证，取消注释）
```

**修改步骤**：

1. 编辑配置文件：`sudo nano sensor_ws/src/sensor_driver/config/mqtt_bridge.yaml`
2. 修改 `host` 为实际 Broker 地址
3. 如需认证，取消 `username` 和 `password` 的注释并填写
4. 保存后重启 MQTT 桥接节点

### 4.3 设备编号配置

```yaml
aggregated_topic:
  enabled: true
  deviceNumber: "213"  # 设备编号，用于 MQTT 话题路由
  period: 5            # 数据上报周期（秒），范围 1-3600
```

**说明**：

- `deviceNumber`：设备唯一标识，用于云端区分不同设备
- `period`：数据上报周期，可根据网络情况调整（建议 5-60 秒）

### 4.4 JSON 消息格式及字段含义

#### 4.4.1 聚合话题格式（默认启用）

MQTT 发布话题：`/airs/environment/up/{deviceNumber}`

```json
{
  "deviceNumber": "213",
  "timestamp": 1672531200,
  "data": {
    "radiation": 856.3,
    "temperature": 25.6,
    "humidity": 60.2,
    "pm1_0": 12.3,
    "pm2_5": 25.6,
    "pm10": 38.9,
  }
}
```

**字段含义**：

| 字段 | 含义              | 单位    | 数据来源                    |
| ------ | ------------------- | --------- | ----------------------------- |
| `deviceNumber`     | 设备编号          | -       | 配置文件设置                |
| `timestamp`     | 时间戳（Unix 秒） | s       | 系统时间                    |
| `radiation`     | 太阳辐射强度      | W/m²   | 太阳辐射传感器 (0x01)       |
| `temperature`     | 温度 1            | ℃      | 温湿度传感器 1 (0x02)       |
| `humidity`     | 湿度 1            | %RH     | 温湿度传感器 1 (0x02)       |
| `pm1_0`     | PM1.0 浓度 1      | μg/m³ | 粉尘传感器 1 (/dev/ttyUSB0) |
| `pm2_5`     | PM2.5 浓度 1      | μg/m³ | 粉尘传感器 1 (/dev/ttyUSB0) |
| `pm10`     | PM10 浓度 1       | μg/m³ | 粉尘传感器 1 (/dev/ttyUSB0) |

**命名规则**：

- 所有数值保留 1 位小数

#### 4.4.2 独立话题格式（可选启用）

如需启用独立话题发布，修改配置：

```yaml
individual_topics:
  enabled: true  # 默认关闭，改为 true 启用
```

启用后，每个传感器数据会单独发布到对应的 MQTT 话题：

| ROS 话题 | MQTT 话题 | JSON 格式 |
| ---------- | ----------- | ----------- |
| `/solar_radiation_01/data`         | `sensors/radiation`          | `{"value": 856.3, "unit": "W/m²"}`          |
| `/temp_humi_02/data`         | `sensors/temperature_02`          | `{"value": 25.6, "unit": "℃"}`          |
| `/temp_humi_02/data`         | `sensors/humidity_02`          | `{"value": 60.2, "unit": "%RH"}`          |
| `/dust_sensor/data`         | `sensors/pm25_01`          | `{"value": 25.6, "unit": "μg/m³"}`          |

### 4.5 配置生效方法

修改配置文件后，需重启 MQTT 桥接节点：

```bash
# 方式一：systemd 服务重启
sudo systemctl restart sensor-mqtt-bridge

# 方式二：手动重启
pkill -f mqtt_bridge_node.py
rosrun sensor_driver mqtt_bridge_node.py

# 验证配置生效
journalctl -u sensor-mqtt-bridge -f
# 查看日志中是否显示新的 Broker 地址
```

---

## 5. 自动启动配置

### 5.1 一键安装脚本

系统提供 `install.sh` 脚本，可自动完成 systemd 服务安装：

```bash
# 1. 进入工作空间目录
cd sensor_ws

# 2. 执行安装脚本
sudo ./install.sh

# 3. 添加用户到 dialout 组（串口访问权限）
sudo usermod -aG dialout $USER

# 4. 重新登录使组权限生效
# 退出后重新 SSH 登录

# 5. 启用开机自启
sudo systemctl enable sensor-roscore solar-radiation-temp-humi dust-sensor-usb0 dust-sensor-usb1 sensor-mqtt-bridge
```

### 5.2 systemd 服务列表

系统包含以下 systemd 服务：

| 服务名称 | 功能           | 依赖关系           |
| ---------- | ---------------- | -------------------- |
| `sensor-roscore.service`         | ROS 核心服务   | 无                 |
| `solar-radiation-temp-humi.service`         | 485 总线传感器 | 依赖 roscore       |
| `dust-sensor-usb0.service`         | 粉尘传感器 1   | 依赖 roscore       |
| `dust-sensor-usb1.service`         | 粉尘传感器 2   | 依赖 roscore       |
| `sensor-mqtt-bridge.service`         | MQTT 桥接      | 依赖所有传感器节点 |

### 5.3 服务管理命令

```bash
# 启用开机自启（首次部署执行一次）
sudo systemctl enable sensor-roscore solar-radiation-temp-humi dust-sensor-usb0 dust-sensor-usb1 sensor-mqtt-bridge

# 启动所有服务
sudo systemctl start sensor-roscore
sudo systemctl start solar-radiation-temp-humi
sudo systemctl start dust-sensor-usb0
sudo systemctl start dust-sensor-usb1
sudo systemctl start sensor-mqtt-bridge

# 停止所有服务
sudo systemctl stop sensor-roscore solar-radiation-temp-humi dust-sensor-usb0 dust-sensor-usb1 sensor-mqtt-bridge

# 重启所有服务
sudo systemctl restart sensor-roscore solar-radiation-temp-humi dust-sensor-usb0 dust-sensor-usb1 sensor-mqtt-bridge

# 查看服务状态
systemctl status sensor-roscore
systemctl status solar-radiation-temp-humi
systemctl status dust-sensor-usb0
systemctl status dust-sensor-usb1
systemctl status sensor-mqtt-bridge

# 查看实时日志
journalctl -u sensor-roscore -f
journalctl -u solar-radiation-temp-humi -f
journalctl -u sensor-mqtt-bridge -f
```

---

## 6. WiFi 配置

### 6.1 配置文件位置

WiFi 配置文件源文件路径：

```
sensor_ws/etc/sensor_ws/config/wifi_config.yaml
```

系统部署后路径（符号链接）：

```
/etc/sensor_ws/config/wifi_config.yaml -> sensor_ws/etc/sensor_ws/config/wifi_config.yaml
```

> ⚠️ **注意**：配置文件通过符号链接指向源文件，修改任意一处都会同步生效。

### 6.2 配置内容详解

```yaml
ssid: "Huanzze"           # WiFi 名称（SSID），区分大小写
password: "whl123456789"  # WiFi 密码
autoconnect: true         # 系统启动时自动连接
priority: 100             # 连接优先级（多网络时使用，数值越大优先级越高）
```

**配置说明**：

- `ssid`：目标 WiFi 网络名称，必须与路由器广播的 SSID 完全一致
- `password`：WiFi 密码，支持 WPA/WPA2 加密
- `autoconnect`：设为 `true` 时，系统启动后自动尝试连接
- `priority`：当有多个可用网络时，优先连接高优先级的网络

### 6.3 修改 WiFi 配置

```bash
# 1. 编辑配置文件
sudo nano /etc/sensor_ws/config/wifi_config.yaml

# 2. 修改为实际 WiFi 信息
ssid: "Your_WiFi_Name"
password: "Your_WiFi_Password"

# 3. 保存退出
# Ctrl+O 保存 → Enter 确认 → Ctrl+X 退出

# 4. 重启 WiFi 自动连接服务
sudo systemctl restart wifi-autoconnect

# 5. 验证连接状态
iwconfig wlan0              # 查看连接的 SSID
ping -c 4 8.8.8.8          # 测试网络连通性
```

### 6.4 WiFi 服务安装

系统提供独立的 WiFi 安装脚本 `install-wifi.sh`：

```bash
# 1. 进入工作空间
cd sensor_ws

# 2. 执行 WiFi 安装脚本
sudo ./scripts/install-wifi.sh

# 3. 验证安装
systemctl status wifi-autoconnect
```

**安装脚本功能**：

- 创建配置文件符号链接到 `/etc/sensor_ws/config/`
- 复制 `wifi-autoconnect.sh` 到 `/usr/local/bin/`
- 安装 systemd 服务 `wifi-autoconnect.service`
- 启用开机自启动

> ℹ️ **说明**：主安装脚本 `install.sh` 也会复制 WiFi 配置文件，但建议使用 `install-wifi.sh` 进行完整安装。

### 6.5 WiFi 自动连接服务

系统使用 systemd 服务管理 WiFi 自动连接：

```bash
# 查看服务状态
systemctl status wifi-autoconnect

# 启用开机自启（如未通过 install-wifi.sh 安装）
sudo systemctl enable wifi-autoconnect

# 手动启动服务
sudo systemctl start wifi-autoconnect

# 查看实时连接日志
journalctl -u wifi-autoconnect -f
```

**服务依赖**：

- 依赖网络服务 `networking.service`
- 在 `multi-user.target` 之前启动

### 6.6 网络验证

```bash
# 查看无线网络状态
iwconfig wlan0

# 查看已获取的 IP 地址
ip addr show wlan0

# 测试网关连通性
ping -c 4 192.168.1.1

# 测试外网连通性
ping -c 4 www.baidu.com

# 查看 DNS 配置
cat /etc/resolv.conf
```

### 6.7 手动连接 WiFi（临时测试）

如需临时连接其他 WiFi（不修改配置）：

```bash
# 扫描可用 WiFi
sudo nmcli dev wifi list

# 连接指定 WiFi
sudo nmcli dev wifi connect "WiFi_Name" password "WiFi_Password"

# 验证连接
ip addr show wlan0
```

### 6.8 常见问题

**问题 1：无法连接 WiFi**

```bash
# 检查 WiFi 配置是否正确
sudo cat /etc/sensor_ws/config/wifi_config.yaml

# 重启网络服务
sudo systemctl restart networking

# 查看错误日志
journalctl -u wifi-autoconnect -n 50
```

**问题 2：连接后无网络**

```bash
# 检查网关配置
ip route show

# 检查 DNS 配置
nslookup www.baidu.com

# 临时添加 DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
```

---

## 7. 附录

### 7.1 ROS 话题列表

| 话题名称 | 消息类型                          | 发布频率 | 说明           |
| ---------- | ----------------------------------- | ---------- | ---------------- |
| `/solar_radiation_01/data`         | sensor_driver/SolarRadiation      | 0.2 Hz   | 太阳辐射数据   |
| `/temp_humi_02/data`         | sensor_driver/TemperatureHumidity | 0.2 Hz   | 温湿度传感器 1 |
| `/temp_humi_03/data`         | sensor_driver/TemperatureHumidity | 0.2 Hz   | 温湿度传感器 2 |
| `/dust_sensor/data`         | sensor_driver/DustSensor          | 1 Hz     | 粉尘传感器 1   |
| `/dust_sensor_01/data`         | sensor_driver/DustSensor          | 1 Hz     | 粉尘传感器 2   |

### 7.2 消息格式详解

#### SolarRadiation（太阳辐射）

```bash
$ rosmsg show sensor_driver/SolarRadiation
float32 radiation  # 辐射强度，单位：W/m²
```

#### TemperatureHumidity（温湿度）

```bash
$ rosmsg show sensor_driver/TemperatureHumidity
float32 temperature  # 温度，单位：℃
float32 humidity     # 湿度，单位：%RH
```

#### DustSensor（粉尘）

```bash
$ rosmsg show sensor_driver/DustSensor
float32 pm1_0   # PM1.0 浓度，单位：μg/m³
float32 pm2_5   # PM2.5 浓度，单位：μg/m³
float32 pm10    # PM10 浓度，单位：μg/m³
```

### 7.3 常用验证命令

```bash
# 查看所有话题
rostopic list

# 查看话题数据
rostopic echo /solar_radiation_01/data

# 查看话题频率
rostopic hz /solar_radiation_01/data

# 查看节点列表
rosnode list

# 查看节点信息
rosnode info /multi_sensor_485_node

# 查看消息定义
rosmsg show sensor_driver/SolarRadiation
```