Convert your Android device into USB keyboard/mouse, control your PC from your Android device remotely, including BIOS/bootloader.
C C++ Java Makefile JavaScript HTML Other
Latest commit 7ea69c6 Feb 3, 2017 @pelya committed on GitHub Merge pull request #74 from ShapeShifter499/master
Shorten name of Moto X Pure patch
Permalink
Failed to load latest commit information.
asus-Zenfone-2-ZE551ML Asus Zenphone 2 kernel, by BORETS24h Dec 21, 2015
fastboot Fastboot binary should have executable flag Dec 17, 2013
hid-gadget-test Do not print help when running hid-gadget-test without -h Oct 18, 2015
lg-g2 LG G2 kernel by Şahin Kureta May 14, 2015
motorola-PhotonQ-CM11.0 More explicit name for Photon Q boot image Jul 7, 2015
nexus5-hammerhead-android-5.0 Updated readme Dec 24, 2014
nexus7-2012-wifi-grouper Experimental Boot mode switching in the USB HID driver, only for kern… May 25, 2015
not-tested Setting USB subclass to 1 (boot) seems to fix no input in MacOsX boot… Oct 22, 2014
old-do-not-use Added Boot mode patch to all other kernel patches May 25, 2015
remote-client Added built-in SDL keyboard Nov 2, 2015
send-pin-with-camera Added send-pin-with-camera app sources to the repo Feb 7, 2015
sony-xperia-z5p Image for Sony Xperia Z5 Premium, curtesy of moon butt74 Feb 23, 2016
sony-z5c Kernel for Sony Z5 Compact, by joe isgood. Nov 26, 2016
.gitmodules Cleaned build files Feb 7, 2015
LICENSE Initial commit Dec 16, 2013
README.md Updated readme Nov 26, 2016
USB-Keyboard.apk Updated .apk file Nov 2, 2015
kernel-3.0.31-galaxy-s2.patch Patch for Samsung Galaxy S2 (GT-I9100) Nov 3, 2016
kernel-3.1.patch Experimental Boot mode switching in the USB HID driver, only for kern… May 25, 2015
kernel-3.10-MotoXPure.patch Shorten name of Moto X Pure patch Feb 2, 2017
kernel-3.10-jiayus3.patch Update jiayus3.patch to Kernel-3.10.104 Nov 20, 2016
kernel-3.10-nexus6.patch Added Boot mode patch to all other kernel patches May 25, 2015
kernel-3.10-nexus9.patch Added Boot mode patch to all other kernel patches May 25, 2015
kernel-3.18.patch Add patch for Android kernel 3.18 Nov 20, 2016
kernel-3.4-HtcOneM8.patch Adding kernel patch for HTC One M8 Oct 24, 2016
kernel-3.4.patch Added Boot mode patch to all other kernel patches May 25, 2015

README.md

Convert your Android device into USB keyboard/mouse, control your PC from your Android device remotely, including BIOS/bootloader.

Apps & tools using android-keyboard-gadget:

Installation

Nexus 7 2012 WiFi (Grouper)

  • Plug your device into PC using USB cable.
  • Power off the device.
  • Hold Volume Down button and Power button for 5 seconds, to enter fastboot mode.
  • Copy appropriate fastboot executable from the directory fastboot.
  • Launch command fastboot oem unlock
  • Confirm unlock action by pressing Power button. This will factory reset your device.
  • Copy boot.img from directory nexus7-2012-wifi-grouper.
  • Launch command fastboot flash boot boot.img.
  • Reboot your device using Power button.
  • Install and run USB Keyboard app.

Nexus 7 2013

LG G2

LG G2 with Cyanogenmod 12.0

Nexus 5

Nexus 4

Sony Ericsson phones

Motorola Moto G with Cyanogenmod

Motorola Moto E with Cyanogenmod

Motorola Moto G 2014

OnePlus One

Galaxy S4

Galaxy Note 2

Huawei Ideos X5

Sony Xperia Z3 and Z3 Compact

Sony Xperia Z Ultra

Xiaomi Redmi 1S

Galaxy Ace 2

Xiaomi MI3

Galaxy Note 4

Asus Zenfone 2 ZE551ML

Sony Xperia Z5 Premium E6853

Sony Xperia Z5 Compact

Xiaomi Redmi 2

Sony Xperia SP

http://forum.xda-developers.com/xperia-sp/development/kernel-helium-v1-t3251298

Xiaomi Redmi Note 3

Other devices

  • You will have to compile the kernel yourself.

Scripting

There is a possibility to send keypresses in an automated way, using terminal emulator for Android or similar app. This is done using hid-gadget-test utility.

First, copy this utility to your device.

adb push hid-gadget-test /data/local/tmp
adb shell chmod 755 /data/local/tmp/hid-gadget-test

You will need to set world-writable permissions on /dev/hidg0, or run hid-gadget-test from root shell.

adb shell
su
chmod 666 /dev/hidg0 /dev/hidg1

To always have root shell, so you don't need to enter 'su' each time, run command

adb root

Then, use hid-gadget-test to send keypresses.

adb shell
cd /data/local/tmp

# Send letter 'a'
echo a | ./hid-gadget-test /dev/hidg0 keyboard

You can also run this command without launching ADB shell, from shell script or .bat file.

adb shell 'echo a | /data/local/tmp/hid-gadget-test /dev/hidg0 keyboard'

Advanced examples.

# Send letter 'B'
echo left-shift b | ./hid-gadget-test /dev/hidg0 keyboard

# Send string 'abcdeZ'
for C in a b c d e 'left-shift z' ; do echo "$C" ; sleep 0.1 ; done | ./hid-gadget-test /dev/hidg0 keyboard

# You may combine several modifier keys
echo left-ctrl left-shift enter | ./hid-gadget-test /dev/hidg0 keyboard

# Try to guess what this command sends
echo left-ctrl left-alt del | ./hid-gadget-test /dev/hidg0 keyboard

# Bruteforce 4-digit PIN-code, that's a particularly popular script
# that people keep asking me for. It executes for 42 hours.
for a in 0 1 2 3 4 5 6 7 8 9; do
for b in 0 1 2 3 4 5 6 7 8 9; do
for c in 0 1 2 3 4 5 6 7 8 9; do
for d in 0 1 2 3 4 5 6 7 8 9; do
echo $a $b $c $d
for C in $a $b $c $d enter ; do echo "$C" ; sleep 0.2 ; done | ./hid-gadget-test /dev/hidg0 keyboard
sleep 15
done
done
done
done

# Press right mouse button
echo --b2 | ./hid-gadget-test /dev/hidg1 mouse

# Hold left mouse button, drag 100 pixels to the right and 50 pixels up, then release
echo --hold --b1 | ./hid-gadget-test /dev/hidg1 mouse
echo --hold --b1 100 0 | ./hid-gadget-test /dev/hidg1 mouse
echo --hold --b1 0 -50 | ./hid-gadget-test /dev/hidg1 mouse
echo --b1 | ./hid-gadget-test /dev/hidg1 mouse

You can check the modification time of file /sys/devices/virtual/hidg/hidg0/dev to know when the USB cable has been plugged into PC, however this does not always work, so it's better to simply check if hid-gadget-test returned an error.

Here's a sample shell script that will send a predefined key sequence when USB cable is plugged into PC:

#!/system/bin/sh
while true; do
    until echo volume-up | ./hid-gadget-test /dev/hidg0 keyboard >/dev/null 2>&1; do
        sleep 2
    done
    echo "USB cable plugged"
    sleep 1
    for C in 'left-meta r' c m d enter s t a r t space i e x p l o r e space x x x period c o m enter \
        ; do echo "$C" ; sleep 0.3 ; done | ./hid-gadget-test /dev/hidg0 keyboard
    echo "Done sending commands"
    while echo volume-up | ./hid-gadget-test /dev/hidg0 keyboard >/dev/null 2>&1; do
        sleep 2
    done
    echo "USB cable unplugged"
done

Here is the list of keys that hid-gadget-test utility supports

If you need to crack a PIN code, but the target system loses keypresses (happens in MacOS BIOS), there is a handy app for that, which uses camera to check if each keypress is recognized.

You can also run DuckyScript files used by USB Rubber Ducky keystroke injection tool, with the help of this neat shell script.

Compiling kernel

You have to run all following commands on Linux. Windows is not supported. These instructions are for Nexus 7 2012, change them for your device accordingly.

To compile kernel, launch commands

git clone https://android.googlesource.com/platform/prebuilts/gcc/linux-x86/arm/arm-eabi-4.8
git clone https://android.googlesource.com/kernel/tegra.git
export PATH=`pwd`/arm-eabi-4.8/bin:$PATH
export ARCH=arm
export SUBARCH=arm
export CROSS_COMPILE=arm-eabi-
cd tegra
git checkout android-tegra3-grouper-3.1-lollipop-mr1
patch -p1 < ../kernel-3.1.patch
make tegra3_android_defconfig
make -j4

Use either kernel-3.1.patch, kernel-3.4.patch, kernel-3.10-nexus6.patch, or kernel-3.10-nexus9.patch, depending on your kernel version.

To compile boot.img, launch commands

mkdir ~/bin
export PATH=~/bin:$PATH
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
mkdir aosp
cd aosp
repo init -u https://android.googlesource.com/platform/manifest -b android-4.4.2_r1
repo sync
cp -f ../tegra/arch/arm/boot/zImage device/asus/grouper/kernel
make -j4 TARGET_PRODUCT=aosp_grouper TARGET_BUILD_VARIANT=userdebug

You then can find boot.img in directory aosp/out/target/product/grouper.

Nexus 7 2012 does not put any SELinux restrictions on the files inside /dev, however most other devices typically restrict all access inside /dev for apps, which means you will be able to use hid-gadget-test command from the root shell, but the Android app will fail to launch.

SELinux can be temporarily disabled with a command

setenforce 0

however this will considerably weaken your device security, so it's better to add specific SELinux exception for /dev/hidg0 and /dev/hidg1.

SELinux rules can be found at path

device/asus/grouper/sepolicy

Replace asus/grouper with your device manufacturer/model, then add following lines to SELinux rules.

In file device.te - the declaration of SELinux security context type:

type hid_gadget_device, dev_type;

In file file_contexts - binding the device paths to the security context:

# USB Gadget
/dev/hidg(.*)                        u:object_r:hid_gadget_device:s0

In file app.te - the rule itself to allow apps using this security context:

allow appdomain hid_gadget_device:chr_file rw_file_perms;

Then recompile boot.img.

Compiling USB Keyboard app

To compile USB Keyboard app, install Android SDK and NDK from site http://developer.android.com/ , and launch commands

git clone https://github.com/pelya/commandergenius.git
cd commandergenius
git submodule update --init --recursive
rm -f project/jni/application/src
ln -s hid-pc-keyboard project/jni/application/src
./changeAppSettings.sh -a
android update project -p project

How it works

The custom kernel you have compiled adds two new devices, /dev/hidg0 for keyboard, and /dev/hidg1 for mouse.

You can open these two files, using open() system call, and write raw keyboard/mouse events there, using write() system call, which will be sent through USB cable to your PC.

Keyboard event is an array of 8 byte length, first byte is a bitmask of currently pressed modifier keys:

typedef enum {
    LCTRL = 0x1,
    LSHIFT = 0x2,
    LALT = 0x4,
    LSUPER = 0x8, // Windows key
    RCTRL = 0x10,
    RSHIFT = 0x20,
    RALT = 0x40,
    RSUPER = 0x80, // Windows key
} ModifierKeys_t;

Remaining 7 bytes is a list of all other keys currently pressed, one byte for one key, or 0 if no key is pressed. Consequently, the maximum amount of keys that may be pressed at the same time is 7, excluding modifier keys.

Professional or 'gamer' USB keyboards report several keyboard HID descriptors, which creates several keyboard devices in host PC, to overcome that 7-key limit.

The scancode table for each key is available in hid-gadget-test utility. Extended keys, such as Play/Pause, are not supported, because they require modifying USB descriptor in kernel patch.

Mouse event is an array of 4 bytes, first byte is a bitmask of currently pressed mouse buttons:

typedef enum {
    BUTTON_LEFT = 0x1,
    BUTTON_RIGHT = 0x2,
    BUTTON_MIDDLE = 0x4,
} MouseButtons_t;

Remaining 3 bytes are X movement offset, Y movement offset, and mouse wheel offset, represented as signed integers. Horizontal wheel is not supported yet.

See functions outputSendKeys() and outputSendMouse() inside file input.cpp for reference implementation.