\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{pgfplots}
\usepackage{bytefield}

\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 len 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\_MODE}    & \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\_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). 
    
    \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}
    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}
