search

inputstick / InputStickAPI-Android

Android API for InputStick USB Receiver
40 stars 10 forks source link

readme

InputStickAPI for Android OS

Important:

Upcoming InputStickUtility app update will no longer work with apps compiled using earlier API versions. Please make sure that your app is compiled using latest API version! Unfortunately latest Android version no longer allows to maintain backwards compatibility.

This will affect only apps using IPC connection method (with InputStickUtility as a proxy). Apps that connect directly to InputStick or send broadcasts to InputStickUtility will not be affected.

About InputStick:

InputStick is an Android-compatible USB receiver. It allows to use your smartphone as a wireless keyboard, mouse, multimedia and game controller.

IMAGE ALT TEXT HERE

How does it work?

InputStick acts as a proxy between USB host and Android device:

Android device <-(Bluetooth)-> InputStick <-(USB)-> PC

alt text

InputStick is detected as a generic keyboard and mouse (USB HID), it makes it compatible with wide range of hardware:

Remember: InputStick behaves EXACTLY as a USB keyboard and mouse - nothing more and nothing less. It is not able to put text directly into system clipboard etc.

More info:

Visit inputstick.com

Download section

GooglePlay

Getting started:

Be sure to check demo apps for more info and implementation examples.

Eclipse: Import InputStickAPI into workspace, add InputStickAPI as a library to your project: Project -> Properties -> Android -> Add.

or to get started ASAP you need to copy only following files into your project: com.inputstick.api.broadcast.InputStickBroadcast (required)

com.inputstick.api.DownloadDialog (option, you can notify user some other way)

com.inputstick.api.hid.HIDKeycodes (option, only if you need keycodes for pressing single keys, like "Enter", "Esc", arrows etc.)

It is recommended to start with: com.inputstick.api.broadcast.InputStickBroadcast this can be as easy as a single line of code (InputStickUtility takes care of everything else):

InputStickBroadcast.type(context, "text to type", "en-US);

If you need more control, use "full" API (requires more code to implement):

Managing connection: com.inputstick.api.basic.InputStickHID

connect(getApplication());
disconnect();
getState();

Implement callback: com.inputstick.api.InputStickStateListener

onStateChanged(int state);

Keyboard interface: com.inputstick.api.basic.InputStickKeyboard

type("text to type", "en-US");
pressAndRelease(HIDKeycodes.ALT_LEFT, HIDKeycodes.KEY_ENTER);

Mouse interface: com.inputstick.api.basic.InputStickMouse

move((byte)10, (byte)5);
click(InputStickMouse.BUTTON_LEFT, 2);

Consumer control interface: com.inputstick.api.basic.InputStickConsumer

consumerAction(InputStickConsumer.VOL_UP);

Gamepad interface: com.inputstick.api.basic.InputStickGamepad

customReport((byte)0x01, (byte)0x00, (byte)0x00, (byte)0x00, (byte)0x00, (byte)0x00);

For more details and usage examples, please take a look at Android demo applications. Download section

Known issues and bugs:

InputStickUtility:

It is highly recommended that InputStickUtility application is installed (available on GooglePlay). It allows to make application development much easier. InputStickUtility provides background service that acts as a proxy between your application and InputStick. When InputStickUtility is used, you don't have to care about:

alt text

There are two ways to communicate with InputStickUtility:

Direct connection:

If you want to avoid installing InputStickUtility application you can make direct connection from your application. You must be able to provide following parameters:

Keyboard layouts:

Always make sure that selected layout matches layout used by USB host (PC). Due to limitations of USB-HID it is not possible for InputStick to know what layout is use by the USB host. This must be manually provided by the user. List of currently available keyboard layouts:

Requirements (BT2.1 version):

Requirements (BT4.0 version):

Technical limitations and things to consider:

USB device - InputStick USB host - PC, game consoles, Raspberry Pi, etc. HID - Human Interface Device (keyboard, mouse, gamepad, etc.)

InputStick communicates with USB host by sending HID reports for each interface (keyboard, mouse, consumer control). HID report - data representing state or change of state of HID interface.

Learn more: USB HID1.11 pdf

Compatibility:

USB host detects InputStick as a generic keyboard, mouse and consumer control composite device. It sees NO difference between physical keyboard/mouse and InputStick. Host does not know anything about Bluetooth interface. In most cases, generic drivers for HID devices are used, there is no need to install any additional software or drivers. If your USB host works with generic USB keyboard, it will most likely also work with InputStick. If necessary, you can make some adjustments to USB interface using InputStickUtility app (requires some knowledge about USB interface).

NO feedback:

In case of HID class devices, USB host does NOT provide any information about itself to USB device:

Think of InputStick as of a blind person with en-US keyboard:

You (app user) must provide all necessary information and feedback!

Typing speed:

InputStick can type text way faster than any human. In some cases this can result in missing characters. Use slower typing speed when necessary. Example: when PC is experiencing have CPU load, it is possible that in sometimes characters will be skipped (same thing will happen when using regular USB keyboard).

Consumer control interface.

Multimedia keys: allows to control media playback, system volume, launch applications. Unfortunately there are differences between OSes in how consumer control actions are interpreted.

Example 1: there are 100 volume levels in Windows OS and 10 levels on Ubuntu. Increasing system volume by 1 will have different effect on each of them.

Example 2: when audio output is muted, increasing system volume by 1 can have different effects: Windows - volume level is increased by 1, but audio output will remain muted. Linux - volume level is uncreased by 1, audio output is unmuted.

Bluetooth:

Time required to establish connection:

Latency: Bluetooth introduces additional latency (several ms in most cases, in some conditions can increase to several hundreds).

Range: Walls and other obstacles will decrease performance of Bluetooth link. BT4.0 devices are generally more sensitive to this (due to Low Energy approach).