ImprovWifi.Transport.Linux 1.1.0

Sang.ImprovWifi

Sang.ImprovWifi 是一个基于 .NET 的 Improv Wi-Fi 配网项目，包含：

• 纯协议层实现
• Windows BLE 外设宿主实现
• Linux / BlueZ BLE 外设宿主实现
• 对应的最小演示程序

当前仓库的目标是：

• 接收并解析 Improv 的 Wi‑Fi 配网命令
• 提供授权状态、错误状态、能力值读取
• 在配网成功后生成并发送 URL 类型的 RPC Result
• 将协议层与平台 BLE 实现分离，便于后续集成到真实设备或系统服务中

功能概览

已实现：

• Improv 协议解析与状态管理
• Wi-Fi 配网命令接收
• Identify 命令处理
• 授权状态切换
• CurrentState / ErrorState / Capabilities / RpcResult 数据提供
• Windows 平台真实 BLE GATT Server
• Linux 平台基于 BlueZ 的 BLE GATT Server
• Windows / Linux 最小控制台示例

当前演示程序默认只做：

• 接收 SSID / Password
• 输出收到的配网信息
• 调用 CompleteProvisioning(url) 返回跳转地址

也就是说，Demo 默认不直接替你执行系统层面的联网操作。如果需要在收到配网信息后真正连接系统 Wi‑Fi，请在 ProvisioningRequested 事件中接入你自己的联网逻辑。

项目结构

• ImprovWifi.Protocol
  • 纯协议层
  • 包含协议常量、编解码、状态机、事件、通用传输抽象
• ImprovWifi.Transport.Windows
  • Windows BLE 宿主实现
  • 使用系统 Bluetooth / GATT API
• ImprovWifi.Transport.Linux
  • Linux BLE 宿主实现
  • 使用 BlueZ + Linux.Bluetooth
• ImprovWifi.Demo.Windows
  • Windows 控制台演示程序
• ImprovWifi.Demo.Linux
  • Linux 控制台演示程序

命名空间结构

• ImprovWifi.Protocol
• ImprovWifi.Protocol.Events
• ImprovWifi.Protocol.Transport
• ImprovWifi.Transport.Windows
• ImprovWifi.Transport.Linux

Target Framework

• ImprovWifi.Protocol
  • .NET 8
  • .NET Standard 2.1
• ImprovWifi.Transport.Windows
  • .NET 8 Windows
• ImprovWifi.Transport.Linux
  • .NET 8
  • .NET 10
• ImprovWifi.Demo.Windows
  • .NET 8 Windows
• ImprovWifi.Demo.Linux
  • .NET 8
  • .NET 10

Improv UUID

Improv 服务及特征 UUID 已定义在 ImprovWifi.Protocol/Protocol/ImprovProtocol.cs：

• Service: 00467768-6228-2272-4663-277478268000
• Current State: 00467768-6228-2272-4663-277478268001
• Error State: 00467768-6228-2272-4663-277478268002
• RPC Command: 00467768-6228-2272-4663-277478268003
• RPC Result: 00467768-6228-2272-4663-277478268004
• Capabilities: 00467768-6228-2272-4663-277478268005

主要 API

协议层核心类型：

• ImprovService
• ImprovPacketCodec
• ImprovTransportServer
• ImprovTransportOptions

ImprovService 主要方法：

• Authorize(bool)
• ProcessRpcCommand(...)
• CompleteProvisioning(string url)
• FailProvisioning(...)
• GetCurrentStatePayload()
• GetErrorStatePayload()
• GetCapabilitiesPayload()

事件：

• ProvisioningRequested
• IdentifyRequested
• RpcResultReady
• CurrentStateChanged
• ErrorStateChanged

构建

在仓库根目录执行：

dotnet build

Usage

可使用以下方式完成配网：

• 微信小程序：Improv 蓝牙配网
• 官方网站：improv-wifi.com

Improv Wi-Fi 官方将该协议定义为一个基于 Bluetooth LE 或 Serial 的开放标准，用于把设备连接到 Wi‑Fi，并在连接成功后返回一个可继续配置设备的 URL。

官方参考：

• 官网首页：https://www.improv-wifi.com/
• BLE 文档入口：https://www.improv-wifi.com/ble/

配网微信小程序：

Windows 运行方式

运行演示程序：

dotnet run --project ImprovWifi.Demo.Windows/ImprovWifi.Demo.Windows.csproj

运行要求：

• 已启用蓝牙
• 蓝牙适配器支持 Peripheral Role
• 允许应用注册本地 GATT Service

运行流程：

1. 启动程序
2. 输入一个 Redirect URL
3. 用支持 Improv 的配网工具扫描设备
4. 点击 Identify
5. Demo 自动执行授权
6. 发送 Wi-Fi 信息
7. Demo 返回 RPC Result URL

Linux 运行方式

运行演示程序：

dotnet run --project ImprovWifi.Demo.Linux/ImprovWifi.Demo.Linux.csproj -f net8.0

运行要求：

• 系统已安装并启动 BlueZ
• bluetoothd 正常运行
• 可通过 bluetoothctl 看到目标适配器，例如 hci0
• 当前用户具备访问蓝牙相关服务的权限

当前 Linux 传输层采用原生 BlueZ D-Bus 实现，底层使用：

• Tmds.DBus

运行流程与 Windows 版一致：

1. 启动程序
2. 输入一个 Redirect URL
3. 用支持 Improv 的配网工具扫描设备
4. 点击 Identify
5. Demo 自动执行授权
6. 发送 Wi-Fi 信息
7. Demo 返回 RPC Result URL

WSL2 说明

如果你在 WSL2 中运行 Linux Demo，需要确认：

• BlueZ 已正确安装并启动
• 蓝牙设备已正确透传到 WSL2
• bluetoothctl 可以看到适配器，例如 hci0

如果 WSL2 只能看到 bluetoothd，但无法真正完成外围设备广播或 GATT Server 注册，请优先检查宿主机蓝牙透传能力和 WSL2 对蓝牙外设模式的支持情况。

Demo 默认行为

Windows 和 Linux 的 Demo 当前都采用最小实现：

• 收到 Identify 后自动授权
• 收到配网信息后输出 SSID 和 Password
• 若已配置 Redirect URL，则立即调用 CompleteProvisioning(url)
• 若未配置 Redirect URL，则调用 FailProvisioning()

如果你要接入真实业务，建议改造以下位置：

• ImprovWifi.Demo.Windows/Program.cs
• ImprovWifi.Demo.Linux/Program.cs

通常做法是：

1. 在 ProvisioningRequested 中处理真实联网逻辑
2. 联网成功后调用 CompleteProvisioning(url)
3. 联网失败时调用 FailProvisioning(error)

适用场景

这个仓库适合以下场景：

• 自定义 IoT 设备蓝牙配网
• 基于 Improv Wi-Fi 的主机侧服务集成
• Windows 或 Linux 下的 BLE 配网实验项目
• 将协议层挂接到你自己的 GATT 宿主实现中

其他

<p align="center"> 更多文章和相关介绍，请关注我的微信公众号：桑榆肖物 <br/> <img src="https://open.weixin.qq.com/qr/code?username=gh_c874018d0317" width="200" height="200"/> </p>