https://github.com/csp0924/csplib
A modular Python toolkit for industrial equipment communication and energy management systems
https://github.com/csp0924/csplib
asyncio energy-management grid-controller industrial-automation modbus python scada toolkit
Last synced: about 1 month ago
JSON representation
A modular Python toolkit for industrial equipment communication and energy management systems
- Host: GitHub
- URL: https://github.com/csp0924/csplib
- Owner: csp0924
- License: apache-2.0
- Created: 2026-01-07T16:59:08.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-04-02T20:02:48.000Z (2 months ago)
- Last Synced: 2026-04-03T09:13:12.279Z (2 months ago)
- Topics: asyncio, energy-management, grid-controller, industrial-automation, modbus, python, scada, toolkit
- Language: Python
- Homepage: https://pypi.org/project/csp0924-lib/
- Size: 1.8 MB
- Stars: 19
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Citation: CITATION.cff
- Notice: NOTICE
Awesome Lists containing this project
README
# CSP Library
[](LICENSE)
[](https://www.python.org/)
[](https://pypi.org/project/csp0924-lib/)
[](https://pepy.tech/projects/csp0924-lib)
CSP Common Library 是一個模組化的 Python 工具集，專為**能源管理系統**與**工業設備通訊**設計。
## 特點
- **8 層分層架構**：Core → Modbus/CAN → Equipment → Controller → Manager → Integration → Storage → Additional
- **Async-first**：所有設備 I/O 與管理器皆採用 asyncio
- **多協議支援**：Modbus TCP/RTU 與 CAN Bus 雙協議設備抽象
- **策略引擎**：PQ/QV/FP/Droop/Island/PVSmooth/LoadShedding/RampStop 等 10+ 內建策略
- **功率補償**：前饋 + 積分閉環補償（PowerCompensator），含 FF Table 自動學習
- **動態保護**：DynamicSOCProtection / GridLimitProtection 從 RuntimeParameters 即時讀取參數
- **功率分配**：Equal / Proportional / SOCBalancing 多機分配，含硬體限制 + 溢出轉移
- **Modbus TCP Gateway**：宣告式暫存器映射、寫入驗證、資料同步，對接 EMS/SCADA
- **韌性機制**：CircuitBreaker（指數退避 + jitter）+ RetryPolicy
- **Event-driven**：設備事件系統 + WeakRef 自動清理
- **精度控制**：`ExecutionConfig.interval_seconds` 支援 float（sub-second 策略如 DReg 0.3 s）；`StrategyExecutor` work-first + 絕對時間錨定漂移補償（v0.8.0）
- **NO_CHANGE sentinel**：`Command.p_target / q_target` 支援 `NO_CHANGE`，策略可宣告「此軸不變更」，`CommandRouter` 跳過對應軸寫入，多策略 cascade 正確組合（v0.8.0）
- **Event-driven Trigger**：`SystemController.attach_read_trigger(device_id)` 綁定設備讀完即觸發策略，搭配 TRIGGERED/HYBRID 模式消除 phase drift（v0.8.0）
- **ContextMapping param_key**：直接從 `RuntimeParameters` 注入 context 欄位，不需手動搬入 extra（v0.8.0）
- **Fluent Builder**：`SystemControllerConfig.builder()` 鏈式配置
- **Operator Pattern**：`Reconciler` Protocol + `TypeRegistry` + YAML Site Manifest，K8s 風宣告式站點配置與自我修復調和迴圈（v0.9.0）
- **按需安裝**：Optional dependencies 避免引入不必要的套件
## 安裝
```bash
# 基本安裝
pip install csp0924_lib
# 按需安裝
pip install csp0924_lib[modbus] # Modbus 通訊
pip install csp0924_lib[can] # CAN Bus 通訊
pip install csp0924_lib[mongo] # MongoDB
pip install csp0924_lib[redis] # Redis（含 Sentinel + TLS）
pip install csp0924_lib[monitor] # 系統監控
pip install csp0924_lib[cluster] # 分散式叢集
pip install csp0924_lib[gui] # FastAPI Web GUI
pip install csp0924_lib[manifest] # YAML Site Manifest（pyyaml）
pip install csp0924_lib[all] # 所有功能
```
## 架構
```
┌─────────────────────────────────────────────────────────────┐
│ Layer 8 Additional │
│ Cluster · Monitor · Notification · ModbusServer · Gateway │
│ Statistics · GUI │
├──────────────────────────────┬──────────────────────────────┤
│ Layer 7 Storage │ Layer 6 Integration │
│ MongoDB · Redis │ Registry · SystemController │
│ │ ContextBuilder · CommandRouter│
├──────────────────────────────┤ Distributor · Orchestrator │
│ Layer 5 Manager ├──────────────────────────────┤
│ Unified · Alarm · Command │ Layer 4 Controller │
│ DataUpload · StateSync │ Strategies · Executor │
│ │ Protection · Compensator │
├──────────────────────────────┴──────────────────────────────┤
│ Layer 3 Equipment │
│ AsyncModbusDevice · Points · Alarms · Transport · Pipeline │
├─────────────────────────────────────────────────────────────┤
│ Layer 2 Modbus / CAN │
│ DataTypes · Codec · Clients (TCP/RTU/Shared) · CAN Bus │
├─────────────────────────────────────────────────────────────┤
│ Layer 1 Core │
│ Logging · Lifecycle · Errors · Health · Resilience │
│ RuntimeParameters │
└─────────────────────────────────────────────────────────────┘
依賴方向：下層 → 上層（下層不可 import 上層）
```
## Quick Start
```python
import asyncio
from csp_lib.modbus import PymodbusTcpClient, ModbusTcpConfig, Float32, UInt16
from csp_lib.equipment.core import ReadPoint, WritePoint
from csp_lib.equipment.device import AsyncModbusDevice, DeviceConfig
device = AsyncModbusDevice(
config=DeviceConfig(device_id="inverter_001", unit_id=1),
client=PymodbusTcpClient(ModbusTcpConfig(host="192.168.1.100")),
always_points=[
ReadPoint(name="voltage", address=0, data_type=Float32()),
ReadPoint(name="power", address=2, data_type=UInt16()),
],
)
async def main():
async with device:
values = await device.read_all()
print(f"Voltage: {values['voltage']}V, Power: {values['power']}W")
asyncio.run(main())
```
更多範例見 [`examples/`](examples/) 目錄。
## 模組總覽
| 層 | 模組 | 說明 | 文件 |
|----|------|------|------|
| L1 | [`core`](docs/02-Core/) | Logging · Lifecycle · Errors · Health · Resilience · RuntimeParameters | [→](docs/02-Core/) |
| L2 | [`modbus`](docs/03-Modbus/) | 資料型別 · Codec · TCP/RTU/Shared 客戶端 | [→](docs/03-Modbus/) |
| L2 | [`can`](docs/03-CAN/) | CAN Bus 客戶端 · 配置 · 例外 | [→](docs/03-CAN/) |
| L3 | [`equipment`](docs/04-Equipment/) | AsyncModbusDevice · Points · Alarms · Transport · Transforms | [→](docs/04-Equipment/) |
| L4 | [`controller`](docs/05-Controller/) | 10+ 策略 · Executor · Protection · Compensator · Calibration | [→](docs/05-Controller/) |
| L5 | [`manager`](docs/07-Manager/) | Unified · Alarm · Command · DataUpload · StateSync | [→](docs/07-Manager/) |
| L6 | [`integration`](docs/06-Integration/) | Registry · SystemController · ContextBuilder · CommandRouter · Distributor | [→](docs/06-Integration/) |
| L7 | [`mongo`](docs/08-Storage/) | MongoConfig · MongoBatchUploader | [→](docs/08-Storage/) |
| L7 | [`redis`](docs/08-Storage/) | RedisClient（Standalone/Sentinel/TLS）· Pub/Sub | [→](docs/08-Storage/) |
| L8 | [`cluster`](docs/09-Cluster/) | Leader Election · State Sync · HA Controller | [→](docs/09-Cluster/) |
| L8 | [`monitor`](docs/10-Monitor/) | 系統指標收集 · 告警評估 · Redis 發佈 | [→](docs/10-Monitor/) |
| L8 | [`notification`](docs/11-Notification/) | 多通道告警分發（Telegram/LINE/自訂） | [→](docs/11-Notification/) |
| L8 | [`modbus_server`](docs/12-Modbus-Server/) | Modbus TCP 模擬伺服器（測試用） | [→](docs/12-Modbus-Server/) |
| L8 | [`modbus_gateway`](docs/12-Modbus-Server/) | Modbus TCP Gateway（EMS/SCADA 介面） | [→](docs/12-Modbus-Server/) |
| L8 | [`statistics`](docs/) | 能源統計（累計度數、運行時數） | — |
| L8 | [`gui`](docs/) | FastAPI Web 介面 | — |
## 控制流程
```
設備讀取 → ContextBuilder → StrategyContext
↓
StrategyExecutor（策略由 ModeManager 決定）
↓
Command → ProtectionGuard → CommandProcessor
↓
PowerDistributor → CommandRouter → 設備寫入
```
## 範例
| 檔案 | 說明 |
|------|------|
| [`01_basic_device.py`](examples/01_basic_device.py) | 基本設備讀寫 |
| [`03_control_strategies.py`](examples/03_control_strategies.py) | 控制策略使用 |
| [`05_system_controller.py`](examples/05_system_controller.py) | SystemController 進階控制 |
| [`14_power_distributor.py`](examples/14_power_distributor.py) | 多機功率分配 |
| [`15_modbus_gateway.py`](examples/15_modbus_gateway.py) | Modbus TCP Gateway |
| [`demo_ess_dreg.py`](examples/demo_ess_dreg.py) | ESS Droop 調頻 + 補償 + 校準 |
| [`demo_full_system.py`](examples/demo_full_system.py) | 完整系統端到端整合 |
完整範例列表見 [`examples/`](examples/)。
## 開發
```bash
# 安裝所有依賴
uv sync --all-groups --all-extras
# 測試
uv run python -m pytest tests/ -v
# Lint + Format + Type Check
uv run ruff check .
uv run ruff format .
uv run mypy csp_lib/
```
## 授權
[Apache License 2.0](LICENSE) — Copyright 2024-2026 Cheng Sin Pang（鄭善淜）
## 引用
```bibtex
@software{csp_library,
title = {CSP Library},
author = {Cheng Sin Pang (鄭善淜)},
year = {2024},
url = {https://github.com/csp0924/csp_lib},
version = {0.9.1}, % x-release-please-version
license = {Apache-2.0}
}
```
詳見 [CITATION.cff](CITATION.cff) · [CHANGELOG.md](CHANGELOG.md)