Updated PiSugar WiFi config (markdown)

铲屎将军 2021-02-27 11:43:58 +08:00
parent 5e2cc32410
commit c76c145c8a

@ -1,55 +1,143 @@
# pisugar-wifi-config
# sugar-wifi-conf
![PR build on master](https://github.com/PiSugar/pisugar-wifi-config/workflows/PR%20build%20on%20master/badge.svg)
![PiSugar Wechat MiniApp](https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/qrcode.jpg)
PiSugar BLE wifi config tool. This is a BLE GATT server to config raspberry pi wifi.
English | [简体中文](https://github.com/PiSugar/sugar-wifi-conf/blob/master/README.cn_zh.md)
Wifi configuration is not an easy job with raspberry pi. When you bring pi to an unfamiliar place,
having no keyboard, no display, it is not possible to reconfigure the rpi's wifi.
A BLE service to configure wifi over bluetooth for a Raspberry Pi. You can:
`pisugar-wifi-config` makes it easy to talk to rpi via BLE and setup the wifi configuration. Your rpi
could be discovered by BLE advertisement, then configurated by pushing a simple SSID/password message.
- get wifi name, ip address, pi model
- config wifi
- get other custom info, e.g. CPU tempreture, CPU load, or whatever you can get by shell
- remote control the pi to execute shell script and get response, such as shutdown, reboot
NOTE 1: Users need to launch `PiSugar` wechat mini program to communicate with `pisugar-wifi-config`.
NOTE 2: Only WPA-PSK is supported.
Tested on Raspberry Pi 3B/3B+/zero w (models with bluetooth) with Raspbian.
## Build
Build and package
To access client-side app, please use Wechat app to scan the QR-code above. Source code of client-side is in folder /sugar-wifi-miniapp.
sudo bash build.sh
If you don't have wechat, you can use web-bluetooth to connect to your pi. Make sure your device and broswer support web-bluetooth api, visit [https://www.pisugar.com/sugar-wifi-conf](https://www.pisugar.com/sugar-wifi-conf) to connect. (Tested on MacOS and Android with Chrome, iOS [WebBLE](https://apps.apple.com/us/app/webble/id1193531073) browser) Source code of web-bluetooth client is in folder /web-bluetooth-client.
## Installation
Install bluez
<p align="center">
<img width="190" src="https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/demo.gif">
<img width="670" src="https://raw.githubusercontent.com/PiSugar/sugar-wifi-conf/master/image/miniapp-demo-en-fix2.jpg">
</p>
sudo apt install bluez
### Quick Install
```
wget http://cdn.pisugar.com/release/sugarwificonfig.sh -O- | sh
```
Old bluez in the raspberry repository need to enable experimental features to support GATT.
If you don't want to enable experimental features, compile and install a newer version of
bluez from source.
### Install from Github
```
git clone https://github.com/PiSugar/sugar-wifi-conf.git
sudo -s . ./sugar-wifi-conf/wificonfig.sh
sudo sed -e 's|ExecStart=.*|ExecStart=/usr/lib/bluetooth/bluetoothd --experimental|g'
-i /lib/systemd/system/bluetooth.service
sudo systemctl daemon-reload
sudo systemctl restart bluetooth
# the scrpit will add sugar-wifi-conf to /etc/rc.local so that it can run on startup
Download `pisugar-wifi-config_<version>.deb` from https://github.com/PiSugar/pisugar-wifi-config/releases , and install
## optional parameters
sudo dpkg -i pisugar-wifi-config_<version>.deb
# edit /etc/rc.local to append parameters to execute path
# param 1: key
# param 2: path to custom config file
# example:
sudo /home/pi/sugar-wifi-conf/build/sugar-wifi-conf pisugar /home/pi/sugar-wifi-conf/custom_config.json
## Security consideration
GATT server stops advertising after 5 miniutes since lunached. To adjust the advertising duration,
edit `/lib/systemd/system/pisugar-wifi-config.server`, add `-t <seconds>`, e.g.
```
# 600 seconds
sudo sed -e 's|ExecStart=.*|ExecStart=/usr/bin/pisugar-wifi-config -t 600|g' \
-i /lib/systemd/system/pisugar-wifi-config.service
sudo systemctl daemon-reload
sudo systemctl restart pisugar-wifi-config
### Custom configuration
By editing the custom config file, you can let the pi broadcast custom data, recieve and execute custom shell scripts. Note: please ensure that the config file is accessable for the program.
custom_config.json example
```
{
"note": {
"info" : {
"label": "name of the item, within 20 bytes",
"command": "the command to get value of the item, within 20 bytes",
"interval": "run command to get data in every X seconds"
},
"commands": {
"label": "name of the item, within 20 bytes",
"command": "the command to execute"
}
},
"info": [
{
"label": "CPU Temp",
"command": "vcgencmd measure_temp | cut -d = -f 2 | awk '{printf \"%s \", $1}'",
"interval": 5
},
{
"label": "CPU Load",
"command": "top -bn1 | grep load | awk '{printf \"%.2f%%\", $(NF-2)}'",
"interval": 1
},
{
"label": "Memory",
"command": "free -m | awk 'NR==2{printf \"%s/%sMB\", $3,$2 }'",
"interval": 5
},
{
"label": "UP Time",
"command": "uptime -p | cut -d 'p' -f 2 | awk '{ printf \"%s\", $0 }'",
"interval": 10
}
],
"commands": [
{
"label": "ls",
"command": "ls"
},
{
"label": "shutdown",
"command": "shutdown"
},
{
"label": "cancel shutdown",
"command": "shutdown -c"
},
{
"label": "reboot",
"command": "reboot"
}
]
}
```
### BLE datasheet
You can build your own client-side app base on this datasheet.
Service uuid: FD2B-4448-AA0F-4A15-A62F-EB0BE77A0000
| charateristic | uuid | properties | note |
| - | :- | :- | :- |
| SERVICE_NAME | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0001 | read | service name |
| DEVICE_MODEL | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0002 | read | pi model info |
| WIFI_NAME | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0003 | notify | current wifi name |
| IP_ADDRESS | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0004 | notify | internal ip addresses |
| INPUT | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0005 | write | input for configuring wifi (deprecated) |
| NOTIFY_MESSAGE | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0006 | notify | response for configuring wifi |
| INPUT_SEP | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0007 | write | input for configuring wifi(subcontracting) |
| CUSTOM_COMMAND_INPUT | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0008 | write | input for custom commands(subcontracting) |
| CUSTOM_COMMAND_NOTIFY | FD2B-4448-AA0F-4A15-A62F-EB0BE77A0009 | notify | response for custom commands(subcontracting) |
| CUSTOM_INFO_LABEL | 0000-0000-0000-0000-0000-FD2BCCCAXXXX | read | label of custom info |
| CUSTOM_INFO | 0000-0000-0000-0000-0000-FD2BCCCBXXXX | notify | value of custom info |
| CUSTOM_COMMAND_LABEL | 0000-0000-0000-0000-0000-FD2BCCCCXXXX | read | label of custom command |
### Input and Output format
| charateristic | format |
| - | :- |
| INPUT_SEP | format: key&%&ssid&%&password%#% (subcontract in 20 btyes) e.g. pisugar&%&home_wifi&%&12345678%#% |
| CUSTOM_COMMAND_INPUT | format: key&%&last_4_digit_uuid%#% (subcontract in 20 btyes) e.g. pisugar&%&1234%#% will execute the custom command with its label uuid end in "1234" |
| CUSTOM_COMMAND_NOTIFY | subcontract in 20 btyes, ended in "%#%" |
| CUSTOM_INFO_LABEL | a custom info label (FD2BCCCA1234) will have a corresponding value (FD2BCCCB1234) |
| CUSTOM_COMMAND_LABEL | all custom commands with be broadcast in uuid "FD2BCCCCXXXX" |
If advertising duration less or equal than 0, GATT server would never stop advertising.
## Bug report
Report bugs here: https://github.com/PiSugar/pisugar-wifi-config/issues
## License
GPLv3