Skip to content

Instantly share code, notes, and snippets.

@PastaJ36

PastaJ36/Wooting USB config protocol.md

Created June 10, 2019 10:51
Show Gist options
  • Save PastaJ36/04b82556bde3cd49183e913c833988ec to your computer and use it in GitHub Desktop.
Save PastaJ36/04b82556bde3cd49183e913c833988ec to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Wooting USB config protocol.md

Wooting USB config protocol

The Wooting config is based around a USH HID Generic interface. The base of this report is from the AVR ASF (http://ww1.microchip.com/downloads/en/appnotes/doc8499.pdf). If I remember correctly there are some slight changes, but nothing to major.

With this generic interface you can basically read and write bytes however you want it. The PC (host) will always initiate the configuration.

The Report In and Out are set as 128 bytes. The feature report size is 8 bytes.

There are two main parts in the protocol:

  1. Commands
  2. Reports

Commands

Commands are initiated with a feature reports from the host. Commands expect a reply from the device (Report Out). Commands are used to provide instructions to the device, or to request data. Some examples for usage are:

  1. Change keyboard profile. Response will just acknowledge.
  2. Get RGB profile. Response will be RGB profile.
  3. Get Analog profile. Response will be Analog profile.

The 8 bytes of the feature report size are used as: [unused, magicword0, magicword1, command ID, parameter0, parameter1, parameter2, parameter3]

Magicwords are used to identify the Host.

Command ID is used to identify which command it is. The parameters are command specific. For example Get RGB profile would have the profile number in the parameters.

The reply (Report Out) is 128 bytes. For structure of this reply see the reports paragraph below.

Reports

Reports are used to write data from the host to the device. No reply is required, but we might add this in the future. Reports are used for example:

  1. Setting a RGB profile.
  2. Setting a keyboard layer.

Reports (Report In for the device) are 128 bytes. The structure is similar to the commands: [magicword0, magicword1, report ID, … data …, crc0, crc1]

Just like with commands the report data is based on the report ID. For a RGB profile for example it is the profile number followed by an array of colours.

We have a CRC over our report, but I’m not sure if that’s necessary.

Any questions or comments please let me know. I can also post some all the Command and Report ID’s we have and / or some snippets if that’s useful.

@PastaJ36
Copy link
Author

PastaJ36 commented Jun 20, 2019 •
edited
Loading 

enum Commands {
  Ping,
  GetVersion,
  ResetToBootloader,
  GetSerial,

  GetRgbProfileCount,
  GetCurrentRgbProfileIndex,
  GetRgbMainProfile,
  LoadRgbProfile,
  SaveRgbProfile,

  GetDigitalProfilesCount,
  GetAnalogProfilesCount,
  GetCurrentKeyboardProfileIndex,
  GetDigitalProfile,
  GetAnalogProfileMainPart,
  GetAnalogProfileCurveChangeMapPart1,
  GetAnalogProfileCurveChangeMapPart2,

  GetNumberOfKeys,
  GetHidCodeDataProfile,
  GetKeyDescriptorDataProfile,

  GetDeviceConfig,

  GetAnalogValues,
  KeysOff,
  KeysOn,
  ActivateProfile,
  getDoubleKeyStrokeItem,
  doSoftReset,
  GetRgbColorsPart1,
  GetRgbColorsPart2,
  GetRgbEffects,
  RefreshRgbColors,
}

enum Reports {
  RgbMainPart = 0,
  DigitalProfileMainPart,
  AnalogProfileMainPart,
  AnalogProfileCurveChangeMapPart1,
  AnalogProfileCurveChangeMapPart2,
  HidCodesDataProfile,
  KeyDescriptorDataProfile,
  DeviceConfig,
  DoubleKeyStroke,
  RgbColorsPart,
  RgbEffects,
  WootdevRawReport,
  SerialNumber,
}

@meeuw
Copy link

meeuw commented May 30, 2023

See also: https://gist.github.com/BigBrainAFK/0ba454a1efb43f7cb6301cda8838f432

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment