Mouse mode

Once a device is connected by default it can send characters. But if you want to control it as a mouse you can enter the mouse mode. This is done with the morse command of .-.-- (configurable in userConfig.py) and then the device can send mouse commands

NB: in iOS you need to make sure Settings -> Accessibility -> AssistiveTouch -> On.

Then to move the mouse use these commands

By default it will only move 5 pixels (default is changeable - see default_mouse_move_step in user/config.py). If you wish the mouse to start moving in one direction and stop when you next send any switch press try using the REPEAT mode

. Repeat Mode

You would send the mouse movement you wish to do - THEN send the repeat command. Eg. Down - Repeat ( -- .) - will repeat moving down and stop on the first press.

You can increase or decrease the speed of movement using some different options:

.-..-- Increase speed

.-..-. Decrease speed

.--.-. Set Speed to 1

.--.-- Set Speed to 5

Mouse buttons are:

• .-- Right Click

• .- Left Click

• ..-- Double Right click

• ..- Double Left click

Click and hold

-. Left click and hold (enter again to toggle off)

-.. Right click and hold (enter again to toggle this off)

So to drag the mouse you could use this technique. Or you could use the REPEAT MOUSE command (.)

To drag the mouse

-. (Click and hold) - (Up) . (Repeat moving up) . (release moving when ready) -. (Release Click and Hold)

Some users may need to control their device with a built in switch scanning option - as well as use morse to type. To do this we have a neat method to enable this where the same device pretends to be a second bluetooth device.

To swap between Morse and Switch mode - Press switch 4. This toggles between the two.

Once you have done this a new BLE device is available known as SW_HID. You should be able to connect to it and then setup switch access. By default the following keys are sent (depending on the button number you are using): Button one mode: Button 1 - Space

Button two mode: Button 1 - Space Button 2 - Enter

Button three mode: Button 1 - Space Button 2 - Enter Button 3 - Backspace

Starting off

If you have a brand new itsybitsy/x80 you will need to read this guide to get it in a state to be used with circuitpython. Once thats ready - you should have a disk drive mounted on your computer called "CIRCUITPY". Download all the code, unzip it and and then drag and drop the contents of morAce/ directory to circuitpy.

It should look like this

Next you need to add some libraries to "lib" directory. If you are a developer we recommend using circup. Simply type within the local directory

circup install -r requirements.txt

If you are not - you'll need to install them by:

• Downloading the bundle for 7.x

• Unzip

• Drag the following flles to the "lib" folder on the CIRCUITPY drive: adafruit_dotstar, adafruit_hid, adafruit_ble

Once completed it should reboot. We recommend using mu Editor to edit any userConfig.py files as you need to. Just note that bluetooth switching or using switch control mode wont work until you change a key file. More on that below.

Key UserConfig Options

You have some options depending on your needs. You will find all settings in the user/ directory. The main settings are in user/config.py and are documented below. Note that text macros and the morse code key set is in morse_code.py and morse_code_shortcuts.py. See #predefined-stringsfor information on those files.

One, Two or Three switch morse functionality

By default the board is set to one switch mode. By using one switch the user needs to send a dot and dash character by holding down the switch at the correct timings. So if you do use this one switch mode be particularly careful of adjusting the length of a dot setting which is default set to 200 ms (a dash by convention is three times the length of a dot).

In two switch mode - you need a switch to send the dot and another for the dash. You still need some timing skills to allow the system to distinguish the end of character time (set as the same time as a dot - so you would need to not press for 200ms). If a user has difficulty with this you may want to use 3 switch mode. In this mode the third switch is the end of character signal. e.g. **** ****In one switch mode. To send the letter "a" (dot dash) you would press switch 1 for 200 ms, release then press switch 1 immediately again for 600 ms. You then need to leave for minimum of 200ms before starting another letter.

In two switch mode you would press switch one for any length of time, release and then press the second switch. Then wait a minimum of 200ms before starting the next letter.

In three switch mode you would press switch 1, then 2, then 3.

To configure this - edit user/config.py - by editing the following lines. Put a 1 against the option you want. Put a zero against the options you don't want.

one_button_mode = 1
two_button_mode = 0
three_button_mode = 0

Length of a dot

For one switch mode you should be aware its set at 200ms by default. You can make this longer or shorter by editing this setting

dot_length = 200

Fast Typing

Some users want to hold down their dot or dash characters. This makes text entry far faster but it can be hard to use if you are new to morse. To turn it on

fast_typing_mode = 0

There are a plethora of other configuration settings in user/config.py - which you are welcome to edit. Just note the details about saving to the board particularly if you want to use the switch control mode or access more than one Bluetooth device. You will need to press switch 1 & 3 to reset the saving function.

Sound (Buzzer) volume

See sound_voiume setting. Set it to 0-10 depending on how loud you want the buzzer feedback

Want to Pair to more than one Bluetooth device or use switch control mode?

By default the code WILL NOT WORK to use these two features. You will need to set the saving_parameters = True in the userConfig.py file to allow this. This is because these modes need to write to the file system by itself - so if you want this we have to disable the neat USB disk drive feature of circuitPy. But dont worry - we've made it easy to switch it back on with a switch press so you can get back to editing the configuration. Once this parameter is set to True then restarting the morAce board will by default put it into a read only mode. You cannot edit config files. To allow editing config files PRESS AND HOLD SWITCH ONE on reboot. If you have no way of pulling the power on your own you can use this morse command to reset the power:

..-..-.. (Reset the power/MCU - set in UserConfig.py)

It will now allow you to edit files on the CIRCUITPY usb drive. But be aware - that if it restarts again it will go back to not allowing you to save to that directory.

The basics

In its default state morace is designed to work with one switch. But it can be used with 1,2 or 3 switches if you configure it that way. So in one switch mode you press for a length of time for a dot and a length of time for a dash and the gap of no sending any characters is what defines the ending of a encoded chunk (a letter or any morse encoded element). You can change these timings in the userConstants.py file if you so wish. There is also a fast typing mode - where holding down the switch will repeat a character. It best works with at least two switches. Using it with one switch requires VERY good timing skills! By default this is off. You can turn it on by editing userConfig.py and setting the parameter of fast_typing_mode to 1

Keyboard keys

These are the pre-defined keys. You can customise these by editing

• .- a

• -... b

• ---. c

• -.. d

• . e

• ..-. f

• --. g

• .... h

• .. i

• .--- j

• -.- k

• .-.. l

• -- m

• -. n

• --- o

• .--. p

• --.- q

• .-. r

• ... s

• - t

• ..- u

• ...- v

• .-- w

• -..- x

• -.-- y

• --.. z

• ----- 0

• .---- 1

• ..--- 2

• ...-- 3

• ....- 4

• ..... 5

• -.... 6

• --... 7

• ---.. 8

• ----. 9

• ----.. \

• ....-- /

• .--... [

• -..--- ]

• --..-- <

• ..--.. >

• ---... (

• ...--- )

• --..- {

• --..- }

• .----- .

• -..... comma

• ----.- _

• ....-. |

• -.----?

• .-.... !

• -....- ;

• .----. :

• .---. -

• ..---- $

• ...-.- %

• ...--. "

• ---..- @

• ..-... \

• --.--- backtick

• -...-- ^

• ---.-- ~

• ..---. #

• .---.. &

• -...- +

• ---.- =

• -..-- *

• ..-- Space

• .-.- Enter

• .-.--. Backspace

• --.... ESC

• --...- Shift

• -.-. Ctrl

• --.-- Alt

• .-..- Arrow Up

• .--.. Arrow Down

• .-.-.. Arrow Left

• .-.-. Arrow Right

• .....- Pg Up

• ...-.. Pg Dn

• ....... Home

• ...-... End

• ---...- Numlock

• --.-.. ScrollLock

• -----. Capslock

• -.-.. Insert

• -.--.. Delete

• --.--. PrtScn

• ---..-. Tab

• --.---- F1

• --..--- F2

• --...-- F3

• --....- F4

• --..... F5

• ---.... F6

• ----... F7

• -----.. F8

• ------. F9

• ------- F10

• .------ F11

• ..----- F12

Sending key combinations

In a typical keyboard you might need to send multiple keys being held down at once. To do this we need to use the HOLD and RELEASE codes

.---.-. HOLD

Send this command first to hold down any key/mouse click and then after send command for key/mouse clik you want to hold

when you are done holding down keys you can release using this command

.---.-- RELEASE

e.g. HOLD Ctrl C RELEASE will hold down the ctrl and C key - and then release it. (NB: You could use sticky keys too if you wish which is a built in feature to most operating systems). We do have another way for common combinations too:

Repeat Command

An alternative way of holding a key is similar to what we do with mouse. You use this by typing a character, then pressing repeat - and it will repeat pressing that. Cancelling the repeat is with any press.

.---.-

Macro Mode

If a user types ....---- in either mouse or keyboard mode then the standard key set (e.g. A-Z etc) can be used with a macro. A user can define these in user/morse_code_shortcuts.py This way you just remember which letter or number is the macro.

Once the macro code is sent - it will revert back to the previous mouse or keyboard mode.

So for example. In Keyboard mode:

....---- (Macro Mode)

.- ("My favourite string here" is sent)

(Back to Keyboard mode)

Keymaps

Be aware that the way morAce works is its just a keyboard. It has no idea of language. What your recieving computers keyboard language is set to - it will send the key it thinks you are sending. You can either send real key presses e.g. [Keycode.SHIFT, Keycode.FIVE] will send the Shift key and the 5 key. On a computer which thinks it has a UK keyboard - that will emit a % but it maybe something else on a different language. Or you can send predefined key mappings - e.g. if you have "%" in either user/morse_code.py or user/morse_code_shortcuts.py the morAce code looks up the correct key mapping fromuser/keymaps which defines this like

You can define what a standard keymap it should be by setting the language in the top of morsecode.py and morse_code_shortcuts.py

You can find already defined keymaps in user/keymaps

morAce

morAce is a Arduino project designed to work with the range of arduino boards - and converts 1, 2 or 3 switch inputs into HID keyboard/Mouse commands. A mode switch allows the device to switch between connected devices meaning you can use this on different computers - with no software or cables since its over Bluetooth

What does it do exactly?

You can use switches (1, 2, or 3) to send morse code signals which are then intepreted by the morAce as Keyboard strokes or mouse movements. Its configurable by editing the arduino file. It will work on any device that listens to a Bluetooth keyboard our mouse - such as an iOS device, Mac, Windows devices. Also with a fourth switch you can change which device it is currently connected to. It cycles between already paired devices.

Want to learn morse?

Try our Project.

Or if you are on a PC and want a way of learning how to use the morse with visual feedback (and word prediction) try .

Why did you make this?

We had 1 then 2 then 3 clients who all needed Morse input solutions for speech. These were typically adults who were literate and either had a significant visual difficulty and reduced physical skills (but in general at least one switch site or two switches with good timing skills) or had learnt morse earlier in life. See a bit more on this . As much as other solutions existed we needed to do it over bluetooth - and two clients needed it to work across phone and a windows device.

Why is it called morAce? How should I pronounce that?!

More-Ace. or Maurice. Whatever you prefer. Thanks to for naming this. Little did he know when he came up with that , who initally wrote this comes from a family where morse code and radio operating was talked about a lot as his dad - Maurice James Wade (Jim) spent his early years as a radio operator for Cable ships sailing the world.

Bill of materials

1 x Ace Centre x80 or:

• x1 or

• x3 (or any )

• x1

• x1

• x1

• x1 Neopixel

Download the firmware here. Note - if you prefer C take a look at the ArduinoC branch. We wont be keeping this up to date but has most of the key features.

Arduino wiring

• Pin 10 - Morse Key 1 State: Active Low (External switch)

• Pin 11 - Morse Key 2 State: Active Low (External switch)

• Pin 12 - Morse Key 3 State: Active Low (External switch)

• Pin 5 - Buzzer State: Active Low (External switch)

• USER Switch - Switch for Connection Swapping State: Active Low (On board - Feather User SW)

• CONN LED(Blue) - LED indication for BLE Connection status State:Active High ("On board - Feather CONN LED - Blinking : Advertising, Not connected, Steady ON : Connected, Not advertising")

Usage

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Files

For the main branch (CircuitPy):

• boot.py - Code that runs on boot. Note the logic in here to turn on/off filesystem wriing

• code.py - The main loop

• extern.py - Helper functions

• morseCode.py - morse code mapping

• userConfig.py - User configurable data. Should be well documented

• userPinMap.py - Map your pins here

• x80PinMap.py - Uses our X80 pin maps

• Morse_BLE_HID.ino - Main source code file

• morseCode.cpp - Library source code file for Morse Code related functions

• morseCode.h - Library header file for Morse Code related functions

• userConfig.h - Configuaration File for settings

• userPinMap.h - Pin mapping file

Why? Why not a different project?

We needed a BLE HID Switch->Morse system - that allowed swapping between several different devices - AND - switching between switch scanning and morse input.

Credits

• Adafruit. For being amazing.

Similar projects

License

The command to change devices is

-.-.--

When this is sent morAce will drop connection with the current connected device and try connecting to the next last paired device. Note - if it doesnt connect within a set time frame (last_connection_check_timeout). It wil return back to the previous connected device.

You can pair a new device once you go into this mode. The max number of devices you could connect to is set by maxSwapConn