245 lines
11 KiB
TeX
245 lines
11 KiB
TeX
\documentclass[]{article}
|
|
\usepackage{fontspec}
|
|
\usepackage{listings}
|
|
\usepackage{titling}
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage[margin=1in]{geometry}
|
|
\usepackage{pdfpages}
|
|
\usepackage{float}
|
|
\usepackage{amssymb}
|
|
\usepackage{alltt}
|
|
\usepackage{verbatim}
|
|
\usepackage{amstext}
|
|
\usepackage{tikz}
|
|
\usepackage{siunitx}
|
|
\usepackage{pgfplots}
|
|
\usepackage{bytefield}
|
|
|
|
\sisetup{group-separator={,}}
|
|
\usetikzlibrary{intersections,calc,positioning,arrows}
|
|
|
|
%opening
|
|
\title {Sharkoon Skiller MECH SGK3 USB control protocol}
|
|
\author {Kacper Donat <kacper@kadet.net>}
|
|
|
|
\tikzstyle{key}=[draw, rounded corners=.3mm, outer sep=2pt]
|
|
\DeclareRobustCommand{\key}[1]{\tikz[baseline={(K.base)}]{\node[key] (K) {#1}}}
|
|
|
|
\begin{document}
|
|
{\huge \noindent \textbf{\thetitle} \vspace{5mm}} \\
|
|
{\large \theauthor} \\
|
|
|
|
\section{Basic info}
|
|
\begin{table}[H]
|
|
\begin{tabular}{l|r}
|
|
\textbf{Property} & \textbf{Value} \\ \hline
|
|
\textbf{VendorID} & 0c45\\
|
|
\textbf{ProductID} & 8513 \\
|
|
\textbf{Control Interface Index} & 1 \\ \hline
|
|
\textbf{Endianness} & Big Endian
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\section{Protocol}
|
|
Commands are submited to keybord via USB control transfer, state updates are send by keyboard via USB interrupts.
|
|
After every command, keyboard should send state update.
|
|
|
|
Every packet has length of 64 bytes, and consist of 8 bytes header followed by payload, which can be up to 56 bytes
|
|
long. It's not possible to split packet into two, instead we should use addressing feature described later.
|
|
|
|
\begin{figure}[H]
|
|
\centering
|
|
\begin{bytefield}[bitwidth=4em]{8}
|
|
\bitheader{0-7} \\
|
|
\bitbox{1}{04h} & \bitbox{2}{checksum} & \bitbox{1}{cmd} & \bitbox{1}{len} & \bitbox{2}{addr} & \bitbox{1}{00h} \\
|
|
\wordbox{3}{payload \\ up to 56 bytes}
|
|
\end{bytefield}
|
|
\end{figure}
|
|
|
|
\subsection{Header}
|
|
Every packet starts with magic byte \texttt{04h}, probably used to determine control packets. Every value is written
|
|
in Big Endian manner, ie. LOW byte commes first. Header is ended with one null byte used for padding.
|
|
|
|
\subsubsection{checksum}
|
|
Magic value is followed by 2-byte long checksum. Checksum calculation method is really trivial - it's just a sum of all
|
|
bytes after checksum.
|
|
|
|
\begin{equation}
|
|
\mathtt{checksum} = \sum_{i=3}^{64} \mathtt{Byte}_i
|
|
\end{equation}
|
|
|
|
\subsubsection{command}
|
|
Command is 1-byte long identifier, which determines payload kind and action taken by keyboard. Commands can be used
|
|
to update keyboard state, or to read state.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\begin{tabular}{l|r|l}
|
|
\textbf{Command} & \textbf{Value} & \textbf{Description} \\ \hline
|
|
\texttt{SK\_CMD\_DISABLE\_LED} & \texttt{01h} & Disables key backlight, takes some time. \\
|
|
\texttt{SK\_CMD\_ENABLE\_LED} & \texttt{02h} & Enables key backlight, takes some time. \\
|
|
\texttt{SK\_CMD\_READ\_???} & \texttt{03h} & Reads some state. \\
|
|
\texttt{SK\_CMD\_READ\_???} & \texttt{05h} & Reads some state. \\
|
|
\texttt{SK\_CMD\_SET\_PROP} & \texttt{06h} & Changes keyboard mode or mode settings. \\
|
|
\texttt{SK\_CMD\_MAP\_KEYS} & \texttt{08h} & Writes key mapping to controller. \\
|
|
\texttt{SK\_CMD\_WRITE\_MACRO} & \texttt{0Ah} & Saves macros in controller memory. \\
|
|
\texttt{SK\_CMD\_SET\_COLOR} & \texttt{11h} & Changes LED RGB values in key given keys, or key range. \\
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
All commands will be described more precisely in later sections.
|
|
|
|
\subsubsection{len}
|
|
Length of payload, up to 56.
|
|
|
|
\subsubsection{addr}
|
|
Address of changed value/register, command specific, if not needed should be set to \texttt{0000h}.
|
|
|
|
\section{commands}
|
|
\subsection{\texttt{SK\_CMD\_DISABLE\_LED} (\texttt{01h})}
|
|
This command disables all LEDs\footnote{And maybe other things, hard to test.} on keyboard. It's useful when we
|
|
need to change few values and don't want to constantly blink diodes.
|
|
|
|
\subsection{\texttt{SK\_CMD\_ENABLE\_LED} (\texttt{02h})}
|
|
This command re-enables all LEDs on keyboard. It's useful when we need to change few values and don't want to
|
|
constantly blink diodes. Both operations are quite long to execute, they can took about 1s.
|
|
|
|
\subsection{\texttt{SK\_CMD\_SET\_PROP} (\texttt{06h})}
|
|
This command is used to change color mode and other settings like brighteness, pulsation direction, polling rate
|
|
etc.
|
|
|
|
\subsubsection{Addressing}
|
|
Changed property is referenced via \texttt{addr}.
|
|
\begin{table}[H]
|
|
\begin{tabular}{l|r|l}
|
|
\textbf{Property} & \textbf{Address} & \textbf{Description} \\ \hline
|
|
\texttt{SK\_PROP\_MODE} & \texttt{00h} & Changes backlight program (pulsing, permamant, custom, etc.) \\
|
|
\texttt{SK\_PROP\_BRIGHTNESS} & \texttt{01h} & Sets brihgtness level \\
|
|
\texttt{SK\_PROP\_SPEED} & \texttt{02h} & Sets animation speed \\
|
|
\texttt{SK\_PROP\_DIRECTION} & \texttt{03h} & Sets animation direction \\
|
|
\texttt{SK\_PROP\_RGB} & \texttt{04h} & LGBT promotion \\
|
|
\texttt{SK\_PROP\_COLOR} & \texttt{05h} & Base color \\
|
|
\texttt{SK\_PROP\_POLLING} & \texttt{0Fh} & Polling rate \\
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsubsection{Payload}
|
|
\paragraph{\texttt{SK\_PROP\_MODE} (\texttt{00h})}
|
|
Payload is 1-byte long mode identifier, possible modes are listed in table below.
|
|
\begin{table}[H]
|
|
\centering
|
|
\begin{tabular}{l|r|l}
|
|
\textbf{Identifier} & \textbf{Value} & \textbf{Name} \\ \hline
|
|
\texttt{SK\_MODE\_WAVE} & \texttt{01h} & Wave \\
|
|
\texttt{SK\_MODE\_DRIFT} & \texttt{02h} & Drift \\
|
|
\texttt{SK\_MODE\_SWIRL} & \texttt{03h} & Swirl \\
|
|
\texttt{SK\_MODE\_CHANGE} & \texttt{04h} & color change \\
|
|
\texttt{SK\_MODE\_PULSATING} & \texttt{05h} & pulsating \\
|
|
\texttt{SK\_MODE\_PERMAMENT} & \texttt{06h} & permament \\
|
|
\texttt{SK\_MODE\_EXPLOSION} & \texttt{07h} & Explosion \\
|
|
\texttt{SK\_MODE\_TRIGGER} & \texttt{08h} & Trigger \\
|
|
\texttt{SK\_MODE\_BURST} & \texttt{09h} & Gamma Ray Burst \\
|
|
\texttt{SK\_MODE\_CHAOS} & \texttt{0Ah} & Chaos \\
|
|
\texttt{SK\_MODE\_COSMIC} & \texttt{0Bh} & Cosmic \\
|
|
\texttt{SK\_MODE\_GRADIENT} & \texttt{0Ch} & Gradient \\
|
|
\texttt{SK\_MODE\_TIDE} & \texttt{0Dh} & Tide \\
|
|
\texttt{SK\_MODE\_LIGHTING} & \texttt{0Eh} & Ball Lighting \\
|
|
\texttt{SK\_MODE\_MATRIX} & \texttt{0Fh} & Matrix \\
|
|
\texttt{SK\_MODE\_RICOCHET} & \texttt{10h} & Ricochet \\
|
|
\texttt{SK\_MODE\_RIPPLE} & \texttt{12h} & Ripple \\
|
|
\texttt{SK\_MODE\_CUSTOM} & \texttt{14h} & Custom
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\paragraph{\texttt{SK\_PROP\_BRIGHTNESS} (\texttt{01h})}
|
|
Payload is 1-byte from range \texttt{00h-05h}, where \texttt{00h} means no light at all and \texttt{05h} is the
|
|
brightest value.
|
|
|
|
\paragraph{\texttt{SK\_PROP\_SPEED} (\texttt{02h})}
|
|
Payload is 1-byte from range \texttt{00h-05h}, where \texttt{00h} is the slowest setting and \texttt{05h} is the
|
|
fastest one.
|
|
|
|
\paragraph{\texttt{SK\_PROP\_DIRECTION} (\texttt{03h})}
|
|
Payload 1-byte value desciring direction, \texttt{00} for left to right/top to bottom and \texttt{ffh} for reverse.
|
|
|
|
\paragraph{\texttt{SK\_PROP\_RGB} (\texttt{04h})}
|
|
Payload is 1-byte long flag, which defines if we should see rainbow (\texttt{01h}) or not (\texttt{00h})
|
|
|
|
\paragraph{\texttt{SK\_PROP\_COLOR} (\texttt{05h})}
|
|
Payload is 3-byte RGB value describing color used by mode, detailed structure is exactly the same as in
|
|
\ref{cmd:color:payload}.
|
|
|
|
\paragraph{\texttt{SK\_PROP\_POLLING} (\texttt{0Fh})}
|
|
Payload is 1-byte long value identifing used polling rate.
|
|
\begin{table}[H]
|
|
\centering
|
|
\begin{tabular}{l|r|l}
|
|
\textbf{Identifier} & \textbf{Value} & \textbf{Polling rate} \\ \hline
|
|
\texttt{SK\_POLL\_125HZ} & \texttt{00h} & \SI{125}{\hertz} \\
|
|
\texttt{SK\_POLL\_250HZ} & \texttt{01h} & \SI{250}{\hertz} \\
|
|
\texttt{SK\_POLL\_500HZ} & \texttt{02h} & \SI{500}{\hertz} \\
|
|
\texttt{SK\_POLL\_1000HZ} & \texttt{03h} & \SI{1000}{\hertz} \\
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{\texttt{SK\_CMD\_SET\_COLOR} (\texttt{11h})}
|
|
This command can be used to change color of 1 or few LEDs at once. This operation takes less than 100ms, and
|
|
refreshes all diodes (in simpler words - they blink). This command only makes sens weh in \texttt{SK\_MODE\_CUSTOM}.
|
|
|
|
\subsubsection{Addressing}
|
|
The \texttt{addr} header value identifies starting address of specific LED in keyboard. Rule of thumb is that keys
|
|
are addressed from left to right, top to bottom staring with \key{Esc} addressed \texttt{0000h}. Key address map can
|
|
be seen below.
|
|
|
|
\begin{figure}[H]
|
|
\resizebox{\linewidth}{!}{
|
|
\begin{tikzpicture}[
|
|
x=.75cm, y=-.65cm,
|
|
key/.append style={
|
|
text width=.7cm,
|
|
minimum height=6mm,
|
|
inner sep=0,
|
|
align=center,
|
|
font=\scriptsize\tt,
|
|
anchor=north west
|
|
}
|
|
]
|
|
\input{color-keyboard.tex}
|
|
\end{tikzpicture}
|
|
}
|
|
\end{figure}
|
|
|
|
\subsubsection{Payload} \label{cmd:color:payload}
|
|
Payload of this command consist of consecutive RGB values, 1-byte per channel, we could describe this struct like that:
|
|
\begin{verbatim}
|
|
typedef struct {
|
|
struct {
|
|
uint8_t r;
|
|
uint8_t g;
|
|
uint8_t b;
|
|
} color[SK_MAX_PAYLOAD / 3];
|
|
} skillerctl_payload_color_t;
|
|
\end{verbatim}
|
|
|
|
\subsubsection{Examples}
|
|
\begin{figure}[h]
|
|
\begin{verbatim}
|
|
0000 04 13 01 11 03 00 00 01 ff 00 00 00 00 00 00 00
|
|
0010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
\end{verbatim}
|
|
\caption{setting color of \key{Esc} to red (\texttt{ff0000h})}
|
|
\end{figure}
|
|
\begin{figure}[h]
|
|
\begin{verbatim}
|
|
0000 04 13 01 11 09 00 00 01 ff ff ff ff ff ff ff ff
|
|
0010 ff 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
|
\end{verbatim}
|
|
\caption{setting color of \key{Esc}, \key{F1}, \key{F2} to white (\texttt{ffffffh})}
|
|
\end{figure}
|
|
|
|
\end{document}
|