Add sleep mode and documentation

- Sleep/wake endpoints for Home Assistant webhooks - Sleep state: dim ( -_-)zzZ with slow breathing animation - Updated CLAUDE.md with full technical reference - Added README.md with user guide and HA integration examples Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-02 21:43:25 -06:00
parent af4ccb9a35
commit 53e6f0bcdd
4 changed files with 238 additions and 30 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,155 @@
+# Sentry-Emote
+
+A minimalist system status monitor that uses ASCII emotes to display server health on an old phone.
+
+![Status: Optimal](https://img.shields.io/badge/status-(%20%5E___%5E)-brightgreen)
+
+## Why?
+
+Turn an old phone (with its OLED screen) into a glanceable ambient display for your home server. Instead of graphs and numbers, see a happy face `( ^_^)` when things are good, and a worried face `( o_o)` when they're not.
+
+## Features
+
+- **OLED-optimized** — Pure black background, saves battery
+- **Glanceable** — Know your server's status from across the room
+- **Extensible** — Add custom detectors for any metric
+- **Personality** — Rotating expressions, celebration animations, sleep mode
+- **Home Assistant ready** — Webhook endpoints for automation
+
+## Quick Start
+
+```bash
+# Clone and setup
+git clone https://github.com/yourusername/sentry-emote.git
+cd sentry-emote
+python -m venv venv
+source venv/bin/activate  # Windows: .\venv\Scripts\activate
+pip install -r requirements.txt
+
+# Run everything
+python sentry.py
+```
+
+Open http://localhost:5000 on your phone (use Fully Kiosk Browser for best results).
+
+## Status Faces
+
+| State | Emote | Meaning |
+|-------|-------|---------|
+| Optimal | `( ^_^)` | All systems healthy |
+| Warning | `( o_o)` | Something needs attention |
+| Critical | `( x_x)` | Immediate action required |
+| Notify | `( 'o')` | Transient notification |
+| Sleeping | `( -_-)zzZ` | Sleep mode active |
+| Disconnected | `( ?.?)` | Can't reach server |
+
+## Built-in Detectors
+
+| Detector | Monitors |
+|----------|----------|
+| **disk_space** | Disk usage on all drives |
+| **cpu** | CPU utilization |
+| **memory** | RAM usage |
+| **service** | Whether processes are running |
+| **network** | Host reachability (ping) |
+
+## Configuration
+
+Edit `config.json` to enable/disable detectors and set thresholds:
+
+```json
+{
+  "aggregator_url": "http://localhost:5000",
+  "detectors": [
+    {
+      "name": "disk_space",
+      "enabled": true,
+      "script": "detectors/disk_space.py",
+      "env": {
+        "CHECK_INTERVAL": "300",
+        "THRESHOLD_WARNING": "85",
+        "THRESHOLD_CRITICAL": "95"
+      }
+    }
+  ]
+}
+```
+
+## Custom Detectors
+
+Create your own detector by POSTing events to the aggregator:
+
+```bash
+curl -X POST http://localhost:5000/event \
+  -H "Content-Type: application/json" \
+  -d '{"id": "my_check", "priority": 2, "message": "Something is wrong", "ttl": 120}'
+```
+
+- `id` — Unique identifier for this event
+- `priority` — 1 (critical), 2 (warning), 3 (notify), 4 (optimal)
+- `message` — What to display
+- `ttl` — Auto-expire after N seconds (for heartbeat pattern)
+
+Clear an event:
+```bash
+curl -X POST http://localhost:5000/clear \
+  -d '{"id": "my_check"}'
+```
+
+## Home Assistant Integration
+
+Add webhook commands to your Home Assistant config:
+
+```yaml
+rest_command:
+  sentry_sleep:
+    url: "http://YOUR_SERVER:5000/sleep"
+    method: POST
+  sentry_wake:
+    url: "http://YOUR_SERVER:5000/wake"
+    method: POST
+```
+
+Trigger from automations:
+
+```yaml
+automation:
+  - alias: "Sentry Sleep at Bedtime"
+    trigger:
+      platform: time
+      at: "23:00:00"
+    action:
+      service: rest_command.sentry_sleep
+
+  - alias: "Sentry Wake in Morning"
+    trigger:
+      platform: time
+      at: "07:00:00"
+    action:
+      service: rest_command.sentry_wake
+```
+
+## API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Web UI |
+| `/status` | GET | Current state as JSON |
+| `/events` | GET | List all active events |
+| `/event` | POST | Register an event |
+| `/clear` | POST | Clear an event by ID |
+| `/sleep` | POST | Enter sleep mode |
+| `/wake` | POST | Exit sleep mode |
+
+## Personality
+
+The emote has personality! In optimal state it:
+
+- Rotates through happy faces every 5 minutes
+- Occasionally winks `( -_^)` or blinks `( ᵕ.ᵕ)`
+- Celebrates `\(^o^)/` when recovering from warnings
+- Each face has its own animation (floating, bouncing, swaying)
+
+## License
+
+MIT