-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
GITBOOK-87: Rewritten the front page - I think easier to read
- Loading branch information
1 parent
58c8760
commit 1e2a491
Showing
25 changed files
with
350 additions
and
309 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,56 +1,62 @@ | ||
| --- | ||
| description: Overview of the project and its components | ||
| cover: .gitbook/assets/jessimage.jpeg | ||
| coverY: 0 | ||
| --- | ||
|
|
||
| # Welcome to the RelayKeys Docs! | ||
| # 😎 Introduction | ||
|
|
||
| > These Docs will help get you up-and-running quickly, guide you through advanced features, and explain the concepts that make RelayKeys so unique. | ||
| Welcome to the RelayKeys Documentation! This comprehensive guide will help you swiftly get started, explore advanced features, and delve into the unique concepts that define RelayKeys. | ||
|
|
||
| ## What is RelayKeys? | ||
| ### Introduction to RelayKeys | ||
|
|
||
| **RelayKeys is an open-source suite of software & hardware for communicating with computers, tablets, phones over a bluetooth connection.** It has been designed to work with AAC (Alternative & Augmentative Communication) devices first and foremost but the technology behind this is useful to many people who need to input text/mouse commands on one computer to access another bluetooth-enabled device. | ||
| RelayKeys is an open-source software and hardware suite designed to facilitate seamless communication between computers, tablets, and phones via Bluetooth connections. While initially tailored for Alternative and Augmentative Communication (AAC) devices, its versatile technology extends its utility to a broader range of users who require text input or mouse commands to access Bluetooth-enabled devices. | ||
|
|
||
| ### Why? | ||
| #### Purpose and Benefits | ||
|
|
||
| Well a range of purposes. For some - its just a convenient way of saving some money on a [KVM switch](https://en.wikipedia.org/wiki/KVM\_switch) - or replacing now hard to find [commercial solutions](https://docs.acecentre.org.uk/products/v/relaykeys/developers/other-projects). | ||
| RelayKeys serves various purposes: | ||
|
|
||
| For the [AceCentre](http://acecentre.org.uk/) we want people with disabilities who are forced to use one system (e.g. a dedicated Eyegaze system) to be able to access other computers and systems they may need to use for work or leisure. This has only been available on a couple of commercial AAC systems - and often need to be on the same network which is sadly often impossible in schools or government workplaces - Or they do work over bluetooth but for only one system in the field exists like this (see [here for more details on these](https://docs.acecentre.org.uk/products/v/relaykeys/developers/other-projects#aac-projects)). Some people may also want to just control their tablet or phone using this technique rather than rely on computer control functions - for example to control music software or photo editing software which usually demands the full screen. Or others want to make custom full screen custom keyboards using their specialist software. | ||
| * **Cost-Effective Solution**: For some, it provides 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 crucial for work or leisure. Unlike limited commercial solutions, RelayKeys functions across devices and doesn't necessitate a shared network. It acts just like a Bluetooth keyboard and mouse - so there is minimal lag.  | ||
| * **Custom Control**: Users can use RelayKeys to control their tablets or phones, particularly useful for tasks like music editing or photo manipulation, which typically demand full-screen control. Any device which responds to a Bluetooth keyboard or mouse will work - e.g. smart TV's. | ||
| * **Open System**: RelayKeys' open architecture ensures longevity and fosters collaboration for system improvements, aiding both people with disabilities and the general population. | ||
|
|
||
| **Why not just rely on other solutions?** Some commercial solutions are great. We advocate using them over our solution when you can. When you can't (e.g. no alternative or restrictions to what devices you can control) then this may be a solution. | ||
| {% embed url="https://www.youtube.com/watch?v=2wrZMGWgvcE" %} | ||
|
|
||
| **We are a commercial developer.. I like it but I think I could do it differently**. Thats great! But please consider the end user. If you as a commercial supplier dont want to continue making this hardware/software solution in the future consider a route to how a user could use a open solution. Please consider either replicating our command set at a serial or CLI level. Are we missing something that your solution provides? Please let us know so we can improve it. | ||
| ### Why Choose RelayKeys? | ||
|
|
||
| **Why not just do this in software alone?** Sure. If you can. On windows - its not possible.. Yet. Maybe in Windows 11. In MacOS it _should_ be - and iOS & Android its definitely possible. But our solution kind of offloads the problem. If you work in one of the mobile environments and want to replicate the functionality go for it - just please consider following some similarity in command structure (take a look at the macros for example) | ||
| While other commercial solutions exist, RelayKeys offers a unique set of advantages: | ||
|
|
||
| **By creating an open system we aim for longevity; even if a developer wants to create their own system we ask to make it compatible by using the same standard way of calling devices.** | ||
| * **User-Centric Approach**: We encourage commercial developers to consider user needs and explore open solutions. If our approach doesn't align with your vision, consider adopting our command set for compatibility and improvement. | ||
| * **Complementary to Software**: RelayKeys has a number of ways it can work with your own software. We have examples of how it can work with AAC Software and an example standalone app written in Python. We can even show examples of how it can be used to display text on [a separate second screen](https://github.com/AceCentre/open-ble-screen).  | ||
| * **Standardization for Compatibility**: An open system ensures compatibility and simplifies development, making it easier for developers to create their own solutions that align with our command structure. | ||
|
|
||
| {% embed url="https://www.youtube.com/watch?v=2wrZMGWgvcE" %} | ||
| **Short demonstration of the main aspects of RelayKeys** | ||
| {% endembed %} | ||
| ### Core Principles | ||
|
|
||
| RelayKeys is built upon a set of core principles that define its essence: | ||
|
|
||
| ## Core Principles | ||
| * **No Client Software/Hardware**: Designed to accommodate workplace and education settings, RelayKeys operates without requiring additional software or hardware on the client device. As long as Bluetooth LE support is present, RelayKeys is functional. | ||
| * **Device Agnostic**: RelayKeys isn't tied to specific devices or software solutions. Its versatility empowers developers to leverage it in various ways, fostering innovation. | ||
| * **Open Architecture**: RelayKeys is an open and transparent system, distinct from closed, proprietary alternatives. This openness encourages collaboration and ensures that technology remains viable even as manufacturers shift focus. | ||
|
|
||
| * **No-Software/Hardware on Client** — Because so many people have restrictions in the workplace or education settings we have designed this solution to not use any additional software or hardware for the client device. This means as long as your client device _supports Bluetooth LE_ then RelayKeys will work. | ||
| * **Agnostic** — RelayKeys is not specific to certain devices or software solutions. It is not designed for anyone piece of software or hardware. We aim to make a solution that is broad in scope and allows a developer to use this how they wish. | ||
| * **Open** — RelayKeys is not a closed, obfuscated, or black-boxed system. Alternative systems have existed for AAC but when technology becomes dropped by manufacturers engineers and clients alike struggle to keep their equipment working. By keeping the technology open we hope that others can fix and develop the solution. Equally, the technology used in this is not just useful to people with disabilities but the general population. We aim to share our progress and hope others build on it. By working together we aim to reduce the steps and overheads to get this feature in all AAC software and other technology solutions; commercial or open-source alike. | ||
| ### The RelayKeys Ecosystem | ||
|
|
||
| ## The RelayKeys Ecosystem | ||
| The RelayKeys ecosystem comprises several key components, each serving a specific role: | ||
|
|
||
| There are several components of the RelayKeys ecosystem, below is a brief overview. Remember that the software below works on one computer (a _**server computer**_ - often the AAC device) and the computers/tablets/mobile phones it connects to are _**receiving devices**_. | ||
| #### RelayKeys-Serial API (RK-Serial) | ||
|
|
||
| ### RelayKeys-Serial API (_aka_ _RK-Serial_) | ||
| Our standardized API enables seamless communication with RelayKeys-compatible hardware devices over serial connections, including USB buses or Bluetooth serial connections. For more information, refer to the [link](https://relaykeys.example.com/rk-serial). | ||
|
|
||
| We have defined a standard for calling a RelayKeys (or RelayKeys compatible) hardware device when available over serial. RelayKeys can be used over a USB bus or Bluetooth serial connection. See [here](developers/relaykeys-serial.md) for more information. | ||
| #### RelayKeys-Service (RK-Service / Daemon) | ||
|
|
||
| ### RelayKeys-Service (_aka_ _RK-Service_ / _Daemon_) | ||
| The RK-Service functions as an RPC service, receiving incoming connections and processing commands. These commands are translated into AT-Commands, simulating HID Keyboard/Mouse actions. The AT Commands are then transmitted via serial connection to Bluetooth-enabled secondary devices. An installer is available for continuous operation on Windows. | ||
|
|
||
| This is a [RPC](https://en.wikipedia.org/wiki/Remote\_procedure\_call) service that listens for incoming connections and parses the commands. These commands are then converted to AT-Commands that are HID Keyboard/Mouse commands. These AT Commands are then sent over a serial connection to a piece of hardware that talks in Bluetooth to a secondary computer. On Windows we have built an installer that runs this continually. | ||
| #### RelayKeys-QT (RK-Desktop) | ||
|
|
||
| ### RelayKeys-QT (_aka_ _RK-Desktop_) | ||
| RK-Desktop is a windowed application responsible for capturing keystrokes and future mouse inputs. It forwards this data to the RelayKeys Service for processing. | ||
|
|
||
| This is a windowed application that captures keypress' (and one day mouse input) and sends this data to the RelayKeys Service | ||
| #### RelayKeys-CLI (RK-CLI) | ||
|
|
||
| ### RelayKeys-CLI (_aka_ _RK-CLI_) | ||
| The RK-CLI provides a command-line interface for interacting with RelayKeys, offering a versatile and efficient method for users comfortable with terminal-based interactions. | ||
|
|
||
| This is a '_command line interface_' which allows programs that do not support native RPC calls to talk to the Service. It allows us to abstract certain features away from the service - and do more complex things like capturing the pasteboard of the computer. | ||
| This documentation aims to empower you with the knowledge needed to harness RelayKeys' capabilities fully. Whether you're an AAC user seeking expanded access or a developer working on groundbreaking solutions, RelayKeys offers a platform that promotes accessibility and innovation. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| # Developing without a board | ||
|
|
||
| If you are developing the 'server' side of things and want to try out the code you can run this without any hardware by having a null serial terminal. To do this, in a terminal run: | ||
|
|
||
| ``` | ||
| python resources/demoSerial.py | ||
| ``` | ||
|
|
||
| then in another terminal run | ||
|
|
||
| ``` | ||
| python relayekeysd.py --noserial | ||
| ``` | ||
|
|
||
| NB: Only tested on MacOS but should work on any posix system. For Windows simply give a COM port that doesn't exist. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.