In order for a device to connect to a StayLinked Server, that Server must have an installed keyboard map that exactly matches the device type and emulation type. Keyboard maps are installed on a server using the StayLinked Administrator. These keyboard maps can be configured with a variety of functions, strings and escapes to meet the requirements of your hosted application. This brief guide describes the different device types, keyboard maps and the available options.
Adding New Keyboard Maps
During the connection handshake each device provides several bits of information to the Server; including screen size, client version, device type among other details. In server versions 15.5 and older, devices that need a keyboard map will report an error Esp0003, No VT/5250/3270 keyboard map found for device devicetype.
Default Keyboard Maps
V16 and newer Windows servers will come preconfigured with default keyboard maps. Future releases of the server process will enable this option on new installations for other platforms. The option can be manually enabled under Server Configuration > Server Settings.
Default keyboard maps take effect when the server process does not have an installed keyboard, Default maps are not installed, and there is no option for the to be automatically installed. Any customization or changes from the default map require the Administrator to manually perform the standard historical process for installing a new keyboard map.
What is a Device Type?
The Device Type for your client will be displayed on the splash screen next to the client version. Device Types are a combination of values specific to each client that tell the server some basic information. Device types are made up of: the manufacturer (PTX in this case is Psion Teklogix), the device model (which is a 7535), the operating system (not used in the example, but typically a C/CE or W/WM for Windows CE or Windows Mobile) and lastly the keyboard type reported by the device operating system (58-key in this example). Some devices may report keyboard types like AN or QW for Alpha-Numeric and QWERTY respectively.
Devices reporting keyboard types of 00 or XX are getting an invalid result from the operating system. These may be resolved by simply rebooting the device. Some devices have removable keyboards that might have a poor connection between the keyboard and handheld. While you may be able to copy a keyboard map with this different device type, the keyboard may not operate as expected. Some devices may need to be repaired for normal keyboard use.
Note that device types can be configured with custom values. It is not recommended that device types are changed because they represent the make and model of the device as well as the software that’s been installed. It is often necessary to exclude or separate a test device from the other devices in order to allocate it to a different device group. Client Settings or Scan2Configure features can be used to adjust the device type. A copy of the preferred keyboard map must be made for any new device types.
Esp0003 and Adding New Keyboards from the Connections List
From the Administrator’s Connections list:
When your device displays the Esp0003 error message, you can quickly add the keyboard map by opening the details display in the Administrator’s Connections List. Just double-click on the connection and select the ‘Add Keyboard Map’ option.
Adding Keyboard Maps Manually
The StayLinked Administrator section for keyboard maps shows a list of installed keyboards. You can add new keyboards, create custom keyboards, edit installed keyboards, or copy installed keyboards. Adding a new keyboard is done by right clicking in the window and selecting ‘Add’. Each keyboard appears in the list multiple times, once for each emulation type. Choose the emulation types that matches the eSP0003 error message or your telnet host entry. Note that UTF8 and SSH emulation hosts utilize the VT emulation type for keyboard maps.
Video – Adding a Keyboard Map
Missing or Unknown Device Types and Keyboard Definitions
New device types are constantly being added to the list of known devices. Your StayLinked Administrator can be updated with the latest list of keyboards by installing the ‘Administrator Keyboard Definition Update’ from the StayLinked downloads site. This updates the Administrator with the latest list, allowing you to install the best available keyboard map for your device. Older Administrator versions may need to be updated to a newer version in order to install the latest keyboard definition update.
If you’ve installed the keyboard update and your device type still does not appear in the list of available keyboards, you can simply install a similar model/keyboard combination and then copy it to match the device type reported by your client. Devices within the same manufacturer line commonly generate consistent key codes. Like models and operating systems do not typically require significant alteration for use on similar devices.
Keyboard Map Entries
In the case of 5250 emulation, the default keyboard entries will meet most (if not all) of your requirements. Other emulation types may require various adjustments. Each keyboard entry is based on two values, the Key Code and the Mnemonic.
Key Codes: When a button is pressed on your device, the operating system generates several different event values. Those values are put together into our key code. Some buttons will not generate a key code or will ‘modify’ the code of the next button you press. For example, pressing the number 1 on our device generated a 313100 as seen in the client’s keyboard test (seen to the right). Pressing Shift does not generate a key code but will instead ‘modify’ the next key pressed, making our [shift] [1] generate a key code of 312101. Key codes are transmitted to the server, where they are compared to a table known as a keyboard map. The keyboard maps will match up key codes to mnemonics.
If the key code displayed in the key test does not appear in the list, you can simply right click to add a new entry to your keyboard map.
Mnemonics: Anything entered for the keyboard map mnemonic column will be applied to that given key code (displayed as code in the keyboard map). Mnemonics can be picked from the pulldown menu or simply typed into the dialogue box. When nothing is mapped to the mnemonic, the server will use the ASCII value of the center two characters in hexadecimal from the key code. These values can be found on various internet sites or using the Windows Character Map (charmap) which shows various hex values as a tooltip for each entry. Mnemonics can also be entered as a hex value, which is particularly useful for characters that cannot be typed into a Windows dialogue.
For example, a common alternative VT escape sequence for function 1 is an escape followed by a capital O and capital P. In StayLinked, that would be mapped as a [hex 1B]OP with the [hex 1B] representing an escape. Anything not included within the square brackets is transmitted as plain text, while anything within square brackets represents a StayLinked command. The same sequence could also be mapped as [hex 1B4F50] with the 1B for an escape, 4F representing the O and 50 representing the P.
One of the options you can select from the mapping pulldown is the [staylinked menu]. This menu provides a few diagnostic features that work with the server. One of these diagnostics is a keyboard test that displays the key code and mapped mnemonic for each key press. This can be very useful in checking your mappings. Please note that changes to the keyboard map will not take effect on your device until it disconnects and reconnects to the server.
VT Emulation Terminal ID
StayLinked uses a default terminal ID of vt420. Some telnet hosts may not support this value and need a different configuration. This is controlled in the telnet host entry as an emulation property. The most common values for a terminal id are vt420 (which is the default used if nothing is specified), vt220 or vt100. A new session must be started for changes to the telnet host entry to take effect.
Note that VT100 emulation is limited to functions F1 thru F4. F5 and higher function keys are only available in more advanced emulation types. If your F5 or higher keys are not functioning, it might be as simple as setting your emulation type to VT220 or higher.
VT Escape Sequence Processing
This setting can have a direct effect on the operation of key sequences in VT emulation. Some telnet hosts will not properly process escape sequences that are delivered across multiple packets. The default setting for VT Escape Sequence Processing is RAW mode. This forces StayLinked to deliver escape sequences in a single transaction.
StayLinked uses square brackets to identify mnemonics, such as [enter]. With VT Escape Sequence Processing set to the ‘Parse Mode’, you’ll need to double any standard bracket character when sending a bracket as part of an escape sequence. For example, with VT Escape Sequence Processing set to Parse mode, an “escape bracket 16 tilda” would be entered as: [hex 1B][[16~ but in RAW mode it would be mapped as: [hex 1B][16~ without the extra square bracket.
Older StayLinked servers would default this option to Parse Mode, while newer installations default to RAW mode.
Common Escape Sequences
5250 and 3270 emulation types use very standardized values for the various mnemonics that can easily be selected from the pulldown menus when adjusting the keyboard map. Various VT emulation applications have developed their own set of escape sequences over the years. Outlined below are some of these special mappings for a few of the more common applications:
| Mapping | VT100 | VT2XX/4XX | SAP Console | HighJump |
| F1 | [hex 1B]OP | [hex 1B][11~ | [hex 1B]OP | F1[enter] |
| F2 | [hex 1B]OQ | [hex 1B][12~ | [hex 1B]OQ | F2[enter] |
| F3 | [hex 1B]OR | [hex 1B][13~ | [hex 1B]OR | F3[enter] |
| F4 | [hex 1B]OS | [hex 1B][14~ | [hex 1B]OS | F4[enter] |
| F5 | [hex 1B][15~ | [hex 1B][15~ | [hex 1B][35~ | F5[enter] |
| Mapping | VT100/2XX/4XX |
| F6 | [hex 1B][17~ |
| F7 | [hex 1B][18~ |
| F8 | [hex 1B][19~ |
| F9 | [hex 1B][20~ |
| F10 | [hex 1B][21~ |
| F11 | [hex 1B][23~ |
| F12 | [hex 1B][24~ |
| F13 | [hex 1B][25~ |
| F14 | [hex 1B][26~ |
| F15 | [hex 1B][28~ |
| F16 | [hex 1B][29~ |
| F17 | [hex 1B][31~ |
| F18 | [hex 1B][32~ |
| F19 | [hex 1B][33~ |
| F20 | [hex 1B][34~ |
Please note that all entries assume VT Escape Sequence Processing is defaulted to RAW mode in the telnet host entry, host properties. If this setting has been configured to ‘Parse’, adjust the entries above replacing unpaired square bracket with a double bracket.
Since F5 is not a standardized function in VT emulation, there are many possible variations on the desired sequence. Other commonly used sequences for F5 are:
[hex 1B]M [hex 1B][16~ [hex 1B]OT
Your application vendor should be able to provide details on the expected values for each key. More information is also available online by searching for ASCII or terminal emulation escape sequence and control codes.
Some applications may also utilize alternate escape sequences for the cursor movement arrow keys. Typical cursor movements are as follows:
| Arrow | Standard Seq | Alternate Seq | Alternate Seq | Alternate Seq |
| Up | [hex 1B][A | [hex 1B][OA | [hex 1B]A | [hex 1B]OA |
| Down | [hex 1B][B | [hex 1B][OB | [hex 1B]B | [hex 1B]OB |
| Right | [hex 1B][C | [hex 1B][OC | [hex 1B]C | [hex 1B]OC |
| Left | [hex 1B][D | [hex 1B][OD | [hex 1B]D | [hex 1B]OD |
Alternate Keyboards
In cases where you might have two different VT emulation hosts that use different keyboard mappings, StayLinked supports a telnet host setting to substitute keyboards.
The first step to creating an alternate map is to make a copy of the original map. You can make a copy of any installed map by right clicking on the entry in the list of installed keyboard maps. This copy will need a unique ‘device type’ as described in the beginning of this article. Once you’ve made the copy, you can open it and make any custom mappings that are required for the specific telnet server. In order to use the alternate keyboard map, you would open the telnet host entry and select Manage > Alternate Keyboards. This opens a dialogue where you can configure the original device type, and the alternative map you would like these devices to use when connecting to this telnet server.
The Server-Based Architecture of Keyboard Maps
StayLinked uses different components in different places to make keyboards perform as configured. The different components of the solution provide different roles or functions as follows:
- StayLinked Administrator – Owns a list of available keyboard maps. These are stored in various KBDEF files in the Administrator’s installation directory. These XML files contain the list of known emulation and device types and are replaced with new copies when you run the Administrator Keyboard Definition Update. When selecting the Keyboard Maps section of the Administrator, the Administrator downloads the current keyboards.xml file from the Server. If changes are made or keyboards are installed, the Administrator pushes the file back to the Server with a notification to re-read the file contents. The old keyboards.xml file would be renamed with a date and time stamp, and the new file would become the current working keyboards.xml file. All new connections to the Server will follow the rules in the current working file.
- StayLinked Server – Compares incoming key codes to the list of installed keyboard maps, performing the custom mnemonic or sending the hex code of the center two characters for any key code that does not have a specific mapping. For example, a key code of 0A3109 would not appear in a default map but would perform the mnemonic [hex 31] based on the key code center value.
- StayLinked Client – On the device, the OS generates values that the client uses to build a key code. This key code is sent to the StayLinked Server where it is compared against the keyboard map. Clients cannot generate events for buttons that do not generate a key code. Special features using the mnemonic [key=XXXXXX] will act as a key code, sending the key code specified in the mnemonic for lookup on the keyboard map for that device.
This information is intended to assist with your usage and configuration of the StayLinked solution. StayLinked can configure key codes to provide any desired mapping but does not have control over the WMS/ERP or hosted application interpretation of those mappings.
Share the post "Keyboard Maps"