balena-os/wifi-connect
GitHub: balena-os/wifi-connect
一个通过热点门户简化Linux设备WiFi配置的开源工具。
Stars: 1487 | Forks: 404
一个由 balena.io 开发的开源 :satellite: 项目
[**下载**][DOWNLOAD] | [**工作原理**](#how-it-works) | [**安装说明**](#installation) | [**支持**](#support) | [**路线图**][MILESTONES]
## 工作原理
WiFi Connect 与 NetworkManager 进行交互，NetworkManager 应该是设备主机操作系统上的活动网络管理器。
### 1. 广播：设备创建接入点
WiFi Connect 检测可用的 WiFi 网络，并创建一个带有强制门户的接入点。使用手机或笔记本电脑连接到该接入点，即可配置新的 WiFi 凭据。
### 2. 连接：用户将手机连接到设备接入点
从您的手机或笔记本电脑连接到设备上打开的接入点。接入点 SSID 默认为 `WiFi Connect`。可以通过设置 `--portal-ssid` 命令行参数或 `PORTAL_SSID` 环境变量来更改它（有关在 balenaOS 上运行时如何管理环境变量，请参阅[本指南](https://balena.io/docs/management/env-vars/)）。默认情况下，网络是未加密的，但可以通过设置 `--portal-portal-passphrase` 命令行参数或 `PORTAL_PASSPHRASE` 环境变量来添加 WPA2 密码。
### 3. 门户：手机向用户显示强制门户
从手机连接到接入点后，它将检测到强制门户并打开其网页。打开任何网页也会重定向到该强制门户。
### 4. 凭据：用户在手机上输入本地 WiFi 网络凭据
强制门户提供从检测到的 WiFi 网络列表中选择一个 WiFi SSID，并为所需网络输入密码的选项。
### 5. 已连接！：设备连接到本地 WiFi 网络
输入网络凭据后，WiFi Connect 将禁用接入点并尝试连接到该网络。如果连接失败，它将重新启用接入点以进行另一次尝试。如果成功，NetworkManager 将保存该配置。
有关命令行参数和环境变量的完整列表，请查看我们的[命令行参数](./docs/command-line-arguments.md)指南。
完整的应用程序流程在[状态流程图](./docs/state-flow-diagram.md)中进行了说明。
## 安装说明
WiFi Connect 设计用于在 Raspbian 或 Debian 等系统上工作，或在 balenaOS 之上的 docker 容器中运行。
### Raspbian/Debian Stretch
WiFi Connect 依赖于 NetworkManager，但默认情况下 Raspbian Stretch 使用 dhcpcd 作为网络管理器。提供的安装 shell 脚本会禁用 dhcpcd，将 NetworkManager 安装为活动网络管理器，并下载并安装 WiFi Connect。
在您的终端中运行以下命令，然后按照屏幕上的说明操作：
`bash <(curl -L https://github.com/balena-io/wifi-connect/raw/master/scripts/raspbian-install.sh)`
### balenaOS
WiFi Connect 可以与 [balena.io](http://balena.io) 应用程序集成。（初次接触 balena.io？请查看[入门指南](https://balena.io/docs/#/pages/installing/gettingStarted.md)。）这种集成通过使用两个共享文件实现：
- [Dockerfile 模板](./Dockerfile.template)管理依赖项。此处包含的示例已包含 WiFi Connect 运行所需的一切。需要添加应用程序依赖项。有关 Dockerfile 的帮助，请查看此[指南](https://balena.io/docs/deployment/dockerfile/)。
- [启动脚本](./scripts/start.sh)应包含运行应用程序的命令。在脚本末尾添加这些命令将确保在 WiFi 正确配置后所有内容都能启动。
在 Python 项目中使用 WiFi Connect 的示例可以在此处找到[此处](https://github.com/balena-io-projects/balena-wifi-connect-example)。
### balenaOS：多容器应用
要在多容器应用上使用 WiFi Connect，您需要：
- 将容器网络模式设置为 host
- 通过添加所需的标签和环境变量来启用 DBUS（更多关于 [balenaOS dbus](https://www.balena.io/docs/learn/develop/runtime/#dbus-communication-with-host-os)）
- 授予容器网络管理员权限
您的 `docker-compose.yml` 文件应如下所示：
```
version: "2.1"
services:
wifi-connect:
build: ./wifi-connect
network_mode: "host"
labels:
io.balena.features.dbus: '1'
cap_add:
- NET_ADMIN
environment:
DBUS_SYSTEM_BUS_ADDRESS: "unix:path=/host/run/dbus/system_bus_socket"
...
```
## 支持的主板/适配器
WiFi Connect 已使用以下 WiFi 适配器成功测试：
适配器 | 芯片
-------------------------------------------|-------------------
[TP-LINK TL-WN722N](http://bit.ly/1P1MdAG) | Atheros AR9271
[ModMyPi](http://bit.ly/1gY3IHF) | Ralink RT3070
[ThePiHut](http://bit.ly/1LfkCgZ) | Ralink RT5370
它也已在 Raspberry Pi 3 的板载 WiFi 上成功测试。
基于这些结果，大多数带有 *Atheros* 或 *Ralink* 芯片组的适配器很可能都可以工作。
以下适配器已知**无法**工作（因为其驱动程序与接入点模式或 NetworkManager 不兼容）：
* 官方 Raspberry Pi 适配器（BCM43143 芯片）
* Addon NWU276（Mediatek MT7601 芯片）
* Edimax（Realtek RTL8188CUS 芯片）
具有类似芯片组的适配器可能无法工作。
只要拥有[兼容的适配器](https://www.balena.io/docs/reference/hardware/wifi-dongles/)，WiFi Connect 预计可与所有 balena.io [支持的主板](https://www.balena.io/docs/reference/hardware/devices/)一起工作。
## 支持
如果您遇到任何问题，请在 GitHub 上[提出问题](https://github.com/balena-io/wifi-connect/issues/new)或[联系我们](https://balena.io/community/)，balena.io 团队将很乐意为您提供帮助。
## 许可证
WiFi Connect 是免费软件，可根据指定条款进行分发。
[许可证](https://github.com/balena-io/wifi-connect/blob/master/LICENSE)。
标签：balena.io, captive portal, Linux 设备, NetworkManager, WiFi 设置, 二进制发布, 嵌入式系统, 开源工具, 接入点配置, 无线网络, 智能设备设置, 物联网, 用户友好配置, 移动配置, 网络共享, 网络工具, 自动化配置, 设备初始化, 请求拦截, 远程配置, 通知系统, 零配置网络