BlinkStick Square RESTful API Server

The Unofficial RESTful API server and test Python3 scripts to control the BlinkStick Square device.

BlinkStickSquare480px.mp4

Pre-Requisites

Basics

• A BlinkStick Square device.
• Data transfer capable cable from Micro USB Male to USB 1.1/2.0/3.0 Male.
• A Python 3.12+ +pip3 working enviroment setup.
• Clone the repository with the following commands:

git clone https://github.com/olafrv/blinkstick_square
git submodule update --init
pip3 install -r requirements.txt

MacOS Tips

• Install libusb with the command brew install libusb.
• Use sudo to allow USB access when executing python or uvicorn.
• Check if BlinkStick visible in the following places/ways (if not replug it):
  • System Information > USB.
  • Running: system_profiler SPUSBDataType or ioreg -p IOUSB.
  • Running: My MacOS utility.
  • Alternatively, lsusb (A `system_profiler`` wrapper in Bash).

Microsoft Windows Tips

• Add User's Python Path, +R > Run: sysdm.cpl > Environment Variables > System Variables > Path > Edit
• Execute taskkill /f /im "uvicorn.exe" or taskkill /f /im "python.exe" to kill any running server.

Microsoft WSL2 Tips

• Close (quit) BlinkStick Client App as it will block the USB device.
• Follow the instructions to install usbipd-win described by Microsoft here.
• First, inside your WSL2 Linux:

sudo apt install linux-tools-generic hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20
cat - | sudo tee /etc/udev/rules.d/99-blinkstick.rules <<EOF
# BlinkStick Square - Allow user to read or write to the device
SUBSYSTEM=="usb", ATTRS{idVendor}=="20a0", ATTRS{idProduct}=="41e5", MODE="0666"
EOF
sudo udevadm control --reload-rules

• Second, from Windows list and attach the device to the WSL2 Linux:

# Windows Command Prompt (CMD) as Administrator
C:\Windows\System32>usbipd wsl list
2-2    20a0:41e5  USB Input Device  Not Attached
C:\Windows\System32>usbipd wsl attach --busid=2-2
C:\Windows\System32>usbipd wsl list
2-2    20a0:41e5  USB Input Device  Attached - WSL

• Third, inside the WSL2 Linux list the device:

# WSL2 Linux Shell
$ apt install usbutils
$ lsusb
Bus 001 Device 003: ID 20a0:41e5 Clay Logic BlinkStick

Usage

Set Username and Password

export BS_SQ_API_USERNAME="admin"  # If not set, defaults to "admin"
export BS_SQ_API_PASSWORD="strong-password"  # If not set, defaults to random value

Docker Compose

docker compose up -d
docker logs blinkstick_square

Uvicorn or Python

• Start the server with the following command:

uvicorn server:app
python server.py    # Alternative

API Frontend

• Head to http://localhost:8000/ API frontend.
• Click on 'Authorize' button and enter the credentials
• Expand the GET methods and click on 'Try it out' option.
• Fill out the parameters and click on 'Execute' button.

Test & Coverage

See coverage.md for details of environment and the lastest tests coverage.

python3 test.py               # Tests
sh coverage/coverage.sh       # Coverage Unix-Like
pwsh coverage\coverage.ps1    # Coverage Windows

The output of the test/coverage is shown below (source):

References

• BlinkStick: https://www.blinkstick.com
• Unix-Like: https://github.com/pyusb/pyusb
• Windows: https://pypi.org/project/pywinusb
• SRC: https://github.com/arvydas/blinkstick-python
• API: https://arvydas.github.io/blinkstick-python/
• Coverage: https://coverage.readthedocs.io/en/7.3.2/
• FastAPI: https://fastapi.tiangolo.com
• UviCorn: https://www.uvicorn.org
• WLS2 Connect USB Devices:
  • https://learn.microsoft.com/en-us/windows/wsl/connect-usb
  • https://github.com/dorssel/usbipd-win
• Testing USB Hardware/Drivers on Windows:
  • https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/muttutil
  • https://learn.microsoft.com/en-us/windows-hardware/drivers/usbcon/how-to-retrieve-information-about-a-usb-device