homebridge-aplvibe/README.md

Homebridge plugin for SleepMe devices using APL as core logic engine

# Homebridge APLVibe Plugin

A Homebridge plugin for SleepMe temperature-controlled sleep systems, demonstrating the **APL Code Protocol** for LLM-centric development.

## Architecture: APL as Core Logic Engine

This plugin showcases how APL (A Programming Language) can serve as the primary logic engine while TypeScript provides a minimal integration layer with Homebridge.

### Layer Separation

```
┌─────────────────────────┐
│    Homebridge API       │  ← Standard HomeKit integration
├─────────────────────────┤
│   TypeScript Shim       │  ← Minimal delegation layer
│   (src/*.ts)            │     - Type safety
│                         │     - API translation
│                         │     - Event handling
├─────────────────────────┤
│   APL Core Engine       │  ← All business logic
│   (src/apl/core.apl)    │     - Device management
│                         │     - State management
│                         │     - Queue processing
│                         │     - Temperature control
│                         │     - Schedule management
└─────────────────────────┘
```

### APL Functions (Single-Character Names)

| Function | Purpose | Example |
|----------|---------|---------|
| `I ⍵` | Initialize with config | `I '{"apiToken":"abc123"}'` |
| `G` | Get devices as JSON | `G` |
| `R ⍵` | Restore accessory | `R "uuid-1234"` |
| `GS ⍵ ⍺` | Get state | `"dev1" GS "CurrentTemperature"` |
| `SS ⍵ ⍺ X` | Set state | `"dev1" SS "TargetTemperature" 22` |
| `Q ⍵` | Queue request | `Q requestObject` |
| `P` | Process queue | `P` |
| `T ⍵ ⍺` | Convert temperature | `20 T "F"` |
| `V ⍵ ⍺` | Validate temperature | `75 V "F"` |
| `AS ⍵` | Apply schedule | `AS "dev1"` |

### Key APL Features Demonstrated

#### Tacit Programming for Temperature Conversion
```apl
C2F←{32+⍵×9÷5}    ⍝ Celsius to Fahrenheit
F2C←{(⍵-32)×5÷9}  ⍝ Fahrenheit to Celsius
```

#### Array Operations for Queue Management
```apl
SQ←{⍵[⍋⍵[;2];]}   ⍝ Sort queue by priority
RL←{(10>+/⍵[;3]≥⌊(⊃¯1↑⎕TS)÷60000)/⍵}  ⍝ Rate limit filter
```

#### Schedule Processing with Time Arithmetic
```apl
PT←{60⊥⍎¨':'(≠⊆⊢)⍵}  ⍝ Parse time to minutes
```

## Benefits of APL Core Approach

### 1. **Conciseness**
- Queue sorting: `⍵[⍋⍵[;2];]` vs 10+ lines of TypeScript
- Rate limiting: Single APL expression vs complex loop logic
- Time calculations: Native array arithmetic

### 2. **Clarity**
- Mathematical operations more readable in APL notation
- Array transformations express intent clearly
- No explicit loops or temporary variables

### 3. **Performance**
- Native array operations for state management
- Efficient sorting and filtering
- Minimal memory allocation

### 4. **Maintainability**
- All business logic in single APL file
- TypeScript layer remains stable
- Logic changes isolated to APL functions

## Installation

```bash
npm install homebridge-aplvibe
```

## Configuration

Add to your Homebridge `config.json`:

```json
{
  "platforms": [
    {
      "name": "APLVibe",
      "platform": "APLVibe",
      "apiToken": "your-sleepme-api-token",
      "unit": "C",
      "pollingInterval": 90,
      "devices": [
        {
          "deviceId": "device-id-1",
          "name": "Bedroom DockPro",
          "schedules": [
            {
              "time": "22:00",
              "temperature": 18
            },
            {
              "time": "06:00", 
              "temperature": 20
            }
          ]
        }
      ]
    }
  ]
}
```

## Features

### Temperature Control
- Celsius/Fahrenheit conversion handled by APL
- Range validation (13-46°C / 55-115°F)
- Real-time temperature monitoring

### Request Queue with Rate Limiting
- Priority-based processing (CRITICAL > HIGH > NORMAL > LOW)
- 10 requests per minute rate limit
- Discrete minute windows for fair distribution

### Scheduled Temperature Changes
- Time-based temperature automation
- Multiple schedules per device
- Automatic application during polling

### Device Management
- Auto-discovery of SleepMe devices
- Online/offline status monitoring
- Water level monitoring (via battery service)

## Development

### Build
```bash
npm run build
```

### Watch Mode
```bash
npm run watch
```

## APL Code Protocol Demonstration

This plugin serves as a reference implementation of the APL Code Protocol, showing how:

1. **TypeScript** provides type safety and integration without business logic
2. **APL** handles all algorithms, state management, and data processing
3. **JSON** serves as the data interchange format between layers
4. **Events** enable loose coupling between APL and TypeScript layers

The result is a maintainable, performant, and concise codebase where:
- Adding new features typically requires only APL changes
- TypeScript layer remains stable and minimal
- Complex logic is expressed clearly in APL's mathematical notation

## License

MIT