# HySystems.AoController

**Repository Path**: hyetec6/HySystems.AoController

## Basic Information

- **Project Name**: HySystems.AoController
- **Description**: 爱鸥（AIOI）电子标签控制、DPS、DAS、PTL系统，分播作业，学习分享
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HySystems.AoController

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

.NET 8 类库与 WPF 演示程序，用于学习 **TCP 以太网** 与 **电子标签 / 亮灯拣选系统控制器** 的通信编程。

典型应用场景包括：

- **电子标签（ESL）**：显示拣货数量、货位信息，支持按键确认
- **亮灯拣选系统（Pick-to-Light）**：通过控制器驱动标签亮灯、刷灯，引导拣货/补货/盘点
- **扫码与上报**：接收控制器转发的扫码枪、CONFIRM 键等事件

本项目为个人/社区 **技术研究与学习** 用途，**非商业产品、非官方 SDK**。

## 免责声明

**请在使用、传播或引用本项目前仔细阅读以下内容：**

1. **与爱鸥系统（AIOI）无任何关系**  
   本项目由社区/个人独立开发与发布，**未获爱鸥系统（AIOI）及其关联公司的授权、认可、赞助或官方支持**。本项目**不代表**爱鸥系统（AIOI）的任何立场或产品。

2. **仅用于学习与技术研究**  
   本项目仅供开发者学习 .NET 网络编程、串行通信、协议解析等知识，**不得用于任何可能侵犯第三方知识产权或违反设备厂商许可条款的用途**。若用于生产环境、商业项目或现场部署，**一切风险与责任由使用者自行承担**。

3. **不涉及爱鸥系统（AIOI）的任何官方内容**  
   本仓库**不包含**爱鸥系统（AIOI）的说明书、协议文档、固件、软件、Logo、商标、产品资料或其他受版权/商标保护的官方材料。代码均为作者根据公开技术信息及自行研究整理实现，**与官方文档无对应关系**，不保证完整、准确或与任何特定型号设备兼容。

4. **商标与名称**  
   「爱鸥」「AIO」「AIOI」等名称、商标及相关产品名称（如有）均属于其各自权利人。本项目提及上述名称**仅为说明兼容场景或学习背景**，不构成商标使用授权，亦不应理解为官方产品或官方文档。

5. **无担保**  
   本项目按「现状」（AS IS）提供，作者不对通信可靠性、设备兼容性、数据正确性及由此产生的直接或间接损失作任何明示或默示担保。

6. **禁止误导性宣传**  
   请勿将本项目描述或宣传为「爱鸥官方库」「AIOI 官方 SDK」或任何暗示与厂商存在合作关系的说法。

> **Summary (English):** An **unofficial, educational** .NET 8 library for learning TCP communication with **electronic shelf label (ESL)** and **pick-to-light** system controllers (display, button confirm, scan events). **Not affiliated with, endorsed by, or sponsored by AIOI (爱鸥系统)**. Contains **no official AIOI materials**. Use at your own risk.

## 功能特性

- 面向 **电子标签 / 亮灯拣选** 控制器的以太网通信（默认端口 `5003`）
- TCP 会话连接，指令串行发送，一问一答，支持同步 / 异步调用
- 通信帧封装：`[STX][序列号3][长度4][数据][ETX]`
- 控制器主动上报（`t` 指令）自动回复 `O` 确认
- 设备数据解析（`AddressInfo`：地址、状态、输入内容、扫码枪）
- 异步文件日志（按日分目录、按大小滚动、过期自动清理）
- 事件 UI 线程封送（`ISynchronizeInvoke` / WPF `Dispatcher` 适配）

## 项目结构

```
HySystems.AoController/
├── HySystems.AoController/     # 核心类库 (net8.0)
│   ├── Controllers/            # ControllerBase、EthernetController
│   ├── Logger/                 # 文件日志
│   ├── Utils/                  # CommandInfo、AddressInfo
│   └── Events/                 # 连接、发送、错误等事件
├── HyHardDemo/                 # WPF 演示 (net8.0-windows)
└── HySystems.AoController.sln
```

## 环境要求

- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- Windows（运行 WPF Demo；类库可用于 WinForms / 控制台等 .NET 8 项目）

## 快速开始

### 编译

```bash
git clone https://github.com/hyetec6/HySystems.AoController.git
cd HySystems.AoController
dotnet build HySystems.AoController.sln
```

### 运行 Demo

```bash
dotnet run --project HyHardDemo
```

1. 填写控制器 IP 与端口（默认 `192.168.1.254:5003`）
2. 点击「连接」
3. 输入指令（如 `P100000112345`）后点击「发送」
4. 下方「通信日志」区域可查看发送 / 应答 / 接收记录

## 类库用法

### WinForms

```csharp
using HySystems.AoController;

var controller = new EthernetController();
controller.IPAddress = "192.168.1.254";
controller.Port = 5003;
controller.SynchronizingObject = this; // Form 实现 ISynchronizeInvoke
controller.Logger.Enabled = true;
controller.Logger.LogDirectory = @".\Log";

controller.CommandReceived += (s, e) =>
{
    var infos = AddressInfo.GetAddressInfos(s);
    if (infos == null) return;
    foreach (var info in infos)
    {
        // 更新 UI：地址 info.Address，数据 info.InputData
    }
};

controller.Connect();
var response = controller.SendCommand("P100000112345");
controller.Close();
```

### WPF

WPF 控件不直接实现 `ISynchronizeInvoke`，可使用 Demo 中的 `DispatcherSynchronizeInvoke`：

```csharp
controller.SynchronizingObject = new DispatcherSynchronizeInvoke(Dispatcher);
```

## 日志配置

```csharp
controller.Logger.Enabled = true;
controller.Logger.LogDirectory = @".\Log";   // 默认 .\Log
controller.Logger.Expiration = 30;         // 保留天数
controller.Logger.LogSize = 3;               // 单文件上限 (MB)
controller.Logger.MaxQueueSize = 10000;      // 内存队列上限，0=不限制
```

日志目录示例：`.\Log\ls_20260624\lslog_000.log`

## 通信协议概要

以下内容仅为本项目实现所依据的**通用帧格式说明**，用于学习理解，**并非爱鸥系统（AIOI）官方协议文档**，亦未复制任何厂商资料。

| 方向 | 说明 |
|------|------|
| 客户端 → 控制器 | 大写指令（如 `P`、`G`、`Z`） |
| 控制器 → 客户端 | 小写应答（`o` 成功、`n` / `n1` 拒绝） |
| 主动上报 | 控制器发 `t...`，客户端需回 `O` 确认 |

帧格式：

```
[STX 0x02] + [序列号 000-999] + [长度 0001-1015] + [数据] + [ETX 0x03]
```

## 主要 API

| 类型 / 成员 | 说明 |
|-------------|------|
| `EthernetController` | 以太网控制器（继承 `ControllerBase`） |
| `Connect()` / `Close()` | 连接 / 断开 |
| `SendCommand(cmd)` | 同步发送并等待应答 |
| `BeginSendCommand(cmd)` | 异步发送 |
| `GetCommand()` | 取一条主动上报指令 |
| `CommandReceived` | 收到 `t` 上报时触发 |
| `EndSendCommand` | 指令发送完成时触发 |
| `ErrorRaised` | 错误或 `n` / `n1` 应答 |

## 开源协议

本项目采用 [MIT License](LICENSE) 发布。

## 贡献

欢迎提交 Issue 与 Pull Request。提交前请确保：

- `dotnet build` 通过
- 不包含内网地址、密钥等敏感信息
- **不包含任何厂商官方文档、固件、Logo 或其他受版权保护的材料**
- 变更说明清晰