sinowisp

(formerly sinowealth-kb-tool)

A utility for reading and writing flash contents on Sinowealth 8051-based USB HID devices (keyboards and mice) through the commonly found ISP bootloader.

Disclaimer

I offer no guarantees that using this tool won't brick your device. Use this tool at your risk.

Usage

Reading

⚠️ A read operation will set an LJMP (0x02) opcode at address <firmware_size-5> if it's not already present there. When this opcode is set, the bootloader considers the main firmware enabled and jumps to it when the device is powered on. This opcode should already be set on most devices and therefore the read operation should not cause any issues.

⚠️ During reading the ISP bootloader will redirect values in 0x0001 - 0x0002 to <firmware_size-4> - <firmware_size-3>. Because of this, the produced payload will be different from how memory is actually laid out in the MCU flash.

# reads firmware excluding isp bootloader 
sinowisp read -d nuphy-air60 foobar.hex

# reads only isp bootloader section
sinowisp read -d nuphy-air60 -s bootloader bootloader.hex

# full dump including firmware and bootloader
sinowisp read -d nuphy-air60 -s full full.hex

# custom device
sinowisp read \
    --platform sh68f90 \
    --vendor_id 0x05ac \
    --product_id 0x024f \
    --firmware_size 61440 \ # optional
    --bootloader_size 4096 \ # optional
    --page_size 2048 \ # optional
    --isp_iface_num 1 \ # optional
    --isp_report_id 5 \ # optional
    --reboot false \ # optional
    foobar.hex

Writing

⚠️ Same as the read operation, the ISP bootloader will write values meant for addresses 0x0001-0x0002 to <firmware_size-4> - <firmware_size-3>.

# overwrites firmware (does not touch the bootloader section)
sinowisp write -p nuphy-air60 foobar.hex

# custom device
sinowisp write \
    --platform sh68f90 \
    --vendor_id 0x05ac \
    --product_id 0x024f \
    --firmware_size 61440 \ # optional
    --bootloader_size 4096 \ # optional
    --page_size 2048 \ # optional
    --isp_iface_num 1 \ # optional
    --isp_report_id 5 \ # optional
    --reboot false \ # optional
    foobar.hex

Supported Hardware

Keyboards

Mice

Bootloader Support

Platforms

Prerequisites

Linux

To enable running this tool without superuser privileges add the following udev rule with xxxx and yyyy replaced with your device Vendor ID and Product ID respectively.

# /etc/udev/rules.d/plugdev.rules
SUBSYSTEMS=="usb", ATTRS{idVendor}=="xxxx", ATTRS{idProduct}=="yyyy", MODE="0660", GROUP="plugdev"
SUBSYSTEMS=="usb", ATTRS{idVendor}=="0603", ATTRS{idProduct}=="1020", MODE="0660", GROUP="plugdev"

Make sure your user is part of the plugdev group.

macOS

If you encounter errors like:

hid_open_path: failed to open IOHIDDevice from mach entry...

Ensure that your terminal application has access to input monitoring.

Acknowledgments

Thanks to @gashtaan for analyzing and explaining the inner workings of the ISP bootloaders. Without his help, this tool wouldn't be here!