Skip to content

customer-setup.md

Latest commit

 

History

History
173 lines (124 loc) · 5.7 KB

customer-setup.md

File metadata and controls

173 lines (124 loc) · 5.7 KB
Raw

VibeTV Setup On Mac

This is the normal customer setup for the Control Center launch flow.

You use:

You do not need USB flashing, PlatformIO, firmware source builds, or the Terminal for normal setup.

VibeTV hardware on a desk

What You Are Setting Up

VibeTV has two setup parts:

  1. Put VibeTV on WiFi. The device needs to be on the same local network as your Mac.
  2. Install the Mac App. The Mac App reads CodexBar usage locally and sends display updates to VibeTV.

app.vibetv.shop gives you the Mac App. The app itself guides both parts.

1. Connect VibeTV To WiFi

  1. Plug VibeTV into power.
  2. Wait until the display shows VibeTV-Setup.
  3. Open WiFi settings on your phone or Mac.
  4. Join the VibeTV-Setup WiFi network.
  5. If the setup page opens automatically, use it.
  6. If it does not open, go to http://192.168.4.1.
  7. Choose a 2.4 GHz home WiFi and save. Use Search again if the network list is stale, or enter the WiFi name manually for a hidden network.
  8. Wait until VibeTV restarts and shows that WiFi is connected.

When this is done, VibeTV should point you to:

app.vibetv.shop

2. Open Control Center

On your Mac, open:

https://app.vibetv.shop

The page offers the signed Mac App download. That is all it does. It does not look at your Mac, and it does not manage VibeTV. Everything after the download happens in the app on your own Mac.

3. Install The Mac App

  1. Select Download Mac App.
  2. Open the downloaded disk image.
  3. Drag VibeTV Control Center into Applications.
  4. Open VibeTV Control Center from Applications.

The app must run from Applications. On first open it installs its own background service, so VibeTV keeps receiving display updates after you close the app window and again after every login.

The app then opens Control Center locally on:

http://127.0.0.1:47832/control-center

If another program already occupies that port, the app picks a different loopback port by itself.

4. Connect VibeTV

Control Center will try to find VibeTV on the same WiFi.

If it finds exactly one device, it connects automatically.

If it cannot find the device, enter the address shown on VibeTV, for example:

192.168.178.123

Then select Connect VibeTV.

What Success Looks Like

  • Control Center says VibeTV is connected.
  • VibeTV stops waiting on the setup screen.
  • Usage appears on the display.
  • Overview, Usage, Theme Library, Settings, Updates, and Support are available in Control Center.

What The Mac App Does

The Mac App is the codexbar-display binary from this repository.

It exists because:

  • CodexBar reads AI provider usage on your Mac.
  • The Mac App reads that usage from CodexBar.
  • Control Center talks to the Mac App locally.
  • The Mac App sends screen updates to VibeTV over local WiFi.

Normal setup and updates never need these. They exist for support:

# Check whether the Mac App is running.
curl -fsS http://127.0.0.1:47832/v1/status

# Reinstall the Mac App without the download.
curl -fsSL https://app.vibetv.shop/install-control-center-companion.sh | bash

# Restart the Mac App.
curl -fsSL https://app.vibetv.shop/install-control-center-companion.sh | bash -s -- --restart

# Stop the Mac App.
curl -fsSL https://app.vibetv.shop/install-control-center-companion.sh | bash -s -- --uninstall

Display Messages

Display Meaning What to do
Starting VibeTV is booting. Wait.
SETUP WIFI / VibeTV-Setup VibeTV needs WiFi setup. Join VibeTV-Setup and open the setup page.
Connecting WiFi VibeTV is joining your home WiFi. Wait.
WiFi connected! / app.vibetv.shop VibeTV is on WiFi. Open Control Center on your Mac.
Open App / app.vibetv.shop VibeTV is waiting for fresh Mac data. Open Control Center and connect VibeTV.
Install Mac App The Mac App is missing. Use the setup step in Control Center.
Update Mac App The Mac App needs an update. Use the update step in Control Center.
Update available A device update is available. Open Control Center and follow the update step.
Update running VibeTV is updating. Do not unplug power.
WiFi reset Saved WiFi settings are being cleared. Wait for VibeTV-Setup to appear again.

If Something Does Not Work

  • If Control Center says the Mac App is not running, make sure VibeTV Control Center is in Applications and open it again.
  • If Control Center cannot find VibeTV, make sure your Mac and VibeTV are on the same WiFi.
  • If .local does not work, use the IP address shown on VibeTV.
  • If VibeTV is still on VibeTV-Setup, finish WiFi setup first.
  • If the app shows one clear action, use that action before trying support commands.

Change WiFi

If VibeTV cannot reconnect to its saved network, wait until the display shows VibeTV-Setup. Join that open WiFi on a phone, open 192.168.4.1, and choose the new 2.4 GHz network. This changes only the WiFi name and password. Existing pairing, themes, brightness, and other VibeTV settings stay unchanged.

An authenticated WiFi reset remains available as an explicit support action while the paired VibeTV is reachable. It is not needed for a normal WiFi change.

Important

  • Normal setup is macOS-first.
  • USB-C is only for power in normal setup.
  • USB flashing is only for support and development.
  • Firmware updates, theme installs, WiFi resets, and asset uploads are hardware write actions. They should happen only through the intended Control Center flow or during an approved support test.