imperial-command-center/SETUP.md

# Command Center - Complete Setup Guide

A Home Assistant touchscreen dashboard for Windows and Linux.

---

## Table of Contents

1. [Prerequisites](#1-prerequisites)
2. [Project Installation](#2-project-installation)
3. [Home Assistant Setup](#3-home-assistant-setup)
4. [Google Calendar Setup](#4-google-calendar-setup-optional)
5. [Camera Setup](#5-camera-setup)
6. [Entity Configuration](#6-entity-configuration)
7. [Building the Application](#7-building-the-application)
8. [Windows Deployment](#8-windows-deployment)
9. [Linux Deployment](#9-linux-deployment)
10. [First Launch](#10-first-launch)
11. [Troubleshooting](#11-troubleshooting)

---

## 1. Prerequisites

### Development Machine (to build the app)

| Requirement | Windows | Linux |
|-------------|---------|-------|
| Node.js | v18+ from [nodejs.org](https://nodejs.org) | `sudo apt install nodejs npm` |
| Git | [git-scm.com](https://git-scm.com) | `sudo apt install git` |
| Code Editor | VS Code recommended | VS Code recommended |

### Touchscreen Device

**Supported Platforms:**
- Windows 10/11 PC or tablet
- Linux PC (Ubuntu, Debian, Raspberry Pi OS)
- Raspberry Pi 4 (4GB+ recommended)

**Requirements:**
- Touchscreen display (or mouse for testing)
- Network access to Home Assistant
- Network access to camera streams (if using cameras)

---

## 2. Project Installation

### Windows

```powershell
# Open PowerShell and navigate to your projects folder
cd C:\Projects

# Clone or copy the project
git clone <your-repo-url> command-center
cd command-center

# Install dependencies
npm install
```

### Linux

```bash
# Navigate to your projects folder
cd ~/projects

# Clone or copy the project
git clone <your-repo-url> command-center
cd command-center

# Install dependencies
npm install
```

### Verify Installation

```bash
npm run dev
```

Open http://localhost:5173 in a browser. You should see the dashboard (it won't have data yet).

---

## 3. Home Assistant Setup

### Step 1: Create a Long-Lived Access Token

The app needs a token to communicate with Home Assistant.

1. **Open Home Assistant** in your browser
2. **Click your username** (bottom-left corner of the sidebar)
3. **Scroll down** to "Long-Lived Access Tokens" section
4. **Click "Create Token"**
5. **Enter a name**: `Command Center`
6. **Click "OK"**
7. **IMPORTANT: Copy the token immediately!** You won't be able to see it again.

Save this token somewhere safe - you'll need it when you first launch the app.

### Step 2: Find Your Entity IDs

You need to know the exact entity IDs for your devices.

1. **Go to Developer Tools** (sidebar) → **States**
2. **Search for your entities** using the filter box
3. **Note down the entity IDs** for:
   - Thermostats (e.g., `climate.living_room_thermostat`)
   - Lights (e.g., `light.kitchen_main`)
   - Locks (e.g., `lock.front_door`)
   - Alarm panel (e.g., `alarm_control_panel.alarmo`)
   - Person entities (e.g., `person.john`)
   - Todo list (e.g., `todo.shopping_list`)

**Tip:** Entity IDs are case-sensitive!

### Step 3: Set Up Alarmo (Optional)

If you want alarm panel functionality:

1. **Install HACS** if you haven't: [hacs.xyz](https://hacs.xyz)
2. **Install Alarmo** from HACS
3. **Configure Alarmo**: Settings → Devices & Services → Alarmo
4. **Set up a PIN code** for arming/disarming
5. **Add sensors** to your alarm zones
6. **Note the entity ID** (usually `alarm_control_panel.alarmo`)

---

## 4. Google Calendar Setup (Optional)

If you want to display your Google Calendar events.

### Step 1: Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. **Sign in** with your Google account
3. Click **"Select a project"** (top bar) → **"New Project"**
4. **Project name**: `Command Center`
5. Click **"Create"**
6. Wait for the project to be created, then select it

### Step 2: Enable the Google Calendar API

1. In the left sidebar, click **"APIs & Services"** → **"Library"**
2. Search for **"Google Calendar API"**
3. Click on **"Google Calendar API"**
4. Click **"Enable"**

### Step 3: Configure OAuth Consent Screen

1. Go to **"APIs & Services"** → **"OAuth consent screen"**
2. Select **"External"** → Click **"Create"**
3. Fill in the required fields:
   - **App name**: `Command Center`
   - **User support email**: Your email
   - **Developer contact email**: Your email
4. Click **"Save and Continue"**
5. On **Scopes** page, click **"Add or Remove Scopes"**
6. Find and check: `https://www.googleapis.com/auth/calendar.readonly`
7. Click **"Update"** → **"Save and Continue"**
8. On **Test users** page, click **"Add Users"**
9. **Add your Google email address**
10. Click **"Save and Continue"** → **"Back to Dashboard"**

### Step 4: Create OAuth Credentials

1. Go to **"APIs & Services"** → **"Credentials"**
2. Click **"Create Credentials"** → **"OAuth client ID"**
3. **Application type**: Select **"Desktop app"**
4. **Name**: `Command Center Desktop`
5. Click **"Create"**
6. **Copy the "Client ID"** (looks like: `123456789-xxxxx.apps.googleusercontent.com`)

### Step 5: Add to Environment File

Add to your `.env` file:

```env
VITE_GOOGLE_CLIENT_ID=123456789-xxxxx.apps.googleusercontent.com
```

---

## 5. Camera Setup

You have **two options** for viewing cameras:

### Option A: Use go2rtc (Recommended)

If you already have go2rtc running (e.g., with Frigate), you can stream cameras directly.

**In your `.env` file:**
```env
VITE_GO2RTC_URL=http://192.168.1.241:1985
```

**In `src/config/entities.ts`, configure your cameras:**
```typescript
cameras: [
  { name: 'FPE', displayName: 'Front Porch', go2rtcStream: 'FPE' },
  { name: 'Backyard', displayName: 'Backyard', go2rtcStream: 'Backyard' },
  // Stream names must match your go2rtc.yaml configuration
],
```

**Verify go2rtc is working:**
- Open `http://your-go2rtc-ip:1985` in a browser
- You should see a list of your camera streams
- Click a stream to verify video plays

### Option B: Use External Camera Viewer App

If you have a separate camera viewer application (like the one we created previously), you can:

1. **Disable the built-in camera overlay** by leaving the cameras array empty:
   ```typescript
   cameras: [],
   ```

2. **Open your camera viewer app** separately when needed

3. **Or modify the camera button** in `Header.tsx` to launch your external app

### Option C: Use Home Assistant Camera Entities

If your cameras are integrated into Home Assistant:

1. The app can display camera snapshots via HA camera entities
2. Configure camera entity IDs in `entities.ts`
3. Note: This provides snapshots, not live video streams

---

## 6. Entity Configuration

### Step 1: Create Environment File

**Windows (PowerShell):**
```powershell
Copy-Item .env.example .env
notepad .env
```

**Linux:**
```bash
cp .env.example .env
nano .env
```

### Step 2: Edit .env File

```env
# Home Assistant - UPDATE THESE
VITE_HA_URL=http://192.168.1.50:8123
VITE_HA_WS_URL=ws://192.168.1.50:8123/api/websocket

# Frigate (optional - for person detection alerts)
VITE_FRIGATE_URL=http://192.168.1.241:5000

# go2rtc (optional - for camera streams)
VITE_GO2RTC_URL=http://192.168.1.241:1985

# Google Calendar (optional - from Step 4)
VITE_GOOGLE_CLIENT_ID=

# Screen timeout in milliseconds (5 minutes = 300000)
VITE_SCREEN_IDLE_TIMEOUT=300000
```

### Step 3: Edit Entity Configuration

Edit `src/config/entities.ts` with your actual entity IDs:

```typescript
export const entitiesConfig: EntitiesConfig = {
  // THERMOSTATS - Update with your thermostat entity IDs
  thermostats: [
    {
      entityId: 'climate.downstairs',  // <-- Your entity ID
      name: 'Downstairs',
      location: 'downstairs',
    },
    {
      entityId: 'climate.upstairs',    // <-- Your entity ID
      name: 'Upstairs',
      location: 'upstairs',
    },
  ],

  // LIGHTS - Group by room, update entity IDs
  lights: [
    // Living Room
    { entityId: 'light.living_room_ceiling', name: 'Ceiling', room: 'Living Room' },
    { entityId: 'light.living_room_lamp', name: 'Lamp', room: 'Living Room' },
    // Kitchen
    { entityId: 'light.kitchen_main', name: 'Main', room: 'Kitchen' },
    // Add more rooms and lights...
  ],

  // DOOR LOCKS - Update entity IDs
  locks: [
    { entityId: 'lock.front_door_lock', name: 'Front Door', location: 'front' },
    { entityId: 'lock.back_door_lock', name: 'Back Door', location: 'back' },
    { entityId: 'lock.garage_entry', name: 'Garage', location: 'garage' },
  ],

  // ALARM - Alarmo entity ID
  alarm: 'alarm_control_panel.alarmo',

  // PACKAGE DETECTION - Binary sensor for package notifications
  packageSensor: 'binary_sensor.package_detected',

  // TODO LIST - Home Assistant todo entity
  todoList: 'todo.shopping_list',

  // CAMERAS - go2rtc stream names (see Camera Setup section)
  cameras: [
    { name: 'FPE', displayName: 'Front Porch', go2rtcStream: 'FPE', frigateCamera: 'FPE' },
    { name: 'Backyard', displayName: 'Backyard', go2rtcStream: 'Backyard', frigateCamera: 'Backyard' },
    // Add your cameras...
  ],

  // PERSON DETECTION - Frigate binary sensors that trigger alerts
  personDetectionEntities: [
    'binary_sensor.front_porch_person_occupancy',
    'binary_sensor.backyard_person_occupancy',
  ],

  // PEOPLE TRACKING - Person entities with optional avatars
  people: [
    {
      entityId: 'person.john',
      name: 'John',
      avatarUrl: '/avatars/john.jpg',  // Place image in public/avatars/
    },
    {
      entityId: 'person.jane',
      name: 'Jane',
      avatarUrl: '/avatars/jane.jpg',
    },
  ],
};
```

### Step 4: Add Avatar Images (Optional)

**Windows:**
```powershell
mkdir public\avatars
# Copy your avatar images to public\avatars\
```

**Linux:**
```bash
mkdir -p public/avatars
cp ~/photos/john.jpg public/avatars/
cp ~/photos/jane.jpg public/avatars/
```

---

## 7. Building the Application

### Test in Development Mode First

```bash
npm run dev
```

Open http://localhost:5173 and verify everything works.

### Build for Production

**For Windows:**
```bash
npm run build:win
```
Output: `dist/Command Center Setup-1.0.0.exe`

**For Linux:**
```bash
npm run build:linux
```
Output: `dist/command-center-1.0.0.AppImage`

**For Current Platform:**
```bash
npm run build
```

---

## 8. Windows Deployment

### Option A: Run the Installer

1. Copy `dist/Command Center Setup-1.0.0.exe` to your Windows touchscreen device
2. Run the installer
3. The app will be installed to Program Files
4. Launch from Start Menu

### Option B: Portable Mode

1. Copy the entire `dist/win-unpacked` folder to your device
2. Run `Command Center.exe` directly

### Auto-Start on Windows

1. Press `Win + R`, type `shell:startup`, press Enter
2. Create a shortcut to the app in this folder
3. The app will start automatically on login

### Kiosk Mode on Windows

**Using Windows Assigned Access (Windows 10/11 Pro):**

1. Create a dedicated user account for the kiosk
2. Go to Settings → Accounts → Family & other users
3. Set up a kiosk (Assigned Access)
4. Select the Command Center app

**Using a startup script:**

Create `start-kiosk.bat`:
```batch
@echo off
start "" "C:\Program Files\Command Center\Command Center.exe" --kiosk
```

### Disable Screen Timeout (Windows)

1. Settings → System → Power & sleep
2. Set "Screen" and "Sleep" to "Never"

Or via PowerShell:
```powershell
powercfg /change monitor-timeout-ac 0
powercfg /change standby-timeout-ac 0
```

---

## 9. Linux Deployment

### Copy the App

```bash
# From your build machine
scp dist/command-center-1.0.0.AppImage user@touchscreen-device:~/

# On the touchscreen device
chmod +x ~/command-center-1.0.0.AppImage
```

### Install Dependencies

```bash
sudo apt update
sudo apt install -y libgtk-3-0 libnotify4 libnss3 libxss1 libasound2 unclutter
```

### Create Startup Script

```bash
nano ~/start-kiosk.sh
```

```bash
#!/bin/bash

# Wait for display
sleep 3

# Disable screen blanking
xset s off
xset -dpms
xset s noblank

# Hide cursor when idle
unclutter -idle 3 -root &

# Start the app
~/command-center-1.0.0.AppImage --no-sandbox
```

```bash
chmod +x ~/start-kiosk.sh
```

### Auto-Start with Systemd

```bash
sudo nano /etc/systemd/system/command-center.service
```

```ini
[Unit]
Description=Command Center Kiosk
After=graphical.target

[Service]
Type=simple
User=YOUR_USERNAME
Environment=DISPLAY=:0
ExecStart=/home/YOUR_USERNAME/start-kiosk.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=graphical.target
```

**Replace `YOUR_USERNAME` with your actual username!**

```bash
sudo systemctl enable command-center.service
sudo systemctl start command-center.service
```

### Raspberry Pi Specific Setup

**Enable auto-login:**
```bash
sudo raspi-config
# → System Options → Boot / Auto Login → Desktop Autologin
```

**Disable screen blanking:**
```bash
sudo nano /etc/xdg/lxsession/LXDE-pi/autostart
```

Add:
```
@xset s off
@xset -dpms
@xset s noblank
```

---

## 10. First Launch

### Step 1: Start the App

Launch the application on your touchscreen device.

### Step 2: Enter Home Assistant Token

1. The app will show "Disconnected" status
2. Look for a **Settings** button (gear icon) or the connection status
3. Click to open settings
4. **Paste your Home Assistant token** (from Step 3.1)
5. Click **"Save & Connect"**

### Step 3: Verify Connection

- Status should change to **"Connected"** (green)
- Your thermostat temperatures should appear
- Lights and locks should show their states

### Step 4: Connect Google Calendar (Optional)

1. Click **"Connect Google Calendar"** in the calendar widget
2. A browser window will open
3. Sign in with your Google account
4. Click **"Allow"** to grant calendar access
5. Close the browser window
6. Calendar events should now appear

---

## 11. Troubleshooting

### "Disconnected" - Can't Connect to Home Assistant

| Check | Solution |
|-------|----------|
| URL correct? | Verify `VITE_HA_URL` matches your HA address |
| Token valid? | Create a new token in HA if expired |
| Network? | Ensure device can reach HA (try ping) |
| Firewall? | Port 8123 must be accessible |
| HTTPS? | If HA uses HTTPS, update URL to `https://` |

### Cameras Not Loading

| Check | Solution |
|-------|----------|
| go2rtc running? | Open `http://go2rtc-ip:1985` in browser |
| Stream names match? | Names in config must match go2rtc exactly |
| Network access? | Device must reach go2rtc server |
| CORS issues? | go2rtc should allow cross-origin requests |

### Entities Show "Loading..."

| Check | Solution |
|-------|----------|
| Entity ID correct? | Check exact ID in HA Developer Tools |
| Entity exists? | Search for it in HA States |
| Case sensitive! | `climate.Living_Room` ≠ `climate.living_room` |

### Google Calendar Won't Connect

| Check | Solution |
|-------|----------|
| Client ID set? | Check `.env` has `VITE_GOOGLE_CLIENT_ID` |
| Test user added? | Your email must be in OAuth test users |
| API enabled? | Google Calendar API must be enabled |
| Popup blocked? | Allow popups for the app |

### App Crashes on Linux

```bash
# Check logs
journalctl -u command-center.service -f

# Run manually to see errors
DISPLAY=:0 ~/command-center-1.0.0.AppImage --no-sandbox 2>&1
```

Common fixes:
- Add `--no-sandbox` flag
- Install missing dependencies: `sudo apt install libgtk-3-0 libnss3`

### Screen Goes Black / Sleeps

**Windows:**
- Settings → Power & sleep → Never

**Linux:**
```bash
xset s off && xset -dpms && xset s noblank
```

### Touch Not Responding (Linux)

```bash
# Check touch device detected
xinput list

# Calibrate touchscreen
sudo apt install xinput-calibrator
xinput_calibrator
```

---

## Quick Reference

### Commands

| Task | Command |
|------|---------|
| Development mode | `npm run dev` |
| Build for Windows | `npm run build:win` |
| Build for Linux | `npm run build:linux` |
| Build for current OS | `npm run build` |

### Linux Service Commands

| Task | Command |
|------|---------|
| Check status | `sudo systemctl status command-center` |
| Start | `sudo systemctl start command-center` |
| Stop | `sudo systemctl stop command-center` |
| Restart | `sudo systemctl restart command-center` |
| View logs | `journalctl -u command-center -f` |

### File Locations

| File | Purpose |
|------|---------|
| `.env` | Environment variables (URLs, API keys) |
| `src/config/entities.ts` | Entity ID configuration |
| `public/avatars/` | Person avatar images |

---

## Network Architecture

```
┌─────────────────────┐
│   Touchscreen       │
│   (Command Center)  │
└──────────┬──────────┘
           │
     ┌─────┴─────┐
     │           │
     ▼           ▼
┌─────────┐  ┌─────────┐
│  Home   │  │ go2rtc  │ (Optional)
│Assistant│  │ Cameras │
│ :8123   │  │ :1985   │
└─────────┘  └─────────┘
     │
     ▼
┌─────────────────────┐
│   Smart Devices     │
│ Lights, Locks, etc. │
└─────────────────────┘
```

---

## Support

If you encounter issues:

1. Check the [Troubleshooting](#11-troubleshooting) section
2. Verify all entity IDs match exactly
3. Check browser console for errors (F12 → Console)
4. Review Home Assistant logs for connection issues