# presence

**Repository Path**: lisf0/presence

## Basic Information

- **Project Name**: presence
- **Description**: No description available
- **Primary Language**: Shell
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# presence

Hardware presence detection framework built on systemd + udev: starts/stops entity services when devices are plugged in or removed, with a watchdog timer that periodically checks and self-heals.

## How it works

- **udev trigger**: each entity ships a `99-presence-<name>.rules` file; HID `add`/`remove` events run `systemctl start/stop presence-<name>.service`.
- **Watchdog**: `presence-watchdog.timer` fires `presence-check.sh` every 10 seconds, which runs each entity's `gone.sh` to reconcile service state with actual hardware presence (e.g. missed `remove` events, accidentally stopped services).
- **Anchor config**: install writes the repo path into `/etc/presence.env` (`PRESENCE_DIR`); all units read it via `EnvironmentFile`, so moving the repo only requires re-running `install.sh`.

## Layout

```
presence/
├── install.sh                 # Install: write anchor, symlink units, enable watchdog timer
├── uninstall.sh               # Uninstall: stop services, remove symlinks, remove anchor
├── lib/
│   └── presence-check.sh      # Watchdog runner: iterates entity gone.sh; one failing entity doesn't abort the loop
├── units/
│   ├── presence-watchdog.timer    # Fires every 10s (OnBootSec=10s)
│   └── presence-watchdog.service  # oneshot, runs presence-check.sh
└── entities/
    └── xbox/                  # Example entity: Xbox Wireless Controller (VID 0x045e)
        ├── 99-presence-xbox.rules   # udev add/remove → start/stop
        ├── presence-xbox.service    # Type=simple with ExecStop; wraps start/stop scripts
        ├── start.sh                 # Long-running process entry (foreground, no daemonization), writes PID
        ├── stop.sh                  # Graceful kill → fallback SIGKILL → remove PID file
        └── gone.sh                  # Check: hardware present? reconcile service state if not
```

## Install / Uninstall

```bash
sudo ./install.sh      # requires root
sudo ./uninstall.sh
```

After install:

- `presence-watchdog.timer` is enabled and started, so it runs at boot
- All units are symlinked into `/etc/systemd/system/`, udev rules into `/etc/udev/rules.d/`
- The repo can be moved; re-run `install.sh` to refresh the anchor

## Adding an entity

Create these files under `entities/<name>/`:

| File | Requirement |
|---|---|
| `99-presence-<name>.rules` | Optional; start/stop the service on device add/remove |
| `presence-<name>.service` | Optional; `Type=simple`, with `ExecStart`/`ExecStop` |
| `start.sh` | Long-running process entry, foreground, no forking; launched by the service |
| `stop.sh` | Cleanup: graceful kill, remove PID file |
| `gone.sh` | Watchdog logic; reconcile service state with hardware presence; must exit 0 |

Convention: the service PID is written to `/run/presence/<name>.pid` (overridable via `PRESENCE_PID_FILE`).

`install.sh` iterates `entities/*/` automatically and symlinks whatever service/rules files exist; re-run it to install new entities.