KMBox

Name: KMBox
Author: @rebind

@rebind / kmbox-netv0.2.4Public

Let programs written for KMBox Net, Ferrum, or DHZBox send keyboard and mouse input through Rebind Link over your network.

Use programs made for a KMBox Net, Ferrum, or DHZBox with Rebind Link. The program runs on another computer and sends its commands over the network.

Needs Rebind 3.5.5 or newer and Rebind Link on Windows or macOS. KMBox Net was tested on Windows and macOS with a test program on the same computer. Ferrum and DHZBox commands were checked only by a local test with simulated output, not with Rebind Link. None of the three has been tested yet with a program on a second computer.

Set up

Open the package in Rebind and select Options. The defaults work as they are.
Start the package. The notice shows the address and port, such as 192.168.2.188 (likely), port 17006. With a VPN or a direct cable to the other computer, the address shown can be the wrong one. If it shows all addresses, or the wrong one, use this computer's address on the network your program uses.
In your program, enter that address and port. For KMBox Net programs, enter the device code 00000000.

The options, if you need them:

This computer's address: leave blank to listen on every network this computer is on. If your program expects a fixed address such as 192.168.2.188, give this computer that address, or change it in the program. Some programs only accept replies from the exact address they sent to, so if the program waits forever and this computer has several addresses, enter the one the program sends to. This case has not been tested.
Port: 0 picks a random port on the first start and keeps it. Set your own if your program needs a fixed one.
Device code: the 8 hex digits your KMBox Net program uses. Ferrum and DHZBox programs do not use a code.
Controlling computer's address: blank answers this computer and any computer with a private network address (such as 192.168.x.x or 10.x.x.x). Enter addresses, separated by commas, to answer only those.

Restart the package after changing an option.

What works

KMBox Net: mouse movement, buttons, scrolling, keyboard input, smooth and curved moves (both as a straight line over the requested time), encrypted commands, and monitor, so the program can see your physical mouse and keyboard
Ferrum km. commands: move, buttons, click, wheel, key down, up, and press, and reading buttons and keys. Ferrum documents these over USB serial; here they are accepted over the network, so the program must send them to this computer's address and port. Ferrum's own network modes use the KMBox Net and DHZBox formats, which are covered above and below.
DHZBox commands: move, buttons, wheel, keys, reading buttons, and monitor. The DHZBox format comes from other people's programs, not a published spec, so scroll direction, key names, and replies are unverified.

Blocking your physical mouse or keyboard (mask, lock) and device settings such as reboot are not supported. The program's requests are accepted but have no effect.

Safety

With the default options, any computer with a private network address that can reach the port can control this computer's keyboard and mouse. The device code is not a password, and Ferrum and DHZBox commands need no code at all. On Windows, Rebind is allowed through the firewall on all networks.

On a network you do not fully trust, enter the controlling computer's address. It is the only option that also covers Ferrum and DHZBox commands; the device code limits KMBox Net commands only. Another computer on the network can still fake an allowed address, so stop the package when you are not using it.

Stop

Stop the package from the editor toolbar, or press Left Ctrl + Left Alt + K (Left Control + Left Option + K on macOS) to stop all scripts. Held keys and buttons are released.

Version

Older release. Installs get 0.2.4.

main.luau12.2 KB

--[[ KMBox Net

  Answers the KMBox Net UDP protocol so programs written for that device can
  send keyboard and mouse input through Rebind Link. Wire contract: the
  vendor's NetConfig/kmboxNet.h and kmboxNet.cpp.

  Every packet starts with four little-endian u32s: device code, rand,
  sequence, command. Clients send one command and wait for any reply, so every
  well-formed command with the right code is answered by echoing that header,
  and anything else is ignored. Automove and bezier are answered when the move
  finishes, as the vendor demo times them. Ferrum and DHZBox text commands
  share the port; see text.luau.
]]

local xxtea = require("./xxtea")
local text_protocols = require("./text")

local cfg = UI.Schema({
  bind_ip = UI.Text("", {
    label = "This computer's address",
    placeholder = "blank = automatic",
    tooltip = "The network address your program sends to. Blank listens on every network this computer is on. Restart after changing.",
  }),
  port = UI.Slider(0, {
    label = "Port",
    min = 0,
    max = 65535,
    step = 1,
    tooltip = "The port your program sends to. 0 picks a random port on the next start. Restart after changing.",
  }),
  device_code = UI.Text("00000000", {
    label = "Device code",
    placeholder = "8 hex digits, e.g. AF425414",
    tooltip = "The code your program is configured with. Restart after changing.",
  }),
  controller_ip = UI.Text("", {
    label = "Controlling computer's address",
    placeholder = "blank = private network addresses",
    tooltip = "Only these addresses are answered. Separate several with commas. Blank answers this computer and private network addresses. Restart after changing.",
  }),
})

local CMD_MOUSE_MOVE = 0xAEDE7345
local CMD_MOUSE_LEFT = 0x9823AE8D
local CMD_MOUSE_MIDDLE = 0x97A3AE8D
local CMD_MOUSE_RIGHT = 0x238D8212
local CMD_MOUSE_WHEEL = 0xFFEEAD38
local CMD_AUTOMOVE = 0xAEDE7346
local CMD_BEZIER = 0xA238455A
local CMD_KEYBOARD = 0x123C2C2F
local CMD_MONITOR = 0x27388020

local MOUSE = {
  [CMD_MOUSE_MOVE] = "move",
  [CMD_MOUSE_LEFT] = "buttons",
  [CMD_MOUSE_MIDDLE] = "buttons",
  [CMD_MOUSE_RIGHT] = "buttons",
  [CMD_MOUSE_WHEEL] = "buttons",
  [CMD_AUTOMOVE] = "timed",
  [CMD_BEZIER] = "timed",
}

local HEADER_BYTES = 16
local MOUSE_BYTES = 72 -- header + soft_mouse_t
local KEYBOARD_BYTES = 28 -- header + soft_keyboard_t
local ENCRYPTED_BYTES = 128
local MONITOR_ON = 0xAA55
local MAX_MOVE_MS = 10000
local RANDOM_PORTS = { 10001, 49151 } -- below the OS ephemeral range

local socket = nil
local code = 0
local key = nil
local allowed = nil -- sender addresses, or nil for private networks
local held_buttons = {} -- button number (1-5) -> true
local held_keys = {} -- HID usage -> true
local skipped = {} -- usages already reported as unsupported
local repress = {} -- held inputs physically released since the last tick
local monitor = nil -- { ip, port } while the client wants reports
local motion_x, motion_y, motion_wheel = 0, 0, 0
local last_report = nil

local function set_button(n, down)
  if down ~= (held_buttons[n] == true) then
    if down then
      HID.Down(`Mouse{n}`)
    else
      HID.Up(`Mouse{n}`)
    end
    held_buttons[n] = down or nil
  end
end

local function set_buttons(mask)
  for n = 1, 5 do
    set_button(n, bit32.btest(mask, bit32.lshift(1, n - 1)))
  end
end

local function press_usage(usage, down)
  local ok, err = pcall(down and HID.Down or HID.Up, `usage:{usage}`)
  if not ok then
    if not skipped[usage] then
      skipped[usage] = true
      Log.Warn(`KMBox Net: skipped key usage {usage}: {err}`)
    end
    return
  end
  held_keys[usage] = down or nil
end

-- apply a soft_keyboard_t snapshot: ctrl bits for 0xE0-0xE7, then 10 usages
local function set_keys(data)
  local want = {}
  local ctrl = string.byte(data, HEADER_BYTES + 1)
  for bit = 0, 7 do
    if bit32.btest(ctrl, bit32.lshift(1, bit)) then
      want[0xE0 + bit] = true
    end
  end
  for i = HEADER_BYTES + 3, KEYBOARD_BYTES do
    local usage = string.byte(data, i)
    if usage ~= 0 then
      want[usage] = true
    end
  end
  for usage in pairs(held_keys) do
    if not want[usage] then
      press_usage(usage, false)
    end
  end
  for usage in pairs(want) do
    if not held_keys[usage] then
      press_usage(usage, true)
    end
  end
end

-- move (dx, dy) evenly over ms, then call done
local function timed_move(dx, dy, ms, done)
  Run(function()
    local start = os.clock()
    local sent_x, sent_y = 0, 0
    local t = 0
    while t < 1 do
      Sleep(1)
      t = if ms > 0 then math.min(1, (os.clock() - start) * 1000 / ms) else 1
      local x, y = math.round(dx * t), math.round(dy * t)
      if x ~= sent_x or y ~= sent_y then
        HID.Move(x - sent_x, y - sent_y)
        sent_x, sent_y = x, y
      end
    end
    done()
  end)
end

local text = text_protocols.new({
  button = set_button,
  key = press_usage,
  send = function(ip, port, bytes)
    socket:SendTo(ip, port, bytes)
  end,
})

local function handle(data, ip, port)
  -- text first: KMBox Net packets hold non-printable bytes (in practice the
  -- zero high byte of the sequence number), so they never match
  if data:match("^[%g%s]+$") and data:find("(", 1, true) then
    local reply = text.handle(data, ip)
    if reply then
      socket:SendTo(ip, port, reply)
    end
    return
  end
  -- encrypted packets are 128 bytes, or longer with only the first 128
  -- enciphered (KuromeSama6/kmboxnet pads to 1024)
  local plain = #data >= HEADER_BYTES and string.unpack("<I4", data) == code
  if not plain and #data >= ENCRYPTED_BYTES then
    data = xxtea.decrypt(string.sub(data, 1, ENCRYPTED_BYTES), key)
  end
  if #data < HEADER_BYTES then
    return
  end
  local device, rand, _, cmd = string.unpack("<I4I4I4I4", data)
  if device ~= code then
    return
  end
  local head = string.sub(data, 1, HEADER_BYTES)
  local function reply()
    socket:SendTo(ip, port, head)
  end

  local kind = MOUSE[cmd]
  if kind then
    if #data < MOUSE_BYTES then
      return
    end
    -- soft_mouse_t: button, x, y, wheel. clients that track no state send
    -- button 0 with moves, so the mask is applied only on button commands.
    local button, x, y, wheel =
      string.unpack("<i4i4i4i4", data, HEADER_BYTES + 1)
    if kind == "timed" then
      timed_move(x, y, math.min(rand, MAX_MOVE_MS), reply)
      return
    end
    if kind == "buttons" then
      set_buttons(button)
    end
    if x ~= 0 or y ~= 0 then
      HID.Move(x, y)
    end
    if wheel ~= 0 then
      HID.Scroll(-wheel) -- positive wheel scrolls down on the device
    end
  elseif cmd == CMD_KEYBOARD then
    if #data < KEYBOARD_BYTES then
      return
    end
    set_keys(data)
  elseif cmd == CMD_MONITOR then
    -- the vendor passes the port as a short, so ports from 32768 arrive
    -- sign-extended with 0xFFFF in the high half instead of 0xAA55
    local high = bit32.rshift(rand, 16)
    if rand ~= 0 and (high == MONITOR_ON or high == 0xFFFF) then
      monitor = { ip = ip, port = bit32.band(rand, 0xFFFF) }
      last_report = nil
    else
      monitor = nil
    end
  end
  -- connect, mask, reboot, config, display and unknown commands are
  -- acknowledged without effect; see README.md
  reply()
end

local function parse_config()
  local ip = cfg.bind_ip:match("^%s*(.-)%s*$")
  if ip == "" then
    ip = "0.0.0.0"
  elseif ip:find(":") then
    error("KMBox Net: This computer's address must be an IPv4 address")
  end
  local device = cfg.device_code:match("^%s*(.-)%s*$")
  if device == "" then
    device = "00000000"
  end
  local hex = device:match("^%x%x%x%x%x%x%x%x$")
  if not hex then
    error("KMBox Net: set Device code to the 8 hex digits your program uses")
  end
  local controllers = {}
  for addr in cfg.controller_ip:gmatch("[^,%s]+") do
    controllers[addr] = true
  end
  return ip, tonumber(hex, 16), if next(controllers) then controllers else nil
end

-- loopback, link-local and private IPv4 senders
local function is_local(ip)
  local a, b = ip:match("^(%d+)%.(%d+)%.%d+%.%d+$")
  a, b = tonumber(a), tonumber(b)
  return a == 127
    or a == 10
    or (a == 172 and b ~= nil and b >= 16 and b <= 31)
    or (a == 192 and b == 168)
    or (a == 169 and b == 254)
end

local function on_datagram(data, from, port)
  if allowed then
    if not allowed[from] then
      return
    end
  elseif not is_local(from) then
    return
  end
  local ok, err = pcall(handle, data, from, port)
  if not ok then
    Log.Warn(`KMBox Net: {err}`)
  end
end

-- port 0 picks a random port and keeps it once a bind succeeds; a reserved
-- or busy port is skipped
local function listen(ip)
  if cfg.port ~= 0 then
    local ok, result = pcall(Net.UDPListen, ip, cfg.port, on_datagram)
    if not ok then
      error(
        `KMBox Net: port {cfg.port} is unavailable; choose another or set 0 for a random one ({result})`
      )
    end
    return result
  end
  for _ = 1, 5 do
    local ok, result = pcall(
      Net.UDPListen,
      ip,
      math.floor(Math.Random(RANDOM_PORTS[1], RANDOM_PORTS[2])),
      on_datagram
    )
    if ok then
      cfg.port = result.port
      return result
    end
  end
  error("KMBox Net: no free random port found; set Port to a free port")
end

function OnStart()
  local ip, device, controllers = parse_config()
  code, key, allowed = device, xxtea.key_for(device), controllers
  socket = listen(ip)
  local shown = ip
  if ip == "0.0.0.0" then
    local likely = Net.LocalIP and Net.LocalIP()
    shown = if likely then `{likely} (likely)` else "all addresses"
  end
  Log.Info(
    `KMBox Net listening on {ip}:{socket.port}, code {string.format(
      "%08X",
      device
    )}`
  )
  UI.Notify(`KMBox Net: {shown}, port {socket.port}`, "success")
end

function OnStop()
  if socket then
    socket:Stop()
    socket = nil
  end
  held_buttons, held_keys, skipped, repress = {}, {}, {}, {}
  monitor, last_report = nil, nil
  text.reset()
end

-- a physical release of a key or button this package holds releases it on
-- Rebind Link too. The relay may send that release after this hook runs, so
-- the press is restored on the next tick.
function OnInputUp(name)
  repress[name] = true
end

local function restore_held()
  for name in pairs(repress) do
    local button = tonumber(name:match("^Mouse(%d)$"))
    local usage = HID.Usage(name)
    if button and held_buttons[button] then
      HID.Down(name)
    elseif usage and held_keys[usage] then
      HID.Down(`usage:{usage}`)
    end
  end
  table.clear(repress)
end

function OnInputMove(dx, dy)
  motion_x += dx
  motion_y += dy
end

-- reported as the physical mouse sends it: positive scrolls up. Commands use
-- the opposite sign (vendor manual); that the device forwards the physical
-- report unflipped is an unverified assumption.
function OnInputScroll(delta)
  motion_wheel += delta
end

local function clamp16(n)
  return math.clamp(n, -32768, 32767)
end

-- monitor: 8-byte mouse report and 12-byte keyboard report of physical input
function OnTick()
  restore_held()
  text.tick()
  if not monitor then
    motion_x, motion_y, motion_wheel = 0, 0, 0
    return
  end
  local buttons = 0
  for n = 1, 5 do
    if Input.IsDown(`Mouse{n}`) then
      buttons = bit32.bor(buttons, bit32.lshift(1, n - 1))
    end
  end
  local mods, keys = 0, {}
  for _, name in Input.GetActiveKeys() do
    local usage = HID.Usage(name)
    if usage and usage >= 0xE0 then
      mods = bit32.bor(mods, bit32.lshift(1, usage - 0xE0))
    elseif usage and #keys < 10 then
      table.insert(keys, usage)
    end
  end
  table.sort(keys)
  for i = #keys + 1, 10 do
    keys[i] = 0
  end
  local report = string.pack(
    "<BBhhhBB" .. string.rep("B", 10),
    1,
    buttons,
    clamp16(motion_x),
    clamp16(motion_y),
    clamp16(motion_wheel),
    1,
    mods,
    table.unpack(keys)
  )
  local moved = motion_x ~= 0 or motion_y ~= 0 or motion_wheel ~= 0
  motion_x, motion_y, motion_wheel = 0, 0, 0
  -- movement is a delta, so a repeat of the same motion is still news
  if moved or report ~= last_report then
    last_report = report
    socket:SendTo(monitor.ip, monitor.port, report)
  end
end

5 files, 27.7 KB.

KMBox

Readme

Set up

What works

Safety

Stop

Files

Versions