# Sensordomo
## A Plan 9-Style Agent for Device Sensors

Every phone and laptop is a sensor array. Sensordomo exposes them as files.

> **Everything is a file. The agent mediates every request.**

In the Plan 9 tradition, sensors aren't APIs — they're paths. The sensordomo agent serves these paths, deciding what each requester sees based on their Acequia token.

---

## The Problem

Device sensors are trapped:

- Locked inside native apps
- No uniform API across platforms
- No authorization model for sensor access
- No pub/sub or streaming
- No way to discover sensors remotely

---

## The Proposal

**Sensordomo** is an Acequia-native sensor agent that exposes all device sensors as files:

- HTTPS URIs (same as WebDAV)
- Token-based access control (requester determines what they see)
- WebSocket for pub/sub streams
- Webhooks for event notifications
- WebRTC for low-latency peer routes

---

## Part of a Larger System

Sensordomo is one half of a sense-act loop:

| Agent | Role | Namespace |
|-------|------|-----------|
| **Sensordomo** | Reads from sensors (input) | `/sensors/` |
| **Actuatordomo** | Writes to actuators (output) | `/actuators/` |
| **Mayordomo** | Orchestrates both (rules, automation) | — |

This pitch focuses on **Sensordomo**.

---

## Everything is a File (Plan 9 Style)

```
/sensors/                     → Directory listing of available sensors
/sensors/camera/              → List cameras
/sensors/camera/0             → GET frame, WS stream, PUT config
/sensors/gps                  → GET location, WS stream
/sensors/motion               → GET reading, WS stream
/sensors/audio                → GET sample, WS stream
/sensors/light                → GET lux value
/sensors/battery              → GET status
```

Same URI, different interaction:

| Method | URI | Result |
|--------|-----|--------|
| GET | `/sensors/motion` | Single reading (JSON) |
| WS | `/sensors/motion` | Continuous stream |
| PUT | `/sensors/camera/0` | Configure sensor |

The agent mediates every request based on who's asking.

---

## Subscriptions as Files (Firebase-style `/on/`)

```
/sensors/motion/on/              → List active subscriptions
POST /sensors/motion/on/         → Create subscription
GET  /sensors/motion/on/abc123   → View subscription config
PUT  /sensors/motion/on/abc123   → Modify subscription
DELETE /sensors/motion/on/abc123 → Unsubscribe
```

**Create a subscription:**
```json
POST /sensors/motion/on/
{
  "callback": "https://myserver.com/motion",
  "hz": 10,
  "event": "change"
}
→ Returns: { "id": "abc123" }
```

**Event types:**
- `value` — Every reading at specified hz
- `change` — Only when value changes
- `threshold` — When exceeds/drops below threshold

Subscriptions are first-class resources — create, read, update, delete.

---

## Models as Files (What to Detect)

```
/models/                              → Available detection models
/models/package-carriers              → FedEx, UPS, USPS, Amazon
/models/faces/                        → Face recognition
/models/faces/family                  → Known family members
/models/motion/person                 → Person detection
/models/audio/doorbell                → Doorbell sound
```

Models can be local or remote Acequia URIs:
- `/models/package-carriers` — Local model
- `https://models.acequia.org/vision/carriers` — Community shared

---

## Example: Package Delivery Subscription

```json
POST /sensors/camera/0/on/
{
  "id": "deliveries",
  "model": "/models/package-carriers",
  "callback": "https://home.acequia.io/alerts",
  "capture": true,
  "cooldown": 300
}
```

Creates `/sensors/camera/0/on/deliveries`

When FedEx/UPS/USPS/Amazon detected:
- Fires webhook to callback
- Includes captured frame
- Won't re-fire for 5 minutes

**Mayordomo can then orchestrate:**
```
PUT /actuators/lock/front-door { "state": "unlocked", "duration": 60 }
PUT /actuators/lights/porch { "state": "on" }
PUT /actuators/speaker/outdoor { "play": "/audio/welcome-delivery.mp3" }
```

---

## Requester-Based Access

The Acequia token determines what sensors you can access:

| Role | Access |
|------|--------|
| Mayordomo | All sensors, full control |
| Parciante | Cameras, location |
| Guest | Read-only, limited sensors |

Custom scopes possible in token claims:
```json
{
  "sensors": ["/sensors/camera/*", "/sensors/gps"],
  "methods": ["GET"],
  "subscribe": false
}
```

---

## Sensor Categories

| Category | Sensors | Platforms |
|----------|---------|-----------|
| Vision | RGB, depth, IR, thermal | All |
| Location | GPS, network, compass | Mobile + some laptops |
| Motion | Accelerometer, gyro | Mobile |
| Audio | Microphone, audio levels | All |
| Environment | Light, pressure, proximity, humidity | Mobile |
| System | Battery, network, storage | All |

---

## Architecture

```
[Phone/Laptop Sensors]
       ↓
[sensordomo agent]
       ↓
┌─────────────────────────────────┐
│  HTTPS REST │ WebSocket │ WebRTC │
└─────────────────────────────────┘
       ↓
[Requester with Acequia token]
```

---

## Lineage

```
photoserver.js (Termux cameras)
       ↓
sensordomo (all sensors, Plan 9-style, Acequia-native)
```

Original: [geo-camera/apps/photoserver.js](https://geo.camera/apps/photoserver.js)

---

## Implementation

See [sensordomo-plan.md](https://guerin.acequia.org/apps/sensordomo/sensordomo-plan.md) for phased implementation details.

---

*Sensordomo: Your device's sensors, as files.*