Metadata-Version: 2.4
Name: kmbox-universal
Version: 0.1.0
Summary: Cross-platform Python client for KMBox Net devices
Author: Free
License-Expression: MIT
Keywords: kmbox,kmboxnet,hid,udp,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# kmbox-universal

Cross-platform Python client for `KMBox Net` devices.

This package merges the useful parts of the public KMBox ecosystem:
- the official `kvmaibox/kmboxnet` protocol and command set
- the Java ergonomics from `OceanTw/KMNet.java`
- the higher-level helpers from `uve192/KMBox.NET`

It adds:
- pure Python UDP transport
- optional encrypted packet sending for `enc_*` operations
- monitor mode with keyboard/mouse state tracking
- mask/unmask helpers
- LCD, debug, VID/PID, reboot, and trace commands
- text typing helpers
- "absolute-ish" cursor movement by homing to top-left first

## Install

```bash
pip install kmbox-universal
```

## Quick Start

```python
from kmbox_universal import KMBoxClient, HidKey

client = KMBoxClient("192.168.2.188", 6314, "39EBDC32")
client.key_press(HidKey.C, 60)
client.move(100, 0)
client.click("left")
```

## Absolute Click Helper

KMBox Net exposes relative mouse movement, not true absolute cursor positioning.
This package provides a pragmatic helper:

```python
client.click_at(10, 10)
```

It first "homes" to the top-left edge, then moves to the requested target.
This works best when:
- the target machine uses one monitor
- the resolution stays fixed
- pointer acceleration is disabled

## Feature Coverage

- connect
- mouse move / move_auto / bezier / wheel / combined mouse packet
- left/right/middle/side buttons
- keyboard down/up/press/combo/text typing
- encrypted `enc_*` mouse and keyboard commands
- monitor mode
- mouse and keyboard mask/unmask
- set config, set VID/PID, reboot, debug, trace
- LCD solid fill and raw image upload

## References

These repositories were used as public references while building this package:
- https://github.com/kvmaibox/kmboxnet
- https://github.com/OceanTw/KMNet.java
- https://github.com/uve192/KMBox.NET

## Publish

Build:

```bash
python -m build
```

Test:

```bash
pytest
```
