The easiest way to get up-and-running is with the Windows Installer, which includes the RelayKeys-CLI, and the RelayKeys-Desktop software. Read on to see how to install and setup.

A quick reminder of how this works

So RelayKeys consists of a hardware solution that talks Bluetooth HID to secondary devices - anything that can pair with bluetooth and understand a keyboard works, and some software on the 'server' device; i.e. the device sending the key/mouse movements. So for our installation we really focus on the 'server' since the recieving device needs no additional hardware or software.

Requirements

RelayKeys is designed to work on Windows, Linux, and Mac Operating Systems. We have built a Windows installer that makes the process easier on that platform. For Mac & Linux, you will need to build the app from the source.

• Windows 7-10

• A USB Port

• Ability to Install the software as Administrator

• A second device to connect to Could be a Windows computer, a Mac, an iPad etc

and most importantly:

• A supported piece of RelayKeys-ready hardware

  • Right now: this is designed to work with the Adafruit nrf52840 express, Adafruit nrf52840 Itsybitsy or Raytac nrf52840 dongle Others will be added to the list as this is developed.

  • Note: if you wish to use a dongle to receive - instead of relying on a device's internal Bluetooth and pairing etc - you will need a second board.

There are 3 broad configurations for RelayKeys

• Wired Mode. This is where one Bluetooth dongle is in the Sending device

• Wireless Mode. This is where a Bluetooth dongle plugged into a power outlet or a battery sits away from the Sending device. This might be useful for devices where you cannot plug anything into the sending device

• Wired + Receiving Dongle. A receiving dongle sits in the receiving device. This is useful where "pairing" is unreliable on the recieving device or there is no Bluetooth stack on the receiving computer.

You need to decide what is best for you.

Plug in your receiving dongle to a device. Your device will see this as a keyboard attached. If you are asked to press some keys for the device to understand it, just close this window for now.

On the sending side, it will pair by default with the receiver. You don't need to do a thing. However, if you have gone and paired with any other devices, you may find this not work. You will need to remove any paired devices and try again.

Either use the drag and drop UF2 method or more steps involved - Arduino uploading method. For the UF2 method

• Download the UF2 file for the itsybitsy board in the current release

• Double click that reset button. You will then get a USB drive on your computer. Drag and drop the UF2 file to the root of that drive.

• It SHOULD disconnect from your pC if successful – but as I say the loghts should change colour to Green

• More details see the steps here

Or the Arduino uploading method.

• Check the setup of your Arduino IDE (remember we're using the nRF52840 board!)

• Upload the sketch to your feather.

• Run the server side code

• Done!

A wide range of Arduino boards supports HID (Human Interface Device). Often these are to emulate simple keypress' but to do more complex things like send one or modifier keys with a key - or to emulate holding a key down for a set period of time is either impossible or difficult to implement. Adafruit has developed the firmware on their Bluefruit nrf* range of boards to emulate HID keyboards well using their AT Commands.

Currently, RelayKeys is designed to work with

• the Adafruit Raytac nrf52840 dongle (Buy from the piHut or Digikey). Note this is the cleanest looking solution and one of the cheapest. We have pre-prepared firmware for this for both receiving and sending.

• Adafruit Feather nRF52840 Express (Buy in the UK from Pimoroni). Note you can use this or the itsybitsy with a battery and have relaykeys work without connecting it directly to your AAC device.

• or with the Adafruit itsybitsy nrf52840

• or with lesser support for the The Adafruit - Bluefruit LE Friend - nRF51822 - v3.0 (Buy in the UK from Pimoroni). Although Note: We really aren't supporting the LE Friend much - we do hear it works, but dragons, beware! See below for details on configuring these.

Once you have your hardware you need to configure and set them up to work with relaykeys. Read on for how you do this for each device.

Either use the drag and drop UF2 method or more steps involved - Arduino uploading method. For the UF2 method

• Download the UF2 file for the raytac dongle in the_ current release__

• Press and hold thr reset button as you plug it into the computer. You will then get a USB drive on your computer. Drag and drop the UF2 file to the root of that drive.

Or the Arduino uploading method.

• Check the setup of your Arduino IDE (remember we're using the nRF52840 board!)

• Upload the sketch to your feather.

• Run the server side code

• Done!

Welcome to the RelayKeys Documentation! This guide will help you swiftly get started, explore advanced features, and understand the concepts that define RelayKeys.

Introduction to RelayKeys

RelayKeys is an open-source software and hardware suite designed to facilitate seamless communication between computers, tablets, and phones via Bluetooth connections. Initially tailored for AAC, its versatile technology extends its utility to a broader range of users who require text input or mouse commands to access Bluetooth-enabled devices.

How do you get it?

You need a piece of hardware - a USB dongle that provides the bluetooth harware to allow your device to be a Bluetooth Keyboard/Mouse. You plug this into your AAC (Host) Windows based device. You can either use a receiving USB dongle on a second device to act as a Bluetooth receiver for devices that don't support bluetooth (and this is pre-paired) or connect directly to Bluetooth enabled devices (Phones, Computers). Once you have the hardware you need to which is designed for Windows.

Purpose and Benefits

RelayKeys serves various purposes:

• Cost-Effective Solution: For some, it offers a cost-effective alternative or replacement for pricey or obsolete hardware.

• Accessibility for Disabilities: Our primary focus is on empowering individuals with disabilities. RelayKeys enables users who rely on dedicated AAC systems, such as Eyegaze, to access other devices essential for work or leisure. Unlike some commercial solutions, RelayKeys functions across devices without needing a shared network. It acts just like a Bluetooth keyboard and mouse, ensuring minimal lag.

• Custom Control: Users can utilize RelayKeys to control their tablets or phones, especially beneficial for tasks like music editing or photo manipulation, which typically require full-screen control. Any device responsive to a Bluetooth keyboard or mouse will work, e.g., smart TVs.

• Open System: RelayKeys' open architecture ensures longevity and promotes collaboration for system improvements, benefiting both individuals with disabilities and the general population.

Why Choose RelayKeys?

While other commercial solutions exist, RelayKeys offers unique advantages:

• User-Centric Approach: We urge commercial developers to prioritize user needs and explore open solutions. If our method doesn't resonate with your vision, consider adopting our command set for compatibility and enhancement.

• Standardization for Compatibility: An open system ensures compatibility and streamlines development, facilitating developers to craft solutions that resonate with our command structure.

Core Principles

RelayKeys adheres to core principles that underpin its philosophy:

• No Client Software/Hardware: Catering to workplace and educational environments, RelayKeys functions without necessitating extra software or hardware on the client device. Provided Bluetooth LE support is available, RelayKeys operates seamlessly.

• Device Agnostic: RelayKeys isn't restricted to specific devices or software solutions. Its adaptability allows developers to apply it diversely, promoting innovation.

• Open Architecture: RelayKeys is a transparent and open system, standing apart from closed, proprietary counterparts. This transparency fosters collaboration and ensures technology remains relevant despite shifting manufacturer priorities.

The RelayKeys Ecosystem

The RelayKeys ecosystem includes key components, each fulfilling a particular function:

RelayKeys-Serial API (RK-Serial)

RelayKeys-Service (RK-Service / Daemon)

The RK-Service acts as an RPC service, accepting incoming connections and interpreting commands. These commands are converted into AT Commands, mimicking HID keyboard/mouse actions. The AT Commands are subsequently relayed through a serial connection to Bluetooth-integrated secondary devices. A Windows installer facilitates continuous operation.

RelayKeys-QT (RK-Desktop)

RK-Desktop is a windowed application tasked with capturing keystrokes and future mouse actions. This data is then relayed to the RelayKeys Service for translation.

RelayKeys-CLI (RK-CLI)

The RK-CLI offers a command-line interface for RelayKeys interaction, serving as an adaptable and efficient tool for those familiar with terminal operations.

Harness the full potential of RelayKeys with this documentation. Whether you're an AAC user aspiring for extensive accessibility or a developer pioneering innovative solutions, RelayKeys presents a platform championing accessibility and creativity.

1. Eyegaze: A technology that tracks where a user is looking on a screen, typically used as an input method for those with limited physical mobility.

2. Daemon: A background process that runs on a computer system, often providing or facilitating services.

• Update it to 0.8.1. Easiest way to do this is to connect to using the Bluefruit app - it will auto-update it if required.

• Plug it in

• Set the switch on the device to CMD mode

• Open up a serial terminal and connect to the device (See for exact settings for your Operating System)

• Turn on HID Mode. More info . To be precise - enter this into your serial terminal

  Copy

    AT+BLEHIDEN=1
  
    ATZ 

(You should see 'OK' after each entry)

• Next change the default speed. i.e. enter this in your serial terminal:

  Copy

    AT+BAUDRATE=115200

• Next put the device into (slide the switch).

• Finally - update the relaykeys.cfg file with

  Copy

    baud = 115200
    

(Or whatever speed you so wish)

Note that this mode is useful on devices where you can't plug anything into your device. The setup can feel strange - what we need to do is tell your relaykeys hardware the device to connect to.

1. Plug in device and follow instructions

2. Pair the main AAC/Host device with it. So pair the computer you have attached it to with RelayKeys hardware. This can feel a bit strange - you are connecting the hardware to the same machine you are on. See for how to put it into pairing mode.

3. Disconnect the relaykeys hardware. In your bluetooth settings you actually need to click on the item and "Remove" device. (NB: If you cant do this it might be because you need to be an admin. The trick is open the Control Panel -> Devices & Printers -> Relaykeys -> Right click, Remove and you will be asked for an Admin password)

4. Plug relaykeys into a power source - away from the computer. Your RelayKeys may have a battery or you might need to plug into a wall USB power source.

5. Double press the User switch It should now shine a nice blue colour!

6. Run RelayKeysd with --ble_mode See for more details

Download the installer from . When downloaded 'Run' the program

Step through the installation procedure. Select 'Normal install' and let the RelayKeys setup software do its thing to install the software in the correct place (By default: C:\Program Files (x86)\Ace Centre\RelayKeys).

Plug-in Your RelayKeys stick & pair with a computer (Wired mode)

1. Make sure the Micro-USB connector is attached to the stick and then attach the female end of the USB lead into your computer

2. You should see your stick light a solid blue ("Paired") or flashing blue ("Un-paired")

If "Flashing". This means you have yet to pair the RelayKeys device with another computer.

Put RelayKeys into a pairing mode

You can do this in three different ways:

• Send a command using the "relaykeys-QT.exe" app and press "Add a device" in the toolbar - or -

• Run "relaykeys-cli.exe ble_cmd:devadd" - or -

• Press the Button on the RelayKeys hardware. It will now flash yellow

• Next pair your device with RelayKeys.

Pair with a Windows Computer

So to connect to Another Windows computer, go to Settings, Bluetooth, "Add a device", and connect to "AceRK"

Pair with an iOS device

Pair with a Mac

To connect to a mac, Open up "System Preferences", Bluetooth and add "AceRK"

Either use the drag and drop UF2 method or more steps involved - Arduino uploading method. For the UF2 method

• Download the UF2 file for the feather nrf52840 express board in the __

• Double click that reset button. You will then get a USB drive on your computer. Drag and drop the UF2 file to the root of that drive.

• It SHOULD disconnect from your Computer if successful and the light should change colour to Green

• More details see the steps

Or the Arduino uploading method.

• Run the server side code

• Done!

You can use RelayKeys in a number of different ways depending on your needs

• Using our desktop software

• Using a Command Line Application (that Third-party software such as AAC software can use)

• Directly communicate over serial in your software.

1. Open up something on the second computer that you can enter text into. E.g. Notes on the iPad, Notepad on Windows or Notes on a mac

2. On your server computer (the one with RelayKeys attached) run "RelayKeys" (search for it in your Windows search bar). Alternatively find it in C:\Program Files(x86)\Ace Centre\RelayKeys\relaykeys-qt.exe

3. With the window having focus - type into it. You should see the keystrokes appear on the second computer

Using it with your AAC software

You can get going by using one of these example files that work with your AAC Software:

• The Grid 3

• MindExpress

• Tobii Communicator

• Tobii Dynavox Snap

When you are ready, have a read of how to integrate the features you need.

👍 You've successfully installed and setup RelayKeys! Now you may want to use the CLI or QT program. Read on to find out how these work.

😞 Got a problem? Dang! See our troubleshooting guide.

If you don't want to use any specific AAC software, you can get going with our demonstration software "RelayKeys-QT" (aka RelayKeys or RelayKeys Desktop). You will find this on your desktop as well as your start programmes if you have installed our software. It has 4 main buttons on the left:

Capture

This screen enables you to capture the keystrokes and mouse movements and any captured input gets sent directly to the currently connected device. To connect a device - see "Devices" screen.

Macro

This screen enables you to create a macro file. This records your mouse or keystrokes and enables you to play it back. This is useful for creating long sequences of commands or say for writing a common piece of text such as a signature. You can play it back in this software or use the macro with the CLI tool.

Connection

This screen enables you to switch between paired devices and change the current mode. This means the RelayKeys hardware can run either as a wired dongle or a wireless device. Use the switch mode to change these modes.

Devices

This screen enables you to add and remove paired devices - as well as removing all devices from the relaykeys hardware.

Most AAC software has a way of connecting to an external application. Some call this "Run Programme or something similar. As long as RelayKeys is installed and the correct hardware is connected you can then call the installed command line application - with the correct syntax.

Take a look at the guides for your software.

The key application you want to access is the relaykeys-cli-win.exe found in C:\Program Files (x86)\Ace Centre\RelayKeys \ For a full list of commands you can send see here.

A tip on notifications

If you pass the --notify flag to the cli application you will get notifications about the devices you are connected to and the status of the device. See here for more information

There is no documented way for third parties integrating their software into commercial AAC software for example integrated notifications. So we have to make use of the operating system notification system. The difficulty on Windows is that by default full screen apps do not see notifications. So to make this work we recommend three alterations to your notifications.

1. Turn Focus Assist off.

2. Turn off the setting "When I'm using an app in full screen mode"

And next - because AAC users wont typically be able to dismiss notifications change the time that they appear for. To do this follow the steps here.

is a AAC software for Tobii Dynavox communication aids . Follow the steps below to add commands to your pageset

Sending the message bar

This is the best way to enter longer texts and allows you to use the communication aid's prediction and phrase banks etc. Use the "Copy" command followed the Run Program command to run relaykeys-cli-win.exe with the paste argument

Simple keystrokes

This is useful for making a keyboard-like page with individual letters and other keys that send one keystroke at a time. Use the Run Program command to run relaykeys-cli-win.exe with the keypress:LETTER argument (where letter is the key you want to send)

Sending keyboard shortcuts

For special commands and shortcuts such as control-C, alt-F4 etc use the Run Program command to run relaykeys-cli-win.exe with the keypress:KEYNAME,MODIFIER argument (where keyname is the key you want to send)

Sending mouse commands

Use the Run Program command to run relaykeys-cli-win.exe with the mousemove:X,Y argument (where X,Y is the distance you want to move the mouse), or the mousebutton:BUTTON,ACTION argument (where BUTTON is the button to use, and ACTION is click or doubleclick etc.)

Controlling RelayKeys

Use the Run Program command to run relaykeys-cli-win.exe with the ble-cmd:reconnect, ble-cmd:switch, or ble-cmd:devname --notify commands

Below are solutions to some common issues that you may experience when working with RelayKeys.

Installation Issues

I can install it - but when I send keystrokes nothing is appearing on the second device?

Try and go through these steps:

1. Is your relaykeys stick properly attached? Make sure the blue light is showing. If not you may have a loose connection somewhere.

2. Is it paired and connected? - you will know this if the blue light is steady (not flashing) on the relaykeys stick

3. check your COM port. Lastly, it may be that the software cannot find the RelayKeys stick in its list of COM ports. to configure and fix your COM port manually.

4. Check your casing and spacing. If you are using the command line applications, be careful - the application is case-sensitive. It should be type: and not Type: for example

It was working all fine but now its not!

Is it paired and been shown to be connected with the receiving device? If so - and its still not sending text you may need to remove the Bluetooth AceRK device and then pair the AceRK again. To do this open RelayKeys-QT app on the sending device - click on "Add device" and then pair on the receiving device.

So I send LSHIFT,2 and I was expecting " but I get a @ - What gives?

Have a look at the You'll need to define/edit a keyboard map for the keyboard you are expecting it to be.

Before you look at using RelayKeys with Snap have you considered ? Its available for TD software and is good! There are some snags - its not multi device compatible and does require the dongle being plugged in.

Adding an action - calling relaykeys

You need to edit your snap pageset - and create a "General" button - then you can add an action to a button. The action

The Grid 3 is a commonly used piece of software for AAC. Follow the steps below to add commands to your gridset

Simple keystrokes

Use the relaykeys-cli-win.exe with the keypress:LETTER argument (where letter is the key you want to send)

Sending the message bar

Use the "Copy" command followed by the relaykeys-cli-win.exe paste argument

Sending multiple commands - e.g. keyboard shortcuts

Sending mouse commands