docs: update README with features, documentation link, and examples

Author: haithium

README.md

@@ -1,10 +1,74 @@
 # evdev
 
-Lua bindings for Linux `evdev` input devices and `/dev/uinput` virtual
-keyboards, pointers.
+Lua bindings for Linux `evdev` input devices and `/dev/uinput` virtual devices
+(keyboards, mice, and relative pointers).
 
-## Install
+Get started with the
+[documentation and tutorials](https://bluelua.github.io/evdev).
+
+[![LuaRocks](https://img.shields.io/luarocks/v/BlueLua/bluelua-evdev?color=blue)](https://luarocks.org/modules/BlueLua/bluelua-evdev)
+[![License](https://img.shields.io/github/license/BlueLua/evdev?color=lightgrey)](LICENSE)
+
+## 🚀 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
+  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
 luarocks install bluelua-evdev
 ```
+
+## 🛠️ Quick Examples
+
+### 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)
+  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()
+```