{"id":18871948,"url":"https://github.com/pisugar/sugar-wifi-conf","last_synced_at":"2026-06-17T05:00:27.687Z","repository":{"id":105899400,"uuid":"175444825","full_name":"PiSugar/sugar-wifi-conf","owner":"PiSugar","description":"A BLE service on raspberry pi for wifi configuration and wireless control.","archived":false,"fork":false,"pushed_at":"2026-04-06T08:04:07.000Z","size":30154,"stargazers_count":163,"open_issues_count":0,"forks_count":51,"subscribers_count":10,"default_branch":"master","last_synced_at":"2026-04-06T10:15:51.301Z","etag":null,"topics":["ble","bluetooth","bluetooth-low-energy","miniapp","pi","raspberry","rpi","web-ble","web-bluetooth","web-bluetooth-api","wechat","weixin","wifi"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PiSugar.png","metadata":{"files":{"readme":"README.cn_zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-03-13T15:08:13.000Z","updated_at":"2026-04-04T01:06:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"297f0f4a-98b2-4a4b-9fc6-bce9bed55775","html_url":"https://github.com/PiSugar/sugar-wifi-conf","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/PiSugar/sugar-wifi-conf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiSugar%2Fsugar-wifi-conf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiSugar%2Fsugar-wifi-conf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiSugar%2Fsugar-wifi-conf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiSugar%2Fsugar-wifi-conf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PiSugar","download_url":"https://codeload.github.com/PiSugar/sugar-wifi-conf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PiSugar%2Fsugar-wifi-conf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","bluetooth-low-energy","miniapp","pi","raspberry","rpi","web-ble","web-bluetooth","web-bluetooth-api","wechat","weixin","wifi"],"created_at":"2024-11-08T05:28:02.137Z","updated_at":"2026-06-17T05:00:27.667Z","avatar_url":"https://github.com/PiSugar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# sugar-wifi-conf\n\n\u003cp\u003e\n  \u003cimg width=\"200\" src=\"https://github.com/user-attachments/assets/e620a5b4-a788-4b72-8f49-fe186f2bf7fa\" /\u003e\n  \u003cimg width=\"200\" src=\"https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/qrcode.jpg\" /\u003e\n\u003c/p\u003e\n\n[English](https://github.com/PiSugar/sugar-wifi-conf) | 简体中文 \n\n让树莓派提供蓝牙BLE服务，使用PiSugar APP/小程序即可随时更改树莓派的wifi连接，获取wifi名称和ip地址等信息，也可以自定义显示系统信息，接受和执行shell命令。\n\n适用于带有蓝牙的树莓派型号(已测试5B/4B/3B+/zero w/zero 2w)，在Raspbain官方镜像可运行。\n\nPiSugar APP / 微信小程序 请扫描上方二维码获取。\n\n小程序源代码详见sugar-wifi-miniapp文件夹。\n\n你也可以使用web蓝牙来连接，请确保你的设备和浏览器支持web-bluetooth api. (已在MacOS和Android的chrome浏览器上测试，iOS可使用[WebBLE](https://apps.apple.com/us/app/webble/id1193531073)浏览器) 使用chrome打开[web蓝牙页面](https://www.pisugar.com/sugar-wifi-conf)进行连接。源码详见web-bluetooth-client文件夹。\n\n\n### 安装\n\n#### 一键安装（推荐）\n\n下载预编译二进制文件并安装为 systemd 服务，无需 Rust 工具链：\n\n```bash\ncurl -sSL https://repo.pisugar.uk/PiSugar/sugar-wifi-conf/raw/master/install-bin.sh | sudo bash\n```\n\n安装指定版本：\n```bash\ncurl -sSL https://repo.pisugar.uk/PiSugar/sugar-wifi-conf/raw/master/install-bin.sh | sudo bash -s -- v0.1.0\n```\n\n**支持的树莓派型号：**\n\n| 型号 | 架构 | 二进制文件 |\n| --- | --- | --- |\n| Pi Zero, Zero W, Pi 1 | ARMv6 (armv6l) | `sugar-wifi-conf-armv6` |\n| Pi 2, 3, 4, Zero 2 W (32位系统) | ARMv7 (armv7l) | `sugar-wifi-conf-armv7` |\n| Pi 3, 4, 5, Zero 2 W (64位系统) | AArch64 (aarch64) | `sugar-wifi-conf-aarch64` |\n\n安装脚本会自动检测架构并下载对应的二进制文件。\n\n#### 从源码编译\n\n源码在 `/rust` 目录。\n\n```\n# 在树莓派上编译安装\ncd rust\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\nsource \"$HOME/.cargo/env\"\ncargo build --release\nsudo mkdir -p /opt/sugar-wifi-config\nsudo cp target/release/sugar-wifi-conf /opt/sugar-wifi-config/\nsudo cp ../custom_config.json /opt/sugar-wifi-config/\n```\n\n或使用安装脚本：\n```\ncd rust \u0026\u0026 sudo bash install.sh\n```\n\n### 可选参数\n```\n# 可修改 /etc/systemd/system/sugar-wifi-config.service 文件改变运行参数\n# 例如：\nsugar-wifi-conf serve --name raspberrypi --key mykey --config /opt/sugar-wifi-config/custom_config.json\n```\n\n安装完成后重启树莓派。进入PiSugar APP的Wifi Config页面或者使用微信扫描二维码进入小程序，即可控制树莓派。\n\n### 通过 BLE 进行 SSH 连接\n\nRust 版本内置了 SSH 隧道功能，可以通过蓝牙 BLE 直接 SSH 到树莓派，无需 WiFi 或 IP 地址。macOS 命令行客户端在 `/ble-ssh-client` 目录。\n\n#### 编译客户端（macOS）\n\n```bash\ncd ble-ssh-client\ncargo build --release\n# 二进制文件在 target/release/ble-ssh\n```\n\n#### 使用方法\n\n```bash\n# 自动模式：扫描 BLE 设备，交互式选择设备，IP 可达时优先使用 IP\nble-ssh\n\n# 指定 IP 地址（BLE 作为备选）\nble-ssh --ip 192.168.1.100\n\n# 纯 IP 模式（不扫描 BLE）\nble-ssh --ip 192.168.1.100 --no-ble\n\n# 强制使用 BLE 隧道（即使 IP 可达）\nble-ssh --force-ble\n\n# 自定义本地端口和扫描超时\nble-ssh --port 2222 --scan-timeout 15\n```\n\n发现多个设备时会显示交互式选择列表：\n```\n  📱 Found: pisugar-a\n  📱 Found: pisugar-b\n\n? Select device\n\u003e pisugar-a (IP: 192.168.1.100)\n  pisugar-b (BLE only)\n\n? Connection mode\n\u003e Auto (prefer IP, BLE fallback)\n  Force BLE\n```\n\n然后在另一个终端连接：\n```bash\nssh pi@localhost -p 2222\n```\n\n隧道活跃时客户端会显示实时传输速度。\n\n#### 工作原理\n\n1. 客户端扫描 PiSugar BLE 设备并连接。\n2. 每次 SSH 连接时，客户端通过 SSH_CTRL 发送 `CONNECT`，服务端连接本地 sshd（127.0.0.1:22）并回复 `OK`。\n3. SSH 数据双向传输：客户端 → SSH_RX → sshd，sshd → SSH_TX → 客户端。\n4. SSH 会话结束时发送 `DISCONNECT`，服务端回复 `CLOSED`。\n5. 如果 Pi 的 IP 可达，客户端会直接通过 TCP 桥接以获得更好速度；否则走 BLE 隧道。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg width=\"190\" src=\"https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/demo.gif\"\u003e\n  \u003cimg width=\"670\" src=\"https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/miniapp-demo-cn-fix2.jpg\"\u003e\n\u003c/p\u003e\n\n### 自定义配置\n\n通过修改配置文件可以让你的树莓派通过BLE更方便的发送系统信息，接受和执行shell命令\n\n注意：若配置文件格式有误或着因权限问题无法读取，小程序端将无法获取自定义的信息。\n\ninfo为客户端显示的参数，注意command获得的结果不能超过20个字符，interval为每次获取结果的间隔秒数。\n\ncommands为客户端可向树莓派发出的shell命令。\n\n```\n{\n  \"info\": [\n    {\n      \"label\": \"CPU Temp\",\n      \"command\": \"vcgencmd measure_temp | cut -d = -f 2 | awk '{printf \\\"%s \\\", $1}'\",\n      \"interval\": 5\n    },\n    {\n      \"label\": \"CPU Load\",\n      \"command\": \"top -bn1 | grep load | awk '{printf \\\"%.2f%%\\\", $(NF-2)}'\",\n      \"interval\": 1\n    },\n    {\n      \"label\": \"Memory\",\n      \"command\": \"free -m | awk 'NR==2{printf \\\"%s/%sMB\\\", $3,$2 }'\",\n      \"interval\": 5\n    },\n    {\n      \"label\": \"UP Time\",\n      \"command\": \"uptime -p | cut -d 'p' -f 2 | awk '{ printf \\\"%s\\\", $0 }'\",\n      \"interval\": 10\n    }\n  ],\n  \"commands\": [\n    {\n      \"label\": \"shutdown\",\n      \"command\": \"shutdown\"\n    },\n    {\n      \"label\": \"reboot\",\n      \"command\": \"reboot\"\n    }\n  ]\n}\n\n```\n\n### 蓝牙BLE服务详细参数\n\n服务uuid: FD2B-4448-AA0F-4A15-A62F-EB0BE77A0000\n\n| 特征值 | uuid | 属性 | 说明 |\n| - | :- | :- | :- |\n| SERVICE_NAME | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0001 | read | 服务名称，固定值 |\n| DEVICE_MODEL | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0002 | read | 树莓派版本 |\n| WIFI_NAME | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0003 | notify | 正在连接的wifi名称 |\n| IP_ADDRESS | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0004 | notify | 现有内网ip地址 |\n| INPUT | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0005 | write | 输入wifi配置信息（已弃用） |\n| NOTIFY_MESSAGE | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0006 | notify | wifi配置操作返回的信息 |\n| INPUT_SEP | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0007 | write | 输入wifi配置信息（分包） |\n| CUSTOM_COMMAND_INPUT | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0008 | write | 输入自定义命令（分包） |\n| CUSTOM_COMMAND_NOTIFY | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0009 | notify | 命令执行返回（分包） |\n| CUSTOM_INFO_LABEL | 0000-0000-0000-0000-0000-FD2BCCCAXXXX | read | 自定义信息显示的标签名 |\n| CUSTOM_INFO | 0000-0000-0000-0000-0000-FD2BCCCBXXXX | notify | 自定义信息显示的数值 |\n| CUSTOM_COMMAND_LABEL | 0000-0000-0000-0000-0000-FD2BCCCCXXXX | read | 自定义命令名称 |\n| SSH_CTRL | FD2B-4448-AA0F-4A15-A62F-EB0BE77A000A | write, notify | SSH 隧道控制（CONNECT / DISCONNECT） |\n| SSH_RX | FD2B-4448-AA0F-4A15-A62F-EB0BE77A000B | write | SSH 数据：客户端 → Pi（原始二进制，512 字节分包） |\n| SSH_TX | FD2B-4448-AA0F-4A15-A62F-EB0BE77A000C | notify | SSH 数据：Pi → 客户端（原始二进制，512 字节分包） |\n\n\n### 通讯格式\n\n| 特征值 | 操作说明 |\n| - | :- |\n| INPUT_SEP | 发送格式为 key%\u0026%ssid%\u0026%password\u0026#\u0026 （分为多条20字节数据传送），例如：pisugar%\u0026%home_wifi%\u0026%12345678\u0026#\u0026 |\n| CUSTOM_COMMAND_INPUT | 发送格式为 key%\u0026%4_digit_uuid\u0026#\u0026（分为多条20字节数据传送，例如：key%\u0026%1234\u0026#\u0026 将执行CUSTOM_COMMAND_LABEL末四位uuid为1234的命令） |\n| CUSTOM_COMMAND_NOTIFY | 分为多条20字节数据传送，结束符为\u0026#\u0026 |\n| CUSTOM_INFO_LABEL | 例如：uuid为FD2BCCCA1234的CUSTOM_INFO_LABEL 对应 uuid为FD2BCCCB1234的CUSTOM_INFO特征值 |\n| CUSTOM_COMMAND_LABEL | 所有的自定义命令都会广播成uuid为 FD2BCCCCXXXX 的特征值，读取特征值可以获取命令的label, uuid后四位可以用发送执行 |\n| SSH_CTRL | 写入 `CONNECT` 打开到 sshd 的隧道，服务端通知 `OK` 或 `ERR:\u003c原因\u003e`。写入 `DISCONNECT` 关闭隧道，服务端通知 `CLOSED`。 |\n| SSH_RX | 原始二进制 SSH 数据，客户端写入后转发到 sshd。每次写入最大 512 字节。 |\n| SSH_TX | 原始二进制 SSH 数据，sshd 发送到客户端的 BLE 通知。每次通知最大 512 字节。 |\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpisugar%2Fsugar-wifi-conf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpisugar%2Fsugar-wifi-conf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpisugar%2Fsugar-wifi-conf/lists"}