appendix-keyboard.tex

\chapter{The MEGA65 Keyboard}

The MEGA65 has a full mechanical keyboard which is compatible with the C65 and
C64 keyboards, and features four distinct cursor keys which work in both C64 and
C65-mode, as well as eleven new C65 keys that normally work only in C65-mode.

\section{Hardware Accelerated Keyboard Scanning}

To make use of the new extended keyboard easier, the MEGA65 features a hardware
accelerated keyboard scan circuit, that provides ASCII/Unicode (not PETSCII!) codes for
keys and key-combinations.  This makes it very simple to use the full capabilities
of the MEGA65's keyboard, including the entry of ASCII symbols such as \{, \_ and |,
which are not possible to type on a normal C64 and C128 keyboards.

The hardware accelerated keyboard scanner has a buffer of 3 keys, which helps to
make it easier to read from the keyboard without having check it too regularly.
Further, the hardware acclerated keyboard scanner supports most Latin-1 code-page
characters, allowing the entry of many accented characters.  These keys are
entered by holding down \megasymbolkey and pressing other keys or key-combinations.
The use of ASCII or Unicode basic-latin symbols not present in the PETSCII character set
requires the use of a font that contains these symbols, and software which supports them.

The hardware accelerated keyboard scanner is very simple to use: First, make sure
that you have the MEGA65 I/O context activated, then read memory location \$D610
(decimal 54800). If the register contains zero, no key has been pressed.  Otherwise the
value will be the ASCII code of the most recent key or key-combination that has
been pressed.  Reading \$D610 again will continue to read the same value until
you {\bf POKE} any value into \$D610. This clears the key from the input buffer.

The hardware accelerated keyboard scanner also provides a register that
indicates which of the modifier keys are currently being held down.  This is
accessed via the read-only register \$D611 (decimal 54801):

\begin{adjustwidth}{}{-2cm}
\begin{multicols}{2}
\begin{description}[align=left,labelwidth=0.2cm]
\item[Bit 0] Right \specialkey{SHIFT}
\item[Bit 1] Left \specialkey{SHIFT}
\item[Bit 2] \specialkey{CTRL}
\item[Bit 3] \megasymbolkey
\item[Bit 4] \specialkey{ALT}
\item[Bit 5] \specialkey{NO\\SCROLL}
\item[Bit 6] \specialkey{CAPS\\LOCK}
\item[Bit 7] Reserved
\end{description}
\end{multicols}
\end{adjustwidth}

Note that the hardware accelerated keyboard scanner operates independently of the
C64 or C65 KERNAL keyboard scanning routines.  That is, the KERNAL will still have
any keys that you have entered buffered in the normal way. For assembly language
programs the easiest solution to this is to disable interrupts via the SEI
instruction.  This prevents the KERNAL keyboard scanner from running.

\subsection{Key Combination Tables}

The following tables show the hex value and unicode character that will be produced
by each key combination. One table is provided for pressing a key on its own, and
one table for each of the \specialkey{SHIFT}, \specialkey{CTRL}, \megasymbolkey, and
\specialkey{ALT} keys.

\begin{minipage}{\textwidth}
\bf{Keys pressed alone:}
\include{keymap_table_1}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{SHIFT}}
\include{keymap_table_2}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{CTRL}}
\include{keymap_table_3}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \megasymbolkey}
\include{keymap_table_4}
\end{minipage}

\begin{minipage}{\textwidth}
\bf{Keys pressed with \specialkey{ALT}}
\include{keymap_table_5}
\end{minipage}

\subsection{Unicode Basic-Latin Keyboard Map}

The following tables are a convenient reference to help you find a key combination
that will produce the desired ASCII/Unicode basic-latin character code.  Note that
a very few codes are difficult to type in practice, because they are mapped to
key combinations that perform other functions, in particular the combination of
\megasymbol + \specialkey{TAB} is normally overridden by the Matrix Mode hardware
debug feature.

\include{unicode_mapping}


\section{Keyboard Theory of Operation}

The MEGA65 keyboard is a full mechanical keyboard, constructed as a matrix. Every
key switch is fitted with a diode, which allows the keyboard hardware to detect
when any combination of keys are pressed at the same time.  This matrix is scanned
by the firmware in the CPLD chip on the keyboard PCB many thousands of times per
second.  The matrix arrangement of the MEGA65 keyboard does not use the C65
matrix layout.

Instead, the CPLD also sorts the natural matrix of the keyboard
into the C65 keyboard matrix order, and transmits this serially via the keyboard
cable to the MEGA65 mainboard.  The MEGA65 core reads this serial data and uses it
to reconstruct a C65-compatible virtual keyboard in the FPGA.  This virtual keyboard
also takes input from the on-screen-keyboard, synthetic keyboard injection mechanism
and/or other keyboard input sources depending on the MEGA65 model.

The end-to-end latency of the keyboard is less than one milli-second.

\section{C65 Keyboard Matrix}

The MEGA65 keyboard presents to legacy software as a C65-compatible keyboard.
In this mode all keys are available for standard PETSCII scanning as per normal.
There is also a hardware accelerated mechanism for detecting arbitrary combinations
of keys that are held down. This is via \$D614 (decimal 54804).  Writing a value
between 0 and 8 to this register selects the corresponding row of the C65 keyboard
matrix, which can then be read back from \$D613.
If a bit is zero, then it means that the key is being pressed. If the bit is one, then
the key is not being pressed.

The left and up cursor keys are special, because they logically press cursor right or down, and the right shift key.
To be able to differentiate between these two situations, you can read \$D60F: Bit 0 is the state of the left cursor
key and bit 1 is the state of the up cursor key.

The C65 keyboard matrix layout is as follows:

\index{Keyboard!matrix}
{\ttfamily
{
\setlength{\def\arraystretch{1.5}\tabcolsep}{1mm}
\begin{center}
\begin{tabular}{|c*{9}{|C{1.02cm}}|}
\hline
& \bf{0} & \bf{1} & \bf{2} & \bf{3} & \bf{4} & \bf{5} & \bf{6} & \bf{7} & \bf{8} \\
\hline
\small  \bf{0} & \specialkey{INST\\DEL} & 3 & 5 & 7 & 9 & + & \pounds & 1 & \specialkey{NO\\SCROLL} \\
\hline
\small  \bf{1} & \specialkey{RETURN} & W & R & Y & I & P  & * & $\leftarrow$ & \specialkey{TAB} \\
\hline
\small  \bf{2} & \megakey{$\rightarrow$} & A & D & G & J & L & ; & \specialkey{CTRL} & \specialkey{ALT}  \\
\hline
\small  \bf{3} & \megakey{F7} & 4 & 6 & 8 & 0 & - & \specialkey{CLR\\HOME} & 2 & \specialkey{HELP} \\
\hline
\small  \bf{4} & \megakey{F1} & Z & C & B & M & . & \specialkey{SHIFT\\right} & \megakey{SPC} & \megakey{F9} \\
\hline
\small  \bf{5} & \megakey{F3} & S & F & H & K & : & = & \megasymbolkey & \megakey{F11} \\
\hline
\small  \bf{6} & \megakey{F5} & E & T & U & O & @ & \megakey{$\uparrow$} & Q & \megakey{F13} \\
\hline
\small  \bf{7} & \megakey{$\downarrow$} & \specialkey{SHIFT\\left} & X & V & N & , & / & \specialkey{RUN STOP} & \specialkey{ESC} \\
\hline
\end{tabular}
\end{center}
}}

Note that the keyboard matrix is identical to the C64 keyboard matrix, except for the addition of one extra column
on the right-hand side.  The cursor left and up keys on the MEGA65 and C65 are implemented as cursor right and down, but
with the right shift key applied.  This enables them to work in C64-mode.  \specialkey{CAPS\\LOCK} is not
part of the matrix, but has its own dedicated line.  Its status can be read from bit 6 of register \$D611 (decimal 54801):

The numbers across the top indicate the columns of the matrix, and the numbers down the left indicate the rows.
The unique scan code of a key is calculated by multiplying the column by eight, and adding the row.  For example,
\specialkey{CLR\\HOME} is in column 6 and row 3. Thus its scan code is $6 \times 8 + 3 = 51$.

\section{Synthetic Key Events}

The MEGA65 keyboard interface logic allows the use of a variety of keyboard types and alternatives. This is partly
to cater for the early development on general purpose FPGA boards, the MEGAphone with its touch interface, and the
desktop versions of the MEGA65 architecture.  The depressing of up to 3 three keys can be simulated via
the registers \$D615 -- \$D617 (decimal 54,805 -- 54,807).  By setting the
lower 7 bits of these registers to any C65 keyboard scan code, the MEGA65 will behave as though that key is being
held down. \widekey{RESTORE} exists outside of the keyboard matrix, as on the C64.  To simulate
holding \widekey{RESTORE} down, write \$52 (ASCII code for a capital R), and to simulate a quick tap
of the \widekey{RESTORE}, write \$72 (ASCII code for a lowercase R).  Another value must be written after the
\$72 value has been written, if you wish to simulate multiple presses of \widekey{RESTORE}.

To release a key, write \$7F (decimal 127) to the register containing the active key press. For example,
to simulate briefly pressing the * key, the following could be used:

\begin{tcolorbox}[colback=black,coltext=white]
\verbatimfont{\codefont}
\begin{verbatim}
POKE DEC("D615"),6*8+1:FORI=1TO100:NEXT:POKE DEC("D615"),127
\end{verbatim}
\end{tcolorbox}

The FOR loop provides a suitable delay to simulate holding the key for a short time.  All statements should be on a single line
like this, if entered directly into the BASIC interpreter, because otherwise the MEGA65 will continue to act as though the * key
is being held down, making it rather difficult to enter the other commands!

\section{Keyboard LED Control}

The LEDs on the MEGA65's keyboard are normally controlled automatically by the
system.  However, it is also possible to place them under user control.  This
is activated by setting bit 7 (decimal 128) of \$D61D (decimal 54813).  The
lower bits indicate which keyboard LED to set.  Values 0 through 11 correspond
to the red, green and blue channels of the four LEDs. The table below shows the
specific values:

\begin{adjustwidth}{}{-2cm}
\begin{description}[align=left,labelwidth=0.2cm]
\item[ 0] left-half of DRIVE LED, RED
\item[ 1] left-half of DRIVE LED, GREEN
\item[ 2] left-half of DRIVE LED, BLUE
\item[ 3] right-half of DRIVE LED, RED
\item[ 4] right-half of DRIVE LED, GREEN
\item[ 5] right-half of DRIVE LED, BLUE
\item[ 6] left-half of POWER LED, RED
\item[ 7] left-half of POWER LED, GREEN
\item[ 8] left-half of POWER LED, BLUE
\item[ 9] right-half of POWER LED, RED
\item[10] right-half of POWER LED, GREEN
\item[11] right-half of POWER LED, BLUE
\end{description}
\end{adjustwidth}

Register \$D61E (decimal 54814) is used to specify the intensity that should be
given to a specific LED (value between 0 and 255).

Note that whatever value is in \$D61E gets written to whatever register is
currently selected in \$D61D.  Therefore to safely change the intensity of one
specific LED ensure \$D61D is set to 255 first. This prevents affecting another
LED when we set the intended intensity value into \$D61E. Now select the target
LED by setting \$D61D to 128 + x, where x is a value from the table above.
Hold the \$D61D, \$D61E configuration for approximately one millisecond to give
the keyboard logic enough time to pick up the new intensity value for the
selected LED.

To return the keyboard LEDs to hardware control, clear bit 7 of \$D61D.

For example to pulse the keyboard LEDs red and blue, the following program
could be used:

\begin{tcolorbox}[colback=black,coltext=white]
\input{examples/ledcycle}
\end{tcolorbox}

\section{Native Keyboard Matrix}

The native keyboard matrix is accessible only from the CPLD on the MEGA65's keyboard.
If you are programming the MEGA65 computer, you should not need to use this.

\begin{adjustwidth}{}{-2cm}
\begin{multicols}{2}
\begin{description}[align=left,labelwidth=0.2cm]
    \item [0] \specialkey{F5}
    \item [1] 9
    \item [2] I
    \item [3] K
    \item [4] <
    \item [5] \specialkey{INST\\DEL}
    \item [6] \specialkey{CLR\\HOME}
    \item [7] O
    \item [8] \megakey{F3}
    \item [9] 8
    \item [10] U
    \item [11] J
    \item [12] M
    \item [13] \megakey{$\rightarrow$}
    \item [14] \pounds
    \item [15] =
    \item [16] \megakey{F1}
    \item [17] 7
    \item [18] Y
    \item [19] H
    \item [20] N
    \item [21] \megakey{$\downarrow$}
    \item [22] -
    \item [23] ;
    \item [24] Reserved
    \item [25] 6
    \item [26] T
    \item [27] G
    \item [28] B
    \item [29] \megakey{$\leftarrow$} (cursor left)
    \item [30] +
    \item [31] :
    \item [32] \specialkey{NO\\SCROLL}
    \item [33] 5
    \item [34] R
    \item [35] F
    \item [36] V
    \item [37] \megakey{SPACE}
    \item [38] 0
    \item [39] L
    \item [40] \specialkey{CAPS\\LOCK}
    \item [41] 4
    \item [42] E
    \item [43] D
    \item [44] C
    \item [45] Reserved
    \item [46] \specialkey{HELP}
    \item [47] \specialkey{RETURN}
    \item [48] \specialkey{ALT}
    \item [49] 3
    \item [50] W
    \item [51] S
    \item [52] X
    \item [53] \megakey{$\uparrow$} (cursor up)
    \item [54] \megakey{F13}
    \item [55] \megakeywhite{$\uparrow$} (next to \widekey{RESTORE})
    \item [56] \specialkey{ESC}
    \item [57] 2
    \item [58] Q
    \item [59] A
    \item [60] Z
    \item [61] right \specialkey{SHIFT}
    \item [62] \megakey{F11}
    \item [63] *
    \item [64] Reserved
    \item [65] 1
    \item [66] Reserved
    \item [67] Reserved
    \item [68] left \specialkey{SHIFT} and \specialkey{SHIFT\\LOCK}
    \item [69] /
    \item [70] \megakey{F9}
    \item [71] @
    \item [72] \specialkey{RUN STOP}
    \item [73] \megakeywhite{$\leftarrow$} (next to 1)
    \item [74] \specialkey{TAB}
    \item [75] \specialkey{CTRL}
    \item [76] \megasymbolkey
    \item [77] >
    \item [78] \megakey{F7}
    \item [79] P
\end{description}
\end{multicols}
\end{adjustwidth}