# Tutorial: 03 - International Keyboards

## 03 - International Keyboards

It is possible to use Scriptel ScripTouch EasyScript devices in a setting where international keyboards are in use. Normally EasyScript devices will emit key codes consistent with the US English keyboard layout which can be a problem if that's not the current system keyboard layout. The EasyScript library does its best to deal with these environments, but depending on your application and configuration there may be some special considerations required to support these types of configurations in your application.

#Background USB Keyboards conform to the human interface specification protocol for keyboards. This specification details how keyboards are to interact with the connected host system. When a key is pressed the index of that key is sent over USB to the host system. That scan code is received by the host system and is translated by the operating system into whichever key corresponds to that key index in the currently configured keyboard.

An issue arises when two keyboards are attached with different layouts. Most operating systems only allow one keyboard layout to be in use at a time. Typing on the keyboard whose layout is not currently configured will cause incorrect characters to be generated. This issue can cause our ScripTouch keyboard devices to emit characters not covered in our specification document. The ScripTouch devices are configured to send keys as if they were in the "English (United States)" keyboard layout.

A standard 104 key keyboard generally looks something like this:

In this diagram you can see every key has a (somewhat) language/layout neutral identifier and a USB HID assigned identifier code. The highlighted keys represent keys that are used in the STN Signature protocol and are keys that will need to be re-mapped if entered in a different layout.

For example if we have a computer with an operating system configured to take keyboard input in the "French (Canada)" layout. The keyboard would be laid out something like this:

In order to correct input for this layout the keys must be remapped to the "English (United States)" layout:

This isn't a simple task, the older versions of our library required a separate conversion table for each different layout that was supported and it required the calling application to let the library know ahead of time which layout was currently in use.

#Solution Approach Used by the Library Browser support for retrieving key identifiers as opposed to character information is rather spotty at the moment. The W3C specifies that browsers should support passing along a "code" attribute with key down and key up events that indicate which actual keyboard key is being pressed regardless of keyboard. In this case it's trivial for the library to figure out which key should have been pressed in the "English (United States)" layout. At the time of this article being written Mozilla Firefox is the only browser to support this attribute. If this attribute is supported all signature and card swipe data will be correctly received, translated and parsed with no work needing to be done on the part of the application writer.

In other browsers (Internet Explorer / Chrome) we're left with the legacy keyCode / which attributes. These are in theory somewhat keyboard layout agnostic but in practice they aren't. We went through and mapped all of the different variations in a large number of different keyboard layouts and came up with a list of different translation tables that allow different keyboards to be translated back to "English (United States)". The problem here is obviously that we don't know at runtime which translation table needs to be used to correct the input.

To this end we added a "beacon" to the end of the signature protocol identifier for protocols C (Uncompressed, Streaming), D (Compressed, Streaming), and E (Compressed, Non-Streaming) that stimulates often-different keys in a known place and order. If this beacon is present the library will attempt to automatically determine at runtime which correction table to use. If the beacon is present any signature produced should automatically be detected and corrected.

For protocols A (Uncompressed, Non-streaming, Legacy) and B (Uncompressed, Non-Streaming) the beacon will not be present due to legacy compatibility concerns. For these protocols it will still be necessary to predetermine which layout is in use prior to signing or card swiping.

#Handling Signatures with Legacy Protocol A / B Firmware Since protocols A and B don't provide the beacon it isn't possible to automatically identify and correct layouts. This means your application must provide the layout that input is expected from.

To do this:

    var easyScript = new ScriptelEasyScript();
    easyScript.fromKeyboardSpec = "<Layout Name (see below)>";

After setting the fromKeyboardSpec do everything else as normal. The library should take care of the translation for you. This layout can be changed at any time but will only take effect when a new signature stream is started (it won't change mid-signature). We do provide a mechanism to allow you to change the layout immediately proceeding a signature by providing a configuration callback. This can be used by doing the following:

    var easyScript = new ScriptelEasyScript();
    easyScript.configurationCallback = function(evt, chr) {
        if (chr === '"') {
            easyScript.fromKeyboardSpec = "ca-fr";
        } else {
            easyScript.fromKeyboardSpec = "us-basic";
        }
    };

In this example since we're only looking to support US keyboards and Canadian French keyboards we can use the first character to switch between layouts. Depending on your requirements you may need to fine tune this. If you need something more robust your best option is to change protocols to one that supports beacons.

We currently support (at least) the following keyboard layouts:

- Albanian
- Arabic (101)
- Arabic (102)
- Arabic (102) AZERTY
- Armenian Eastern (Legacy)
- Armenian Phonetic
- Armenian Typewriter
- Armenian Western (Legacy)
- Assamese (India) Assamese - INSCRIPT
- Azeri Cyrillic
- Azeri Latin
- Bangla (India) - Bengali - INSCRIPT
- Bangla (India) - Bengali - INSCRIPT (Legacy)
- Bashkir
- Belarusian
- Belgian (Comma)
- Belgian (Period)
- Belgian French
- Bengali
- Bosnian (Cyrillic)
- Bulgarian
- Bulgarian (Latin)
- Bulgarian (Phonetic Traditional)
- Bulgarian (Phonetic)
- Bulgarian (Typewriter)
- Canadian French
- Canadian French (Legacy)
- Candian Multilingual Standard
- Central Atlas Tamazight
- Central Kurdish
- Chinese Microsoft Bopomofo
- Chinese Microsoft ChangJie
- Chinese Microsoft Quick
- Croatian
- Czech
- Czech (QWERTY)
- Czech Programmers
- Danish
- Divehi Phonetic
- Divehi Typewriter
- Dutch
- English (India)
- English (UK)
- English (US)
- Estonian
- Faeroese
- Finnish
- Finnish with Sami
- French
- French (Canada)
- Georgian (Ergonomic)
- Georgian (Legacy)
- Georgian (MES)
- Georgian (Old Alphabets)
- Georgian (QWERTY)
- German
- German (IBM)
- Greek
- Greek (220)
- Greek (220) Latin
- Greek (319)
- Greek (319) Latin
- Greek Latin
- Greek Polytonic
- Greenlandic
- Guarani
- Gujarati
- Hausa
- Hawaiian
- Hebrew
- Hebrew (Standard)
- Hindi (India) - Devanagari - INSCRIPT
- Hindi Traditional
- Hungarian
- Hungarian 101-key
- Icelandic
- Igbo
- Inuktitut - Latin
- Inuktitut - Naqittuat
- Irish
- Italian
- Italian (142)
- Japanese
- Kannada
- Kazakh
- Korean
- Kyrgyz Cyrillic
- Lao
- Latin American
- Latvian
- Latvian (QWERTY)
- Latvian (Standard)
- Lithuanian
- Lithuanian IBM
- Lithuanian Standard
- Luxembourgish
- Macedonian (FYROM)
- Macedonian (FYROM) - Standard
- Malayalam
- Maltese 47-Key
- Maltese 48-Key
- Maori
- Marathi
- Mongolian (Mongolian Script)
- Mongolian Cyrillic
- Multilingual (Canada)
- Nepali
- Norwegian
- Norwegian with Sami
- Odia
- Pashto (Afghanistan)
- Persian
- Persian (Standard)
- Polish (214)
- Polish (Programmers)
- Portuguese
- Portuguese (Brazil ABNT)
- Portuguese (Brazil ABNT2)
- Punjabi
- Romanian (Legacy)
- Romanian (Programmers)
- Romanian (Standard)
- Russian
- Russian (Typewriter)
- Russian - Mnemonic
- Sakha
- Sami Extended Finland-Sweden
- Sami Extended Norway
- Scottish Gaelic
- Serbian (Cyrillic)
- Serbian (Latin)
- Sesotho sa Leboa
- Setswana
- Sinhala
- Sinhala - Wij 9
- Slovak
- Slovak (QWERTY)
- Slovenian
- Sorbian Extended
- Sorbian Standard
- Sorbian Standard (Legacy)
- Spanish
- Spanish (Latin American)
- Spanish Variation
- Swedish
- Swedish with Sami
- Swiss French
- Swiss German
- Syriac
- Syriac Phonetic
- Tajik
- Tamil
- Tatar
- Tatar (Legacy)
- Telugu
- Thai Kedmanee
- Thai Kedmanee (non-ShiftLock)
- Thai Pattachote
- Thai Pattachote (non-ShiftLock)
- Tibetan (PRC)
- Tibetan (PRC) - Updated
- Traditional Mongolian (Standard)
- Turkish F
- Turkish Q
- Turkmen
- US
- US English Table for IBM Arabic 238_L
- Ukrainian
- Ukrainian (Enhanced)
- United Kingdom
- United Kingdom Extended
- United States - Dvorak
- United States-Dvorak for left hand
- United States-Dvorak for right hand
- United States-International
- Urdu
- Uyghur
- Uyghur (Legacy)
- Uzbek Cyrillic
- Vietnamese
- Wolof
- Yoruba