{"id":40275088,"url":"https://github.com/olafrv/blinkstick_square","last_synced_at":"2026-01-20T03:05:19.356Z","repository":{"id":203634906,"uuid":"710064541","full_name":"olafrv/blinkstick_square","owner":"olafrv","description":"BlinkStick Square RESTful API server and test Python3 scripts (Unofficial)","archived":false,"fork":false,"pushed_at":"2025-03-24T20:26:01.000Z","size":1201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T20:32:31.708Z","etag":null,"topics":["blinkstick","iot","python3"],"latest_commit_sha":null,"homepage":"https://www.blinkstick.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olafrv.png","metadata":{"files":{"readme":"README.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}},"created_at":"2023-10-26T00:19:56.000Z","updated_at":"2025-03-24T20:26:04.000Z","dependencies_parsed_at":"2024-05-03T22:48:48.809Z","dependency_job_id":null,"html_url":"https://github.com/olafrv/blinkstick_square","commit_stats":null,"previous_names":["olafrv/blinkstick_square"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/olafrv/blinkstick_square","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olafrv%2Fblinkstick_square","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olafrv%2Fblinkstick_square/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olafrv%2Fblinkstick_square/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olafrv%2Fblinkstick_square/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olafrv","download_url":"https://codeload.github.com/olafrv/blinkstick_square/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olafrv%2Fblinkstick_square/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28594958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["blinkstick","iot","python3"],"created_at":"2026-01-20T03:05:18.703Z","updated_at":"2026-01-20T03:05:19.350Z","avatar_url":"https://github.com/olafrv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlinkStick Square RESTful API Server\n\nThe Unofficial [RESTful API server](server.py) and \n[test](test.py) Python3 scripts to control the\n[BlinkStick Square](https://www.blinkstick.com/products/blinkstick-square) \ndevice.\n\nhttps://github.com/olafrv/blinkstick_square/assets/987499/0d43afc5-ec32-4dd1-9299-25bf6d0d29a1\n\n## Pre-Requisites\n\n### Basics\n\n* A [BlinkStick Square](https://www.blinkstick.com/products/blinkstick-square) device.\n* Data transfer capable cable from Micro USB Male to USB 1.1/2.0/3.0 Male.\n* A Python 3.12+ +pip3 working enviroment setup (optionally, virtual).\n\n### Installation\n\n* Clone the repository with the following commands:\n\n```sh\ngit clone https://github.com/olafrv/blinkstick_square\ncd blinkstick_square\ngit submodule update --init\npython -m venv .venv       # if you want to use Python Virtual enviroment\nsource .venv/bin/activate  # if you want to use Python Virtual enviroment \npip3 install -r requirements.txt\n```\n\n### MacOS Tips\n\n![MacOS USB Devices](./docs/macos_usb_devices.png)\n\n* Install `libusb` with the command `brew install libusb`.\n* Use `sudo` to allow USB access when executing `python` or `uvicorn`.\n* Check if BlinkStick visible in the following places/ways (if not **replug** it):\n  * [System Information \u003e USB](https://support.apple.com/en-gb/guide/mac-help/mchlp1641/mac).\n  * Running: `system_profiler SPUSBDataType` or `ioreg -p IOUSB`.\n  * Running: My [MacOS utility](./macos_utils/list_devices.sh).\n  * Alternatively, [lsusb](https://github.com/jlhonora/lsusb) (A `system_profiler`` wrapper in Bash).\n\n### Microsoft Windows Tips \n\n* Add User's Python Path, \u003cWIN\u003e+R \u003e Run: sysdm.cpl \u003e Environment Variables \u003e System Variables \u003e Path \u003e Edit\n* Execute `taskkill /f /im \"uvicorn.exe\"` or `taskkill /f /im \"python.exe\"`  to kill any running server.\n\n### Microsoft WSL2 Tips\n\n* Close (quit) [BlinkStick Client App](https://www.blinkstick.com/help/downloads) as it will block the USB device.\n* Follow the instructions to install [usbipd-win](https://github.com/dorssel/usbipd-win)\n  described by Microsoft [here](https://learn.microsoft.com/en-us/windows/wsl/connect-usb).\n* First, inside your WSL2 Linux:\n```sh\nsudo apt install linux-tools-generic hwdata\nsudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20\ncat - | sudo tee /etc/udev/rules.d/99-blinkstick.rules \u003c\u003cEOF\n# BlinkStick Square - Allow user to read or write to the device\nSUBSYSTEM==\"usb\", ATTRS{idVendor}==\"20a0\", ATTRS{idProduct}==\"41e5\", MODE=\"0666\"\nEOF\nsudo udevadm control --reload-rules  # Sometimes reboot is required!\n```\n* Second, from Windows list and attach the device to the WSL2 Linux:\n```sh\n# Windows Command Prompt (CMD) as Administrator\nC:\\Windows\\System32\u003eusbipd wsl list\n2-2    20a0:41e5  USB Input Device  Not Attached\nC:\\Windows\\System32\u003eusbipd wsl attach --busid=2-2\nC:\\Windows\\System32\u003eusbipd wsl list\n2-2    20a0:41e5  USB Input Device  Attached - WSL\n```\n* Third, inside the WSL2 Linux list the device:\n```sh\n# WSL2 Linux Shell\n$ apt install usbutils\n$ lsusb\nBus 001 Device 003: ID 20a0:41e5 Clay Logic BlinkStick\n```\n\n### Raspberry Pi + Raspbian OS Tips\n\n* The command `lsusb` should be already installed.\n* Add the udev rules (See Microsoft WSL2 Tips) and reboot.\n* Then you should see the USB device with `lsusb -vvv` (without errors).\n\n## Usage\n\n### Set Username and Password inside `.env`\n\n```sh\t\nBS_SQ_API_USERNAME=\"admin\"            # If not set, defaults to \"admin\"\nBS_SQ_API_PASSWORD=\"strong-password\"  # If not set, defaults to RANDOM value!\n```\n\n### Option 1: Uvicorn or Python w/wo Python Virtual Environment\n\n* Start the server with one of the following command:\n```sh\n# See the previous tips sections if facing issues\nuvicorn server:app  # default\nuvicorn --host 0.0.0.0 --port 8000 server:app\npython3 server.py  # alternative without uvicorn\n# If Python virtual environment (sudo ignores $PATH):\n.venv/bin/uvicorn server:app\n.venv/bin/uvicorn server:app --host 0.0.0.0 --port 8000 server:app\n.venv/bin/python3 server.py\n```\n\n### Option 2: Docker Compose\n\n```sh\ndocker compose up -d\ndocker logs blinkstick_square\n```\n\n### Run the application on boot\n\n```bash\nbash service.sh  # Install the service on boot\njournalctl -u blinkstick  # Check the service logs (Also './logs/*.log')\n# sudo systemctl stop blinkstick\n# sudo systemctl start blinkstick\n```\n\n### Access API Frontend\n\n* Go to http://localhost:8000/ (or http://\u003cIP\u003e:8000).\n* Click on 'Authorize' button and enter the credentials\n* Expand the GET methods and click on 'Try it out' option.\n* Fill out the parameters and click on 'Execute' button.\n\n## Test \u0026 Coverage\n\nSee [coverage.md](coverage.md) for details of environment\nand the lastest tests coverage.\n\n```sh\npython3 test.py               # Tests\nsh coverage/coverage.sh       # Coverage Unix-Like\npwsh coverage\\coverage.ps1    # Coverage Windows\n```\n\nThe output of the test/coverage is shown below ([source](docs/bssq_test.cast)):\n\n[![asciicast](https://asciinema.org/a/618281.png)](https://asciinema.org/a/618281) \n\n\n## References\n\n* BlinkStick: https://www.blinkstick.com\n* Unix-Like: https://github.com/pyusb/pyusb\n* Windows: https://pypi.org/project/pywinusb\n* SRC: https://github.com/arvydas/blinkstick-python\n* API: https://arvydas.github.io/blinkstick-python/\n* Coverage: https://coverage.readthedocs.io/en/7.3.2/\n* FastAPI: https://fastapi.tiangolo.com\n* UviCorn: https://www.uvicorn.org\n* WLS2 Connect USB Devices:\n  * https://learn.microsoft.com/en-us/windows/wsl/connect-usb\n  * https://github.com/dorssel/usbipd-win\n* Testing USB Hardware/Drivers on Windows:\n  * https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/muttutil\n  * https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/how-to-retrieve-information-about-a-usb-device","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folafrv%2Fblinkstick_square","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folafrv%2Fblinkstick_square","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folafrv%2Fblinkstick_square/lists"}