diff --git a/PiSugar-WiFi-config.md b/PiSugar-WiFi-config.md index 5255034..cd7e07d 100644 --- a/PiSugar-WiFi-config.md +++ b/PiSugar-WiFi-config.md @@ -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 +

+ + +

- 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_.deb` from https://github.com/PiSugar/pisugar-wifi-config/releases , and install +## optional parameters - sudo dpkg -i pisugar-wifi-config_.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 `, 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