Hotel Pi - Raspberry Pi TV Kiosk System

A production-grade, hotel-style TV kiosk application built with SvelteKit, Node.js, and Directus CMS.

Overview

Hotel Pi provides a fullscreen, remote-controlled kiosk interface for Raspberry Pi 4/5, designed to mimic modern hotel TV systems with:

• Idle Screen: Time, date, and welcome message with ambient visuals
• Home Menu: Gridded navigation to main features
• Dynamic Content: Restaurants and attractions from Directus CMS
• Media Integration: Seamless Plex/Kodi launch support
• Remote Control: HDMI-CEC input handling via Node.js service
• WebSocket Communication: Real-time event delivery between control service and frontend

Architecture

┌─────────────────────────────────────────────────────┐
│              Chromium Kiosk (fullscreen)            │
│         SvelteKit Frontend (localhost:5173)         │
└───────────────────┬─────────────────────────────────┘
                    │ WebSocket
┌───────────────────▼─────────────────────────────────┐
│    Node.js Control Service (localhost:3001)         │
│  - HDMI-CEC listener (cec-client)                   │
│  - System command executor                          │
│  - WebSocket event emitter                          │
└───────────────────┬─────────────────────────────────┘
                    │
        ┌───────────┴────────────┬──────────────┐
        │                        │              │
┌───────▼──────────┐  ┌──────────▼────────┐   │
│  Directus CMS    │  │ PostgreSQL DB     │   │
│  REST API        │  │                   │   │
└──────────────────┘  └───────────────────┘   │
                                               │
                                   ┌───────────▼─────────┐
                                   │ System Services     │
                                   │ - Plex              │
                                   │ - Kodi              │
                                   │ - Chromium          │
                                   └─────────────────────┘

Quick Start

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• Raspberry Pi 4 or 5 (or Linux/macOS for development)

Setup

1. Clone and install dependencies:

   git clone <repo>
   cd Hotel_Pi
   cp .env.example .env
   

2. Start services with Docker Compose:

   docker-compose up -d
   

3. Run frontend (development):

   cd frontend
   npm install
   npm run dev
   

4. Run control service (in separate terminal):

   cd control-service
   npm install
   npm run dev
   

5. Access the system:

   • Frontend: http://localhost:5173
   • Directus: http://localhost:8055
   • Control Service: ws://localhost:3001

Directory Structure

Hotel_Pi/
├── frontend/                 # SvelteKit application
│   ├── src/
│   │   ├── routes/          # Page components
│   │   ├── lib/             # Shared utilities
│   │   ├── components/      # Reusable UI components
│   │   └── app.svelte       # Root layout
│   ├── svelte.config.js
│   └── package.json
├── control-service/         # Node.js control service
│   ├── src/
│   │   ├── server.js        # Main entry point
│   │   ├── cec-handler.js   # HDMI-CEC listener
│   │   └── commands.js      # System command executor
│   └── package.json
├── directus/                # CMS configuration
│   ├── extensions/
│   └── snapshots/
├── docker/                  # Docker Compose files
│   └── docker-compose.yml
├── scripts/                 # Launch and control scripts
│   ├── launch-kiosk.sh
│   ├── launch-plex.sh
│   └── return-to-kiosk.sh
└── docker-compose.yml       # Main orchestration

Configuration

See .env.example for all available configuration options.

Key settings:

• VITE_API_URL: Directus API endpoint
• VITE_WS_URL: Control service WebSocket endpoint
• CEC_DEVICE: Serial device for HDMI-CEC (typically /dev/ttyAMA0)
• IDLE_TIMEOUT_MINUTES: Auto-return to idle screen after this duration

Development

Frontend Development

cd frontend
npm run dev

Hot-reload enabled. Access at http://localhost:5173

Control Service Development

cd control-service
npm run dev

WebSocket server available at ws://localhost:3001

CMS Setup

Directus runs at http://localhost:8055

Default credentials (change in production):

• Email: admin@example.com
• Password: (set during first run)

Deployment (Raspberry Pi)

1. Install system dependencies:

   sudo apt-get update
   sudo apt-get install -y docker.io docker-compose chromium-browser libcec-dev
   

2. Build production bundle:

   cd frontend
   npm run build
   

3. Deploy with Docker Compose:

   docker-compose -f docker/docker-compose.yml up -d
   

4. Launch kiosk (runs on startup):

   ./scripts/launch-kiosk.sh
   

Input Handling

HDMI-CEC Remote Events

• Arrow Keys: Navigate menu
• Select/OK: Choose item
• Back: Return to previous screen
• Any key: Wake from idle screen

Control service translates CEC codes and emits WebSocket events.

Performance Optimization

• CSS animations preferred over JavaScript
• Lazy loading for images
• Optimized SVG assets
• Minimal JavaScript dependencies
• Service worker caching

Production Considerations

• Change all default credentials
• Set up HTTPS for Directus (if public)
• Configure CORS properly
• Set environment-specific secrets
• Enable log rotation
• Set up health checks
• Configure automatic restarts

Troubleshooting

HDMI-CEC not working

• Check device: ls -la /dev/ttyAMA0
• Test with cec-client command directly
• Verify CEC is enabled on TV

WebSocket connection fails

• Check firewall rules
• Ensure control service is running: curl http://localhost:3001/health
• Review browser console for connection errors

Frontend not loading

• Check Docker logs: docker logs hotel_pi_frontend
• Verify API URL in .env
• Clear browser cache

Contributing

1. Create a feature branch
2. Make changes following the code style
3. Test on Raspberry Pi if possible
4. Submit a pull request

License

MIT

Support

For issues and questions, please open an issue on GitHub.