# iot-device-simulator

**Repository Path**: xiaohan2013/iot-devices-simulator

## Basic Information

- **Project Name**: iot-device-simulator
- **Description**: iot设备数据模拟器，并为iot agent提供mcp服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sparkplug B 工厂能源监控系统

基于 Sparkplug B v1.0 工业协议的制造工厂能源监控系统，覆盖变压器、电表、光伏、空压机、储能、流量传感器六类设备，实现仿真接入、协议解析、资产台账、时序存储、数据洞察、告警运维全链路。

## 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│  层1: 边缘接入层 (Sparkplug B 标准协议)                      │
│  EMQX Data Simulator / spb_simulator.py                     │
│  主题: spBv1.0/{site_id}/{msg_type}/{gateway_id}/{device_id} │
├─────────────────────────────────────────────────────────────┤
│  层2: 消息治理层 (EMQX 5.7+)                                 │
│  spb_decode() → 规则1: DDATA→InfluxDB                       │
│             → 规则2: DBIRTH/DDEATH→HTTP→业务服务             │
├─────────────────────────────────────────────────────────────┤
│  层3: 数据存储层 (双库分工)                                   │
│  SQLite: 站点/设备/测点/告警/事件                             │
│  InfluxDB: 时序测点 (三级Bucket冷热分离)                      │
├─────────────────────────────────────────────────────────────┤
│  层4: 应用查询层                                              │
│  SQLite SQL: 资产/告警/运维                                  │
│  InfluxDB Flux: 能耗趋势/光伏/储能/空压机                    │
└─────────────────────────────────────────────────────────────┘
```

## 目录结构

```
devices/
├── README.md                       # 项目总说明
├── standards/                      # 标准化编码字典
│   ├── device_type_dict.yaml       # 设备类型字典
│   └── point_code_dict.yaml        # 测点编码字典 (53个标准测点)
├── alembic/                        # 数据库迁移 (Alembic)
│   ├── alembic.ini                 # ➡ data/spb_energy.db
│   └── versions/                   # 建表 + 种子数据
├── data/                           # SQLite 数据库文件
├── emqx/                           # EMQX 配置
│   ├── README.md                   # 配置指南
│   ├── spb_rule_ddata_to_influx.sql # 规则1: DDATA→InfluxDB
│   └── spb_rule_events_to_http.sql # 规则2: 事件→HTTP
├── simulator/                      # 仿真配置
│   ├── spb_simulator.py            # SPB仿真器 (站点/设备从数据库加载)
│   └── templates/                  # 6类设备模板
│       ├── transformer.yaml
│       ├── electric_meter.yaml
│       ├── pv_inverter.yaml
│       ├── air_compressor.yaml
│       ├── energy_storage_pcs.yaml
│       ├── energy_storage_bms.yaml
│       └── flow_sensor.yaml
├── services/                       # 业务服务
│   ├── __init__.py
│   ├── spb_receiver.py             # HTTP回调接收器 (FastAPI)
│   ├── spb_influx_writer.py        # 🔥 MQTT→InfluxDB 桥接 (pysparkplug SDK)
│   ├── device_registry.py          # 设备注册/状态
│   └── alarm_service.py            # 告警管理
├── queries/                        # 标准化查询
│   ├── sqlite/                     # 6条业务查询
│   │   ├── 001_asset_inventory.sql
│   │   ├── 002_online_rate.sql
│   │   ├── 003_device_points.sql
│   │   ├── 004_alarm_stats.sql
│   │   ├── 005_device_events.sql
│   │   └── 006_site_summary.sql
│   └── influxdb/                   # 6条Flux洞察查询
│       ├── 001_plant_power.flux
│       ├── 002_pv_generation.flux
│       ├── 003_storage_dispatch.flux
│       ├── 004_compressor_load.flux
│       ├── 005_monthly_energy.flux
│       └── 006_device_online_rate.flux
├── scripts/                        # 运维脚本
│   ├── startup.ps1                 # 🔥 一键启动 (Docker + Alembic + 服务)
│   ├── backup_db.ps1               # 数据库备份
│   ├── archive_alarms.ps1          # 告警归档
│   └── health_check.ps1            # 系统健康检查
└── docs/                           # 文档
    └── ...
```

## 快速开始

### 前置依赖

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- Docker Desktop (EMQX + InfluxDB)

### 1. 数据库初始化 (建表 + 种子数据)

```bash
uv run alembic -c alembic.ini upgrade head
```

### 2. 启动基础设施 (EMQX MQTT + InfluxDB)

```bash
docker compose -f ../common/docker-compose.yml up -d
```

### 3. 一键启动

```powershell
.\scripts\startup.ps1
```

含 Docker 检查 → 端口检查 → Docker Compose 启服 → Alembic 迁移 → SPB Influx Writer → SPB Receiver → SPB Simulator 全流程。

### 4. 分步启动

**SPB InfluxDB 桥接服务 (MQTT → InfluxDB):**

```bash
uv run python services/spb_influx_writer.py
```

**SPB 事件接收服务:**

```bash
uv run uvicorn services.spb_receiver:app --host 0.0.0.0 --port 8001
```

**SPB 仿真器:**

```bash
uv run python simulator/spb_simulator.py
```

### 5. 运行健康检查

```powershell
powershell -File scripts/health_check.ps1
```

## 标准化编码体系

### 测点编码前缀

| 前缀 | 含义 | 数量 |
|------|------|------|
| P | 功率/电气参数 (Power) | 12 |
| E | 电量/电能 (Energy) | 2 |
| PV | 光伏参数 (PhotoVoltaic) | 8 |
| AC | 空压机参数 (Air Compressor) | 8 |
| ES | 储能参数 (Energy Storage) | 11 |
| AF | 气流量参数 (Air Flow) | 2 |
| S | 状态/告警参数 (Status) | 7 |
| G | 网关参数 (Gateway) | 3 |

### 设备类型

| 类型编码 | 中文名 | 设备数量 |
|----------|--------|----------|
| transformer | 变压器 | 1 |
| electric_meter | 智能电表 | 2 |
| pv_inverter | 光伏逆变器 | 1 |
| air_compressor | 空压机 | 1 |
| energy_storage_pcs | 储能PCS | 1 |
| energy_storage_bms | 储能BMS | 1 |
| flow_sensor | 流量传感器 | 1 |
| spb_gateway | SPB网关 | 1 |

## 数据流

### Sparkplug B 状态机

```
NBIRTH (网关上线) → 对各设备 DBIRTH (全量测点宣告)
                  → 周期 DDATA (测点数据上报)
                  → DDEATH (设备离线遗嘱)
```

### 数据写入方案

1. **DDATA→InfluxDB**: `spb_influx_writer.py` 订阅 MQTT → protobuf 解码 → 写入 InfluxDB (energy-realtime)
2. **事件→HTTP**: EMQX 规则引擎匹配 DBIRTH/DDEATH/告警DDATA，回调 `spb_receiver` 服务写入 SQLite

## 许可证

项目内部使用