flowm / etherkey

Emulate a conventional USB keyboard with a scriptable, network capable microcontroller.

Etherkey

Emulate a conventional USB keyboard with a scriptable network capable microcontroller.

By using dedicated hardware it is possible to control systems even before the operating system is booted and without being dependent on the running software. For example this allows automatic bootloder selectios or modification of BIOS settings.

Requirements

• Teensy (tested on Teensy 3 and 4.1),
• One of the following:
  • a) USB-to-UART Adapter, for example
  • b) Raspberry PI

Setup

• Flash the Teensy with the sketch in the etherkey folder. (Using Teensyduino)
• Connect the Teensy's USB-Port to the System you want to control.

a) Direct connection to Teensy

You may connect directly to the Teensy, using a USB-to-UART Adapter.

Connect Ground to Teensy's GND-Pin, TX to Pin 0, RX to Pin 1.

Now you can use any tool you like to connect to the Teensy. Baudrate is 57600, device most likely /dev/ttyUSB0 on Linux/UNIX. For example: cu -l /dev/ttyUSB0 -s 57600

b) Using a Raspberry PI for Network features

Example setup with a Raspberry PI for the ethernet connection.

Connect GND of the Raspberry to Teensy's GND-Pin, TX to Pin 0, RX to Pin 1.

When using Raspbian as operating system, the serial port must be configured for outgoing connections. After that a serial connection can be established with cu -l /dev/ttyAMA0 -s 57600. On newer Raspberry PI or Raspbian versions you might need to use /dev/serial0 instead.

Usage and Syntax

Mode selection

Ctrl+Q to switch between modes.

Available modes:

• Interactive mode
• Command mode
• Debug mode

Interactive mode

Directly sends the recieved keystroke Supported Characters:

• All printable ASCII characters
• Arrow keys
• Backspace
• Enter
• Delete
• Tab
• Escape

Command mode

Parses the whole line and interprets the first Word as command. Available commands:

SendRaw

Sends the rest of the line literally

Send

Sends the rest of the line while interpreting special characters. This command behaves similarly to the send command of AutoHotkey

Modifiers

The following characters are treated as modifiers:

• !: Send the next character with the ALT key pressed.

  Example: Send text!a sends the keys "This is text" and then presses ALT+a.

• +: Send the next character with the SHIFT key pressed.

  Example: Send +abC sends the keys "AbC".

• ^: Send the next character with the CTRL key pressed.

  Example: Send ^c sends a CTRL+c keystroke.

• #: Send the next character with the WIN key pressed.

  Example: Send #d sends a WIN + d keystroke.

These modifiers can be combined, so a ^+t would send a CTRL+SHIFT+t, thus restoring the last tab in Firefox.

Keynames

Non printable characters can be sent by specifying the keyname enclosed in braces:

• {Enter}
• {Escape}
• {Space}
• {Tab}
• {Backspace}/{BS}
• {Delete}/{Del}
• {Insert}/{Ins}
• {Up}
• {Down}
• {Left}
• {Right}
• {Home}
• {End}
• {PgUp}
• {PgDn}
• {Windows}/{Win}
• {F1}..{F12}

These keynames can also be combined with modifiers. For example Send ^!{Delete} sends the CTRL+SHIFT+Delete combination.

Escape sequence

To send a single character literally, it can be enclosed in braces:

• {x}
• {!}
• {+}
• {^}
• {#}
• {{}
• {}}

This syntax can also be used to repeat a keystroke multiple times:

Enclose the character or keyname followed by a whitespace and the number of repetitions in braces.

• For example: {x 10} sends the x character 10 times and {Enter 5} presses the Enter key 5 times.

Unicode characters

Arbitrary Unicode characters can be sent by specifying the 4-digit character code after the operating system specific command:

UnicodeLinux or UCL

Initializes the GKT+/Qt Unicode Sequence and sends the following 4-digit hexadecimal Unicode Character.

• For example: {UCL 00F8}

UnicodeWindows or UCW (experimental)

Initializes the Windows Unicode Sequence and sends the following Unicode Character. Please note: Some Windows applications require 4-digit decimal Code (e.g. Wordpad, Chrome), some other require 4-digit hexadecimal Code (e.g. Notepad++, Firefox)

You might as well need to change a Registry Setting on your Windows machine.

• For example: {UCW 00F8}/{UCW 0248}

Debug mode

Displays information about the received character (ASCII code, USB keycode)

Client

TODO

Known issues/ Caveats

Keyboard Layouts

Due to the nature of the emulation on a USB keyboard layer, the list of available characters is determined by the keyboard layout on the target host.

Additionally only basic ASCII characters are transmitted correctly over the serial interface.

Thus an English keyboard layout is recommended for conventional usage. This is also configured by default in the Teensyduino development environment, but can be changed under "Tools" -> "Keyboard Layout".

To transmit other keys:

• Sending keys by their name in command mode

• Mixing keyboard layouts for transmission to send keystrokes defined by their position on the keyboard

  By setting the desired keyboard layout on the target system while configuring an English keyboard layout on the Teensy and the controlling system, it is possible to send keystronkes independent of the possibility to transmit the associated character. This works as the pressed key is interpreted on the controlling system.

etherkey's Issues

Teensy 4

Will this work with any of the Teensy 4 series? I'm brand new to the Arduino world, so I don't know enough to find out the answer to this myself yet.

The current note on the linked PJRC page says this: "Chips for Teensy 3.2 have been delayed until March 2023. Earlier this year we were told "gradual improvement in Q2" and limited supply in Q3 with most chips arriving by Q4. Now NXP has delayed the first chips until March 2023, and the rest until June 2023. PJRC is planning to resume production of Teensy 3.2 when these chips arrive, but if possible, we suggest switching to Teensy 4.0 or Teensy 4.1 for new projects. The IMXRT chip on Teensy 4 is less impacted by the global chip shortage. "

It would be great to be able to use this on a chip that's a little more widely available, since I'd like to get started on a project before June of next year... 😅

Interactive gtk client with json rpc support

This is not really an issue, but I just wanted to use this platform to announce a gtk based client that I wrote for etherkey. It is in my branch https://github.com/dov/etherkey/tree/with-mouse . Feel free to reject the issue.

With this client you can a fully working kvm solution for controlling two computers with one keyboard. And in addition, the host computer can send macros, and even files to the client computer by json rpc.

See the gtk-kvm-client/ReadMe.md file for a brief explanation about my branch.

Of course, none of this would have been possible without etherkey, for which I offer my thanks and appreciation!

Add Support for function Keys

Hello first of all thanks for sharing with us this great thing.

Could you please add Support for Fuction Keys ?
Like F1 - F12 so one could open the BIOS for example when the system is booting up ?

With modification, can this control two computers?

I'm interested in sending the exact same keystrokes to multiple computers at once. With some modification, would Etherkey be able to do this? I think it'd involve connecting a second Teensy to some other Raspberry Pi pins and transmitting the same signals to both Teensies.

If so, what part of the code should I modify?

Need Help with Etherkey Script for Mac-Windows Interaction

I'm reaching out as I'm quite new to this and could use some guidance with the Etherkey script. Firstly, thank you for providing this valuable tool.

I've been attempting to control a Windows PC from my Mac, utilizing the Etherkey system. However, I'm encountering some difficulties in getting the key presses to function as expected. While I've tried following the documentation, I'm not observing any key presses being sent.

Here's a brief overview of my setup:

Flashed Etherkey firmware onto a Teensy microcontroller.
Connected the Teensy to my Windows PC.
Connected my Mac to the Teensy via a USB to TTL cable.

My main questions revolve around the usage of the Etherkey script (Etherkey.py) and the interaction between my systems. I have a few specific concerns:

Running Location: Should I be executing the Etherkey.py script on my Mac or my Windows PC? I attempted running it from my Mac, modifying the serial_cmd to connect to PuTTY's COM port, but I only see a blank screen on PuTTY.

Modes: On Windows, the script indicates "connected," but I'm unsure about how to access the specific modes (Interactive, Command, Debug) as detailed in the documentation.

Also what would be the serial command if its a non linux machine

I would greatly appreciate any assistance you could provide in clarifying these points and helping me get the Etherkey system up and running effectively. Your expertise would be immensely valuable to someone like me who's just starting out.

Can this remotely wake up a computer through a usb connection

I have a gaming laptop but not supporting wake on lan or wireless lan. It can be waked through keyboard or mouse through clicking. Does this project help in this situation. If you have better solutions please le me know as well. Thanks!

Ctrl+Alt+Delete

Hi,

I have Etherkey working on an RPi 4B (using minicom) but am unable to send Ctrl+Alt+Delete to a Windows 10 PC. I tried using
Send ^!{Delete}
and
Send ^!{Del}
and other combinations, but this did not work. Individually the modifier keys work but not together with {Del}. Can you offer any advice?

By the way, I note that on recent Raspian releases I need to use /dev/serial0 rather than /dev/ttyAMA0 - perhaps the documentation can be updated. Speaking of which, what is the best way to Send a command like this from a command line (for me this is the primary use case)? Should I just pipe it to /dev/serial0 ?

Combined Modifiers Not Working

From both PuTTY and PySerial on Windows to a Windows target I was unable to send multiple modifiers in the format specified in the readme (^+t for CTRL+SHIFT+t). I played around with many different arrangements and ended up finding that for format ^T+ ended up working. I didn't get a chance to dig into your code to try and find a reason, but at least wanted to post this in case it helped someone else since there does seem to be a workaround.

For completeness: I used the instructions here for running your project on an Arduino based device rather than a Teensy.

Thanks,
James