LUME Commerce Operations Guide

LUME Commerce Operations Guide

Hardware Requirements

• LUME device (depth camera + mic array + HDMI out)
• Power supply (USB-C PD, 45W minimum)
• HDMI cable to venue display (TV, monitor, or projector)
• WiFi connection (2.4GHz or 5GHz, minimum 10 Mbps)
• Optional: Ethernet adapter for wired connection

Installation

Physical Setup

1. Mount the LUME device at counter height, facing the queue area
2. The depth camera should have a clear view of the ordering zone (2-5 meters range)
3. Connect the power supply via USB-C
4. Connect HDMI to the venue display
5. The display should face customers, not the barista
6. Position the mic array facing the ordering position (within 2 meters of where customers stand)

Network Setup

1. Connect to venue WiFi via the companion app
2. The device will broadcast its local IP on the display during first boot
3. Access the dashboard at `http://<device-ip>:9600/dashboard`
4. Verify connection status shows green in the dashboard header

First-Time Setup

1. Venue Configuration

Edit `config/venue.json` with your venue details:

{
  "id": "your-venue-id",
  "name": "Your Venue Name",
  "slug": "your-venue",
  "zones": [],
  "branding": {
    "logo_url": null,
    "watermark_position": "bottom-right",
    "primary_color": "#00E5FF",
    "venue_tag": "@yourvenue"
  },
  "payment_method": "counter"
}

Payment method options: `counter`, `square_terminal`, `stripe_terminal`

2. Menu Import

Option A: Use a template

cp config/menu-templates/coffee-shop.json src/nlu/vocabulary.json

Option B: Create a custom menu

Follow the format in `src/nlu/vocabulary.json`. Each item needs:
- `id`: unique identifier
- `name`: display name
- `price`: numeric price
- `category`: one of `espresso`, `latte`, `coffee`, `cold_brew`, `tea`, `specialty`, `food`, `seasonal`
- `aliases`: list of voice aliases (how customers might say it)

Option C: Update via API

curl -X POST http://localhost:9600/api/venue/menu \
  -H 'Content-Type: application/json' \
  -d '{"items": [...]}'

3. Zone Calibration

Define analytics zones for your space:

curl -X POST http://localhost:9600/api/venue/zones \
  -H 'Content-Type: application/json' \
  -d '{
    "zones": [
      {
        "name": "Queue",
        "zone_type": "queue",
        "bounds": [0.0, 0.0, 0.5, 1.0]
      },
      {
        "name": "Service",
        "zone_type": "service",
        "bounds": [0.5, 0.0, 1.0, 0.5]
      },
      {
        "name": "Seating",
        "zone_type": "seating",
        "bounds": [0.5, 0.5, 1.0, 1.0]
      }
    ]
  }'

Bounds are normalized 0-1 coordinates: [x_min, y_min, x_max, y_max].
Use the heatmap at `/analytics/heatmap` to verify zones match your layout.

Daily Operations

Morning Checklist

1. Verify LUME device is powered and display shows the welcome screen
2. Check dashboard at `/dashboard` -- connection status should be green
3. Verify menu is current (seasonal items enabled/disabled)
4. Run a test order: say "can I get a latte" to confirm voice ordering works

During Service

• The dashboard auto-refreshes every 10 seconds
• Kitchen display at `/kitchen` shows active orders
• Kitchen staff marks orders ready by tapping the order card
• The HDMI display shows order confirmations and pickup notifications

End of Day

• Check the dashboard for daily metrics (orders processed, average wait time)
• Review content clips captured at `/analytics/content`
• No manual shutdown needed. The device can run 24/7.

Troubleshooting

Voice ordering not working

1. Check that the mic array is not obstructed
2. Test with `/order/transcript`:

   curl -X POST http://localhost:9600/order/transcript \
     -H 'Content-Type: application/json' \
     -d '{"transcript":"a latte please"}'

3. If the API responds but voice doesn't, the mic hardware may need reseating
4. Check the STT provider connectivity (Deepgram requires internet)
5. Verify the menu has aliases that match what customers say

Analytics showing zero occupancy

1. Check the depth camera has a clear field of view
2. Verify zones are configured: `curl http://localhost:9600/api/venue`
3. Look at the heatmap: `curl http://localhost:9600/analytics/heatmap`
4. If heatmap shows activity but zones are empty, recalibrate zone bounds

Kitchen display disconnected

1. Refresh the kitchen display page at `/kitchen`
2. Check that the device and kitchen tablet are on the same network
3. The WebSocket connection at `/kitchen/ws` should auto-reconnect
4. If persistent, restart the kitchen display browser tab

Dashboard shows "Offline"

1. Check that the device is powered and connected to WiFi
2. Try pinging the device IP
3. Check the health endpoint: `curl http://localhost:9600/health`
4. If health responds but dashboard fails, clear browser cache

Orders stuck in "Preparing"

1. Kitchen staff may have missed the order
2. Check `/kitchen/orders` for the full list
3. Mark ready manually:

   curl -X POST http://localhost:9600/kitchen/ORDER_ID/ready

API Reference

Health & Status

Ordering

Kitchen

Analytics

Content

Companion App API

Management

Example: Full Order Flow

# 1. Submit a voice transcript
curl -X POST http://localhost:9600/order/transcript \
  -H 'Content-Type: application/json' \
  -d '{"transcript":"can I get a latte and a croissant"}'

# 2. Confirm the order
curl -X POST http://localhost:9600/order/confirm

# 3. Check kitchen orders
curl http://localhost:9600/kitchen/orders

# 4. Mark order ready (replace ORDER_ID with actual ID)
curl -X POST http://localhost:9600/kitchen/ORDER_ID/ready

# 5. Check analytics
curl http://localhost:9600/analytics/current