controlX — Uživatelská příručka v1

Platforma pro mobilní OSC ovladače interaktivních instalací.
Builder (desktop web) + controlX App (iOS / Android) — Direct Mode, žádný server.

1. Co je controlX

1.1 Přehled

controlX se skládá ze dvou částí:

• Builder — desktopová webová aplikace pro tvorbu ovladačů.
  Spustíte ji na počítači, navrhujete rozvržení stránek a komponent.
• controlX App — nativní mobilní aplikace (iOS, Android).
  Načtete do ní projekt z Builderu a ovládáte instalaci přímo z telefonu.

Komunikace probíhá v Direct Mode: telefon posílá OSC/UDP pakety přímo do cílového zařízení v lokální síti — bez serveru, bez cloudu.

1.2 Základní koncepty

1.3 Grid a breakpointy

Každá stránka má responzivní grid. Počty sloupců závisí na orientaci a šířce displeje:

Každou komponentu lze pro konkrétní breakpoint přemístit, změnit její rozměr nebo ji zcela skrýt (mode: hide).

2. První ovladač v Builderu krok za krokem — scénář S-Play

Tento návod předpokládá, že v lokální síti máte ENTTEC S-Play se statickou IP adresou.

2.1 Spuštění Builderu

# v kořenu repozitáře
pnpm --filter builder dev

Otevřete http://localhost:5173 v prohlížeči.

2.2 Vytvoření projektu

1. Klikněte na + Nový projekt.
2. Zadejte název (např. „S-Play ovladač") a potvrďte.
3. Projekt se otevře v editoru (Shell).

2.3 Přidání targetu (S-Play)

1. Klikněte na tlačítko Targets v horní liště.
2. V modálu klikněte + Přidat.
3. Vyplňte:
   • Název: S-Play
   • Profil zařízení: ENTTEC S-Play — port se automaticky doplní na 8000
   • Host: IP adresa vašeho S-Play v síti (např. 192.168.1.100)
   • Port: 8000 (nebo jak máte nastaveno v S-Play)
4. Uložte.

2.4 Přidání komponenty

1. V levém panelu (Palette) najděte Momentary Button.
2. Přetáhněte ho na canvas (nebo klikněte a zvolte místo na gridu).
3. Komponenta se zobrazí na canvasu.

2.5 Konfigurace akce (OSC)

1. Vyberte komponentu na canvasu — v pravém panelu (Inspector) se zobrazí její vlastnosti.
2. Přejděte na záložku Akce (Events).
3. Klikněte + Přidat akci u události press.
4. Zvolte typ OSC Send a vyplňte:
   • Target: S-Play
   • Adresa: /splay/playlist/play/1
   • Argumenty: přidejte int32 s hodnotou 1
5. Uložte.

Tip: S-Play přijímá triggery ve formátu /splay/playlist/play/<N>. Číslo N je index playlistu (od 1). Viz dokumentaci S-Play OSC API.

2.6 Náhled

Klikněte na Preview v horní liště. Otevře se fullscreen overlay s živým renderem projektu. Ovladač je interaktivní — v Log panelu vidíte každou vyslanou OSC zprávu (simulátor, bez skutečného UDP).

2.7 Export projektu

Klikněte na Export v horní liště. Prohlížeč stáhne soubor s-play-ovladac.controlx.json.

Tento soubor přenesete do App — viz kapitola 6.

3. Komponenty — referenční přehled

3.1 Momentary Button (button.momentary)

Tlačítko drží stav stisknutí. Akce press se spustí při stisku, release při uvolnění.

Typické použití: spuštění scény, spuštění playlistu.

3.2 Toggle Button (button.toggle)

Přepínací tlačítko. Uchovává stav ON/OFF. Akce on se spustí při přepnutí do ON, off při přepnutí do OFF.

Typické použití: zapnutí/vypnutí osvětlení, mute kanálu.

3.3 Slider

Posuvník pro výběr hodnoty v rozsahu. Akce change se spouští při pohybu (s ohledem na rate limit).

Typické použití: intenzita světla, hlasitost, fade.

3.4 XY Pad (xypad)

Dvouosý dotykový pad. Odesílá dvě hodnoty najednou (X a Y). Akce change.

Typické použití: pohyb v 2D prostoru, pan/tilt hlavy, XY fade.

3.5 Label

Statický textový štítek. Žádné interakce, slouží k popisu rozvržení.

3.6 Image

Zobrazuje obrázek. Lze použít jako ozdobný prvek nebo mapu ovladače.

3.7 Container

Prázdný kontejner pro vizuální seskupení. Nemá vlastní interakci.

4. Targety a OSC

4.1 Definice targetu

Každý target představuje jedno OSC zařízení v síti. Vlastnosti:

4.2 Vestavěné profily zařízení

Při výběru profilu se automaticky doplní výchozí port a zpřístupní se Test Message (bezpečný testovací příkaz, např. nastavení master intensity).

4.3 Typy OSC argumentů

Argumenty Slideru a XY Padu mohou být bind reference — hodnota se doplní z aktuálního stavu komponenty za běhu (např. bind: "value" pro slider, bind: "x" / bind: "y" pro xypad).

4.4 Typy akcí

4.5 Rate limit

Globální rate limit (projekt → Runtime politika → oscRateLimit) omezuje frekvenci OSC zpráv napříč celou App. Výchozí hodnota je 30 zpráv/s.

Slider má navíc vlastní rateLimit v milisekundách — minimální interval mezi dvěma zprávami od tohoto slideru. Hodí se pro zařízení citlivá na příliš rychlý OSC traffic.

Důležité: OSC/UDP je fire-and-forget — sent neznamená, že zařízení zprávu přijalo nebo zpracovalo. Diagnostická obrazovka v App zobrazuje počty sent / failed (failed = chyba na síťové vrstvě), ale nerozlišuje, zda zařízení zprávu ignorovalo nebo zpracovalo.

5. Témata

5.1 Vestavěná témata

controlX obsahuje šest hotových témat:

Poznámka k Glass Premium: Téma využívá CSS backdrop-filter. Na zařízeních nebo prohlížečích bez podpory se automaticky degraduje na solidní barvu (rgba 0.92).

5.2 Přepnutí tématu v Builderu

V horní liště Builderu vyberte téma z rozbalovacího menu ThemePicker. Změna je okamžitá a je součástí undo history.

5.3 Responzivní chování

Téma se aplikuje na celý projekt. Komponenty používají výhradně sémantické CSS proměnné (--cx-*) — přepnutím tématu se změní vzhled všech komponent najednou.

6. Přenos projektu do telefonu

Jsou tři způsoby, jak dostat projekt z Builderu do App.

6.1 QR kód přes LAN (doporučeno)

Počítač (Builder):

1. Spusťte handoff server:

   node scripts/handoff-server.mjs
   # Server naslouchá na portu 9441
   # Pokud port 9441 obsazen: HANDOFF_PORT=9444 node scripts/handoff-server.mjs
   

2. V Builderu klikněte na tlačítko ⊞ Phone v horní liště.
3. Zobrazí se QR kód s URL projektu.

iPhone (App):

1. Foťákem naskenujte QR kód → Safari otevře URL.
2. Zkopírujte URL z adresního řádku Safari.
3. Otevřete controlX App.
4. Klepněte na Load from URL.
5. Vložte URL a potvrďte.

Projekt se načte a zobrazí v runtime.

Bezpečnost: Token v URL je jednorázový — po prvním stažení přestane fungovat. Platnost je 10 minut.

6.2 Export / Import souboru

Export (Builder → soubor):
Klikněte na Export v horní liště. Prohlížeč stáhne <název-projektu>.controlx.json.

Import (soubor → App):
V App přetáhněte soubor nebo klikněte na Import a vyberte .controlx.json. Soubor musí být přenesen přes AirDrop, Files, nebo jiný mechanismus sdílení souborů na iOS.

Import do Builderu:
V pracovním prostoru (Workspace) přetáhněte soubor .controlx.json nebo klikněte na ↓ Import.

6.3 Deep link (controlx://)

App podporuje URL schéma controlx://load?url=<encoded-url>. Tato funkce vyžaduje Xcode rebuild pro aktivaci registrace URL schématu na iOS. Standardní postup: QR kód nebo ruční vložení URL (viz 6.1).

7. Provoz v App

7.1 Run mode

Při otevření projektu přejde App do run mode:

• Chrome (navigační prvky) je skrytý — celá obrazovka patří projektu.
• Displej zůstane aktivní (keep-awake) po celou dobu běhu projektu.
• Orientace displeje se uzamkne dle nastavení projektu (runtimePolicy.orientation):
  portrait / landscape / any (výchozí).

Jak odkrýt chrome: Podržte prst 2 sekundy v levém dolním rohu obrazovky. Chrome se zobrazí na 8 sekund, poté se opět skryje.

7.2 PIN zámek

Pokud má projekt nastaveno editLock: pin:

• Projekt se v App spustí normálně.
• Při pokusu o přechod do nastavení nebo výběru jiného projektu App zobrazí PIN dialog.
• PIN je uložen jako SHA-256 hash — nikdy se neexportuje v čitelné podobě.
• Po třech nesprávných pokusech platí 30sekundové blokování.

PIN nastavíte v Builderu (Inspector → Runtime politika).

7.3 Diagnostická obrazovka

Otevřete ji tlačítkem Log nebo z menu při odhalení chrome.

Test Message odešle bezpečný testovací příkaz dle profilu zařízení (viz kapitola 4.2) a zobrazí výsledek.

Clear vymaže viditelné záznamy (od daného okamžiku). Export sdílí log jako textový soubor.

Připomínka: sent v diagnostice znamená, že UDP paket odešel ze zařízení. Nepotvrzuje, že ho zařízení na druhém konci přijalo nebo zpracovalo. Client isolation na přístupovém bodu může tiše zahazovat pakety.

7.4 Reconnect

Při návratu aplikace do popředí nebo při připojení k síti App automaticky obnoví spojení transportní vrstvy.

8. Síťový checklist instalace

Problémy s OSC komunikací jsou v 90 % způsobeny síťovou konfigurací. Projděte tento checklist před každou instalací.

8.1 Wi-Fi infrastruktura

• Dedikovaná Wi-Fi síť — ideálně separátní SSID jen pro ovládací zařízení a instalaci. Sdílená veřejná Wi-Fi je nevhodná.
• Client isolation VYPNUTO — většina přístupových bodů (AP) má client isolation zapnutou z bezpečnostních důvodů. Musí být vypnutá, jinak telefon nemůže komunikovat s jinými zařízeními ve stejné Wi-Fi síti.
  Hledejte v nastavení AP: „AP isolation", „wireless isolation", „client isolation". Vypněte.

8.2 IP adresy

• Statická IP pro OSC zařízení — S-Play, Resolume, DMX brány atd. musí mít statickou IP. Dynamická IP (DHCP) se může změnit po restartu, čímž přestane fungovat nastavený target.
• Telefon ve stejné podsíti — telefon a cílové zařízení musí být ve stejné síti (stejný subnet).

8.3 Firewall a UDP

• Firewall na počítači / serveru — pokud cílové zařízení běží na počítači (Resolume), zkontrolujte, zda firewall povoluje příchozí UDP na příslušném portu (Resolume: 7000).
• S-Play: UDP port 8000 musí být dostupný z telefonu.

8.4 iOS — Local Network permission

Při prvním spuštění App na iOS se zobrazí dialog:

„controlX chce komunikovat se zařízeními v lokální síti."

Klepněte Povolit (Allow). Bez tohoto povolení App nemůže odesílat UDP pakety do LAN. Povolení lze zpětně změnit v Nastavení → Soukromí a zabezpečení → Místní síť → controlX.

8.5 Ověření funkčnosti

1. Otevřete diagnostickou obrazovku v App.
2. V sekci Síť zkontrolujte, zda má telefon IP adresu (ne N/A browser).
3. U každého targetu klepněte Test Message — dle výsledku zjistíte, zda UDP dosáhne cíle.
4. Pokud Test Message selže, zkontrolujte výše uvedené body (client isolation, statická IP, firewall, Local Network permission).

9. Agentické ovládání (MCP)

controlX MCP server umožňuje Claude a dalším AI nástrojům přímo manipulovat s projekty bez nutnosti grafického rozhraní.

9.1 Spuštění serveru

node mcp/server.mjs
# Server komunikuje přes stdio (MCP protokol)

9.2 Automatické propojení s Claude Code

V kořeni repozitáře je soubor .mcp.json. Claude Code ho detekuje automaticky — MCP server se spustí při otevření projektu v Claude Code.

9.3 Claude Desktop

Přidejte do claude_desktop_config.json:

{
  "mcpServers": {
    "controlx": {
      "command": "node",
      "args": ["/absolutní/cesta/ke/controlx/mcp/server.mjs"],
      "description": "controlX Builder — project data management"
    }
  }
}

9.4 Nástroje

Resource: controlx://guide — referenční průvodce pro agenty (schema koncepty, EditOp reference, typy komponent).

9.5 Omezení MCP serveru

MCP server nemá přístup k OSC transportu. Nemůže odesílat OSC zprávy do instalace. Správa projektových dat ano — spuštění show ne. To vyžaduje operátora s controlX App.

9.6 Úložiště

Projekty jsou uloženy jako JSON soubory v ~/Documents/controlX/.

10. FAQ a řešení problémů

App neposílá OSC zprávy

1. Zkontrolujte diagnostickou obrazovku (kapitola 7.3).
2. Má telefon IP adresu? → Wi-Fi připojeno
3. Client isolation? → Vypněte na AP (kapitola 8.1)
4. Správná IP a port targetu? → Porovnejte s nastavením zařízení
5. iOS Local Network permission? → Nastavení → Soukromí → Místní síť → controlX → Povolit
6. Firewall? → Povolte UDP na cílovém portu

QR kód nefunguje (nelze načíst URL)

• Je spuštěn handoff server? (node scripts/handoff-server.mjs)
• Je port 9441 volný? → Zkuste HANDOFF_PORT=9444 node scripts/handoff-server.mjs
• Jsou počítač a telefon ve stejné Wi-Fi síti?
• URL platí 10 minut a je jednorázová — vygenerujte nový QR.

Projekt se nenačte (Import selže)

• Soubor byl poškozen nebo upraven ručně → checksum se neshoduje.
• Exportujte projekt znovu z Builderu.

Builder neukládá změny

• Builder ukládá do localStorage prohlížeče.
• Pokud otevřete projekt v inkognito nebo smažete data prohlížeče, projekty zmizí.
• Exportujte pravidelně jako .controlx.json zálohu.

Slider přetěžuje zařízení OSC příkazy

• Nastavte rateLimit slideru (v ms) v Inspectoru.
• Případně zaškrtněte releaseOnly — zpráva se odešle jen po puštění prstu.

PIN zapomenut

Projekt je uložen s pinHash. PIN je jednosměrný hash (SHA-256), nelze ho zpětně zjistit.
Řešení: exportujte projekt z Builderu (kde PIN nezablokuje export), upravte runtimePolicy.editLock na none a reimportujte.

Po restartu S-Play se target nedostupný

S-Play má dynamickou IP z DHCP → přidělila se nová adresa.
Řešení: nastavte statickou IP v S-Play a/nebo v DHCP rezervaci na routeru.

controlX App nevidím v App Store

PoC verze není v App Store. Instalace probíhá přes Xcode (TestFlight ve fázi beta). Kontaktujte XLAB pro přístup.

controlX příručka v1 — verze 2026-07-17 — XLAB