From 0559bed90792db9e8484b3f077e949c3190ba5ed Mon Sep 17 00:00:00 2001 From: haithium <128622475+haithium@users.noreply.github.com> Date: Sun, 28 Jun 2026 02:54:23 +0000 Subject: [PATCH] docs: generate docs for evdev --- docs/src/evdev/api/ecodes.md | 47 ------------ docs/src/evdev/api/uinput.md | 8 +- docs/src/evdev/index.md | 48 +++--------- docs/src/evdev/types.md | 141 ++++++++++++++++++----------------- 4 files changed, 86 insertions(+), 158 deletions(-) delete mode 100644 docs/src/evdev/api/ecodes.md diff --git a/docs/src/evdev/api/ecodes.md b/docs/src/evdev/api/ecodes.md deleted file mode 100644 index 2135451..0000000 --- a/docs/src/evdev/api/ecodes.md +++ /dev/null @@ -1,47 +0,0 @@ -# `ecodes` - -Linux input event code constants used when reading events from `/dev/input` or -emitting events through `uinput`. - -## Usage - -```lua -local evdev = require "evdev" - -local Device = evdev.device.open -local dev = assert(Device("/dev/input/event3")) - -for e in dev:events() do - if e.type == evdev.ecodes.EV_KEY and e.code == evdev.ecodes.KEY_ENTER then - print("Enter key event", e.value) - end -end -``` - -## [`EV`] - -Event type constants used in the `type` field of Linux input events. - -## [`SYN`] - -Synchronization constants used to separate or mark input event packets. - -## [`REL`] - -Relative axis constants used with `EV_REL` events, such as mouse movement and -wheel input. - -## [`BTN`] - -Button constants used with `EV_KEY` events for mouse, joystick, gamepad, tablet, -and other button-like inputs. - -## [`KEY`] - -Keyboard and consumer key constants used with `EV_KEY` events. - -[`EV`]: ../types#ev -[`SYN`]: ../types#syn -[`REL`]: ../types#rel -[`BTN`]: ../types#btn -[`KEY`]: ../types#key diff --git a/docs/src/evdev/api/uinput.md b/docs/src/evdev/api/uinput.md index c626f43..615a4dd 100644 --- a/docs/src/evdev/api/uinput.md +++ b/docs/src/evdev/api/uinput.md @@ -226,10 +226,10 @@ ui:sync() [`create(spec?)`]: #create [`emit(type, code, value)`]: #emit [`evdev.UInput`]: /evdev/api/uinput -[`evdev.ecodes.btn`]: /evdev/api/ecodes -[`evdev.ecodes.ev`]: /evdev/api/ecodes -[`evdev.ecodes.key`]: /evdev/api/ecodes -[`evdev.ecodes.rel`]: /evdev/api/ecodes +[`evdev.ecodes.btn`]: /evdev/types#evdev-ecodes-btn +[`evdev.ecodes.ev`]: /evdev/types#evdev-ecodes-ev +[`evdev.ecodes.key`]: /evdev/types#evdev-ecodes-key +[`evdev.ecodes.rel`]: /evdev/types#evdev-ecodes-rel [`evdev.eventValue`]: /evdev/types#evdev-eventvalue [`evdev.fd`]: /evdev/types#evdev-fd [`evdev.uinputSpec`]: /evdev/types#evdev-uinputspec diff --git a/docs/src/evdev/index.md b/docs/src/evdev/index.md index d0737fe..d2e4988 100644 --- a/docs/src/evdev/index.md +++ b/docs/src/evdev/index.md @@ -1,71 +1,45 @@ # evdev +[![Test](https://img.shields.io/github/actions/workflow/status/BlueLua/evdev/test.yml?branch=main&label=test&style=flat-square)](https://github.com/BlueLua/evdev/actions/workflows/test.yml) [![LuaRocks](https://img.shields.io/luarocks/v/BlueLua/bluelua-evdev?color=blue&style=flat-square)](https://luarocks.org/modules/BlueLua/bluelua-evdev) ![Lua Versions](https://img.shields.io/badge/lua-5.1%20%7C%205.2%20%7C%205.3%20%7C%205.4%20%7C%205.5%20%7C%20LuaJIT-blue?style=flat-square) ![Platform](https://img.shields.io/badge/platform-linux-blue?style=flat-square) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/BlueLua/evdev/blob/main/LICENSE) -Lua bindings for Linux `evdev` input devices and `/dev/uinput` virtual devices -(keyboards, mice, and relative pointers). +Lua bindings for Linux evdev input devices and /dev/uinput virtual devices. + +Check out the [documentation] for guides and examples. ## ✨ Features - **Device Discovery**: List and search for connected input devices by name, path, or physical location. -- **Event Stream**: Easily read kernel input events with high-resolution - timestamps. -- **Virtual Devices (uinput)**: Emulate any hardware input device (mouse, - keyboard, gamepad) programmatically. -- **Event Selector**: Poll multiple input devices concurrently in a single +- **Event Stream**: Read kernel input events with high-resolution timestamps. +- **Virtual Devices**: Emulate any hardware input device (mouse, keyboard, + gamepad) programmatically via uinput. +- **Event Selector**: Poll multiple devices concurrently in a single non-blocking event loop. - **Multiple Lua Versions**: Compatible with LuaJIT, Lua 5.1, 5.2, 5.3, 5.4, and 5.5. ## 📦 Installation -Install the library via LuaRocks: - -```bash +```sh luarocks install bluelua-evdev ``` ## 🚀 Usage -### Listening to Key Presses - ```lua local evdev = require "evdev" --- Find and open the primary keyboard local dev = assert(evdev.device.open("/dev/input/event0")) -print("Opened device: " .. dev.name) --- Process events in a loop for event in dev:events() do if evdev.events.is_press(event) then - print("Key Pressed! Code: " .. event.code) + print("Key pressed: " .. event. code) end end ``` -### Creating a Virtual Keyboard - -```lua -local evdev = require "evdev" -local ecodes = evdev.ecodes - --- Create the virtual keyboard -local ui = assert(evdev.uinput.create()) - --- Press Shift + A -ui:emit(ecodes.EV_KEY, ecodes.KEY_LEFTSHIFT, 1) -ui:emit(ecodes.EV_KEY, ecodes.KEY_A, 1) -ui:sync() - --- Release Shift + A -ui:emit(ecodes.EV_KEY, ecodes.KEY_A, 0) -ui:emit(ecodes.EV_KEY, ecodes.KEY_LEFTSHIFT, 0) -ui:sync() - -ui:close() -``` +[documentation]: https://bluelua.github.io/evdev diff --git a/docs/src/evdev/types.md b/docs/src/evdev/types.md index f902a8f..7855355 100644 --- a/docs/src/evdev/types.md +++ b/docs/src/evdev/types.md @@ -1,6 +1,7 @@ --- title: "Types" description: "Types defined in the evdev module." +pageClass: "types-page" --- Types defined in the evdev module. @@ -9,51 +10,53 @@ Types defined in the evdev module. Open and manage input devices. -| Field | Type | Optional | -| ------------ | ------------------------------------------------------------------- | -------- | -| `close` | `fun(self): (ok:true?, err:string?)` | No | -| `fd` | `fun(self): (fd:`[`evdev.fd`]`?, err:string?)` | No | -| `flush` | `fun(self): (count:integer?, err:string?)` | No | -| `get_repeat` | `fun(self): (delay:integer?, period:integer?, err:string?)` | No | -| `grab` | `fun(self): (ok:true?, err:string?)` | No | -| `is_open` | `fun(self): boolean` | No | -| `poll` | `fun(self): (ready:boolean?, err:string?)` | No | -| `read` | `fun(self): (event:`[`evdev.event`]`?, err:string?)` | No | -| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | No | -| `ungrab` | `fun(self): (ok:true?, err:string?)` | No | +| Key | Type | +| ------------ | ------------------------------------------------------------------------------------------------ | +| `close` | `fun(self): (ok:true?, err:string?)` | +| `fd` | fun(self): (fd:evdev.fd?, err:string?) | +| `flush` | `fun(self): (count:integer?, err:string?)` | +| `get_repeat` | `fun(self): (delay:integer?, period:integer?, err:string?)` | +| `grab` | `fun(self): (ok:true?, err:string?)` | +| `is_open` | `fun(self): boolean` | +| `poll` | `fun(self): (ready:boolean?, err:string?)` | +| `read` | fun(self): (event:evdev.event?, err:string?) | +| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | +| `ungrab` | `fun(self): (ok:true?, err:string?)` | ## [`evdev.coreUInput`](https://github.com/BlueLua/evdev/blob/main/types/uinput.d.lua#L66-L77) Open virtual input device handle. -| Field | Type | Optional | -| ------------ | ------------------------------------------------------------------------------------------------------------ | -------- | -| `close` | `fun(self): (ok:true?, err:string?)` | No | -| `emit` | `fun(self, type:`[`evdev.ecodes.ev`]`, code:integer, value:`[`evdev.eventValue`]`): (ok:true?, err:string?)` | No | -| `get_repeat` | `fun(self): (delay:integer?, period_or_err:(integer` \| `string)?)` | No | -| `info` | `fun(self): (info:`[`evdev.deviceInfo`]`?, err:string?)` | No | -| `is_open` | `fun(self): boolean` | No | -| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | No | -| `sync` | `fun(self): (ok:true?, err:string?)` | No | +| Key | Type | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `close` | `fun(self): (ok:true?, err:string?)` | +| `emit` | fun(self, type:evdev.ecodes.ev, code:integer, value:evdev.eventValue): (ok:true?, err:string?) | +| `get_repeat` | `fun(self): (delay:integer?, period_or_err:(integer\|string)?)` | +| `info` | fun(self): (info:evdev.deviceInfo?, err:string?) | +| `is_open` | `fun(self): boolean` | +| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | +| `sync` | `fun(self): (ok:true?, err:string?)` | ## [`evdev.deviceInfo`](https://github.com/BlueLua/evdev/blob/main/types/device.d.lua#L14-L28) Input device metadata. -| Field | Type | Optional | Description | -| -------------- | ---------- | -------- | ----------------------------------------------------------- | -| `bustype` | `integer` | No | Bus type from the kernel input ID. | -| `id_aliases` | `string[]` | Yes | Symlink aliases under `/dev/input/by-id`, when available. | -| `name` | `string` | Yes | Device name reported by the kernel. | -| `path` | `string` | No | Device node path. | -| `path_aliases` | `string[]` | Yes | Symlink aliases under `/dev/input/by-path`, when available. | -| `phys` | `string` | Yes | Physical device path, when available. | -| `product` | `integer` | No | Product ID from the kernel input ID. | -| `uniq` | `string` | Yes | Unique identifier string, when available. | -| `vendor` | `integer` | No | Vendor ID from the kernel input ID. | -| `version` | `integer` | No | Hardware version from the kernel input ID. | - -## [`evdev.ecodes.btn`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L9-L134) +| Key | Type | Description | +| --------------- | ---------- | ----------------------------------------------------------- | +| `bustype` | `integer` | Bus type from the kernel input ID. | +| `id_aliases?` | `string[]` | Symlink aliases under `/dev/input/by-id`, when available. | +| `name?` | `string` | Device name reported by the kernel. | +| `path` | `string` | Device node path. | +| `path_aliases?` | `string[]` | Symlink aliases under `/dev/input/by-path`, when available. | +| `phys?` | `string` | Physical device path, when available. | +| `product` | `integer` | Product ID from the kernel input ID. | +| `uniq?` | `string` | Unique identifier string, when available. | +| `vendor` | `integer` | Vendor ID from the kernel input ID. | +| `version` | `integer` | Hardware version from the kernel input ID. | + +## [`evdev.ecodes.btn`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L5-L134) + +Button codes (e.g. mouse buttons, joysticks, gamepads). | Name | Value | | --------------------- | ----- | @@ -181,7 +184,10 @@ Input device metadata. | `BTN_Y` | `308` | | `BTN_Z` | `309` | -## [`evdev.ecodes.ev`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L140-L156) +## [`evdev.ecodes.ev`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L136-L156) + +Event types (e.g. key press, relative movement, absolute position, +synchronization). | Name | Value | | -------------- | ----- | @@ -200,7 +206,9 @@ Input device metadata. | `EV_SW` | `5` | | `EV_SYN` | `0` | -## [`evdev.ecodes.key`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L162-L688) +## [`evdev.ecodes.key`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L158-L688) + +Keyboard key codes. | Name | Value | | ------------------------------ | ----- | @@ -729,7 +737,9 @@ Input device metadata. | `KEY_ZOOMOUT` | `419` | | `KEY_ZOOMRESET` | `420` | -## [`evdev.ecodes.rel`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L694-L711) +## [`evdev.ecodes.rel`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L690-L711) + +Relative axis codes (e.g. mouse movement, scroll wheels). | Name | Value | | ------------------- | ----- | @@ -749,7 +759,10 @@ Input device metadata. | `REL_Y` | `1` | | `REL_Z` | `2` | -## [`evdev.ecodes.syn`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L717-L725) +## [`evdev.ecodes.syn`](https://github.com/BlueLua/evdev/blob/main/types/_enums.d.lua#L713-L725) + +Synchronization event codes used to group events or signal device status +changes. | Name | Value | | --------------- | ----- | @@ -764,14 +777,14 @@ Input device metadata. A Linux input event. -| Field | Type | Optional | Description | -| -------- | -------------------- | -------- | ----------------------------------------------------------- | -| `code` | `integer` | No | Key/button/axis code, e.g. `KEY_A`. | -| `device` | [`evdev.Device`] | Yes | The Device object that produced this event. | -| `sec` | `integer` | Yes | Timestamp seconds. | -| `type` | [`evdev.ecodes.ev`] | No | Event type, e.g. `EV_KEY`. | -| `usec` | `integer` | Yes | Timestamp microseconds. | -| `value` | [`evdev.eventValue`] | No | Event value, e.g. `0` = release, `1` = press, `2` = repeat. | +| Key | Type | Description | +| --------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- | +| `code` | `integer` | Key/button/axis code, e.g. `KEY_A`. | +| `device?` | evdev.Device | The Device object that produced this event. | +| `sec?` | `integer` | Timestamp seconds. | +| `type` | evdev.ecodes.ev | Event type, e.g. `EV_KEY`. | +| `usec?` | `integer` | Timestamp microseconds. | +| `value` | evdev.eventValue | Event value, e.g. `0` = release, `1` = press, `2` = repeat. | ## [`evdev.eventValue`](https://github.com/BlueLua/evdev/blob/main/types/evdev.d.lua#L3-L6) @@ -795,26 +808,14 @@ Path to an evdev device node or related input path. Configuration used to create a `/dev/uinput` virtual device. -| Field | Type | Optional | Description | -| ------------- | ---------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | -| `bustype` | `integer` | Yes | Linux bus type (default: `BUS_USB` / 3). | -| `event_types` | [`evdev.ecodes.ev`]`[]` | Yes | Event types to enable. Defaults to `EV_SYN`, plus `EV_KEY`/`EV_REP` for keyboard keys and `EV_REL` for relative axes. | -| `keys` | `(`[`evdev.ecodes.key`] \| [`evdev.ecodes.btn`]`)[]` | Yes | Keys/buttons to expose. Defaults to all real `KEY_*` and `BTN_*` codes when omitted. | -| `name` | `string` | Yes | Device name shown by the kernel (default: `"Lua evdev virtual keyboard"`). | -| `path` | `string` | Yes | uinput control node (default: `"/dev/uinput"`). Kernel assigns `/dev/input/eventX`. | -| `product` | `integer` | Yes | Product ID (default: `0xE7DE`). | -| `rels` | [`evdev.ecodes.rel`]`[]` | Yes | Relative axes to expose. Defaults to all real `REL_*` codes when omitted. | -| `vendor` | `integer` | Yes | Vendor ID (default: `0x1209`). | -| `version` | `integer` | Yes | Version number (default: `1`). | - - -[`evdev.Device`]: /evdev/api/device -[`evdev.deviceInfo`]: /evdev/types#evdev-deviceinfo -[`evdev.ecodes.btn`]: /evdev/api/ecodes -[`evdev.ecodes.ev`]: /evdev/api/ecodes -[`evdev.ecodes.key`]: /evdev/api/ecodes -[`evdev.ecodes.rel`]: /evdev/api/ecodes -[`evdev.eventValue`]: /evdev/types#evdev-eventvalue -[`evdev.event`]: /evdev/types#evdev-event -[`evdev.fd`]: /evdev/types#evdev-fd - +| Key | Type | Description | +| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| `bustype?` | `integer` | Linux bus type (default: `BUS_USB` / 3). | +| `event_types?` | evdev.ecodes.ev[] | Event types to enable. Defaults to `EV_SYN`, plus `EV_KEY`/`EV_REP` for keyboard keys and `EV_REL` for relative axes. | +| `keys?` | (evdev.ecodes.key\|evdev.ecodes.btn)[] | Keys/buttons to expose. Defaults to all real `KEY_*` and `BTN_*` codes when omitted. | +| `name?` | `string` | Device name shown by the kernel (default: `"Lua evdev virtual keyboard"`). | +| `path?` | `string` | uinput control node (default: `"/dev/uinput"`). Kernel assigns `/dev/input/eventX`. | +| `product?` | `integer` | Product ID (default: `0xE7DE`). | +| `rels?` | evdev.ecodes.rel[] | Relative axes to expose. Defaults to all real `REL_*` codes when omitted. | +| `vendor?` | `integer` | Vendor ID (default: `0x1209`). | +| `version?` | `integer` | Version number (default: `1`). |