黑匣开放平台文档

Appearance

On this page

KmboxNet模块 ​

创建KMNet实例并连接 ​

创建并连接 KMNet 盒子

lua
local kmnet, result = newKMNet(ip, port, uuid)

功能：创建一个 KMNet 实例，并尝试连接到指定的 KMNet 盒子。这是使用所有后续 API 的前提。

参数：

  • ip string 盒子的 IP 地址（显示屏上会有显示）。
  • port string 通信端口号（显示屏上会有显示）。
  • uuid string 盒子的UUID地址（显示屏幕上有显示）。

返回值：

  • kmnet KMNetBridge 成功连接时返回的 KMNet 实例，用于后续操作。如果连接失败，此值可能为 nil。
  • result number 连接结果：0 表示成功，其他负数参见错误代码。

示例：

lua
local kmnet, ret = newKMNet("192.168.1.100", "9999", "0x11223344")
if ret ~= 0 then
    print("连接 KMNet 盒子失败，错误码：", ret)
    return
end
print("KMNet 盒子连接成功！")

停止并断开连接 ​

停止与 KMNet 盒子的通讯并断开连接

lua
kmnet:stop()

功能：停止与 KMNet 盒子的通讯并断开连接，释放相关资源。

参数：无。

返回值：无。

示例：

lua
kmnet:stop()
print("已断开与 KMNet 盒子的连接。")

鼠标相对移动 ​

模拟鼠标相对当前位置移动

lua
kmnet:mouse_move(x, y)

功能：模拟鼠标相对当前位置移动指定的 x 和 y 距离。

参数：

  • x number X轴相对移动距离（可正可负）。
  • y number Y轴相对移动距离（可正可负）。

返回值：number，操作结果，0 表示成功，其他值参见错误代码。

示例：

lua
local ret = kmnet:mouse_move(100, 50) -- 鼠标向右下移动 100, 50
if ret ~= 0 then
    print("鼠标移动失败，错误码：", ret)
end

鼠标左键控制 ​

控制鼠标左键的按下或抬起

lua
kmnet:mouse_left(isdown)

功能：控制鼠标左键的按下或抬起状态。

参数：

  • isdown boolean true 为按下左键，false 为抬起左键。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_left(true)  -- 按下鼠标左键
-- 等待一段时间或执行其他操作
kmnet:mouse_left(false) -- 抬起鼠标左键

鼠标右键控制 ​

控制鼠标右键的按下或抬起

lua
kmnet:mouse_right(isdown)

功能：控制鼠标右键的按下或抬起状态。

参数：

  • isdown boolean true 为按下右键，false 为抬起右键。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_right(true)
kmnet:mouse_right(false)

鼠标中键控制 ​

控制鼠标中键的按下或抬起

lua
kmnet:mouse_middle(isdown)

功能：控制鼠标中键的按下或抬起状态。

参数：

  • isdown boolean true 为按下中键，false 为抬起中键。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_middle(true)
kmnet:mouse_middle(false)

鼠标滚轮控制 ​

模拟鼠标滚轮滚动

lua
kmnet:mouse_wheel(wheel)

功能：模拟鼠标滚轮滚动指定的步数。

参数：

  • wheel number 滚动步数。正数向上滚动，负数向下滚动。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_wheel(120)  -- 向上滚动
kmnet:mouse_wheel(-120) -- 向下滚动

鼠标侧键1控制 ​

控制鼠标侧键1的按下或抬起

lua
kmnet:mouse_side1(isdown)

功能：控制鼠标侧键1（通常是拇指键）的按下或抬起状态。

参数：

  • isdown boolean true 为按下，false 为抬起。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_side1(true)
kmnet:mouse_side1(false)

鼠标侧键2控制 ​

控制鼠标侧键2的按下或抬起

lua
kmnet:mouse_side2(isdown)

功能：控制鼠标侧键2（通常是拇指键）的按下或抬起状态。

参数：

  • isdown boolean true 为按下，false 为抬起。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mouse_side2(true)
kmnet:mouse_side2(false)

鼠标综合控制 ​

同时控制鼠标按钮、相对移动和滚轮

lua
kmnet:mouse_all(button, x, y, wheel)

功能：在一个指令中同时控制鼠标的按钮状态、相对移动距离和滚轮滚动。

参数：

  • button number 按钮状态的位域值。例如：
    • 0 (无按钮按下)
    • 1 (左键)
    • 2 (右键)
    • 4 (中键)
    • 8 (侧键1)
    • 16 (侧键2)
    • 可以通过按位或组合多个按钮，例如 1 | 2 表示同时按下左右键。
  • x number X轴相对移动距离。
  • y number Y轴相对移动距离。
  • wheel number 滚轮滚动步数。

返回值：number，操作结果，0 表示成功。

示例：

lua
-- 同时按下左键并向右下移动 10, 10
local ret = kmnet:mouse_all(1, 10, 10, 0)
if ret ~= 0 then
    print("鼠标综合控制失败，错误码：", ret)
end

鼠标自动模拟人工移动 ​

鼠标自动模拟人工移动到指定相对坐标

lua
kmnet:mouse_move_auto(x, y, time_ms)

功能：鼠标自动模拟人工移动到指定的相对坐标，移动过程会耗时 time_ms，模拟人手移动轨迹。

参数：

  • x number 目标X轴相对坐标。
  • y number 目标Y轴相对坐标。
  • time_ms number 移动耗时（毫秒）。

返回值：number，操作结果，0 表示成功。

示例：

lua
-- 鼠标在 500 毫秒内从当前位置自动移动到相对 (200, 150) 的位置
local ret = kmnet:mouse_move_auto(200, 150, 500)
if ret ~= 0 then
    print("鼠标自动移动失败，错误码：", ret)
end

鼠标贝塞尔曲线移动 ​

鼠标沿着二阶贝塞尔曲线移动

lua
kmnet:mouse_move_beizer(x, y, ms, x1, y1, x2, y2)

功能：鼠标沿着二阶贝塞尔曲线移动到目标坐标。

参数：

  • x number 目标点的 X 坐标。
  • y number 目标点的 Y 坐标。
  • ms number 移动耗时（毫秒）。
  • x1 number 第一个控制点（P1）的 X 坐标。
  • y1 number 第一个控制点（P1）的 Y 坐标。
  • x2 number 第二个控制点（P2）的 X 坐标。
  • y2 number 第二个控制点（P2）的 Y 坐标。

返回值：number，操作结果，0 表示成功。

示例：

lua
-- 鼠标在 1000 毫秒内从当前位置，通过两个控制点 (100, 100) 和 (600, 200) 移动到 (500, 300)
local ret = kmnet:mouse_move_beizer(500, 300, 1000, 100, 100, 600, 200)
if ret ~= 0 then
    print("鼠标贝塞尔移动失败，错误码：", ret)
end

键盘按下 ​

模拟键盘按键按下

lua
kmnet:keydown(vkey)

功能：模拟指定虚拟按键的按下操作。

参数：

  • vkey number 按键的虚拟键码。具体键码请参考 HidTable.h 或相关文档。

返回值：number，操作结果，0 表示成功。

示例：

lua
-- 假设 VK_A 是字母 'A' 的虚拟键码 (例如 0x04)
local VK_A = 0x04 -- 这是一个假设值，请查阅 HidTable.h
local ret = kmnet:keydown(VK_A)
if ret ~= 0 then
    print("按下 'A' 键失败，错误码：", ret)
end

键盘抬起 ​

模拟键盘按键抬起

lua
kmnet:keyup(vkey)

功能：模拟指定虚拟按键的抬起操作。

参数：

  • vkey number 按键的虚拟键码。

返回值：number，操作结果，0 表示成功。

示例：

lua
local VK_A = 0x04 -- 这是一个假设值，请查阅 HidTable.h
local ret = kmnet:keyup(VK_A)
if ret ~= 0 then
    print("抬起 'A' 键失败，错误码：", ret)
end

键盘按键模拟点击 ​

模拟键盘按键按下并抬起

lua
kmnet:keypress(vkey, ms)

功能：模拟指定虚拟按键的按下和抬起操作，并在按下后等待指定毫秒再抬起。

参数：

  • vkey number 按键的虚拟键码。
  • ms number 按下后等待的毫秒数。

返回值：number，操作结果，0 表示成功。

示例：

lua
local VK_ENTER = 0x28 -- 假设回车键的键码
local ret = kmnet:keypress(VK_ENTER, 50) -- 模拟按下回车键并保持 50 毫秒
if ret ~= 0 then
    print("模拟回车键点击失败，错误码：", ret)
end

开启/关闭物理键鼠监控 ​

开启或关闭盒子上的物理键鼠数据监控

lua
kmnet:monitor(port)

功能：开启或关闭盒子上的物理键鼠数据监控功能。开启后，可以通过后续的 monitor_mouse_* 和 monitor_keyboard 函数查询物理键鼠状态。

参数：

  • port number 监控端口号。传入 0 表示关闭监控功能。

返回值：number，操作结果，0 表示成功。

示例：

lua
local monitor_port = 8888
local ret = kmnet:monitor(monitor_port) -- 开启监控
if ret ~= 0 then
    print("开启监控失败，错误码：", ret)
end

-- ... 进行监控查询操作 ...

kmnet:monitor(0) -- 关闭监控

查询物理鼠标左键状态 ​

查询物理鼠标左键当前状态

lua
local state = kmnet:monitor_mouse_left()

功能：查询物理鼠标左键的当前按下状态。

参数：无。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local left_state = kmnet:monitor_mouse_left()
if left_state == 1 then
    print("物理鼠标左键当前处于按下状态。")
else
    print("物理鼠标左键当前处于抬起状态。")
end

查询物理鼠标中键状态 ​

查询物理鼠标中键当前状态

lua
local state = kmnet:monitor_mouse_middle()

功能：查询物理鼠标中键的当前按下状态。

参数：无。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local middle_state = kmnet:monitor_mouse_middle()

查询物理鼠标右键状态 ​

查询物理鼠标右键当前状态

lua
local state = kmnet:monitor_mouse_right()

功能：查询物理鼠标右键的当前按下状态。

参数：无。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local right_state = kmnet:monitor_mouse_right()

查询物理鼠标侧键1状态 ​

查询物理鼠标侧键1当前状态

lua
local state = kmnet:monitor_mouse_side1()

功能：查询物理鼠标侧键1的当前按下状态。

参数：无。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local side1_state = kmnet:monitor_mouse_side1()

查询物理鼠标侧键2状态 ​

查询物理鼠标侧键2当前状态

lua
local state = kmnet:monitor_mouse_side2()

功能：查询物理鼠标侧键2的当前按下状态。

参数：无。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local side2_state = kmnet:monitor_mouse_side2()

查询物理鼠标XY坐标值 ​

查询物理鼠标当前的XY坐标值

lua
local ret, x, y = kmnet:monitor_mouse_xy()

功能：查询物理鼠标当前的相对XY坐标值。

参数：无。

返回值：

  • ret number 操作结果，0 表示成功。
  • x number 物理鼠标的X坐标值。
  • y number 物理鼠标的Y坐标值。

示例：

lua
local ret, mouse_x, mouse_y = kmnet:monitor_mouse_xy()
if ret == 0 then
    print(string.format("物理鼠标当前坐标：X=%d, Y=%d", mouse_x, mouse_y))
else
    print("查询鼠标坐标失败，错误码：", ret)
end

查询物理鼠标滚轮值 ​

查询物理鼠标滚轮当前值

lua
local ret, wheel = kmnet:monitor_mouse_wheel()

功能：查询物理鼠标滚轮的当前滚动值。

参数：无。

返回值：

  • ret number 操作结果，0 表示成功。
  • wheel number 物理鼠标滚轮的当前值。

示例：

lua
local ret, mouse_wheel_val = kmnet:monitor_mouse_wheel()
if ret == 0 then
    print("物理鼠标滚轮值：", mouse_wheel_val)
else
    print("查询鼠标滚轮失败，错误码：", ret)
end

查询键盘指定按键状态 ​

查询物理键盘指定按键状态

lua
local state = kmnet:monitor_keyboard(vk_key)

功能：查询物理键盘上指定虚拟键码按键的当前按下状态。

参数：

  • vk_key number 按键的虚拟键码。

返回值：number，1 表示按下，0 表示抬起。

示例：

lua
local VK_SPACE = 0x2C -- 假设空格键的键码
local space_state = kmnet:monitor_keyboard(VK_SPACE)
if space_state == 1 then
    print("物理键盘空格键当前处于按下状态。")
end

屏蔽物理鼠标左键 ​

屏蔽物理鼠标左键输入

lua
kmnet:mask_mouse_left(enable)

功能：屏蔽或解除屏蔽物理鼠标左键的输入。屏蔽后，物理左键的点击将不会被操作系统识别。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_left(true)  -- 屏蔽物理鼠标左键
-- ...
kmnet:mask_mouse_left(false) -- 解除屏蔽物理鼠标左键

屏蔽物理鼠标右键 ​

屏蔽物理鼠标右键输入

lua
kmnet:mask_mouse_right(enable)

功能：屏蔽或解除屏蔽物理鼠标右键的输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_right(true)

屏蔽物理鼠标中键 ​

屏蔽物理鼠标中键输入

lua
kmnet:mask_mouse_middle(enable)

功能：屏蔽或解除屏蔽物理鼠标中键的输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_middle(true)

屏蔽物理鼠标侧键1 ​

屏蔽物理鼠标侧键1输入

lua
kmnet:mask_mouse_side1(enable)

功能：屏蔽或解除屏蔽物理鼠标侧键1的输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_side1(true)

屏蔽物理鼠标侧键2 ​

屏蔽物理鼠标侧键2输入

lua
kmnet:mask_mouse_side2(enable)

功能：屏蔽或解除屏蔽物理鼠标侧键2的输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_side2(true)

屏蔽物理鼠标X轴坐标 ​

屏蔽物理鼠标X轴坐标输入

lua
kmnet:mask_mouse_x(enable)

功能：屏蔽或解除屏蔽物理鼠标X轴的移动输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_x(true)  -- 屏蔽鼠标X轴移动

屏蔽物理鼠标Y轴坐标 ​

屏蔽物理鼠标Y轴坐标输入

lua
kmnet:mask_mouse_y(enable)

功能：屏蔽或解除屏蔽物理鼠标Y轴的移动输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_y(true)  -- 屏蔽鼠标Y轴移动

屏蔽物理鼠标滚轮 ​

屏蔽物理鼠标滚轮输入

lua
kmnet:mask_mouse_wheel(enable)

功能：屏蔽或解除屏蔽物理鼠标滚轮的输入。

参数：

  • enable boolean true 启用屏蔽，false 解除屏蔽。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:mask_mouse_wheel(true)

屏蔽物理键盘指定按键 ​

屏蔽物理键盘指定按键输入

lua
kmnet:mask_keyboard(vkey)

功能：屏蔽物理键盘上指定虚拟键码按键的输入。

参数：

  • vkey number 按键的虚拟键码。

返回值：number，操作结果，0 表示成功。

示例：

lua
local VK_W = 0x1A -- 假设 'W' 键的键码
kmnet:mask_keyboard(VK_W) -- 屏蔽物理键盘的 'W' 键

解除物理键盘指定按键的屏蔽 ​

解除物理键盘指定按键的屏蔽

lua
kmnet:unmask_keyboard(vkey)

功能：解除物理键盘上指定虚拟键码按键的屏蔽。

参数：

  • vkey number 按键的虚拟键码。

返回值：number，操作结果，0 表示成功。

示例：

lua
local VK_W = 0x1A -- 假设 'W' 键的键码
kmnet:unmask_keyboard(VK_W) -- 解除屏蔽物理键盘的 'W' 键

解除所有物理屏蔽 ​

解除所有物理键鼠的屏蔽

lua
kmnet:unmask_all()

功能：解除所有之前设置的物理键鼠屏蔽。

参数：无。

返回值：number，操作结果，0 表示成功。

示例：

lua
kmnet:unmask_all() -- 解除所有物理键鼠的屏蔽

错误代码 ​

kmbonet.h 中定义的错误代码：

  • err_creat_socket = -9000：创建socket失败
  • err_net_version：socket版本错误
  • err_net_tx：socket发送错误
  • err_net_rx_timeout：socket接收超时
  • err_net_cmd：命令错误
  • err_net_pts：时间戳错误
  • success = 0：正常执行
  • usb_dev_tx_timeout：USB devic发送失败

注意事项 ​

  • KMNetBridge 实例通常只需要创建一次。kmbonet.h 中的 sockClientfd 是一个全局变量，多次调用 kmNet_init 可能会导致未预期的行为。
  • 在程序退出或不再需要连接时，请务必调用 kmnet:stop() 来断开连接并释放资源。
  • 键盘虚拟键码 vkey 需要查阅 HidTable.h 文件或相关文档以获取准确值。
  • 鼠标按钮的 button 参数在 kmNet_mouse_all 中是位域，需要按位或操作符来组合（例如 Lua 中的 | 或 bit.bor()）。
  • 监控功能需要先通过 kmnet:monitor() 开启，并在完成后关闭。
  • 所有的函数都返回一个 number 类型的结果码，0 代表成功，其他负数代表错误。建议在 Lua 代码中对这些返回值进行检查，以便及时发现并处理问题。