Skip to content

Latest commit

 

History

History
136 lines (106 loc) · 4.59 KB

README.md

File metadata and controls

136 lines (106 loc) · 4.59 KB
Raw

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

MacOS USB Devices

  • 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):

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):

asciicast

References