imperial-command-center/SETUP.md

Command Center - Complete Setup Guide

A Home Assistant touchscreen dashboard for Windows and Linux.

---

Table of Contents

1. Prerequisites
2. Project Installation
3. Home Assistant Setup
4. Google Calendar Setup
5. Camera Setup
6. Entity Configuration
7. Building the Application
8. Windows Deployment
9. Linux Deployment
10. First Launch
11. Troubleshooting

---

1. Prerequisites

Development Machine (to build the app)

Requirement	Windows	Linux
Node.js	v18+ from nodejs.org	sudo apt install nodejs npm
Git	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

# 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

# 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

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
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
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:

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:

VITE_GO2RTC_URL=http://192.168.1.241:1985

In src/config/entities.ts, configure your cameras:

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:

   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):

Copy-Item .env.example .env
notepad .env

Linux:

cp .env.example .env
nano .env

Step 2: Edit .env File

# 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:

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:

mkdir public\avatars
# Copy your avatar images to public\avatars\

Linux:

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

npm run dev

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

Build for Production

For Windows:

npm run build:win

Output: dist/Command Center Setup-1.0.0.exe

For Linux:

npm run build:linux

Output: dist/command-center-1.0.0.AppImage

For Current Platform:

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:

@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:

powercfg /change monitor-timeout-ac 0
powercfg /change standby-timeout-ac 0

---

9. Linux Deployment

Copy the App

# 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

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

Create Startup Script

nano ~/start-kiosk.sh

#!/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

chmod +x ~/start-kiosk.sh

Auto-Start with Systemd

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

[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!

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

Raspberry Pi Specific Setup

Enable auto-login:

sudo raspi-config
# → System Options → Boot / Auto Login → Desktop Autologin

Disable screen blanking:

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

# 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:

xset s off && xset -dpms && xset s noblank

Touch Not Responding (Linux)

# 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 section
2. Verify all entity IDs match exactly
3. Check browser console for errors (F12 → Console)
4. Review Home Assistant logs for connection issues