Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
morAce is a Arduino project designed to work with the Adafruit nrf52840 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
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.
Try our Morse-Learn 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 MorseWriter.
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 here. 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.
More-Ace. or Maurice. Whatever you prefer. Thanks to Michael Ritson for naming this. Little did he know when he came up with that Will Wade, 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.
You dont have to use our circuitPy code using the Ace Centre's x80 but its easier. x80 is addon board for adafruit itsybitsy sized boards that allows simpler way of accessing switches and adds a buzzer to a Adafruit board. If you need to configure your adafruit nrf52840 feather express or nrf52840 itsybitsy - read this guide.
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
If you are not - you'll need to install them by:
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.
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.
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
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.
We recommend reading the rest of this guide before editing them so you understand what they do.
See sound_voiume
setting. Set it to 0-10 depending on how loud you want the buzzer feedback
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.
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
By default morAce is set to go to keyboard mode first. But you can toggle between keyboard mode and mouse mode with .-.--
.-
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
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:
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.
.---.-
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)
Note you can use keycodes e.g. [Keycode.LEFT_CONTROL, Keycode.C]
or strings with special characters e.g."First row\nSecond row"
. Just be aware of the language of the device you are typing into. You may need to set the keycode correctly for this to work reliably. See below for more information
You might want to consider making use of the operating systems own keyboard shortcuts. For example this is available in MacOS and iOS. On iOS this is found under Settings->General-> Keyboards-> Text Replacement.
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 from
user/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
These are the pre-defined keys. You can customise these by editing
(There are also some special keys. For a full listing view them in )
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 (.
)
-. (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
1 x Ace Centre x80 or:
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.
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")
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
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
We needed a BLE HID Switch->Morse system - that allowed swapping between several different devices - AND - switching between switch scanning and morse input.
Adafruit. For being amazing.
Warning: This wont work unless you've enabled your morAce to write the filesystem. See for how to do this.
x1 or
x3 (or any )
x1
x1
x1
See also this
Wire it all up. Set your settings in userConfig.py
. Make sure your board is setup to run CircuitPy (and ) and drag and drop the files to the CIRCUITPY disk drive. Pair your device with a compatible device (PC, Mac, Linux, iOS, Android) - and away you go.
There will be bugs. Please submit them to the .
All the Arduino code is in the sub-directory morace .
For the branch:
Tania Finlayson - and her husband for developing (and general all round awesomeness) for building . Please buy one if you want to support this project
Jim Lubin - and his fab Morse archive
- who have been great recently about pushing along the morse agenda
who helped immensely with a lot of the code on this project.
- Andrii Pavlyshyn who has done a lot of the changes to circuitPy and ironed out a lot of bugs.
- A really nice replica of the Adap2U sip/puff Morse code to keyboard/mouse system used by Jim Lubin. Its neat - runs on CircuitPython. The BLE libraries though arent full featured yet.
. One of the few that attempt to this project over bluetooth. Ours has a few more features than this.
. This was a bit of a kickstart to do this project (see also )
- a neat project which has some morse functionality built in using the . Also uses the feather. (See more at )
- a project to switch between switch scanning and using Gboard.
- this project has EVERYTHING you would ever need for proper morse code. We doff our cap..
Left Up .--.
Up -
Right Up ...-
Left ..
Right ...
Left Down ...--
Down --
Right Down ...---
Warning: This wont work unless you've enabled your morAce to write the filesystem. See here for how to do this.
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
If you need morAce to forget all your paired devices you just need to delete the database on the circuitpy drive