hotel_pi/API.md

API Reference

Frontend Environment Variables

# Directus CMS endpoint
VITE_API_URL=http://localhost:8055

# Control service WebSocket
VITE_WS_URL=ws://localhost:3001

# Welcome message on idle screen
VITE_WELCOME_NAME=Guest

# Auto-return to idle after (minutes)
VITE_IDLE_TIMEOUT=5

Control Service API

WebSocket Messages

The control service listens on ws://localhost:3001

Client → Server

{
  "type": "launch-plex",
  "payload": {}
}

{
  "type": "return-to-kiosk",
  "payload": {}
}

{
  "type": "restart-kiosk",
  "payload": {}
}

{
  "type": "execute",
  "payload": {
    "command": "ls -la /tmp"
  }
}

Server → Client

{
  "type": "connected",
  "payload": {
    "timestamp": "2024-03-20T12:34:56Z"
  }
}

{
  "type": "input",
  "payload": {
    "type": "up"
  }
}

Input event types:

• up, down, left, right - Navigation
• select - Confirm selection
• back - Go back

HTTP Endpoints

Health Check

GET http://localhost:3001/health

{
  "status": "healthy",
  "timestamp": "2024-03-20T12:34:56Z",
  "processes": ["plex"]
}

Directus API

Collections

Restaurants

GET http://localhost:8055/items/restaurants?fields=*,image.*

[
  {
    "id": "uuid",
    "name": "La Bella Vita",
    "description": "Italian cuisine",
    "cuisine_type": "Italian",
    "website_url": "https://example.com",
    "phone": "+1-555-0123",
    "image": {
      "id": "file-id",
      "filename_disk": "restaurant.jpg"
    },
    "status": "published"
  }
]

Attractions

GET http://localhost:8055/items/attractions?fields=*,image.*

[
  {
    "id": "uuid",
    "name": "City Museum",
    "description": "World-class art",
    "category": "Museum",
    "distance_km": 2.5,
    "image": {
      "id": "file-id",
      "filename_disk": "museum.jpg"
    },
    "website_url": "https://example.com",
    "hours": "10 AM - 6 PM",
    "status": "published"
  }
]

Get Images

# Direct image URL
http://localhost:8055/assets/{filename}

# Example
http://localhost:8055/assets/restaurant-12345.jpg

Frontend Store API

import {
  currentScreen,      // 'idle' | 'home' | 'restaurants' | 'attractions'
  selectedIndex,      // Currently selected menu item index
  restaurants,        // Array of restaurant items
  attractions,        // Array of attraction items
  wsConnected,        // Boolean - WebSocket connection status
  pushScreen,         // (screen) => void
  popScreen,          // () => void
  resetNavigation,    // () => void
} from '$lib/store.js';

CMS Integration

Fetch Data

import { fetchRestaurants, fetchAttractions } from '$lib/api.js';

const restaurants = await fetchRestaurants();
const attractions = await fetchAttractions();

Generate QR Codes

import { generateQRCode } from '$lib/qrcode.js';

const qrDataUrl = await generateQRCode('https://example.com');
// Returns: data:image/png;base64,...

WebSocket Connection

import WebSocketManager from '$lib/websocket.js';

const ws = new WebSocketManager('ws://localhost:3001');

ws.on('connected', () => console.log('Connected'));
ws.on('input', (data) => console.log('Input:', data));

ws.connect();
ws.send('launch-plex');

System Commands

Launch Scripts

# Start kiosk
./scripts/launch-kiosk.sh

# Launch Plex
./scripts/launch-plex.sh

# Return to kiosk
./scripts/return-to-kiosk.sh

# Initialize system (Raspberry Pi)
./scripts/init-system.sh

# Rebuild services
./scripts/rebuild.sh

# Stop services
./scripts/stop.sh

# View logs
./scripts/logs.sh [service]

# Control service CLI
./scripts/control.sh [command]

Docker Compose Services

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View status
docker-compose ps

# View logs
docker-compose logs -f [service]

# Services:
# - postgres       (Database)
# - directus       (CMS)
# - frontend       (Kiosk UI)
# - control-service (Remote control)

Environment Configuration

Root .env

# Frontend
VITE_API_URL=http://localhost:8055
VITE_WS_URL=ws://localhost:3001
WELCOME_NAME=Guest
IDLE_TIMEOUT_MINUTES=5

# Control Service
PORT=3001
CEC_DEVICE=/dev/ttyAMA0
PLEX_LAUNCH_COMMAND=/usr/bin/plex-htpc
KIOSK_LAUNCH_COMMAND=/home/pi/scripts/launch-kiosk.sh

# Directus
DATABASE_URL=postgresql://directus:directus123@postgres:5432/directus
SECRET=your-secret-key
AUTH_SECRET=your-auth-secret
DB_CLIENT=postgres
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=directus123
CORS_ORIGIN=http://localhost:5173

# Postgres
POSTGRES_USER=directus
POSTGRES_PASSWORD=directus123
POSTGRES_DB=directus

Error Handling

Common HTTP Status Codes

• 200 - Success
• 404 - Not found (collection doesn't exist)
• 401 - Unauthorized (authentication required)
• 500 - Server error

WebSocket Errors

{
  "type": "error",
  "payload": {
    "message": "Command failed"
  }
}

Rate Limits

No rate limits configured by default. Configure in production:

Directus:

• Settings → Project Settings → Rate Limiting

Control Service:

• Implement in server.js middleware