Add support for multiple keyboard layouts

The Keyboard.begin() method now accepts a keyboard layout as an optional
argument, which defaults to KeyboardLayout_en_US. The layout data has
been moved to a separate file.

Right now, en_US is the only available layout, but extra layouts can be
defined by adding the appropriate definition files and declaring them in
Keyboard.h.

Author: edgar-bonet

src/Keyboard.cpp

@@ -20,6 +20,7 @@
 */
 
 #include "Keyboard.h"
+#include "KeyboardLayout.h"
 
 #if defined(_USING_HID)
 
@@ -64,10 +65,12 @@ Keyboard_::Keyboard_(void)
 {
 	static HIDSubDescriptor node(_hidReportDescriptor, sizeof(_hidReportDescriptor));
 	HID().AppendDescriptor(&node);
+	_asciimap = 0;
 }
 
-void Keyboard_::begin(void)
+void Keyboard_::begin(const uint8_t *layout)
 {
+	_asciimap = layout;
 }
 
 void Keyboard_::end(void)
@@ -79,144 +82,6 @@ void Keyboard_::sendReport(KeyReport* keys)
 	HID().SendReport(2,keys,sizeof(KeyReport));
 }
 
-extern
-const uint8_t _asciimap[128] PROGMEM;
-
-#define SHIFT 0x80
-const uint8_t _asciimap[128] =
-{
-	0x00,             // NUL
-	0x00,             // SOH
-	0x00,             // STX
-	0x00,             // ETX
-	0x00,             // EOT
-	0x00,             // ENQ
-	0x00,             // ACK
-	0x00,             // BEL
-	0x2a,          // BS  Backspace
-	0x2b,          // TAB Tab
-	0x28,          // LF  Enter
-	0x00,             // VT
-	0x00,             // FF
-	0x00,             // CR
-	0x00,             // SO
-	0x00,             // SI
-	0x00,             // DEL
-	0x00,             // DC1
-	0x00,             // DC2
-	0x00,             // DC3
-	0x00,             // DC4
-	0x00,             // NAK
-	0x00,             // SYN
-	0x00,             // ETB
-	0x00,             // CAN
-	0x00,             // EM
-	0x00,             // SUB
-	0x00,             // ESC
-	0x00,             // FS
-	0x00,             // GS
-	0x00,             // RS
-	0x00,             // US
-
-	0x2c,          // ' '
-	0x1e|SHIFT,    // !
-	0x34|SHIFT,    // "
-	0x20|SHIFT,    // #
-	0x21|SHIFT,    // $
-	0x22|SHIFT,    // %
-	0x24|SHIFT,    // &
-	0x34,          // '
-	0x26|SHIFT,    // (
-	0x27|SHIFT,    // )
-	0x25|SHIFT,    // *
-	0x2e|SHIFT,    // +
-	0x36,          // ,
-	0x2d,          // -
-	0x37,          // .
-	0x38,          // /
-	0x27,          // 0
-	0x1e,          // 1
-	0x1f,          // 2
-	0x20,          // 3
-	0x21,          // 4
-	0x22,          // 5
-	0x23,          // 6
-	0x24,          // 7
-	0x25,          // 8
-	0x26,          // 9
-	0x33|SHIFT,    // :
-	0x33,          // ;
-	0x36|SHIFT,    // <
-	0x2e,          // =
-	0x37|SHIFT,    // >
-	0x38|SHIFT,    // ?
-	0x1f|SHIFT,    // @
-	0x04|SHIFT,    // A
-	0x05|SHIFT,    // B
-	0x06|SHIFT,    // C
-	0x07|SHIFT,    // D
-	0x08|SHIFT,    // E
-	0x09|SHIFT,    // F
-	0x0a|SHIFT,    // G
-	0x0b|SHIFT,    // H
-	0x0c|SHIFT,    // I
-	0x0d|SHIFT,    // J
-	0x0e|SHIFT,    // K
-	0x0f|SHIFT,    // L
-	0x10|SHIFT,    // M
-	0x11|SHIFT,    // N
-	0x12|SHIFT,    // O
-	0x13|SHIFT,    // P
-	0x14|SHIFT,    // Q
-	0x15|SHIFT,    // R
-	0x16|SHIFT,    // S
-	0x17|SHIFT,    // T
-	0x18|SHIFT,    // U
-	0x19|SHIFT,    // V
-	0x1a|SHIFT,    // W
-	0x1b|SHIFT,    // X
-	0x1c|SHIFT,    // Y
-	0x1d|SHIFT,    // Z
-	0x2f,          // [
-	0x31,          // bslash
-	0x30,          // ]
-	0x23|SHIFT,    // ^
-	0x2d|SHIFT,    // _
-	0x35,          // `
-	0x04,          // a
-	0x05,          // b
-	0x06,          // c
-	0x07,          // d
-	0x08,          // e
-	0x09,          // f
-	0x0a,          // g
-	0x0b,          // h
-	0x0c,          // i
-	0x0d,          // j
-	0x0e,          // k
-	0x0f,          // l
-	0x10,          // m
-	0x11,          // n
-	0x12,          // o
-	0x13,          // p
-	0x14,          // q
-	0x15,          // r
-	0x16,          // s
-	0x17,          // t
-	0x18,          // u
-	0x19,          // v
-	0x1a,          // w
-	0x1b,          // x
-	0x1c,          // y
-	0x1d,          // z
-	0x2f|SHIFT,    // {
-	0x31|SHIFT,    // |
-	0x30|SHIFT,    // }
-	0x35|SHIFT,    // ~
-	0x00              // DEL
-};
-
-
 uint8_t USBPutChar(uint8_t c);
 
 // press() adds the specified key (printing, non-printing, or modifier)
@@ -225,6 +90,10 @@ uint8_t USBPutChar(uint8_t c);
 // call release(), releaseAll(), or otherwise clear the report and resend.
 size_t Keyboard_::press(uint8_t k)
 {
+	// Do not be too harsh on users who forget to begin().
+	if (!_asciimap) {
+		begin();
+	}
 	uint8_t i;
 	if (k >= 136) {			// it's a non-printing key (not a modifier)
 		k = k - 136;
@@ -237,10 +106,16 @@ size_t Keyboard_::press(uint8_t k)
 			setWriteError();
 			return 0;
 		}
-		if (k & 0x80) {						// it's a capital letter or other character reached with shift
+		if ((k & ALT_GR) == ALT_GR) {
+			_keyReport.modifiers |= 0x40;   // AltGr = right Alt
+			k &= 0x3F;
+		} else if ((k & SHIFT) == SHIFT) {
 			_keyReport.modifiers |= 0x02;	// the left shift modifier
 			k &= 0x7F;
 		}
+		if (k == ISO_REPLACEMENT) {
+			k = ISO_KEY;
+		}
 	}
 
 	// Add k to the key report only if it's not already present
@@ -280,10 +155,16 @@ size_t Keyboard_::release(uint8_t k)
 		if (!k) {
 			return 0;
 		}
-		if (k & 0x80) {							// it's a capital letter or other character reached with shift
+		if ((k & ALT_GR) == ALT_GR) {
+			_keyReport.modifiers &= ~(0x40);   // AltGr = right Alt
+			k &= 0x3F;
+		} else if ((k & SHIFT) == SHIFT) {
 			_keyReport.modifiers &= ~(0x02);	// the left shift modifier
 			k &= 0x7F;
 		}
+		if (k == ISO_REPLACEMENT) {
+			k = ISO_KEY;
+		}
 	}
 
 	// Test the key report to see if k is present.  Clear it if it exists.

src/Keyboard.h

@@ -83,6 +83,8 @@
 #define KEY_F23           0xFA
 #define KEY_F24           0xFB
 
+// Supported keyboard layouts
+extern const uint8_t KeyboardLayout_en_US[];
 
 // Low level key report: up to 6 keys and shift, ctrl etc at once
 typedef struct
@@ -96,10 +98,11 @@ class Keyboard_ : public Print
 {
 private:
   KeyReport _keyReport;
+  const uint8_t *_asciimap;
   void sendReport(KeyReport* keys);
 public:
   Keyboard_(void);
-  void begin(void);
+  void begin(const uint8_t *layout = KeyboardLayout_en_US);
   void end(void);
   size_t write(uint8_t k);
   size_t write(const uint8_t *buffer, size_t size);

src/KeyboardLayout.h

@@ -0,0 +1,65 @@
+/*
+  KeyboardLayout.h
+
+  This file is not part of the public API. It is meant to be included
+  only in Keyboard.cpp and the keyboard layout files. Layout files map
+  ASCII character codes to keyboard scan codes (technically, to USB HID
+  Usage codes), possibly altered by the SHIFT or ALT_GR modifiers.
+
+  == Creating your own layout ==
+
+  In order to create your own layout file, copy an existing layout that
+  is similar to yours, then modify it to use the correct keys. The
+  layout is an array in ASCII order. Each entry contains a scan code,
+  possibly modified by "|SHIFT" or "|ALT_GR", as in this excerpt from
+  the Italian layout:
+
+      0x35,          // bslash
+      0x30|ALT_GR,   // ]
+      0x2e|SHIFT,    // ^
+
+  Do not change the control characters (those before scan code 0x2c,
+  corresponding to space). Do not attempt to grow the table past DEL. Do
+  not use both SHIFT and ALT_GR on the same character: this is not
+  supported. Unsupported characters should have 0x00 as scan code.
+
+  For a keyboard with an ISO physical layout, use the scan codes below:
+
+      +---+---+---+---+---+---+---+---+---+---+---+---+---+-------+
+      |35 |1e |1f |20 |21 |22 |23 |24 |25 |26 |27 |2d |2e |BackSp |
+      +---+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-----+
+      | Tab |14 |1a |08 |15 |17 |1c |18 |0c |12 |13 |2f |30 | Ret |
+      +-----++--++--++--++--++--++--++--++--++--++--++--++--++    |
+      |CapsL |04 |16 |07 |09 |0a |0b |0d |0e |0f |33 |34 |31 |    |
+      +----+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+---+----+
+      |Shi.|32 |1d |1b |06 |19 |05 |11 |10 |36 |37 |38 |  Shift   |
+      +----+---++--+-+-+---+---+---+---+---+--++---+---++----+----+
+      |Ctrl|Win |Alt |                        |AlGr|Win |Menu|Ctrl|
+      +----+----+----+------------------------+----+----+----+----+
+
+  The ANSI layout is identical except that key 0x31 is above (rather
+  than next to) Return, and there is not key 0x32.
+
+  Give a unique name to the layout array, then declare it in Keyboard.h
+  with a line of the form:
+
+    extern const uint8_t KeyboardLayout_xx_YY[];
+
+  == Encoding details ==
+
+  All scan codes are less than 0x80, which makes bit 7 available to
+  signal that a modifier (Shift or AltGr) is needed to generate the
+  character. With only one exception, keys that are used with modifiers
+  have scan codes that are less than 0x40. This makes bit 6 available
+  to signal whether the modifier is Shift or AltGr. The exception is
+  0x64, the key next next to Left Shift on the ISO layout (and absent
+  from the ANSI layout). We handle it by replacing its value by 0x32 in
+  the layout arrays.
+*/
+
+#include <Arduino.h>
+
+#define SHIFT 0x80
+#define ALT_GR 0xc0
+#define ISO_KEY 0x64
+#define ISO_REPLACEMENT 0x32