wayland-automation 0.2.0

A tool for automating Wayland tasks using system packages wtype and wayland-info

Wayland Automation

A lightweight Python tool for automating pointer and keyboard actions on Wayland. This project allows you to perform basic clicks, swipes, auto-clicks, and keyboard actions using virtual devices in your Wayland environment.

---

Features

Pointer Automation (Mouse)

• Basic Click:
  Move the pointer to a specified (x, y) coordinate and optionally perform a click (left or right).

• Swipe:
  Simulate a drag gesture by swiping from one coordinate to another, with a customizable speed.

• Auto-Click:
  Wait for a configurable delay, then repeatedly click at the current pointer position for a set duration at defined intervals.

Keyboard Automation

• Typewrite:
  Type out a string with an optional delay between each character.

• Press:
  Simulate a single key press (key down then key up).

• Hotkey:
  Simulate key combinations (e.g., Ctrl+A).

---

Requirements

• Python 3.x

• Wayland Environment:
  Ensure you are running a Wayland session.

• System Dependencies:
  This project relies on the following system-level utilities, which are not available via PyPI:

  • wayland-info: Used to obtain your screen resolution.

    • Installation:
      • Debian/Ubuntu:

        sudo apt install wayland-utils
        

      • Arch Linux:

        sudo pacman -S wayland-utils
        

  • wtype: Used for simulating keyboard actions.

    • Installation
      • Debian/Ubuntu:

        sudo apt install wtype
        

      • Arch Linux:

        sudo pacman -S wtype
        

---

Installation

Install via PyPI

The package is available on PyPI and can be installed using:

pip install wayland-automation

Install from Source

1. Clone the Repository:

   git clone https://github.com/OTAKUWeBer/Wayland-automation.git
   cd Wayland-automation
   

2. (Optional) Create a Virtual Environment:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install System Dependencies:
   Ensure that both wayland-info and wtype are installed and available in your system's PATH as described above.

4. Install the Python Package:

   pip install .
   

   For development, consider using an editable install:

   pip install -e .
   

---

Usage

Pointer Automation (Mouse)

The pointer automation is handled by mouse_controller.py.

Basic Click (Python API)

Move the pointer to (x, y) and optionally perform a click.

from wayland_automation.mouse_controller import Mouse

mouse = Mouse()
mouse.click(100, 200, button="left")  # Perform a left click

Swipe (Drag)

Simulate a swipe (drag) gesture from one coordinate to another.

mouse.swipe(100, 200, 400, 500, speed=1.5)

Auto-Click

Automatically click at the current pointer position repeatedly.

mouse.auto_click(initial_delay=2, interval=0.2, duration=15, button="right")

Example: Track Mouse Position

from wayland_automation import mouse_position_generator

# Continuously track mouse position
for x, y in mouse_position_generator():
    print(f"Mouse is at: ({x}, {y})")

Keyboard Automation (Python API)

from wayland_automation.keyboard_controller import Keyboard
import time

kb = Keyboard()
time.sleep(2)  # Gives time to switch to another window

kb.typewrite("Hello, Wayland!", interval=0.05)
kb.press("enter")
kb.hotkey("ctrl", "a")

---

How It Works

1. Virtual Device Initialization:
   The scripts connect to the Wayland server via a Unix socket and initialize virtual devices (pointer and keyboard) using the Wayland protocol.

2. Message Protocol:
   Low-level Wayland messages are sent to move the pointer, simulate button events, and emulate keyboard actions via wtype.

3. Screen Resolution:
   A helper script in the utils directory uses wayland-info to retrieve your current screen resolution, ensuring accurate pointer positioning.

4. Modes Implementation:

   • Pointer Modes:
     Click, swipe, and auto-click actions are implemented by sending sequences of Wayland messages.
   • Keyboard Mode:
     The keyboard module supports text entry, single key presses, and hotkey combinations.

---

Contributing

Contributions, bug reports, and feature requests are welcome. Please open an issue or submit a pull request on the GitHub repository.

---

Acknowledgements

Special thanks to Zai-Kun for the foundational work on Wayland communication mechanisms that inspired this project.