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.

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,
}

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