{% extends "sega.html" %}
{% block title %}Touchscreen{% endblock %}
{% block body %}
<h1>The MaiMai Touchscreen</h1>

<p>The touchscreen for MaiMai, pre-DX, is powered by a {{part("838-15221")|safe}} board, connected to <code>COM3</code>.
</p>
<p>Unlike other IO boards, this board communicates using a custom, text-based, protocol.</p>

<h2 id="serial">Serial configuartion</h2>
<table>
    <tr>
        <td>Port</td>
        <td>COM3</td>
    </tr>
    <tr>
        <td>Baud rate</td>
        <td>9600</td>
    </tr>
    <tr>
        <td>Bits per byte</td>
        <td>8</td>
    </tr>
    <tr>
        <td>Stop bits</td>
        <td>0</td>
    </tr>
    <tr>
        <td>Parity bits</td>
        <td>0</td>
    </tr>
</table>

<h2 id="packet">Packet format</h2>
<p>As previously mentioned, all packets are text. This means, for the most part, values will stay within a normal
    printable range. More importantly, null bytes are not permitted as they will be interpted as the end of the string.
</p>
<p>Packets sent from the game to the board are surrounded in braces, <code>{like this}</code>. Packets sent from the
    board to the game are surrounded in parentheses, <code>(like this)</code>.</p>

<h3 id="halt"><code>{HALT}</code></h3>
<table class="code">
    <tr>
        <td><code>{</code></td>
        <td><code>H</code></td>
        <td><code>A</code></td>
        <td><code>L</code></td>
        <td><code>T</code></td>
        <td><code>}</code></td>
    </tr>
</table>
<p>This instructs the board to stop sending the state of the touchscreen. No response is expected.</p>
<h3 id="stat"><code>{STAT}</code></h3>
<table class="code">
    <tr>
        <td><code>{</code></td>
        <td><code>S</code></td>
        <td><code>T</code></td>
        <td><code>A</code></td>
        <td><code>T</code></td>
        <td><code>}</code></td>
    </tr>
</table>
<p>This instructs the board to begin sending the state of the touchscreen (detailed below). No response is expected.</p>
<h3 id="xxth"><code>{??th}</code></h3>
<table class="code">
    <tr>
        <td><code>{</code></td>
        <td><code>L</code>/<code>R</code></td>
        <td>sensor</td>
        <td><code>t</code></td>
        <td><code>h</code></td>
        <td><code>}</code></td>
    </tr>
</table>
<p>This requests the configured threshold value for a specific sensor from the board. The expected response is as
    follows:</p>
<table class="code">
    <tr>
        <td><code>(</code></td>
        <td><code>L</code>/<code>R</code></td>
        <td>sensor</td>
        <td> </td>
        <td>threshold value</td>
        <td><code>)</code></td>
    </tr>
</table>
<h3 id="xxth"><code>{??k?}</code></h3>
<table class="code">
    <tr>
        <td><code>{</code></td>
        <td><code>L</code>/<code>R</code></td>
        <td>sensor</td>
        <td><code>k</code></td>
        <td>threshold</td>
        <td><code>}</code></td>
    </tr>
</table>
<p>This configures the threshold value for a specific sensor. The expected response is as follows:</p>
<table class="code">
    <tr>
        <td><code>(</code></td>
        <td><code>L</code>/<code>R</code></td>
        <td>sensor</td>
        <td> </td>
        <td> </td>
        <td><code>)</code></td>
    </tr>
</table>

<h2 id="push">Active mode</h2>
<p>After a <code>{STAT}</code> packet is received, the board enters a mode where it begins constantly transmitting the
    state of the touchscreen. The data sent is in the following format:</p>

<table class="code">
    <tr>
        <td><code>(</code></td>
    </tr>
    <tr>
        <td>P1: A1,B1,A2,B2,x</td>
        <td>P1: A3,B3,A4,B4,x</td>
        <td>P1: A5,B5,A6,B6,x</td>
        <td>P1: A7,B7,A8,B8,C</td>
    </tr>
    <tr>
        <td>padding</td>
        <td>padding</td>
    </tr>
    <tr>
        <td>P2: A1,B1,A2,B2,x</td>
        <td>P2: A3,B3,A4,B4,x</td>
        <td>P2: A5,B5,A6,B6,x</td>
        <td>P2: A7,B7,A8,B8,C</td>
    </tr>
    <tr>
        <td>padding</td>
        <td>padding</td>
    </tr>
    <tr>
        <td><code>)</code></td>
    </tr>
</table>

<p>Each data byte is a bit mask of the 5 values it contains, mapped to <code>1<sub>h</sub></code>,
    <code>2<sub>h</sub></code>, <code>4<sub>h</sub></code>, <code>8<sub>h</sub></code>, and <code>10<sub>h</sub></code>
    respectively. While sending <code>1f<sub>h</sub></code> would be a valid byte, it is recommended to make use of the
    upper bits to keep the value within a printable range. I personally recommend masking with
    <code>40<sub>h</sub></code> (<code>'@'</code>) for this purpose. Values will then range from <code>@</code> to
    <code>_</code>. Bits indicated with <code>x</code> are unused. It is recommended, but not required, to leave them
    unset.
</p>
<p>The four bytes marked as padding are unused, with the only requirement being that they are non-null. It is
    recommended, but not required, to set them to <code>40<sub>h</sub></code> (<code>'@'</code>).</p>

<details>
    <summary>Individual bit breakdown</summary>

    <table class="code">
        <thead>
            <tr>
                <td rowspan="2">Byte</td>
                <td rowspan="2">Player</td>
                <td colspan="8">Bit</td>
                <td rowspan="2">ASCII</td>
            </tr>
            <tr>
                <td>7</td>
                <td>6</td>
                <td>5</td>
                <td>4</td>
                <td>3</td>
                <td>2</td>
                <td>1</td>
                <td>0</td>
            </tr>
        </thead>
        <tr>
            <td>0</td>
            <td></td>
            <td>0</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>(</td>
        </tr>
        <tr>
            <td>1</td>
            <td>P1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B2</td>
            <td>A2</td>
            <td>B1</td>
            <td>A1</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>2</td>
            <td>P1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B4</td>
            <td>A4</td>
            <td>B3</td>
            <td>A3</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>3</td>
            <td>P1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B6</td>
            <td>A6</td>
            <td>B5</td>
            <td>A5</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>4</td>
            <td>P1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B8</td>
            <td>A8</td>
            <td>B7</td>
            <td>A7</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>5</td>
            <td></td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>@</td>
        </tr>
        <tr>
            <td>6</td>
            <td></td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>@</td>
        </tr>
        <tr>
            <td>7</td>
            <td>P2</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B2</td>
            <td>A2</td>
            <td>B1</td>
            <td>A1</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>8</td>
            <td>P2</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B4</td>
            <td>A4</td>
            <td>B3</td>
            <td>A3</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>9</td>
            <td>P2</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B6</td>
            <td>A6</td>
            <td>B5</td>
            <td>A5</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>10</td>
            <td>P2</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>B8</td>
            <td>A8</td>
            <td>B7</td>
            <td>A7</td>
            <td><i>varies</i></td>
        </tr>
        <tr>
            <td>11</td>
            <td></td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>@</td>
        </tr>
        <tr>
            <td>12</td>
            <td></td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>0</td>
            <td>@</td>
        </tr>
        <tr>
            <td>13</td>
            <td></td>
            <td>0</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>1</td>
            <td>0</td>
            <td>0</td>
            <td>1</td>
            <td>)</td>
        </tr>
    </table>
</details>

<p>An example may aid here. The following image is what transmitting <code>(FIBT@@@@@@@@)</code> is interpreted as:</p>
<img src="{{ROOT}}/images/maimai_FIBT.png" class="graphic">

{% endblock %}