Kao/README.md

Sentry-Emote

A minimalist system status monitor that uses ASCII emotes to display server health on an old phone.

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

# 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:

{
  "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:

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:

curl -X POST http://localhost:5000/clear \
  -d '{"id": "my_check"}'

Home Assistant Integration

Add webhook commands to your Home Assistant config:

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:

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