Introducing the Braille keyboard

Before you can start typing, you have to first set the buttons for each braille dot.

You decide how to place the dots. You need to enter each dot position in order from one to six. After that swipe down for a newline.

MBraille remembers the position of each dot, but you can always reprogram the dots if you have forgotten. Reinitialize the layout with a four finger swipe right.

Note that in the layout the dot positions are not entirely fixed but allow for your hand positions to drift while still keeping the input accurate.

Using the keyboard

The braille key input begins when one finger goes down and ends when all fingers are lifted. You can tap all the dots simultaneously or in sequence as long as at least one finger remains on the screen.

By default, contracted Braille is not used, but if available, it can be turned on from settings. To quickly turn contractions on and off while entering text, hold down dot 6 with one finger and flick up or down with another finger.

Swipe gestures

MBraille swipe gestures work best when they are short and fast.

Swipe directions

When referring to swipe direction confusion can arise depending on how you hold your phone or tablet.

So the directions are taken from the Braille characters themselves and the following convention is used:

Right: Direction from dot 1 to dot 4 Left: Direction from dot 4 to dot 1 Up/Down: You choose this when you initialize the keyboard.

One-finger swipes

Swipe right to enter a space. Swipe down to enter a newline. Both space and newline trigger the expansion of contractions in the preceding word. Swipe left to delete the previous character. Swipe up to hear what you have written.

Two-finger swipes

Two finger swipe left to delete last word.

Two finger swipe right for newline. This is the same a swipe down in MBraille, but provided for compatibility with iOS and Android braille input.

Two finger swipe up to repeat last thing spoken.

Three-finger swipes

Three-Finger Swipe Left: Undo Reverses recent actions, including text edits (cuts, deletions, clearing), and closes read-only files.

Three-Finger Swipe Down: Erase/Close Erases all current writing. Alternatively, shake the device to erase. For read-only files, this closes the file and restores the previous content.

Three-Finger Swipe Up: Command Mode Opens the command interface for advanced actions, such as sending text messages, and managing files (open, save). See "Commands" below for details.

Four-finger swipes

Four finger swipe up closes the keyboard and takes you to previous screen. Four finger swipe right resets the keyboard layout. Four finger swipe down gives a short context sensitive help.

Alternatively, you can access context-sensitive help by holding dot 1 and swiping up with two fingers.

Scrub gesture

MBraille supports a two-finger scrub gesture (swipe left-right-left quickly with two fingers) to go back or close files, similar to iOS conventions. This is an alternative to the four-finger swipe up gesture.

Clipboard

If you switch to another application from MBraille, the current text is automatically copied to the clipboard. You can then paste the text in the other application. Then just open the app switcher and select MBraille to get back.

To copy just a given block of text from MBraille to another application, mark and copy your block as described in the next topic and and invoke the app switcher.

Editing text

You can do simple editing with MBraille, preview what you have written, and move text around by selecting, cutting, and pasting. You can even paste text from other applications into MBraille for editing.

All editing gestures work on the same principle: use one hand to press and hold one or more braille dots to select the gesture, then swipe up, down, left, or right with your other hand to activate the selected gesture.

When editing existing words or entering punctuation, it is often more convenient to use uncontracted Braille. To quickly toggle contractions on and off while entering text, hold down dot 6 with one finger and flick up or down with another finger.

Previewing text and moving the insertion point

Hold down braille dot 3 with one finger. Use another finger to flick left or right to have your text read word by word. Flick up or down to change the granularity of movement. You can move in the text by character, by word, by sentence, by line or by paragraph.

To quickly read to the end of text from the cursor, flick right with two fingers while holding dot 3. Flick left with two fingers to read from beginning to cursor. The cursor position is not changed when you do this.

Flick up while holding dot 3 to hear number of characters and words in the text.

You can move to the beginning of text by holding dots 1 and 3 and flicking left. You can move to the end of text by holding dots 1 and 3 and flicking right.

Bookmarks

You can save bookmarks at any position in your saved files and navigate between them using gestures:

- Save a bookmark: Hold dots 1 and 3 and swipe down with two fingers - Next bookmark: Hold dots 1 and 3 and swipe right with two fingers - Previous bookmark: Hold dots 1 and 3 and swipe left with two fingers

These next and previous bookmark gestures cycle through all the bookmarks in the current file. If you reach the end, they wrap around to the beginning (and vice versa). You must save your file before adding bookmarks.

For named bookmarks and how to delete bookmarks, see the "Named Bookmarks" section in the commands documentation.

Selecting, cutting, copying and pasting text

Navigate in the text using the preview function. Once you have found your spot, press down dot 2 while still holding dot 3. With dots 2 and 3 held, moving around with flicks selects the text that is passed over. VoiceOver announces the selected text as you move. To hear the full selection, swipe up with two fingers while still holding dots 2 and 3.

To copy the selected text, swipe up with dots 2 and 3 still held down. To cut the selected text, swipe down.

To paste text at the insertion point, hold down dot 2 and flick down with another finger. Hold down dot 2 and flick up to hear what currently is in the clipboard. You can paste text you copied with MBraille copy or cut function, or text that you copied from another application.

To quickly extend the selection to beginning or end of text, hold down dots 1,2,3 and swipe left or right.

Searching

Hold dots 4,5,6 and swipe up or down to enter search mode.

The swipe direction determines the search direction: down for forward, up for backwards.

Type your search string and swipe down for newline, at which point the string you entered is searched from current point to direction chosen. If found, the cursor is placed at beginning of match and line number and sentence it is in is announced.

Swipe down again to find the next match. The search automatically wraps around at end or beginning. If it wraps you will hear an announcement.

To get out of search mode hold dots 4,5,6 again and swipe up or down again. The input cursor is left at the position of last match.

Spelling

You can configure spelling aids in the MBraille settings.

You have 3 options for spelling in settings:

1. Check spelling after each word, beeps on misspelled word. This is the master switch, if it is not on, you will not get spelling.

2. Only check spelling during preview by word. This modifies the spelling behavior so that you will not be interrupted by beeps when writing.

3. Spell out the suggested word. This affects how the proposed corrections are announced.

So the first switch in settings is the master switch for enabling / disabling spelling.

Correcting spelling mistakes

When MBraille detects a spelling mistake, it can also suggests a list of possible corrections.

You can select a suggestion with a gesture:

When you hear a beep for a mistake while typing or previewing, you can immediately pick a suggestion from a list by holding down dot 1 and swiping up or down. The first choice in the list is the mistyped word, in case you wish to keep it. As soon as you lift your fingers, the correction is done and you can resume typing.

If in the settings you have selected to automatically spell out the suggestions, you'll hear each suggestion similar to hello below.

"hello, h,e,l,l,o"

Regardless of the setting, you can force spelling out a suggestion by holding dot 1 and swiping right. That will also report the number of suggestions, like

hello, h,e,l,l,o, 4 of 14

User spelling dictionary

You can add the word you wrote to spelling dictionary by holding dot 1 for the first suggestion, which is the word that caused the beep, and swiping left. You will be asked for a confirmation to add the word to the spelling dictionary.

dict command will list the words in your user dictionary, allowing you to remove words.

Commands from the keyboard

You can at any time execute commands from the braille keyboard. Swipe up with 3 fingers to enter the command mode and type your command followed by possible arguments, followed by a newline to run the command.

In command mode you can type and edit your command as usual with braille, but the command buffer is kept completely separate from your regular text. So if you go to beginning of text or end of text in command mode, you will get to beginning or end of your command.

Note that when in the command mode, you can use the preview gestures move by line to go back or forward through the command history. A shortcut is holding dot 4 and swiping up to got to previous command in history, or swiping down to go forward. Even if you are not in command mode, holding dot 4 and swiping up will directly get you to the last command you ran.

Command Usage

Some commands target the text you have written. For example, to send a text message, you first type your message. Then you can send it away using the commands mail or sms.

The commands you enter in MBraille are saved, so you can browse and re-execute old commands. For example, if you keep texting the same handful of persons, it is convenient not having to type the command again.

At the beginning of line, hold dot 4 and swipe up to go back in history, down to go forward. When you lift your finger from dot 4, it is as if you had typed again the old command. Just swipe down for newline to play it again.

Sending mail

You first type your mail message, then add the command.

Usage:

mail "Hello there" Jack

Follow this with a newline and the send mail form is brought up with the Subject set to "Hello there" and To: pre-filled with the email address for Jack. Subject needs to be quoted if it contains spaces. Recipient emails are looked up from contacts by their first or last name. You can add multiple recipients.

mail "Hello there" Jack Jill

will send the mail to both Jack and Jill.

For the recipient you don't need to write out the full name, a prefix is enough. You just need to use enough letters to tell the names apart. For example, to send an email to Jill when you have both Jane and Jill in your address book, you would need to type just ji. The name lookup is not case sensitive and you can add as many recipients as you wish. If you have not typed enough letters to tell multiple recipients apart, you will be warned.

To use both first name and last name to specify the recipient, you must separate the names with a period. So if you have in your contacts Jill Jones, and Jill Smith, you need to use the last name to tell the two Jill's apart. You can address an email to Jill Jones by abbreviating her name to jill.j or even just to j.j, if you have no other people in contacts whose first and last name both start with j. Note that if you are using contracted English Braille, to type the period between the first and last name you escape it with dot 4 before it. So a.b would be dots 1 4 256 12. An alternative is to toggle to uncontracted Braille on the fly to enter the arguments.

You can also give an explicit email address instead of a contact name. To type @ sign, switch to uncontracted braille by holding dot 6 and flicking up or down.

SMS text messages

sms

On a line by itself will launch the SMS send screen with the current text pre-pasted.

You can also pre-fill the recipient numbers in the same way as for the mail command. Just give the first few letters of the recipient name as parameter. For example

sms Joh

Would pre-fill the number for John. You can also give the full telephone number as an argument.

If your recipient has multiple telephones, you will be asked which one to use in a selection list. To directly pick the first mobile or iPhone number from the list, you can prefix your recipient name with "m:" as follows:

sms m:john

Dialing a number or contact

dial name or number

Calls given contact or number. The contact can be abbreviated as for sms or mail commands. The call is opened as soon as you swipe down for a new line.

Adding Calendar entries

You can create a new Calendar item from MBraille with the cal command. The current text is added to the calendar entry as notes. The arguments to specify the time follow the cal command.

Usage:

cal title starts [ends] [alert [time]] [location: place]

Examples:

cal Meeting 17:30

Schedules an event with title Meeting for 17:30. If now is before 17:30, the meeting is for today, if it is already past 17:30, the date it is automatically set for tomorrow.

cal Pickup laundry 2017-06-07-13:00 alert 30 min

Would add a calendar entry for June 7, 2017 at 1 PM, with title Pickup laundry, and add an alert to the event 30 minutes before.

cal Paris 2017-08-08

Since there is no time, this is automatically an all day event.

cal Piano lesson 2017-07-07-14:00 2017-07-07-15:00 alert 1 hour

Adds an event with starting and ending time, with an alert 1 hour before the event.

cal Meeting 5pm location: lobby

Schedules a meeting for 5 pm, location being lobby.

Different formats for specifying date are supported. In the USA MM.DD.YY format is understood, outside USA the order is day, month year; DD.MM.YY. For time, 24 hour clock is always supported, but so is 1:00 PM format.

cal Coffee 2017-05-16-16:00

cal Coffee 21/3/14-10am

You can also leave out the year, in which case the current year is used, or the following year if the date has passed.

Natural language dates

In addition to the formats above, you can also use natural language to specify dates and times. This is useful when you want to quickly create an event without remembering the exact date format. Examples:

cal Meeting next Tuesday at 3pm

cal Birthday Sep 12

cal Standup tomorrow

cal Team sync friday 3pm to 5pm

When a time range is given (like "3pm to 5pm"), both start and end times are set automatically.

Desktop support

On desktop platforms (Windows, macOS, Linux), the cal command creates and opens an .ics calendar file. The file is opened with your default calendar application, allowing you to review and save the event.

Typing Speed Test

To practice your typing speed, you can use the speedtest command.

Usage:

speedtest seconds

speedtest phrase

When you start a test, you'll hear a tone. When you stop a test, you'll hear the same tone as in the start. If you make a mistake when testing with a sample sentence, you'll hear a different tone after a word to signal a typo.

Examples:

speedtest 10

swipe down, you'll hear the starting tone. Type for 10 seconds and you'll hear the same tone to signal 10 seconds have elapsed. Hold dot 3, swipe up to preview by sentence and swipe left to hear your results.

speedtest sample text to type

swipe down, you'll hear the starting tone. Type "sample text to type" and end with space or newline. If you make a typo, you'll hear a different tone and need to correct your mistake. Once you have entered the text again without mistakes, you'll hear a tone to signal you are finished. Hold dot 3, swipe up to preview by sentence and swipe left to hear your results.

speedtest wr

is a shorthand for typing:

speedtest The razor-toothed piranhas of the genera Serrasalmus and Pygocentrus are the most ferocious freshwater fish in the world. In reality they seldom attack a human. This is the official phrase used in the Guinness World Records texting attempt, see [Records_and_competition][1] for more information.

[1]: http://en.m.wikipedia.org/wiki/Text_messaging#Records_and_competition "Records_and_competition"

Using Web Search Engines

You can at any time do Google, DuckDuckGo, StartPage or Yandex searches. The search will open your default browser to display the search results.

Google

Usage:

google word1 word2

You can abbreviate the command to goo

Example:

goo "Albert Einstein"

Note that you can quote search terms, as you can with a regular Google search. If you don't give any parameters, all of your current text is used as search keywords.

Getting help

To consult help directly from the Braille keyboard, you can give the help command.

Usage:

help

File Management

Commmands:

open filename

Opens filename.txt from MBraille folder. If you use another suffix than .txt, you need to specify it.

open

Without filename will let you browse the files in /MBraille folder. If you don't remember the filename, but remember it at the letter A in it, you can do ".open A" and you'll get a list of all files with letter A in the name.

Swipe left/right or up/down to go through the list, double tap when you have the file you wish to open. At bottom of screen there is a cancel button if you wish to cancel the action.

save

Saves the current buffer with the name it was opened with. If a new buffer, the default name is notes.txt

save filename

Saves the current buffer as filename.txt. It is saved under /MBraille folder which you can see with a file explorer, or when you connect to your PC.

delete filename

Deletes the file, asking for a confirmation. If you leave the filename out, or give partial filename, you will be presented a list of matching filenames.

Named Bookmarks

In addition to the quick bookmark gestures (holding dots 1 and 3 and swiping with two fingers), MBraille has named bookmarks. All bookmarks are saved across sessions and can be shared between files.

Commands:

bookmark [name]

Adds a bookmark at the current cursor position. If a name is provided, the bookmark can be referenced by that name later. If no name is given, an bookmark with filename and order number is created. You must save your file before adding bookmarks.

Examples:

bookmark Chapter 1

Creates a named bookmark called "Chapter 1" at the current position.

bookmark

Creates an unnamed bookmark at the current position.

jump name

Jumps to a previously saved bookmark by name. If the bookmark is in a different file, that file will be opened automatically.

Example:

jump Chapter 1

Moves the cursor to the "Chapter 1" bookmark.

rmbookmark name

Removes a named bookmark from the current file.

Example:

rmbookmark Chapter 1

Deletes the "Chapter 1" bookmark.

list bookmarks

Shows a list of all bookmarks sorted by file and position. Use left/right swipes to navigate the list, press newline to jump to a bookmark, or swipe left with two fingers to delete a bookmark from the list.

The bookmark list shows entries in the format: - Named bookmarks: "bookmark name, filename: number" - Unnamed bookmarks: "filename: number"

Bookmarks from the current file are listed first, followed by bookmarks from other files.

Note: Bookmarks are automatically cleaned up when files are deleted.

Aliases

With aliases you can create shorthand forms for arbitrary text. The alias is expanded when you swipe for space or newline. One possible use for aliases are emojis.

There is a sample alias.mb file distributed with MBraille with some predefined aliases.

Try for example typing RH in capitals an see what you get!

You can open the alias file in MBraille with "open" command and edit it to your heart's content.

Aliases defined in this file. To change aliases, just edit the alias.mb file and save it. All aliases are re-read from the file when it is saved or when MBraille starts. Note that when alias.mb is the file being edited, all aliases are disabled.

Note that if you are using cloud file sync, your aliases are automatically synced between devices. As alias.mb is a simple text file, you can just open alias.mb in any editor to make modifications, or send a useful alias.mb file to your friends. The file can be transferred from-to MBraille either through Dropbox, Google Drive or Onedrive

You can of course edit alias.mb in MBraille itself, using "open alias.mb" and save commands. During the editing of alias.mb, the aliases are disabled.

The file format is:

myalias1: definition myalias2: another alias definition

Empty lines are ignored, as well as lines starting with #

Instead of colon, you can also use '=' sign to denote the start of definition. The leftmost sign matters. (Not all braille tables have '=', so I chose ':' as the default.)

Multiple lines in aliases

Aliases can expand to multiple lines. To define a multiline alias:

1. Start the alias with NAME: followed by nothing on the same line. 2. Write each line of the alias content on its own line. 3. End the alias with :end on its own line.

For example, the following would expand to 5 lines:

MYSIG: Charlie Brown Lucky Street 8, 00100 Happytown Finland tel. +358 9 1234 5678 :end

Command Aliases

These are aliases that only work when they are the first word in the command buffer. Perhaps an example is the best way to explain them.

If you put the following line in alias.mb: command ml: mail mbraille-test@lists.mpaja.com

That will create a command alias called ml. Now, when you swipe up with 3 fingers, type ml, and swipe down, it will launch the mail app, using the current buffer as the mail body and the "To" address pointing to the testers' mailing list.

I chose ml as shorthand for "Mailing List," but feel free to choose your own aliases. Other examples:

text
  command fr: lang fr
  command en: lang en
  command w: whatsapp family

Now the new commands would be fr, en, and w. These would change the language to French, change the language to English, and open WhatsApp to send a message to your family (assuming you have a group called "family" in WhatsApp).

Alias Gesture Binding

There are 4 gestures you can bind to an alias. The gestures are: Hold dot 5 and swipe Up, Down, Left, or Right.

The syntax for these is:

bind-5u: existing-alias-name bind-5d: existing-alias-name bind-5l: existing-alias-name bind-5r: existing-alias-name

Again, some examples. Let's assume your alias.mb has the lines:

gbyf: So Long, and Thanks for All the Fish. bind-5u: gbyf

Now, when you are writing in MBraille, if you hold dot 5 and swipe up, the phrase "So Long, and Thanks for All the Fish." is inserted at the cursor!

You can also bind the gestures to command aliases. So, to switch the braille table to French with a gesture, you could do:

command fr: lang fr bind-5r: fr

Notes

Alias expansion happens before any contracted braille expansion. If you include an alias in an alias definition, the alias included will not be expanded.

Working with third party applications

Whatsapp message

If you have Whatsapp installed, you can send a message to a Whatsapp contact.

Usage:

whatsapp contact

Opens Whatsapp and automatically fills the receiver and message text from MBraille.

If you want to select the contact in Whatsapp itself, but still pass the message text from MBraille, you can launch Whatsapp without the contact argument.

Cloud sync for MBraille files

MBraille currently supports Dropbox, Google Drive and Onedrive (Microsoft)

These can be turned on from Settings. You need to authenticate with the corresponding service.

The files are synchronized when ever you cold-start MBraille.

MBraille also syncs documents to the cloud during the following operations, if cloud sync is enabled and connected:

- On save: After successfully saving a file locally, it uploads the file to the cloud. - On delete: After deleting a file locally, it removes the file from the cloud. - On open: It checks for and downloads a newer cloud version if available before opening the file.

Syncing is not automatic at set intervals or on app close; it occurs reactively based on these file operations.

Odds and Ends

Additional Symbols

MBraille supports the following multi cell symbols. If you are using the setting where all characters are announced, the voice feedback is a little confusing, as separate cells are announced in braille ASCII until the word is complete.

UEB symbols supported by MBraille

Symbol	Dots
"	6-2356
#	456-1456
$	4-234
%	46-356
&	4-12346
(	5-126
)	5-345
*	5-35
+	5-235
-	5-36
...	256-256-256
/	456-34
<	4-126
=	5-2356
>	4-345
@	4-1
[	46-126
\	456-16
]	46-345
^	4-26
_	46-36
{	456-126
}	456-345
~	4-35
¢	4-14
£	4-123
¥	4-13456
§	45-234
©	45-14
«	456-236
®	45-1235
°	45-245
¶	45-1234
»	456-356
×	5-236
è	46-16-15
é	45-34-15
÷	5-34
α	46-1
β	46-12
γ	46-1245
δ	46-145
ε	46-15
ζ	46-1356
η	46-156
θ	46-1456
ι	46-24
κ	46-13
λ	46-123
μ	46-134
ν	46-1345
ξ	46-1346
ο	46-135
π	46-1234
ρ	46-1235
σ	46-234
τ	46-2345
υ	46-136
φ	46-124
χ	46-12346
ψ	46-13456
ω	46-2456
—	6-36
——	5-6-36
‘	6-236
’	6-356
“	45-236
”	45-356
†	4-6-1456
‡	4-6-12456
•	456-256
₣	4-124
₦	4-1345
€	4-15
™	45-2345
←	1256-246
↑	1256-346
→	1256-135
↓	1256-146
♀	45-1346
♂	45-13456
♭	3456-126
♮	3456-16
♯	3456-146
〃	5-2

For older English Braille MBraille supports

Symbol	Dots
#	456-1456
%	4-25-1234
&	4-12346
'	6-236
'	356-3
*	5-35
*	35-35
+	5-235
-	5-36
.	3-3-3
/	456-34
:	4-156
=	5-2356
@	4-1
[	6-2356
]	2356-3
¢	4-14
£	4-123
$	4-234
¥	4-13456
©	45-14
®	45-1235
×	5-236
÷	5-34
–	36-36
–	36-36-36-36
″	4-35
€	4-15
™	45-2345

Self Voicing

You can use the Braille keyboard without VoiceOver turned on. MBraille will detect that VoiceOver is not running and automatically use self voicing.

Giving feedback

To send mail to MBraille developers, you can give the feedback command.

Usage:

feedback [subject]

Examples:

feedback Thanks for a job well done!

Without any arguments feedback uses the default Subject: "MBraille feedback"

It will add the device information and MBraille version info to the message, which it takes from you MBraille text buffer. The feedback is sent as email from your devices's standard email app.

Change Braille table language

If your phone language does not match the Braille table you would like to use, or if you know Braille in multiple languages, you can change the Braille table on the fly with the lang command.

Usage:

lang [language code]

Examples:

lang da

Would change the braille table to Danish for the current session.

Design and coding

+ Harri Pasanen

Software used

Hunspell https://hunspell.github.io/ Liblouis https://github.com/liblouis/liblouis

Table of Contents

Introducing the Braille keyboard

Using the keyboard

Swipe gestures

Swipe directions

One-finger swipes

Two-finger swipes

Three-finger swipes

Four-finger swipes

Scrub gesture

Clipboard

Editing text

Previewing text and moving the insertion point

Bookmarks

Selecting, cutting, copying and pasting text

Searching

Spelling

Correcting spelling mistakes

User spelling dictionary

Commands from the keyboard

Command Usage

Sending mail

SMS text messages

Dialing a number or contact

Adding Calendar entries

Natural language dates

Desktop support

Typing Speed Test

Using Web Search Engines

Google

DuckDuckGo

StartPage

Yandex

Opening the web browser

Multimedia

Spotify

YouTube

Getting help

File Management

Named Bookmarks

Aliases

Multiple lines in aliases

Command Aliases

Alias Gesture Binding

Notes

Working with third party applications

Whatsapp message

Cloud sync for MBraille files

Odds and Ends

Additional Symbols

UEB symbols supported by MBraille

For older English Braille MBraille supports

Self Voicing

Giving feedback

Change Braille table language

Design and coding

Software used