Metadata-Version: 2.4
Name: pikvm_lib
Version: 0.5.0
Summary: Library to control PiKVM with Python
Author-email: guanana <guanana2@gmail.com>
License: GNU v3
Project-URL: Homepage, https://github.com/guanana/pikvm-lib
Project-URL: Issues, https://github.com/guanana/pikvm-lib/issues
Keywords: pikvm,pikvm-lib,kvm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pyotp<=2.9.0
Requires-Dist: websocket-client>=1.7.0
Requires-Dist: pillow>=11.3.0
Dynamic: license-file

# PiKVM-Lib: A Python library for controlling/automating PiKVM Devices

[![codecov](https://codecov.io/gh/guanana/pikvm-lib/graph/badge.svg?token=ZTJV7JLUTK)](https://codecov.io/gh/guanana/pikvm-lib)

PiKVM-Lib is a Python library that provides a simple and intuitive API for controlling PiKVM devices. 
With PiKVM-Lib, you can easily perform various actions on your PiKVM devices, such as:

* Getting system information
* Controlling ATX power
* Managing Mass Storage Device (MSD) images
* Interacting with General-Purpose Input/Output (GPIO) channels
* Taking snapshots and receive image
* Reading snapshots with OCR and receive text representation
* Send keys to the server


With PiKVM-Lib, you can automate tasks, integrate PiKVMs into your existing applications, 
and extend the capabilities of your PiKVM devices.

## Installation

To install PiKVM, simply run the following command in your terminal:

```bash
pip install pikvm-lib
```

## PiKVM device control

After installing PiKVM, you can import it into your Python script and create an instance of the `PiKVM` class. The `PiKVM` class constructor takes the following parameters:

* `hostname`: The hostname or IP address of the PiKVM device
* `username`: The username for authentication
* `password`: The password for authentication


```python
from pikvm_lib import PiKVM

pikvm_instance = PiKVM(hostname="192.168.1.10", username="admin", password="password")
```

Once you have created an instance of the `PiKVM` class, you can use it to interact with your PiKVM device. 
For example, you can get the system information of the device:

```python
system_info = pikvm_instance.get_system_info()
print(system_info)
```

You can also control the ATX power of the device:

```python
pikvm_instance.set_atx_power(action="on")
```

For more information on how to use PiKVM, 
please refer to the official documentation: [PiKVM official web](https://docs.pikvm.org/) and [PiKVM API Reference](https://docs.pikvm.org/api/)

### Usage examples

Here are some examples of how to use PiKVM to perform common tasks:

* **Getting system information:**

```python
from pikvm_lib import PiKVM

pikvm_instance = PiKVM(hostname="192.168.1.10", username="admin", password="password")
system_info = pikvm_instance.get_system_info()
print(system_info)
```

* **Turning on the ATX power:**

```python
pikvm_instance.set_atx_power(action="on")
```

* **Uploading an MSD image:**

```python
pikvm_instance.upload_msd_image(filepath="/path/to/image.iso")
```

* **Connecting the MSD:**

```python
pikvm_instance.connect_msd()
```

* **Switching a GPIO channel:**

```python
pikvm_instance.switch_gpio_channel(channel=1, state=1)
```

* **Take snapshot and receive OCR text:**

```python
pikvm_instance.get_streamer_snapshot(snapshot_path="/home/user/pikvm-snapshots",
                            filename="test.txt", ocr=True)
```

* **Take snapshot and receive PIL image:**

```python
pikvm_instance.get_streamer_image()
```

* **Send Key Press:**

```python
pikvm_instance.press('a')
```

* **Send Hot Key:**

```python
pikvm_instance.hotkey('ctrl', 'alt', 'delete')
```

* **Move Mouse to Location (x,y):**

```python
pikvm_instance.send_mouse_move_event(128, 256)
```

* **Click Mouse at Location:**

```python
pikvm_instance.send_click("left")

```

* **Drag mouse to Location (x,y):**
```python
pikvm_instance.send_mouse_event(button, "true")
pikvm_instance.send_mouse_move_event(128, 256)
pikvm_instance.send_mouse_event(button, "false")

```
