BrailleKeyboard #

Introduction #

This is a small app that turns an ordinary keyboard into a braille keyboard. To enter a braille combination you press all the keys correponding to the braille code, and then release any or all of them to indicate that the code is complete.

The app is written and tested for Windows 64 and implements Unified English Braille (UEB) based upon The Rules of Unified English Braille, Second Edition 2013.

Being a keyboard, not an editor in its own right, BrailleKeyboard interacts with other Windows apps. As such, the formatting aspects of UEB, for example bold and italics, are left to the individual apps, and therefore ignored by BrailleKeyboard. For most apps that implement bold and italic formatting, you would use the standard keyboard shortcuts Ctrl + B amd Ctrl + I.

Prerequisites #

You will need a keyboard which will send all the keystrokes when multople keys are pressed at once. So far this has worked for me on all the keyboards I have tried (standalone and laptop), but I gather some cheaper keyboards may not do this correctly.

Current keyboard mappings are hardcoded and correspond to a QWERTY keyboard. The mappings don't use any keys that are different between a UK and a US keyboard. BrailleKeyboard has been explicitly tested on UK and US English keyboard layouts, and should work on any keyboard layout using the standard English QWERTY layout.

Specifications #

Operating System: Windows x64 (tested on Windows 10 and 11 with an English QWERTY keyboard)

Braille: based upon Unified English Braille, 2nd edition 2013

Basics #

Console #

When running, the keyboard opens a console window into which it puts any logging. This doesn not need to be focused, but does give a mechanism for lknowing when the keyboard is running and will appear in the TaskBar. There is no need for the user to interact with the console in any way, unless trying to obtain debugging information. See Configuration->Logging for more details.

Using The Keyboard #

BrailleKeyboard maps the letter and punctuation keys of the standard keyboard. The numeric, number keypad, function, cursor and control keys are all unaffected and will work as normal. Thus, when BraiileKeyboard is enabled the letter and punctuation section of the keyboard will act for braille, which will mean most of the keys do nothing. See below for the mappings of these keys to braille. Only the mapped keys are active when BrailleKeyboard is enabled.

All the unaffected keys work as normal when BrailleKeyboard is enabled, including in combination with letter keys. For example, when BrailleKeyboard is active, you will need to press the keys F and J to achoeve the letter C (as pins 1 and 4). The key C will do nothing as it is not mapped as a braille pin or as a cursor key. However, if the Control key is pressed, then the key C is available to be used in combination, and would in most applications instruct a copy operation. The effect is that if a control key is used, then the braille functionality is disabled until no control key is pressed.

Keyboard Layout #

Braille Pins #

BrailleKeyboard reassigns the alphabetic and punctuation keys on your keyboard. The surrounding keys are unaffected and work as normal, namely the control keys, Space, Return, and the numeric keys. Function leys. any numeric keypad and cursor keys are similarly unaffected. If you use the control keys (Shift, Control, Alt, Windows) the alphabetic keys work as normal. Ctrl + Return will switch the Braille component of the keyboard on or off, both using Braillekeyboard, when active and the normal keyboard keys. When BrailleKeyboard is turned off, your keyboard will operate completely normally.

The assignment of keys to braille is based upon an English QWERTY keyboard and is anchored on the F and J keys, which should have tactile bumps. I use this app with my index fingers on the F and J and my other fingers resting on the neighbouring keys of the row. This means that the left hand operates the standard Braille pins 1 through 3, and the right hand pins 4 through 6, each jand using the index through to the ring finger. The little fingers rest over what are often referred to as pins 7 and 8 for extended Braille, but here are used for control purposes, not extended Braille. Both thumbs use the Space key, which works as normal.

This gives the following pin to key mappings:

Pins 1 through 6 are used as defined in the UEB specification. Pin 8 is used as the Return or Enter key. Pin 7 on its own is used as Tab.

For convenience, the keys G and H are mapped to be duplicate Backspace and Delete keys respectively, and can be reached by moving the closer index finger between the tactile keys, left finger from F to G (Backspace) and right finger from J to H (Delete).

On most keyboads the keys Ctrl, Windows and Alt are from left to right in the bottom left corner. When used in conjunction with Pin 7, pins 3 through 1 function as those keys. Thus pins 7 and 3 together represent the Ctrl key. Pins 7, 3 and 1 together would be Ctrl + Alt, Pins 7, 3 and 8 are Ctrl + Return and will turn off BrailleKeyboard. In UEB, a capital letter is marked with a preceding pin 6 code, and thus with the control keys, pin 6 is treated as Shift. Pin 7 with either pin 4 or pin 5 will turn off these control keys.

Thus, when used in combination with pin 7, pins 1 through 6 work as follows:

The control combination is only maintained for a single action. It is also disabled when BrailleKeyboard is disabled.

Disabling and Enabling #

BrailleKeyboard can be disabled without having to close the app. Control + Return will disable it until the key combination is used again. Disabling can be done using BrailleKeyboard itself (using pins 7, 3 and 8) or the standard Control and Return keys. Re-enabling can only be done with the standard keys as the braille input is not active.

Cursor Mappings #

Whilst the keys surrounding the letters and punctuation are unaffected in their functionality, it is more convenient for their actions to be more close at hand. To this end, certain editing and cursor functions are available from keys adjacent to those previously described.

Cursor movement is available via the W, E, I and O keys. These can be reached by moving the third and fourth fingers of each hand to the line of keys above that used for Braille.

Configuration #

The configuration file is optional, and is only used when BrailleKeyoard starts. BrailleKeyboard will need to be restarted to pick up any changes. If it is missing then the keyboard will use default settings, with completely syandard UEB. The configuration file uses JSON format as described below. The keyboard looks for the file at %APPDATA%\Roaming\BrailleKeyboard\config.json, where %APPDATA% is usually C:\Users\<user>\AppData. The file can safely be deleted at any point.

See the example config.json that demonstrates the configurations described below.

Logging #

There are four log levels, ERROR, WARN, INFO, and DEBUG. The default level is INFO. These levels control how much information is logged into the console window. ERROR only logs when an error occurs, and WARN for less urgent issues. INFO gives general staus messages, most of which occur during start up. DEBUG provides much more detailed information aimed at diagnosing any observed issues.

Note, that at no point is any logging saved to disk. This is deliberate, as in DEBUG mode, it is possible, and for debugging necessary, to track every keystroke, with obvious security implications. As such, for any logging to be transferred to another party, the user will have to manually copy it from the console window to another document. It is highly recommended NOT to use DEBUG mode in general use, and only use that mode when specifically trying to reproduce an issue for investigation, at which point there is no need to use potentially sensitive information.

The key for setting the logging property is logLevel. "logLevel": "info". The value is case insensitive.

Wordsigns #

UEB has a defined, standard set of wordsigns intended for general use. These are the defaults used by BrailleKeyboard and are named "ueb". However, it can be useful to redefine the wordsigns for specialised, contextual use. These extra wordsigns sets can be defined in the configuration file.

There are two formats that can be used. The first is a dictionary of strings, in which case the set will act like the ueb set in terms of capitalization. The second option is a dictionary of two word lists, defining one word for lower case use, and one for upper case. This can be useful in contexts where words are only ever in one case, such as in coding, for example, C++. Examples of both forms are included in the example configuration file.

If a key is omitted in the dictionary definition, then no wordsigns will be defined for that key.

The configuration file can also define which wordsign dictionary should be used when BrailleKeyboard is started. The default is the internally defined "ueb" standard set of wordsigns.

The dictionary in use can be changed by pressing Shift + Return. The subsequent input will be used to find the desired wordsign dictionary and not treated as general keyboard input. The search finishes as soon as there is no name match for a wordsign dictionary, or there is only one possible dictionary that it could be. In the first case, the wordsign dictionary will remain unchanged. In the second case, the matching wordsign dictionary will become active. In botn cases, the outcome will be logged at INFO level to the console, and keystrokes will again be passed on.

For easiest use of switching wordsign dictionaries, on the assunption that most users won't define a large number of dictionaries, it is recommended that the naming key use a different first letter for each set. Then you only need to use Shift + Return and a single letter to switch the active wordsign dictionary.

From version 1.1, a couple of custom wordsigned are available, @ and #. These are intended to take an email and a phone number, although the contents are not validated, and so can coatain anything. For custom dictionaries, just ise the @ or # as they key. To configure for the default UEB wordsign dictionary, use the top level ueb_@ and ueb_# keys. See the example configuration file for examples.

Potential Gotcha from Contraction Implementation #

Contractions, wordsigns, groupsigns, etc. are implemented by the BrailleKeyboard sending extra, virtual keystrokes in addition to those directly input by the user, when the conditions are met.

For example, the wordsign for the letter p is "people". When a standalone letter p is followed by a Space, the BrailleKeyboard will send the extra keystrokes for the letters e, o, p, l and e before passing on the Space. If the standalone letter is different then backspaces will also be sent to correct the foregoing text. For example, the wordsign for the letter x is "it". In this case, a standalone letter x followed by a Space, would produce the extra keystrokes Backspace, i and t before the Space is passed on.

The gotcha arises because BrailleKeyboard has no concept of which application has focus whilst you are typing, acting as just an intermediary between your physical keyboard and the applications on your PC. Thus, if for example, you type a standalone letter, then switch application, and then type a Space, the standalone letter woil be received by the first application, and the subsequent wordsign expansion will be received by the second application. Because BrailleKeyboard is unaware of application focus, it does not treat typing in a new application as separate from the previous application.

An easy way to prevent this effect is to type a Grade 1 glyph as your first action in a new application, as this will block any contraction exopansions, as in standard UEB.