KMBoxNet Java Client

A modern Java implementation of the KMBox-Net protocol for controlling keyboard and mouse inputs via network.

Installation

Building from Source

Clone the repository and install to your local Maven repository:

git clone https://github.com/OceanTw/KMNet.java.git
cd KMNet.java
mvn clean install

Add to Your Project

Add to your pom.xml:

<dependency>
    <groupId>dev.ocean.kmbox</groupId>
    <artifactId>KMNet</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Quick Start

KMBoxClient client = new KMBoxClient();

// connect to the device
client.init("192.168.2.188", "8338", "24ba5054");

// move mouse 100 pixels right and 100 pixels down
client.mouse().move((short) 100, (short) 100);

// click left mouse button
client.mouse().left(true);
client.mouse().left(false);

// type text
client.keyboard().type("hello world");

// close connection
client.close();

Connection

Initialize Connection

KMBoxClient client = new KMBoxClient();

// connect to device with IP, port, and MAC address
int result = client.init("192.168.2.188", "8338", "24ba5054");

// check if connection was successful
if (result != ErrorCodes.SUCCESS) {
    System.err.println("Connection failed: " + result);
}

Configuration

// change device IP and port
client.setConfig("192.168.2.188", 8338);

// reboot the device
client.reboot();

Mouse Control

Basic Movement

// move mouse 100 pixels right, 50 pixels down
client.mouse().move((short) 100, (short) 50);

Mouse Buttons

// press left button
client.mouse().left(true);
// release left button
client.mouse().left(false);

// press right button
client.mouse().right(true);
// release right button
client.mouse().right(false);

// press middle button
client.mouse().middle(true);
// release middle button
client.mouse().middle(false);

Mouse Wheel

// scroll up
client.mouse().wheel(5);

// scroll down
client.mouse().wheel(-5);

Advanced Movement

// move 500, 300 pixels over 1000ms with smooth trajectory
client.mouse().moveAuto(500, 300, 1000);

// move 500, 300 pixels over 2000ms using bezier curve with control points
client.mouse().moveBeizer(800, 600, 2000, 200, 100, 600, 500);

Keyboard Control

Key Press

import dev.ocean.kmbox.hid.HidKeys;

// press key down
client.keyboard().down(HidKeys.KEY_A);
Thread.sleep(100);
// release key
client.keyboard().up(HidKeys.KEY_A);

Single Key Press

// press and release key automatically
client.keyboard().press(HidKeys.KEY_ENTER);

Type Text

// type a string of text
client.keyboard().type("hello world");

Modifier Keys

// simulate Ctrl+C
client.keyboard().down(HidKeys.KEY_LEFTCONTROL);
client.keyboard().down(HidKeys.KEY_C);
client.keyboard().up(HidKeys.KEY_C);
client.keyboard().up(HidKeys.KEY_LEFTCONTROL);

Common Keys

HidKeys.KEY_A to HidKeys.KEY_Z
HidKeys.KEY_1_EXCLAMATION_MARK to HidKeys.KEY_0_CPARENTHESIS
HidKeys.KEY_ENTER
HidKeys.KEY_ESCAPE
HidKeys.KEY_BACKSPACE
HidKeys.KEY_TAB
HidKeys.KEY_SPACEBAR
HidKeys.KEY_F1 to HidKeys.KEY_F12
HidKeys.KEY_LEFTCONTROL
HidKeys.KEY_LEFTSHIFT
HidKeys.KEY_LEFTALT
HidKeys.KEY_LEFT_SUPER

Event Monitoring

Enable Monitoring

// start monitoring on port 10000
client.monitor((short) 10000);

Mouse Events

import dev.ocean.kmbox.listeners.MouseListener;
import dev.ocean.kmbox.events.*;

// add listener for mouse events
client.mouse().addListener(new MouseListener() {
    @Override
    public void onMouseButton(MouseButtonEvent event) {
        // triggered when any mouse button state changes
        System.out.println(event.getButton() + " " + 
            (event.isPressed() ? "pressed" : "released"));
    }

    @Override
    public void onMouseMove(MouseMoveEvent event) {
        // triggered when mouse moves
        System.out.println("Mouse: " + event.getX() + ", " + event.getY());
    }

    @Override
    public void onMouseWheel(MouseWheelEvent event) {
        // triggered when mouse wheel scrolls
        System.out.println("Wheel: " + event.getDelta());
    }
});

Keyboard Events

import dev.ocean.kmbox.listeners.KeyboardListener;

// add listener for keyboard events
client.keyboard().addListener(event -> {
    // triggered when any key state changes
    System.out.println("Key " + event.getKeyCode() + " " + 
        (event.isPressed() ? "pressed" : "released"));
});

Disable Monitoring

// stop monitoring
client.monitor((short) 0);

Direct State Checking

// check if left button is currently pressed
if (client.mouse().monitor().left() == 1) {
    System.out.println("Left button is pressed");
}

// check if A key is currently pressed
if (client.keyboard().monitor().isPressed((short) HidKeys.KEY_A) == 1) {
    System.out.println("A key is pressed");
}

Complete Example

import dev.ocean.kmbox.KMBoxClient;
import dev.ocean.kmbox.listeners.MouseListener;
import dev.ocean.kmbox.listeners.KeyboardListener;
import dev.ocean.kmbox.events.*;
import dev.ocean.kmbox.hid.HidKeys;
import dev.ocean.kmbox.protocol.ErrorCodes;

public class Main {
    public static void main(String[] args) {
        KMBoxClient client = new KMBoxClient();

        try {
            // connect to device
            int result = client.init("192.168.2.188", "8338", "24ba5054");
            
            if (result != ErrorCodes.SUCCESS) {
                System.err.println("Connection failed: " + result);
                return;
            }

            // register mouse event listener
            client.mouse().addListener(new MouseListener() {
                @Override
                public void onMouseButton(MouseButtonEvent event) {
                    // detect left clicks
                    if (event.getButton() == MouseButtonEvent.Button.LEFT) {
                        System.out.println("Left click detected");
                    }
                }
            });

            // register keyboard event listener
            client.keyboard().addListener(event -> {
                // stop monitoring when ESC is pressed
                if (event.getKeyCode() == HidKeys.KEY_ESCAPE && event.isPressed()) {
                    try {
                        client.monitor((short) 0);
                    } catch (Exception e) {
                        e.printStackTrace();
                    }
                }
            });

            // start monitoring hardware input
            client.monitor((short) 10000);

            // perform mouse actions
            client.mouse().move((short) 500, (short) 500);
            client.mouse().left(true);
            Thread.sleep(50);
            client.mouse().left(false);

            // perform keyboard actions
            client.keyboard().type("Hello from KMBoxNet");
            client.keyboard().press(HidKeys.KEY_ENTER);

            // wait for events
            Thread.sleep(30000);

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // always close connection
            client.close();
        }
    }
}

Error Codes

ErrorCodes.SUCCESS                 0       // operation successful
ErrorCodes.ERR_CREAT_SOCKET       -9000   // failed to create socket
ErrorCodes.ERR_NET_VERSION        -8999   // network version mismatch
ErrorCodes.ERR_NET_TX             -8998   // network transmission error
ErrorCodes.ERR_NET_RX_TIMEOUT     -8997   // network receive timeout
ErrorCodes.ERR_NET_CMD            -8996   // command mismatch
ErrorCodes.ERR_NET_PTS            -8995   // packet timestamp mismatch

Event Types

MouseButtonEvent

event.getButton()       // MouseButtonEvent.Button (LEFT, RIGHT, MIDDLE, SIDE1, SIDE2)
event.isPressed()       // true if button is pressed
event.isReleased()      // true if button is released
event.getTimestamp()    // event timestamp in milliseconds

MouseMoveEvent

event.getX()            // x coordinate
event.getY()            // y coordinate
event.getTimestamp()    // event timestamp in milliseconds

MouseWheelEvent

event.getDelta()        // scroll amount (positive = up, negative = down)
event.getTimestamp()    // event timestamp in milliseconds

KeyboardEvent

event.getKeyCode()      // HID key code
event.isPressed()       // true if key is pressed
event.isReleased()      // true if key is released
event.getTimestamp()    // event timestamp in milliseconds

Help & Support

Message me on Discord (@oceaning) for help

License

MIT