README.md



SmartShelf 智能库位灯控系统


项目简介

SmartShelf（智能料架灯控边缘服务）是一款运行在树莓派上的工业级库位灯控系统。该系统通过 HTTP API 与上位系统交互，控制 WS281x LED 灯条和 GPIO 三色灯塔灯，实现智能仓储中的库位指示、拣货引导、状态提示等功能。


核心功能


库位灯控：通过 LED 灯条指示具体库位位置，支持多种颜色（红、绿、蓝、黄、白等）

灯塔状态灯：A/B 两面各配置绿/黄/红三色 GPIO 灯塔灯，显示通道工作状态

闪烁提醒：支持库位灯闪烁模式，用于紧急或特殊任务提示

上位系统对接：支持主动轮询和被动 API 调用两种工作模式

配置热更新：支持在线上传库位配置文件，无需重启服务

网络配置：内置网络配置管理，支持 DHCP 和静态 IP


系统架构

┌─────────────────────────────────────────────────────────────┐
│                     SmartShelf System                       │
├─────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │   REST API   │  │  HTTP API    │  │  Web Console │       │
│  │   (v1)       │  │  (/api/*)    │  │  (Frontend)  │       │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
├─────────┼─────────────────┼─────────────────┼───────────────┤
│         │                 │                 │               │
│  ┌──────▼───────┐  ┌──────▼───────┐  ┌──────▼───────┐       │
│  │   Flask    │  │   业务逻辑层  │  │  硬件抽象层  │       │
│  │   路由层    │  │  (post.py)   │  │              │       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                              │              │
│         ┌────────────────────────────────────┼─────────┐    │
│         │                                    │         │    │
│  ┌──────▼───────┐  ┌────────────────┐  ┌────▼────────▼─┐ │
│  │  WS281x      │  │   GPIO         │  │   CSV 配置     │ │
│  │  LED 灯条    │  │   三色灯塔灯    │  │   文件         │ │
│  │  (2路通道)   │  │   (6路输出)    │  │                │ │
│  └──────────────┘  └────────────────┘  └────────────────┘ │
└─────────────────────────────────────────────────────────────┘


目录结构

smartshelf/
├── app/
│   ├── __init__.py          # Flask 应用初始化、日志配置、启动线程
│   ├── routes.py            # HTTP 路由定义（灯控 API、配置接口）
│   ├── post.py              # 上位系统通信、轮询线程、闪烁调度
│   ├── led_strip.py         # WS281x LED 灯条驱动封装
│   ├── driver_gpio.py       # GPIO 灯塔灯控制
│   ├── config_ip.py         # 网络配置管理
│   ├── autoback.py          # 自动备份与 OTA 升级
│   ├── qr_code.py           # 库位二维码生成
│   ├── g.py                 # 全局配置对象（LED 颜色顺序等）
│   ├── templates/           # HTML 模板文件
│   │   ├── base.html
│   │   ├── ledtest.html     # LED 测试页面
│   │   ├── shelfconfig.html # 货架配置页面
│   │   └── ipconfig.html    # 网络配置页面
│   └── static/              # 静态资源
│       ├── index.html       # Web 控制台主页
│       ├── assets/          # 前端构建资源
│       ├── css/             # Bootstrap 样式
│       ├── js/              # JavaScript 库
│       └── uploads/         # 上传文件目录（库位配置 CSV）
├── config.py                # 应用配置类
├── neotelshelf.py           # Flask Shell 上下文
├── docs/                    # 文档目录
│   └── SMARTSHELF-API-AND-DOTNET8-MIGRATION.md
└── version.txt              # 版本号


硬件要求


运行平台


树莓派（Raspberry Pi 3/4 或更高版本）

操作系统：Raspberry Pi OS (32/64-bit)

运行权限：必须以 root 身份运行（WS281x DMA、GPIO 操作需要）


硬件接口


WS281x LED 灯条（2路）


逻辑通道
BCM GPIO
说明


Channel 1 (A面)
GPIO 12
数据信号线


Channel 2 (B面)
GPIO 21
数据信号线


LED 数量：可配置，默认支持最多 1000 颗
信号频率：800 KHz
亮度：0-255 可配置


GPIO 三色灯塔灯（6路）


灯塔灯
BCM GPIO
说明


greenA (A面绿)
GPIO 5
正常工作状态


yellowA (A面黄)
GPIO 6
有任务状态（自动联动）


redA (A面红)
GPIO 16
异常/停止状态


greenB (B面绿)
GPIO 17
正常工作状态


yellowB (B面黄)
GPIO 27
有任务状态（自动联动）


redB (B面红)
GPIO 23
异常/停止状态


数据配置


库位配置文件 (linePositions.csv)

位置,优先级,高度,宽度,料仓ID,设备IP,区域ID,灯索引
S11695-02-035,1,100,50,1,192.168.1.100,1,0
S11695-02-036,2,100,50,1,192.168.1.100,1,1
S11695-02-101,1,100,50,1,192.168.1.100,2,0
S11695-02-102,2,100,50,1,192.168.1.100,2,1


字段说明：


位置 (第0列)：库位编码，唯一标识

区域ID (第6列)：灯条通道，1=Channel 1，2=Channel 2，3=双面

灯索引 (第7列)：该库位在对应灯条上的像素下标（从0起）


服务器连接配置 (state/ipconfig.csv)

http://192.168.1.100:8080,CID001


第一列：服务器基址
第二列：设备 CID（客户端标识）


API 接口文档


1. REST v1 接口（纯文本响应）


库位亮灯

GET /rest/api/v1/shelf/posOn?posId=库位@颜色;库位@颜色

示例：
/rest/api/v1/shelf/posOn?posId=S11695-02-035@green;S11695-02-036@red

响应：posOn OK / posOn FAIL


库位灭灯

GET /rest/api/v1/shelf/posOff?posId=库位;库位

示例：
/rest/api/v1/shelf/posOff?posId=S11695-02-035;S11695-02-036

响应：posOff OK / posOff FAIL


全亮/全灭

GET /rest/api/v1/shelf/allPosOn      # 所有灯白色
GET /rest/api/v1/shelf/allPosOff     # 所有灯熄灭
GET /rest/api/v1/shelf/keepAlive     # 心跳检测


灯塔灯控制

GET /rest/api/v1/shelf/lightHouse?op=GA@ON;YA@OFF;RA@ON

灯码说明：
- GA/YA/RA = A面绿/黄/红
- GB/YB/RB = B面绿/黄/红
- 操作：ON/OFF

响应：OK / FAIL


2. JSON API 接口


聚合开灯

POST /api/open
Content-Type: application/json

{
  "params": "statusa=green;5=red;statusb=yellow;10=blue"
}

响应：
{"status": 0, "msg": "success"}           # 成功
{"status": 1, "msg": {"failed": "5=red"}} # 部分失败


参数说明：


statusa/statusb：控制 A/B 面状态灯

数字：按 /positionlist 顺序的 1-based 索引

库位名=颜色：直接指定库位和颜色


聚合关灯

POST /api/close
Content-Type: application/json

{
  "params": "statusa;5;10"
}


3. 单库位控制接口


开灯

POST /ledopen
Content-Type: application/json

{
  "light_led": "S11695-02-035",
  "light_led_color": "green"
}


关灯

POST /ledoff
Content-Type: application/json

{
  "off_led": "S11695-02-035"
}


重置所有灯

POST /resetled


4. 状态灯控制接口


开状态灯

POST /workinglight
Content-Type: application/json

{
  "workchannel": "channel1",  // channel1=A面, channel2=B面
  "workcolor": "green"        // green/yellow/red
}


关状态灯

POST /workingoff
Content-Type: application/json

{
  "workchannel": "channel1",
  "workcolor": "green"
}


5. 系统管理接口


获取运行状态

POST /getstate

响应：
[
  {
    "state": "on",           // on/off
    "msg": "未进行测试动作",
    "ipconfig": {
      "ip": "http://...",
      "cid": "CID001",
      "post": "success"      // success/failed/wait
    },
    "version": "1.73"
  }
]


启动/停止轮询

POST /startpost    # 启动与上位系统的轮询通信
POST /stoppost     # 停止轮询


上传配置文件

POST /upload/
Content-Type: multipart/form-data

file: linePositions.csv

响应：{"filename": "linePositions.csv"}


获取库位列表

GET /positionlist

响应：["S11695-02-035", "S11695-02-036", ...]


获取配置状态

GET /config_state

响应：true / false


获取设备 MAC 地址

GET /getmac

响应：B8:27:EB:XX:XX:XX


6. 网络配置接口（仅 Linux）


获取网络信息

POST /get_networkinfo

响应：
{
  "interface": "eth0",
  "ip_address": "192.168.1.100",
  "netmask": "255.255.255.0",
  "gateway": "192.168.1.1"
}


配置网络

POST /ip_config
Content-Type: application/x-www-form-urlencoded

# DHCP 模式
dhcp=on

# 静态 IP 模式
new_ip=192.168.1.100&new_mask=255.255.255.0&router_ip=192.168.1.1

响应：Apply Successfully, System will reboot in 5 seconds


上位系统通信协议


轮询机制

当启动轮询（/startpost）后，系统每秒向服务器发送 POST 请求：

POST {ip}/service/store/communication
Content-Type: application/json

{
  "boxStatus": {
    "1": {
      "boxId": 1,
      "status": 1,
      "msg": null,
      "temperature": null,
      "humidity": null,
      "data": {}
    }
  },
  "alarmList": [],
  "cid": "CID001",
  "seq": 1,          // 递增序列号
  "op": 0,
  "data": {},
  "status": 1,
  "msg": null
}


服务器响应指令

服务器在响应的 data 字段中下发控制指令：


开灯指令

{
  "data": {
    "open": "库位=颜色|库位=颜色=闪烁时长|..."
  }
}

示例：
{
  "data": {
    "open": "S11695-02-035=green|S11695-02-036=red=5000|S11695-02-037=blue"
  }
}


说明：


两段（库位=颜色）：常亮
三段（库位=颜色=毫秒）：闪烁指定时长，约每 333ms 翻转亮灭


关灯指令

{
  "data": {
    "close": "库位|库位|..."
  }
}


全关灯/全开灯

{
  "data": {
    "closeAll": "任意值"          // 关闭所有灯
  }
}

{
  "data": {
    "openAll": "green"            // 所有灯设为指定颜色
  }
}


灯塔灯控制

{
  "data": {
    "lightHouseOpenOrClose": "open=A=green|close=B=red"
  }
}


安装与部署


1. 环境准备

# 更新系统
sudo apt-get update
sudo apt-get upgrade -y

# 安装 Python 3 及依赖
sudo apt-get install python3 python3-pip -y

# 安装系统依赖（WS281x 需要）
sudo apt-get install python3-dev swig -y


2. 安装 Python 依赖

# 进入项目目录
cd /prog/smartshelf

# 安装依赖
pip3 install flask flask-babel requests chardet qrcode pillow matplotlib rpi_ws281x


3. 配置启动


使用 systemd 服务

创建服务文件 /etc/systemd/system/smartshelf.service：

[Unit]
Description=SmartShelf LED Control Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/prog/smartshelf
Environment="PYTHONPATH=/prog/smartshelf"
ExecStart=/usr/bin/python3 /prog/smartshelf/neotelshelf.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target


启用服务：

sudo systemctl daemon-reload
sudo systemctl enable smartshelf
sudo systemctl start smartshelf


查看日志

# 查看服务日志
sudo journalctl -u smartshelf -f

# 查看应用日志
tail -f /prog/smartshelf/logs/smart.log


4. 首次配置


上传库位配置文件：

curl -X POST -F "file=@linePositions.csv" http://192.168.1.100:5000/upload/


配置服务器地址：

curl -X POST http://192.168.1.100:5000/updateip \
 -H "Content-Type: application/json" \
 -d '{"ip": "http://192.168.1.200:8080", "cid": "CID001"}'


启动轮询：

curl -X POST http://192.168.1.100:5000/startpost


开发与调试


本地开发（非树莓派环境）

在非树莓派环境下运行时，系统会自动进入模拟模式：


WS281x 操作仅打印日志
GPIO 操作仅打印日志
无需 root 权限


Web 控制台

启动后访问 http://<树莓派IP>:5000/ 进入 Web 控制台，可：


可视化测试 LED 灯条
查看和管理库位配置
配置网络参数
查看日志和系统状态


颜色支持

系统支持以下颜色名称（不区分大小写）：


基础色：red, green, blue, yellow, white, off

扩展色：orange, cyan, magenta, purple, pink

更多：lightblue, skyblue, forestgreen, darkgreen, firebrick, indianred

十六进制：#RRGGBB 格式


配置参数


货架配置（g.py）


参数
类型
默认值
说明


LED_ColorSort
int
2 (RGB)
LED 颜色顺序：1=GRB, 2=RGB


LED_COUNT
int
1000
单条灯带最大像素数


TOWER_CUSTCONTROL
int
0
0=自动联动状态灯，1=手动控制


应用配置（config.py）


参数
默认值
说明


URL
http://192.168.1.100:8080/service/store/communication
服务器通信地址


DEFAULT_COLOR
green
默认亮灯颜色


LOG_LEVEL
logging.WARNING
日志级别


LOG_FOLDER
logs/smart.log
日志文件路径


注意事项


权限要求：必须以 root 身份运行，否则 WS281x 和 GPIO 操作将失败

硬件安全：确保 LED 灯条供电充足，避免电源不足导致闪烁异常

网络配置：首次部署需要配置网络参数，建议使用静态 IP

配置文件：CSV 文件编码会自动检测，建议统一使用 UTF-8 或 GBK

并发访问：灯条操作在多线程环境下是安全的，但 API 调用过多可能导致闪烁


故障排查


常见问题


问题
可能原因
解决方法


灯条不亮
GPIO 未初始化/电源问题
检查 GPIO 12/21 连接，确认 5V 电源供电充足


灯条颜色异常
颜色顺序配置错误
检查 LED_ColorSort 配置，尝试切换 RGB/GRB


无法连接服务器
IP/CID 配置错误
使用 /getstate 检查配置，重新调用 /updateip


配置文件加载失败
CSV 格式/编码问题
检查文件编码，确保表头正确


GPIO 操作失败
非 root 权限运行
使用 sudo 或修改 systemd 服务配置


日志诊断

# 实时查看日志
tail -f /prog/smartshelf/logs/smart.log

# 查看最近日志
curl -X POST http://192.168.1.100:5000/taillog


版本历史


版本
日期
主要更新


v1.73
2024
当前版本，支持库位灯闪烁控制


许可证

本项目为内部工业控制系统，仅供授权用户使用。


技术支持


项目维护：智能仓储系统团队
问题反馈：通过 TeamViewer 远程协助（/openteamview 接口）


注意：本文档基于代码分析生成，具体部署请参考现场实施文档和实际环境配置。