Q Family Agent — Podsumowanie Wykonawcze

Marzec 2026

Problem

Współczesne rodziny z dziećmi toną w chaosie logistycznym — dziesiątki aplikacji, kalendarzy, list zakupów, grup na WhatsApp, arkuszy z budżetem. Alexa i Siri potrafią ustawić timer, ale nie potrafią zaplanować wegetariańskiego tygodniowego jadłospisu z uwzględnieniem alergii trzylatka i terminu ważności produktów w lodówce. Istniejące rozwiązania to albo „głupie" organizery bez AI (Cozi, FamilyWall), albo generyczne AI bez kontekstu rodzinnego (ChatGPT, Alexa).

Rozwiązanie

Q Family Agent — pierwszy prawdziwy agent AI dla rodziny. Nie chatbot, nie aplikacja — agent, który żyje z rodziną na Telegramie, zna jej preferencje, rutyny i potrzeby, i proaktywnie działa: planuje posiłki, zarządza kalendarzem, inwentaryzuje lodówkę za pomocą kamery (AI vision), steruje smart home, pilnuje budżetu, przypomina o wizytach lekarskich i umawia fryzjera przez telefon.

Q wyrasta z działającego prototypu — agent codziennie obsługuje prawdziwą polską rodzinę od miesięcy. Moduły Obiadkowo (posiłki), Kalendarz, Storage Master (inwentaryzacja AI) i integracja Loxone smart home są przetestowane w produkcji.

Produkt

Trzy warianty wejścia na rynek:

  • Q Cloud (MVP, start Q3 2026) — czysta chmura, 49 zł/mies, onboarding w 5 minut
  • Q Hybrid (rekomendowany, Q2 2027) — mały hub domowy (399 zł) + chmura, dane lokalnie, smart home bridge
  • Q Box (2028) — dedykowany mini PC dla power-userów

Subskrypcje: Free (2 moduły, 500 wiadomości) → Family 39 zł/mies (all-in) → Premium 79 zł/mies (unlimited + custom voice).

Rynek

TAM: 48 mln rodzin z dziećmi w EU (~29 mld EUR/rok). SAM: 3 mln tech-savvy rodzin PL+DACH+Nordics (~1,4 mld EUR/rok). SOM 3-letni: 10 000 płacących rodzin, ARR ~5,4 mln EUR.

Żaden konkurent nie łączy jednocześnie: prawdziwej AI, głębokiego kontekstu rodzinnego i agentowości (zdolności do działania). Q siedzi na tym blue ocean.

Unit Economics

Plan Family (39 zł/mies): koszt AI + infra ~19 zł → marża brutto 51%. CAC ~120 zł, LTV ~975 zł, LTV/CAC ~8x. Koszty AI spadają ~30% rocznie — marża rośnie do 65-70% na skali.

Go-to-Market

Faza 1 (Q2 2026): Closed beta, 50 rodzin, walidacja PMF. Faza 2 (Q4 2026): Launch PL, 1000 rodzin, content + referral + influencerzy. Faza 3 (2027): Expansion DACH + Nordics, Q Hybrid launch, 10 000+ rodzin.

Finansowanie

Pre-seed: 1 mln PLN (Q1-Q2 2026) — MVP, beta, launch PL. Seed: 3 mln PLN (Q1 2027) — zespół 12 osób, hardware, ekspansja EU. Break-even: Q4 2028 przy ~12 000 aktywnych użytkowników.

Zespół MVP

6 osób: CEO/Product, CTO/Backend, Full-stack dev, AI/ML Engineer, UX/Designer, Community/Growth. Koszt: 101k zł/mies.

Dlaczego Q wygra

  1. Timing — LLM-y właśnie osiągnęły wystarczającą jakość, okno first-mover jest teraz
  2. Kumulujący się moat — im dłużej rodzina używa Q, tym trudniej odejść (switching cost)
  3. Blue ocean — nikt nie łączy AI + family context + agentowość
  4. Zdrowe unit economics — 51% marży, LTV/CAC 8x, jasna ścieżka do rentowności
  5. Zbudowane na prawdziwym użyciu — nie teoria, a codziennie działający agent w prawdziwej rodzinie

Q to nie kolejna apka. To nowy członek rodziny.

Pełna analiza: Q_BUSINESS_PLAN.md

Q Family Agent — Analiza Biznesowa i Plan Produktu

Wersja: 1.0 | Data: Marzec 2026 | Autor: Q Strategy Team

Spis treści

  1. Executive Summary
  2. Analiza rynku
  3. Produkt — trzy warianty
  4. Onboarding w 10 minut
  5. Moduły i marketplace
  6. Model biznesowy
  7. Technologia
  8. Go-to-market
  9. Zespół MVP i finansowanie
  10. Ryzyka
  11. GDPR / RODO
  12. Projekcje finansowe — 3 lata
  13. Roadmapa 24 miesiące
  14. Podsumowanie — dlaczego Q wygra

1. Executive Summary

Wizja

Q Family Agent to pierwszy na świecie prawdziwy agent AI dla rodziny — nie kolejny asystent głosowy, nie aplikacja do list zakupów, nie chatbot z FAQ. Q to cyfrowy członek rodziny, który planuje posiłki, zarządza kalendarzem, inwentaryzuje zawartość szafek za pomocą kamery, steruje inteligentnym domem, pilnuje budżetu i proaktywnie rozwiązuje problemy, zanim rodzina je zauważy.

Problem

Współczesna rodzina z dziećmi żongluje dziesiątkami narzędzi: Google Calendar, aplikacje do zakupów, Notion, WhatsApp grupy, arkusze z budżetem, osobne apki do smart home. Żadne z tych narzędzi nie rozmawia ze sobą. Alexa i Siri potrafią ustawić timer i włączyć muzykę — ale zapytane „co zrobić z kurczakiem, który jest w lodówce, na obiad dla czterech osób, z czego jedno dziecko nie je papryki?" — odpowiadają bełkotem albo odsyłają do Google.

Alexa i Siri są głupie. Nie dlatego, że technologia nie istnieje — modele językowe (LLM) potrafią dziś rozwiązywać złożone problemy. Problem polega na tym, że Amazon i Apple projektują asystentów jako interfejsy do swoich ekosystemów, nie jako agentów działających w imieniu rodziny. Siri sprzedaje Apple Music. Alexa sprzedaje produkty z Amazon. Nikt nie buduje agenta, który naprawdę pracuje DLA rodziny.

Rozwiązanie

Q Family Agent zmienia paradygmat:

  • Agent-first, nie app-first — Q nie czeka na komendy. Wie, że w środę Ewa idzie do fryzjera, więc proponuje wcześniejszy obiad. Wie, że za trzy dni kończy się mleko, bo śledzi zużycie. Wie, że Bruno ma urodziny kolegi za tydzień, bo widział zaproszenie w kalendarzu.
  • Jeden interfejs — Telegram — zero nowych aplikacji do instalowania. Rodzina pisze i mówi do Q jak do człowieka, w języku naturalnym.
  • Prywatność lokalna — dane rodziny zostają na urządzeniu domowym lub w zaszyfrowanej chmurze pod kontrolą rodziny, nigdy nie służą do trenowania modeli AI.
  • Modularny — rodzina włącza tylko te moduły, których potrzebuje. Marketplace pozwala dodawać nowe funkcje jak aplikacje w telefonie.

Q wyrasta z działającego prototypu — agent już działa w prawdziwej polskiej rodzinie od miesięcy, zarządzając posiłkami (moduł Obiadkowo), kalendarzem, inwentaryzacją (Storage Master z rozpoznawaniem obrazów) i integracją ze smart home Loxone. Teraz czas przejść od prototypu do produktu.

2. Analiza rynku

Rynek docelowy

Segment pierwszorzędny: Rodziny z dziećmi w wieku 0–12 lat, w których oboje rodzice pracują, w Polsce i Europie.

  • Polska: ok. 5,2 mln gospodarstw domowych, z czego ~2,8 mln to rodziny z dziećmi. Około 1,5 mln to rodziny z dziećmi w wieku przedszkolnym i wczesnoszkolnym, gdzie obciążenie logistyczne jest największe.
  • Europa (EU-27): ok. 48 mln rodzin z dziećmi poniżej 15 lat.

Profil klienta idealnego (ICP):

  • Para 28–42 lata, 1–3 dzieci
  • Oboje pracują (często zdalnie/hybrydowo)
  • Technologicznie sprawni (ale niekoniecznie techniczni)
  • Dochód gospodarstwa 8 000–20 000 zł/mies
  • Zmęczeni „mentalnym obciążeniem" zarządzania domem
  • Posiadają lub rozważają smart home

Konkurencja

Konkurent Co robi Słabości
Amazon Alexa Asystent głosowy, smart home, zakupy Głupia AI, zero kontekstu rodzinnego, sprzedaje produkty Amazon
Apple Siri + Home Asystent głosowy, HomeKit Zamknięty ekosystem, brak agentowej inteligencji, zero proaktywności
Google Assistant + Nest Asystent, smart home, kalendarz Zbieranie danych, brak koherencji rodzinnej, deprecation risk
Cozi Family Organizer Wspólny kalendarz, listy, posiłki Brak AI, ręczne wpisywanie, brak smart home, przestarzały UX
FamilyWall Kalendarz, lokalizacja, listy Brak AI, nie jest agentem, nie podejmuje działań
OurHome Obowiązki domowe, nagrody dla dzieci Wąski zakres, brak integracji, brak AI
ChatGPT / Claude (raw) Generyczna AI Brak pamięci rodzinnej, brak integracji, wymaga promptowania

Kluczowy insight: Żaden istniejący produkt nie łączy trzech rzeczy jednocześnie: (1) prawdziwej inteligencji AI, (2) kontekstu rodzinnego, (3) zdolności do działania (agentowości). Q jest jedynym produktem na przecięciu tych trzech kręgów.

TAM / SAM / SOM

Metryka Wartość Uzasadnienie
TAM (Total Addressable Market) ~48 mln rodzin EU × 50 EUR/mies = 29 mld EUR/rok Wszystkie rodziny z dziećmi w EU, pełna adopcja
SAM (Serviceable) ~3 mln rodzin tech-savvy PL+DACH+Nordics × 40 EUR/mies = 1,4 mld EUR/rok Rodziny aktywne cyfrowo w kluczowych rynkach
SOM (3 lata) ~10 000 płacących rodzin × 45 EUR/mies = 5,4 mln EUR/rok Realistyczny cel po 3 latach

Rynek asystentów AI rośnie w tempie ~35% CAGR. Segment „family tech" jest jeszcze nieukonstytuowany — co daje przewagę first-mover.

3. Produkt — trzy warianty

Wariant A: Q Box (hardware + subskrypcja)

Koncept: Dedykowany mini PC (na bazie ARM, np. Raspberry Pi 5 / Orange Pi 5 / custom board) w eleganckiej obudowie z logo Q, gotowy do podłączenia.

Specyfikacja:

  • ARM SoC, 8 GB RAM, 64 GB eMMC
  • WiFi 6, Bluetooth 5.2, Ethernet
  • Zainstalowany OpenClaw + Q Agent, skonfigurowany fabrycznie
  • Obudowa premium, rozmiar pudełka od zapałek (8×6×3 cm)
  • Zasilacz USB-C

Cena: 799 zł (jednorazowo) + subskrypcja od 99 zł/mies

Plusy: Pełna kontrola danych (local-first), niska latencja, działa bez internetu (podstawowe funkcje), poczucie „posiadania"

Minusy: Wyższy koszt wejścia, logistyka hardware, serwis, zwroty

Wariant B: Q Cloud (SaaS, zero hardware)

Koncept: Czysta chmura — rodzina zakłada konto, łączy Telegram, konfiguruje przez kreator webowy. Agent Q działa na serwerach Q.

Cena: 199 zł/mies (plan Family) lub 169 zł/mies w planie rocznym

Plusy: Zero barier wejścia, instant setup, brak logistyki hardware, łatwiejszy scaling

Minusy: Zależność od internetu, dane w chmurze (nawet zaszyfrowane — percepcja), wyższe koszty operacyjne (compute), brak integracji smart home bez dodatkowego bridge'a

Wariant C: Q Hybrid (REKOMENDOWANY)

Koncept: Mały hub (Q Puck — wielkość podkładki pod mysz) + chmura. Hub obsługuje:

  • Lokalną pamięć rodziny (zaszyfrowana)
  • Bridge do smart home (Zigbee/Z-Wave/Matter)
  • Lokalne przetwarzanie prostych komend (offline mode)
  • Backup cache gdy internet padnie

Inteligencja AI działa w chmurze Q, ale wrażliwe dane pozostają na hubie.

Cena: 399 zł (hub) + subskrypcja od 99 zł/mies

Plusy: Balans prywatności i wygody, integracja smart home out-of-the-box, percepcja bezpieczeństwa, niższy koszt wejścia niż Q Box, lepszy niż pure SaaS

Minusy: Nadal wymaga wysyłki hardware (ale tańszy i prostszy)

Rekomendacja strategiczna

Uruchomienie z Q Cloud jako MVP (zero hardware = szybki start), równolegle rozwijanie Q Hybrid jako produkt premium na Q3 2026. Q Box jako opcja dla power-userów / entuzjastów smart home w 2027.

4. Onboarding w 10 minut

Cel: od rozpakowania (lub rejestracji) do działającego agenta rodzinnego w maksymalnie 10 minut. Każda minuta powyżej to utracony klient.

Scenariusz Q Cloud (5 minut)

Krok Czas Opis
1. Rejestracja 1 min Wejdź na q.family, podaj email, wybierz plan
2. Połącz Telegram 1 min Kliknij link → otwiera Telegram → /start
3. Kreator rodziny 2 min Q pyta: „Jak masz na imię? Ile osób w rodzinie? Jak mają na imię dzieci? Ile mają lat?" — konwersacyjnie, nie formularz
4. Pierwszy moduł 1 min „Włączyć Obiadkowo? Będę planować posiłki dla rodziny" → Tak → „Ktoś nie je czegoś?" → gotowe
Suma 5 min Agent działa, zna rodzinę, planuje pierwszy obiad

Scenariusz Q Hybrid (10 minut)

Krok Czas Opis
1. Rozpakuj 1 min Hub + zasilacz + karta z QR kodem
2. Podłącz 1 min Zasilacz do prądu, hub autostart
3. QR → WiFi 2 min Skanuj QR → otwiera app/web → wybierz WiFi, wpisz hasło
4. Konto + Telegram 2 min Email, połącz Telegram botowi
5. Kreator rodziny 3 min Jak wyżej, plus: „Widzę urządzenia smart home — połączyć Loxone?"
6. Gotowe 1 min Q: „Cześć, jestem Q! Znam już was. Co zrobimy na obiad?"
Suma 10 min Pełny agent z smart home

Kluczowe zasady onboardingu

  1. Konwersacyjny, nie formularzowy — Q pyta jak człowiek, nie jak formularz rejestracji
  2. Progressive disclosure — nie zasypuj wszystkim na raz. Pierwszy dzień = 1-2 moduły
  3. Instant value — w ciągu 5 minut Q musi zrobić coś użytecznego (np. zaproponować obiad)
  4. Fallback na głos — cały onboarding można przejść voice messages na Telegramie
  5. Zero technicznego języka — „połącz się z domową siecią" zamiast „skonfiguruj WiFi SSID"

5. Moduły i marketplace

Q działa na modelu modularnym — core agent + moduły, które rodzina włącza i wyłącza. Docelowo marketplace z modułami od społeczności.

Moduły core (wbudowane)

🍽️ Obiadkowo (Planowanie posiłków)

  • Planowanie jadłospisu na tydzień z uwzględnieniem diet, alergii, preferencji
  • Generowanie listy zakupów z rozbiciem na sklepy
  • Przepisy krok po kroku dostosowane do poziomu umiejętności
  • Śledzenie co rodzina lubi / nie lubi (feedback po posiłku)
  • Integracja z budżetem (szacunkowy koszt posiłków)
  • Wartość: Oszczędność 3-5h/tydzień na planowaniu + mniej food waste

📅 Kalendarz rodzinny

  • Wspólny kalendarz całej rodziny z synchronizacją Google/Apple Calendar
  • Inteligentne konflikty: „Ewa, Bruno ma karate o 16, a ty fryzjera o 15:30 — kto go zawiezie?"
  • Proaktywne przypomnienia z kontekstem
  • Urodziny, imieniny, rocznice — Q pamięta i przypomina z wyprzedzeniem
  • Planowanie tygodnia w niedzielę
  • Wartość: Zero zapomnianych wydarzeń, mniej stresu koordynacyjnego

📦 Storage Master (Inwentaryzacja AI)

  • Zrób zdjęcie szafki / lodówki / spiżarni → Q rozpoznaje zawartość (GPT-4o Vision)
  • Śledzi co jest, co się kończy, co przeterminowane
  • Automatyczne dodawanie do listy zakupów
  • Inwentaryzacja sezonowa: ubrania dzieci, zabawki, narzędzia
  • Wartość: Koniec z kupowaniem drugiego masła bo „nie wiedziałam że mamy"

Moduły premium (w subskrypcji Family/Premium)

❤️ Zdrowie rodziny

  • Śledzenie wizyt lekarskich, szczepień, badań
  • Przypomnienia o lekach i suplementach
  • Milestones rozwojowe dzieci (Tymek — 2 lata — czy mówi 50 słów?)
  • Książeczka zdrowia cyfrowa
  • Notatki z wizyt lekarskich (dyktuj Q co powiedział pediatra)
  • Wartość: Pełna historia zdrowotna rodziny w jednym miejscu

🏠 Smart Home

  • Integracja z Loxone, Home Assistant, Matter/Thread
  • Scenariusze rodzinne: „Dobranoc" = zamknij rolety, wycisz światła, włącz alarm
  • Automatyzacje kontekstowe: „Jeśli Ewa wyjeżdża z pracy (kalendarz), włącz ogrzewanie"
  • Sterowanie głosowe przez Q na Telegramie
  • Wartość: Smart home, który naprawdę jest smart — bo zna kontekst rodziny

💰 Budżet domowy

  • Śledzenie wydatków (ręczne + OCR paragonów)
  • Budżet miesięczny z kategoriami
  • Alerty: „Uwaga, 80% budżetu na jedzenie wydane, a zostało 12 dni"
  • Porównania miesiąc do miesiąca
  • Planowanie większych wydatków (wakacje, remonty)
  • Wartość: Kontrola finansowa bez excela

Przyszłe moduły (roadmapa)

Moduł Opis Timeline
🎓 Edu Kids Pomoc w lekcjach, plan nauki, śledzenie postępów Q1 2027
🚗 Auto Manager Przeglądy, ubezpieczenia, tankowanie, OC/AC Q2 2027
🐕 Pet Care Wizyty u weterynarza, karma, szczepienia Q2 2027
✈️ Travel Planner Planowanie wakacji, rezerwacje, dokumenty Q3 2027
👵 Elder Care Opieka nad starszymi rodzicami, leki, wizyty Q4 2027
🏘️ Community Integracja z sąsiedztwem, wspólne zakupy 2028

Marketplace (2027+)

Otwarta platforma dla developerów tworzących moduły Q:

  • SDK + dokumentacja
  • Revenue share: 70% developer / 30% Q
  • Recenzje i oceny od rodzin
  • Certyfikacja bezpieczeństwa (obowiązkowa dla modułów z danymi)

6. Model biznesowy

Plany subskrypcyjne

Q Starter Q Family Q Premium
Cena 99 zł/mies 199 zł/mies 349 zł/mies
Uzasadnienie ceny Jak prywatna niania na pół godziny Jak prywatny asystent rodzinny 24/7 Jak concierge + smart home manager
Członkowie rodziny 4 6 10+ (multi-generational)
Moduły 3 core (Obiadkowo, Kalendarz, TODO) Wszystkie core + premium Wszystkie + beta + priorytet
Wiadomości/mies 1 000 10 000 Unlimited
Głos (TTS/STT) ✅ (basic) ✅ (premium voice) ✅ (custom voice)
Smart Home ❌ ✅ (1 system) ✅ (unlimited)
Storage Master 20 skanów/mies Unlimited Unlimited
AI Vision (skany, zdjęcia) ✅ ✅ ✅
Telefony (Twilio) ❌ 10/mies 50/mies
Proaktywność Przypomnienia Pełna (sugestie, alerty, planowanie) Pełna + automatyzacje
Wsparcie Email (48h) Email (12h) + chat Priorytetowe (4h) + video onboarding
Dodatkowe — Backup cloud, Family reports Custom voice, API access, white-glove setup

Dlaczego 199 zł/mies? Q nie jest apką — to prywatny agent AI pracujący 24/7. Zastępuje: apkę do posiłków (30 zł), kalendarz rodzinny (20 zł), asystenta zakupowego (20 zł), organizatora domu (20 zł), i robi rzeczy których żadna apka nie robi (proaktywne sugestie, telefonowanie, skanowanie szafek). Rodzina z dwójką dzieci wydaje 200-500 zł/mies na subskrypcje — Q zastępuje kilka z nich i daje 10x więcej wartości.

Unit economics (plan Family — 199 zł/mies)

Pozycja Koszt/użytkownik/mies
LLM API (Claude Sonnet — główny reasoning) ~25 zł
GPT-4o Vision (Storage, skany, zdjęcia) ~8 zł
Whisper (STT) ~3 zł
ElevenLabs (TTS) ~5 zł
Infrastruktura (compute, DB, CDN) ~8 zł
Twilio (telefony, 10 połączeń) ~5 zł
Komunikacja (Telegram/WhatsApp) ~1 zł
Wsparcie (proporcjonalnie) ~5 zł
Suma kosztów ~60 zł
Przychód 199 zł
Marża brutto ~70% (~139 zł)

Target marża brutto na skali: 75-80% (cache, batching, własne modele do prostych zadań, negocjacje volume z API providers).

CAC / LTV

Metryka Wartość Uzasadnienie
CAC (Cost of Acquisition) ~400 zł Premium positioning, influencer marketing, demo days, onboarding support
Monthly churn ~3% Niższy niż tańsze produkty — agent staje się "członkiem rodziny", dane się kumulują
Avg. lifetime 33 miesiące 1/0.03 ≈ 33 (prawie 3 lata!)
LTV (plan Family) 199 × 33 = 6 567 zł Brutto; netto po kosztach: ~4 587 zł
LTV/CAC ~16x (brutto), ~11x (netto) Znakomity stosunek — premium product, sticky users

Przychody dodatkowe

  1. Hardware margin — Q Hybrid hub: koszt ~180 zł, cena 399 zł, marża ~55%
  2. Marketplace commission — 30% od sprzedaży modułów third-party
  3. B2B / white-label — licencja Q dla deweloperów osiedli smart home, sieci przedszkoli
  4. Affiliate — polecanie produktów (np. składniki z Frisco, urządzenia smart home)

7. Technologia

Architektura

┌─────────────────────────────────────────────┐
│                  Q Cloud                     │
│  ┌─────────┐  ┌──────────┐  ┌────────────┐ │
│  │ OpenClaw │  │ Module   │  │ Family     │ │
│  │ Core     │  │ Runtime  │  │ Memory DB  │ │
│  └────┬─────┘  └────┬─────┘  └─────┬──────┘ │
│       │              │              │        │
│  ┌────┴──────────────┴──────────────┴──┐     │
│  │         Agent Orchestrator          │     │
│  └────┬──────────┬──────────┬──────────┘     │
│       │          │          │                │
│  ┌────┴───┐ ┌───┴────┐ ┌──┴──────┐         │
│  │Claude  │ │GPT-4o  │ │Whisper/ │         │
│  │Sonnet  │ │Vision  │ │Eleven   │         │
│  └────────┘ └────────┘ └─────────┘         │
└──────────────────┬──────────────────────────┘
                   │ Encrypted API
         ┌─────────┴─────────┐
         │    Q Hub (local)  │
         │  • Family vault   │
         │  • Smart home     │
         │  • Offline cache  │
         └─────────┬─────────┘
                   │
    ┌──────────────┼──────────────┐
    │              │              │
┌───┴───┐   ┌────┴────┐   ┌────┴────┐
│Telegram│   │ Loxone  │   │ Matter  │
│ Bot    │   │         │   │ devices │
└────────┘   └─────────┘   └─────────┘

Stack technologiczny

Warstwa Technologia Uzasadnienie
Core engine OpenClaw Sprawdzony w produkcji, agent framework z narzędziami
Główny LLM Claude Sonnet (Anthropic) Najlepsza jakość rozumowania, bezpieczeństwo AI, polski
Vision GPT-4o Vision (OpenAI) Najlepsze rozpoznawanie obiektów w zdjęciach
STT OpenAI Whisper Najlepsza transkrypcja polskiego
TTS ElevenLabs (Antoni) Naturalny polski głos, niskie latency
Baza danych Cloudflare D1 (SQLite edge) + R2 (storage) Tanie, szybkie, global edge
Hosting Cloudflare Workers + Pages Serverless, skalowalny, tani
Smart home Loxone API, Home Assistant, Matter/Thread Pokrycie 90%+ rynku PL
Komunikacja Telegram Bot API Darmowe, bogate (głos, zdjęcia, buttony), cross-platform
Telefonia Twilio Niezawodne, programowalne połączenia
Monitoring Sentry + custom dashboards Wykrywanie problemów w real-time

Kluczowe decyzje technologiczne

  1. OpenClaw jako core — nie budujemy frameworka agentowego od zera. OpenClaw dostarcza: orkiestrację narzędzi, pamięć, sub-agentów, integrację z modelami. To fundament, na którym budujemy wartość rodzinną.

  2. Multi-model — nie jesteśmy zależni od jednego dostawcy AI. Claude do rozumowania, GPT-4o do wizji, Whisper do mowy. Jeśli jeden dostawca podniesie ceny lub degraduje jakość — przełączamy.

  3. Telegram jako UI — kontrowersyjna decyzja, ale genialna:

    • Zero kosztów rozwoju natywnej apki (oszczędność ~500k zł)
    • Cross-platform od dnia 1 (iOS, Android, desktop, web)
    • Użytkownicy już mają Telegrama (lub instalują w 2 min)
    • Rich features: voice messages, zdjęcia, inline buttons, grupy
    • Docelowo: własna apka jako upgrade, Telegram pozostaje kanałem

  4. Local-first encryption — wrażliwe dane (zdrowie, finanse, rutyny) szyfrowane kluczem rodziny, przechowywane na hubie lub w zaszyfrowanym blobie w chmurze. Serwer Q nigdy nie widzi odszyfrowanych danych.

8. Go-to-market

Faza 1: Closed Beta (Q2 2026, 3 miesiące)

Cel: 50 rodzin, walidacja product-market fit

  • Rekrutacja przez społeczności parentingowe (Facebook grupy, fora)
  • Kryterium: rodziny z dziećmi 0-10, tech-savvy, Telegram
  • Q Cloud only (zero hardware w beta)
  • Bezpłatne, w zamian za cotygodniowy feedback
  • Metryki sukcesu:
    • DAU/MAU > 60%
    • NPS > 50
    • Retention 30-day > 70%
    • Min. 3 interakcje/dzień/rodzina

Budget: 30 000 zł (hosting, API, community management)

Faza 2: Public Launch PL (Q4 2026, 6 miesięcy)

Cel: 1 000 płacących rodzin do końca Q1 2027

Kanały:

  1. Content marketing (40% budżetu)

    • Blog: „Jak AI zmienia życie polskich rodzin"
    • YouTube: cotygodniowe demo Q w akcji (real family, real problems)
    • SEO na frazy: „planowanie posiłków", „organizacja rodziny", „smart home dla rodziny"

  2. Referral program (30% budżetu)

    • „Zaproś rodzinę — oboje dostajecie miesiąc Premium gratis"
    • Viralny mechanizm: Q jako agent sam może wysłać zaproszenie
    • Cel: k-factor > 0.3

  3. Influencer marketing (20% budżetu)

    • Współpraca z 10-15 parent influencerami (Instagram, TikTok)
    • Nie reklama — autentyczne użycie Q przez miesiąc, dokumentowanie
    • Koszt: 2 000-5 000 zł/influencer

  4. PR (10% budżetu)

    • Launch w mediach tech (Spider's Web, Antyweb, Tabletowo)
    • Kąt: „Polski startup AI robi to, czego nie potrafi Alexa"
    • Product Hunt launch (międzynarodowy buzz)

Budget: 200 000 zł

Faza 3: Expansion EU (2027)

Cel: 10 000 rodzin w PL + 5 000 w DACH + Nordics

  • Lokalizacja na DE, EN, SV, NO, DA
  • Partnerstwa z deweloperami smart home (Loxone ma silną bazę w DACH)
  • Q Hybrid launch (hardware)
  • Biuro w Berlinie lub Wiedniu (bliskość do Loxone HQ w Austrii)

Budget: 1 500 000 zł (z rundy seed)

9. Zespół MVP i finansowanie

Zespół MVP (6 osób)

Rola Opis Koszt mies. (brutto)
CEO / Product Wizja, produkt, fundraising. Founder. 15 000 zł
CTO / Backend OpenClaw core, architektura, API, AI pipeline 22 000 zł
Full-stack dev Onboarding web, dashboard, moduły 18 000 zł
AI/ML Engineer Optymalizacja promptów, fine-tuning, koszty AI 20 000 zł
UX/Designer Onboarding flow, brand, materiały marketingowe 14 000 zł
Community / Growth Beta management, content, social media, support 12 000 zł
Suma 101 000 zł/mies

Roczny koszt zespołu: ~1,2 mln zł. Z overheadem (biuro, narzędzia, prawnik, księgowa): ~1,5 mln zł/rok.

Finansowanie

Runda pre-seed: 1 000 000 PLN (Q1-Q2 2026)

Źródło: Business angels, polskie fundusze pre-seed (SMOK VC, Tar Heel Capital, Innovation Nest)

Użycie:

  • 6 miesięcy runway dla zespołu: 600k zł
  • Infrastruktura + API costs: 150k zł
  • Marketing (beta + launch): 200k zł
  • Prawnik + IP + rejestracja: 50k zł

Milestone do seed: 500 płacących rodzin, NPS > 50, unit economics dodatnie

Runda seed: 3 000 000 PLN (Q1 2027)

Źródło: VC (Market One Capital, Inovo, bValue) + granty (NCBiR, EIC Accelerator)

Użycie:

  • Rozbudowa zespołu do 12 osób: 1 800k zł (12 mies)
  • Hardware Q Hybrid (R&D + pierwsza partia 1000 szt): 400k zł
  • Marketing EU expansion: 500k zł
  • Infrastruktura skalowania: 200k zł
  • Rezerwa: 100k zł

Milestone do Series A: 10 000+ rodzin, expansion na 3+ rynki EU, MRR > 1M zł

10. Ryzyka

1. AI Hallucinations (Wysokie ryzyko, wysokie impact)

Problem: LLM może podać błędną informację medyczną, złe alergeny w przepisie, nieprawidłowy termin.

Mitigacja:

  • Moduł zdrowia: disclaimery „nie jestem lekarzem", krytyczne info weryfikowane z bazą
  • Obiadkowo: baza alergii zakodowana twardo (nie zależy od LLM)
  • Kalendarz: eventy weryfikowane z API kalendarza, nie z pamięci LLM
  • „Red zone" — tematy, w których Q zawsze odsyła do specjalisty (zdrowie, prawo, finanse powyżej progu)
  • Monitoring halucynacji: automatyczne flagi na niespójne odpowiedzi

2. Prywatność i zaufanie (Wysokie ryzyko, bardzo wysokie impact)

Problem: Rodziny powierzają Q najintymniejsze dane — zdrowie dzieci, finanse, rutyny dnia.

Mitigacja:

  • Local-first architecture (dane na hubie / zaszyfrowane w chmurze)
  • Certyfikacja RODO, transparentne privacy policy w prostym języku
  • „Q, zapomnij o X" — natychmiastowe kasowanie
  • Regularne audyty bezpieczeństwa (zewnętrzne)
  • Open-source kluczowych komponentów szyfrowania

3. Koszty AI (Średnie ryzyko, wysokie impact)

Problem: Koszty API (Claude, GPT-4o, ElevenLabs) mogą rosnąć lub być nieprzewidywalne przy skali.

Mitigacja:

  • Multi-model: proste zapytania → tańsze modele (Haiku, GPT-4o-mini)
  • Agresywne cache'owanie (semantyczne, per-family)
  • Batching requests
  • Negocjacje volume discounts od 1000+ rodzin
  • Własne modele do prostych zadań (fine-tuned smol models)
  • Target: <10 zł/rodzinę/mies na AI przy skali 10k rodzin

4. Konkurencja Big Tech (Średnie ryzyko, średnie impact)

Problem: Apple/Google/Amazon mogą odpalić „Family AI" z miliardowym budżetem.

Mitigacja:

  • Big Tech jest wolny — cykle produktowe 2-3 lata
  • Big Tech nie zrozumie niszy (historycznie: Alexa Skills to graveyard)
  • Nasz moat: głęboki kontekst rodzinny kumulowany latami, nie do skopiowania
  • Community i marketplace lock-in
  • First-mover advantage w Polsce i CEE

5. Adoption barrier (Średnie ryzyko, wysokie impact)

Problem: Rodziny mogą nie chcieć „kolejnej aplikacji" / nie ufać AI z dziećmi.

Mitigacja:

  • Telegram = nie kolejna apka, to czat który już mają
  • Onboarding 5-10 min z instant value
  • Word-of-mouth od zachwyconych early adopters
  • Content edukacyjny: „AI nie zastępuje rodzica — odciąża go"
  • Darmowy plan na start (zero risk)

11. GDPR / RODO

Fundamentalne zasady

  1. Local-first by design — wrażliwe dane przechowywane na urządzeniu rodziny (Q Hub) lub zaszyfrowane end-to-end w chmurze kluczem rodziny. Serwer Q nie ma dostępu do odszyfrowanych danych.

  2. Minimalizacja danych — zbieramy tylko to, co niezbędne do działania modułów. Rodzina kontroluje, które moduły mają dostęp do jakich danych.

  3. Prawo do zapomnienia — komenda „Q, zapomnij o X" lub „Q, skasuj wszystko" → natychmiastowe, nieodwracalne usunięcie. Dashboard RODO z wizualizacją: jakie dane Q przechowuje.

  4. Prawo do przenoszenia — eksport wszystkich danych rodziny w formacie JSON/CSV jednym kliknięciem.

  5. Brak profilowania reklamowego — dane rodziny NIGDY nie służą do reklam, nie są sprzedawane, nie trenują modeli AI.

Implementacja techniczna

Element Rozwiązanie
Szyfrowanie at rest AES-256, klucz generowany na urządzeniu rodziny
Szyfrowanie in transit TLS 1.3
Przetwarzanie LLM Dane anonimizowane przed wysłaniem do API (imiona → tokeny)
Retencja Domyślnie: bezterminowo (rodzina decyduje). Konto skasowane → dane usunięte w 30 dni
DPO Wyznaczony Data Protection Officer od momentu >1000 użytkowników
DPIA Data Protection Impact Assessment przed każdym nowym modułem przetwarzającym dane wrażliwe
Lokalizacja danych EU only (Cloudflare EU, backup w PL)
Zgody Granularne zgody per moduł, łatwe do cofnięcia
Dzieci Specjalna ochrona danych dzieci (art. 8 RODO) — zgoda rodzica wymagana

Przewaga konkurencyjna

RODO to nie obciążenie — to przewaga marketingowa. W erze Cambridge Analytica i wycieków danych, rodziny szukają produktów, którym mogą zaufać. „Twoje dane nigdy nie opuszczają twojego domu" to potężny selling point, zwłaszcza vs Alexa (Amazon słucha) i Google (Google profiluje).

12. Projekcje finansowe — 3 lata

Założenia

  • Start Q Cloud: Q3 2026
  • Start Q Hybrid: Q2 2027
  • Średnia cena subskrypcji: 45 zł/mies (mix Free/Family/Premium)
  • Avg. price per paying user: ~199 zł/mies (mix Starter 99 zł, Family 199 zł, Premium 349 zł → weighted avg)
  • Monthly churn: 3% (spadający do 2.5% w Y3 — premium product = sticky)
  • CAC: 400 zł (spadający do 250 zł w Y3 dzięki word-of-mouth i referral)
  • Koszt AI per user: 60 zł/mies (spadający do 40 zł/mies w Y3 dzięki optymalizacji, cache, local models)

Tabela projekcji (kwartalne)

Okres Nowi users Churn Aktywni users Płacący (65%) ARPU (zł) MRR (zł) Koszty AI (zł) Koszty zespół (zł) Marketing (zł) Inne (zł) Wynik mies. (zł)
Q3 2026 100 3 97 63 199 12 537 5 820 101 000 40 000 15 000 -149 283
Q4 2026 250 18 329 214 199 42 586 19 740 101 000 80 000 15 000 -173 154
Q1 2027 400 35 694 451 199 89 749 27 060 150 000 100 000 20 000 -207 311
Q2 2027 600 55 1 239 805 199 160 195 48 300 150 000 120 000 25 000 -183 105
Q3 2027 800 85 1 954 1 270 199 252 730 76 200 180 000 120 000 30 000 -153 470
Q4 2027 1 000 110 2 844 1 849 199 367 951 110 940 180 000 100 000 30 000 -52 989
Q1 2028 1 200 140 3 904 2 538 199 505 062 126 900 200 000 100 000 35 000 +43 162
Q2 2028 1 500 170 5 234 3 402 199 676 998 170 100 200 000 80 000 35 000 +191 898
Q3 2028 1 800 210 6 824 4 436 199 882 764 221 800 220 000 80 000 40 000 +320 964
Q4 2028 2 000 250 8 574 5 573 199 1 109 027 222 920 220 000 60 000 40 000 +566 107

Podsumowanie roczne

Rok Users (koniec) Płacący ARR (zł) Koszty roczne (zł) Wynik (zł)
2026 (H2) 329 214 511 080 ~1 130 000 -618 920
2027 2 844 1 849 4 414 776 ~2 950 000 +1 464 776
2028 8 574 5 573 13 306 692 ~4 070 000 +9 236 692

Break-even: Q1 2028, przy ~3 900 aktywnych użytkowników (~2 500 płacących).

Uwaga: Przy ARPU 199 zł/mies break-even następuje znacznie szybciej niż przy 39 zł. To jest siła premium pricing — mniej użytkowników potrzebnych do rentowności, wyższy LTV, lepszy support per user.

Scenariusze

Scenariusz Users Y3 Płacący Y3 ARR Y3 Break-even
Pesymistyczny 4 000 2 600 6,2 mln zł Q3 2028
Bazowy 8 500 5 500 13,1 mln zł Q1 2028
Optymistyczny 15 000 9 750 23,3 mln zł Q3 2027

13. Roadmapa 24 miesiące

2026

Miesiąc Milestone Deliverables
Kwi 2026 Formalizacja spółki Sp. z o.o., regulamin, privacy policy, brand identity
Maj 2026 MVP Q Cloud Onboarding web, Telegram bot, Obiadkowo, Kalendarz
Cze 2026 Closed Beta start 50 rodzin, feedback loop, iteracje tygodniowe
Lip 2026 Storage Master Moduł inwentaryzacji z vision AI
Sie 2026 Beta rozszerzony 200 rodzin, plany subskrypcyjne, płatności (Stripe)
Wrz 2026 Public beta PL Landing page, PR campaign, influencerzy
Paź 2026 Launch 1.0 Product Hunt, media, pełne 3 plany
Lis 2026 Moduł Zdrowie Wizyty, szczepienia, milestones dzieci
Gru 2026 1 000 users Milestone pre-seed → seed pitch

2027

Miesiąc Milestone Deliverables
Sty 2027 Seed round close 3 mln zł, rozbudowa zespołu
Lut 2027 Moduł Budżet Śledzenie wydatków, OCR paragonów
Mar 2027 Q Hybrid R&D Prototyp hardware, wybór SoC, projekt obudowy
Kwi 2027 Smart Home module Loxone + Home Assistant integration
Maj 2027 Lokalizacja DE/EN Tłumaczenia, kulturowa adaptacja
Cze 2027 Q Hybrid pilot 100 szt. dla beta testerów
Lip 2027 Edu Kids beta Pomoc w lekcjach, quizy edukacyjne
Sie 2027 Launch DACH Niemcy, Austria, Szwajcaria
Wrz 2027 Q Hybrid launch Sprzedaż Q Hybrid, e-commerce
Paź 2027 5 000 users Milestone seed → Series A prep
Lis 2027 Marketplace beta SDK, dokumentacja, pierwsi devs
Gru 2027 Launch Nordics Szwecja, Norwegia, Dania

2028

Miesiąc Milestone Deliverables
Sty 2028 10 000 users Series A pitch
Lut 2028 Własna apka mobile iOS + Android (React Native), Telegram pozostaje
Mar 2028 Series A close 15-20 mln zł target
Kwi 2028 Q Box launch Dedykowany hardware dla enthusiasts

14. Podsumowanie — dlaczego Q wygra

Pięć powodów, dla których Q Family Agent zdominuje rynek family AI

1. Timing jest idealny. LLM-y osiągnęły punkt, w którym naprawdę rozumieją kontekst rodziny. Rok temu to było niemożliwe. Za dwa lata Big Tech obudzi się i zacznie kopiować. Okno na first-mover advantage jest TERAZ — 2026/2027.

2. Moat kumuluje się z czasem. Im dłużej rodzina używa Q, tym więcej Q wie o niej. Po roku Q zna diety, rutyny, preferencje, relacje, harmonogramy, budżety, stan zdrowia, zawartość lodówki. Tego nie da się skopiować. Switching cost rośnie eksponencjalnie. To ten sam moat, który ma Spotify z playlistami — ale głębszy, bo dotyczy życia, nie muzyki.

3. Family tech to blue ocean. Cozi ma 20 mln użytkowników ale zero AI. Alexa ma AI ale zero kontekstu rodzinnego. Nikt nie siedzi na przecięciu. Q jest jedynym produktem, który łączy prawdziwą inteligencję AI z głębokim zrozumieniem rodziny i zdolnością do działania.

4. Unit economics działają. 51% marży brutto na planie Family, LTV/CAC > 4x, break-even w 2028. To nie jest moonshot — to biznes z jasną ścieżką do rentowności. Koszty AI spadają ~30% rocznie. Nasza marża będzie rosnąć.

5. Zaczęliśmy od prawdziwej rodziny. Q nie jest teoretycznym produktem wymyślonym w biurze. Q już działa — codziennie, w prawdziwej polskiej rodzinie. Planuje obiady, zarządza kalendarzem, inwentaryzuje lodówkę, steruje domem. Wiemy co działa, bo tego UŻYWAMY. To najlepsza walidacja, jaką startup może mieć.

Wizja na 5 lat

Q Family Agent stanie się niewidzialną, niezastąpioną częścią życia miliona europejskich rodzin — agentem, który nie tylko organizuje dom, ale sprawia, że rodziny mają więcej czasu dla siebie nawzajem.

To nie jest apka. To nie jest gadżet. To nowy członek rodziny.

Cześć, jestem Q. Ogarnę to.

Dokument przygotowany w marcu 2026. Dane i projekcje oparte na aktualnych cennikach dostawców AI, badaniach rynku family tech oraz doświadczeniach z działającego prototypu Q w środowisku produkcyjnym.

Q × Loxone — Kompletna Dokumentacja Integracji

Wersja: 1.0 | Data: 2026-03-01 | Autor: Q Agent
Status: Dokument referencyjny — gotowy do implementacji

Spis treści

  1. Architektura systemu
  2. Loxone API — szczegółowa dokumentacja
  3. Bezpieczeństwo — KLUCZOWE
  4. Proaktywne funkcje AI
  5. Istniejące biblioteki i integracje
  6. Dashboard (q-home.pages.dev)
  7. Implementacja — fazy
  8. Ryzyka i mitygacja
  9. Koszty

1. Architektura systemu

1.1 Diagram architektury

┌─────────────────────────────────────────────────────────────────┐
│                        SIEĆ LOKALNA                             │
│                                                                 │
│  ┌──────────────┐    WebSocket/HTTPS    ┌──────────────────┐    │
│  │   Loxone      │◄───────────────────►│   Q Bridge        │    │
│  │   Miniserver  │   (WSS na Gen.2)     │   (Node.js)       │    │
│  │   Gen.2       │                      │   Mac mini 24/7   │    │
│  └──────────────┘                      └────────┬─────────┘    │
│                                                  │              │
└──────────────────────────────────────────────────┼──────────────┘
                                                   │
                                          HTTPS/WSS│(internet)
                                                   │
                              ┌─────────────────────┼────────────────────┐
                              │                     │                    │
                    ┌─────────▼──────┐   ┌─────────▼──────┐   ┌────────▼───────┐
                    │  Q AI Layer     │   │  Dashboard      │   │  Telegram Bot  │
                    │  (Claude API)   │   │  React/CF Pages │   │  Notifications │
                    │  Analiza +      │   │  q-home.pages   │   │  + Sterowanie  │
                    │  Decyzje        │   │  .dev            │   │                │
                    └────────────────┘   └────────────────┘   └────────────────┘

1.2 Komponenty

Komponent Technologia Rola Lokalizacja
Loxone Miniserver Gen.2 Embedded Linux Kontroler smart home, I/O, logika Sieć lokalna
Q Bridge Node.js + node-lox-ws-api Proxy WebSocket, cache stanów, kolejka komend Mac mini (lokalnie)
Q AI Layer Claude Sonnet API Analiza wzorców, decyzje, NLP Cloud (Anthropic API)
Dashboard React + Vite UI do monitorowania i sterowania Cloudflare Pages
Telegram Bot Node.js (Telegraf) Powiadomienia, sterowanie głosowe/tekstowe Mac mini → Telegram API

1.3 Protokoły komunikacji

  • Bridge ↔ Miniserver: WebSocket RFC 6455 (ws:// lub wss:// na Gen.2), port 80/443
  • Bridge ↔ Cloud: HTTPS (REST API do Claude), WSS (real-time do Dashboard)
  • Bridge ↔ Telegram: HTTPS (Bot API polling/webhook)
  • Dashboard ↔ Bridge: WSS (live state updates), HTTPS (komendy)

1.4 Zasada kluczowa

Q jest OVERLAY, nie DEPENDENCY. Jeśli Q Bridge padnie, Miniserver i cały system Loxone działa normalnie — wszystkie lokalne automatyzacje, sceny i sterowanie z aplikacji Loxone pozostają nienaruszone. Q dodaje warstwę inteligencji, ale nigdy nie staje się single point of failure.

2. Loxone API — szczegółowa dokumentacja

2.1 REST Web Services

Loxone Miniserver udostępnia HTTP API do odczytu stanów i sterowania urządzeniami. Struktura komendy:

http(s)://<IP_MINISERVER>/dev/sps/io/<CONTROL_NAME>/<COMMAND>

Odczyt stanu

# Status pojedynczej kontrolki (np. światło w salonie)
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomLight/state"

# Odpowiedź XML:
# <LL control="dev/sps/io/LivingroomLight" value="1" Code="200"/>

# Wszystkie wyjścia kontrolki
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomLight/all"

# Status całego Miniservera
curl -u user:password "http://192.168.1.100/status"

Sterowanie

# Włącz światło
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomLight/On"

# Wyłącz światło
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomLight/Off"

# Impuls (toggle)
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomLight/Pulse"

# Ustaw wartość analogową (np. dimmer na 75%)
curl -u user:password "http://192.168.1.100/dev/sps/io/BedroomDimmer/7.5"

# Rolety — otwórz
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomBlinds/PulseUp"

# Rolety — zamknij
curl -u user:password "http://192.168.1.100/dev/sps/io/LivingroomBlinds/PulseDown"

# Temperatura — ustaw na 21.5°C (Virtual Analog Input)
curl -u user:password "http://192.168.1.100/dev/sps/io/TargetTemp/21.5"

Formaty odpowiedzi

Odpowiedzi zwracane są w formacie XML:

<!-- Sukces -->
<LL control="dev/sps/io/LivingroomLight" value="1" Code="200"/>

<!-- Błąd — kontrolka nie istnieje -->
<LL control="dev/sps/io/Unknown" value="" Code="500"/>

Kody odpowiedzi:

  • 200 — komenda przyjęta i wykonana
  • 401 — brak autoryzacji
  • 500 — błąd (np. kontrolka nie istnieje)

Wartości sterowania

Typ Dozwolone wartości
Digital On, Off, Pulse, 1, 0
Digital 2-wyjściowy PulseUp, PulseDown, PulseOpen, PulseClose, UpOn, UpOff, DownOn, DownOff
Analog Dowolna liczba zmiennoprzecinkowa (separator: .) np. 21.5, -5.2
Text Dowolny tekst UTF-8

2.2 WebSocket API

WebSocket API to preferowany sposób komunikacji z Miniserver — zapewnia real-time status updates i niski narzut komunikacyjny.

Nawiązanie połączenia

const WebSocket = require('ws');

// Połączenie WebSocket (RFC 6455)
const ws = new WebSocket('ws://192.168.1.100/ws/rfc6455', {
  headers: {
    'Sec-WebSocket-Protocol': 'remotecontrol'
  }
});

ws.on('open', () => {
  console.log('Połączono z Miniserver');
  
  // Sprawdź wersję structure file
  ws.send('jdev/sps/LoxAPPversion3');
});

ws.on('message', (data) => {
  if (typeof data === 'string') {
    // Odpowiedź tekstowa (JSON)
    const response = JSON.parse(data);
    console.log('Odpowiedź:', response);
  } else {
    // Dane binarne — status events
    handleBinaryEvent(data);
  }
});

Protokół binarny — Value Events

Miniserver wysyła aktualizacje stanów jako binarne wiadomości WebSocket. Format nagłówka:

Byte 0:    Typ wiadomości (0x00-0x06)
Byte 1:    Info/Identifier  
Byte 2-3:  Reserved
Byte 4-7:  Długość payloadu (Uint32 LE)

Typy wiadomości:

Typ Nazwa Opis
0x00 Text Odpowiedź tekstowa
0x01 Binary File Plik binarny (np. LoxAPP3.json skompresowany)
0x02 Value Events Aktualizacje wartości (UUID + Float64)
0x03 Text Events Aktualizacje tekstowe (UUID + String)
0x04 Daytimer Events Timer events
0x05 Out-of-service Miniserver niedostępny
0x06 Keepalive Heartbeat response
0x07 Weather Events Dane pogodowe

Parsowanie Value Events (typ 0x02)

function handleValueEvents(buffer) {
  const events = [];
  let offset = 0;
  
  while (offset < buffer.length) {
    // UUID: 16 bytes (jako dwa Uint64 LE → string hex)
    const uuidBytes = buffer.slice(offset, offset + 16);
    const uuid = formatUUID(uuidBytes);
    offset += 16;
    
    // Value: Float64 LE (8 bytes)
    const value = buffer.readDoubleLE(offset);
    offset += 8;
    
    events.push({ uuid, value });
  }
  
  return events;
}

function formatUUID(bytes) {
  const hex = Buffer.from(bytes).toString('hex');
  return `${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}`;
}

Aktywacja status updates

// Po autentykacji — włącz automatyczne wysyłanie zmian stanów
ws.send('jdev/sps/enablestatusupdate');

// Od tego momentu Miniserver wysyła binarne Value Events
// przy każdej zmianie stanu dowolnej kontrolki

Keepalive / Heartbeat

// Wysyłaj keepalive co 60 sekund
setInterval(() => {
  ws.send('keepalive');
}, 60000);

// Miniserver odpowiada wiadomością typu 0x06
// Jeśli brak odpowiedzi w ciągu 5s — reconnect

Limit połączeń: Miniserver obsługuje do 31 równoczesnych klientów WebSocket. Sprawdź dostępność slotów przez atrybut hasEventSlots w odpowiedzi na połączenie.

2.3 Structure File (LoxAPP3.json)

Structure File to JSON opisujący całą konfigurację Miniservera — pokoje, kategorie, kontrolki, ich stany i komendy. Jest fundamentem dla mapowania UUID ↔ czytelna nazwa.

Pobieranie

// Przez WebSocket
ws.send('data/LoxAPP3.json');

// Przez HTTP
// curl -u user:password "http://192.168.1.100/data/LoxAPP3.json"

Wersjonowanie i cache

// Sprawdź wersję przed pobraniem (oszczędność transferu)
ws.send('jdev/sps/LoxAPPversion3');
// Odpowiedź: {"lastModified": "2026-01-15 14:30:22"}

// Porównaj z zapisaną wersją — pobierz tylko jeśli się zmieniło

Struktura pliku

{
  "lastModified": "2026-01-15 14:30:22",
  "msInfo": {
    "serialNr": "504F94XXXXX",
    "msName": "Loxone Miniserver",
    "projectName": "Dom Strzelczyków",
    "localUrl": "192.168.1.100",
    "tempUnit": 0,
    "currency": "PLN",
    "currentUser": { "name": "Q", "uuid": "..." }
  },
  "rooms": {
    "0f1e2d3c-...": {
      "uuid": "0f1e2d3c-...",
      "name": "Salon",
      "image": "...",
      "defaultRating": 0,
      "isFavorite": false,
      "type": 1
    },
    "1a2b3c4d-...": {
      "uuid": "1a2b3c4d-...",
      "name": "Sypialnia",
      "image": "...",
      "type": 1
    }
  },
  "cats": {
    "aabb0011-...": {
      "uuid": "aabb0011-...",
      "name": "Oświetlenie",
      "image": "...",
      "type": "lights"
    }
  },
  "controls": {
    "12345678-abcd-...": {
      "uuid": "12345678-abcd-...",
      "name": "Lampa główna",
      "type": "Switch",
      "room": "0f1e2d3c-...",
      "cat": "aabb0011-...",
      "states": {
        "active": "12345678-abcd-...-s1"
      },
      "subControls": {}
    }
  }
}

Typy kontrolek (najważniejsze dla Q)

Typ Opis Stany Komendy
Switch Przełącznik on/off active (0/1) On, Off, Pulse
Dimmer Ściemniacz position (0-100), active On, Off, <value> (0-100)
Jalousie Rolety/żaluzje position (0-1), shadePosition FullUp, FullDown, Stop, <pos>
IRoomControllerV2 Termostat pokojowy tempActual, tempTarget, mode setManualTemperature/<temp>
Alarm System alarmowy armed, triggered, level ⛔ Q NIE steruje
Gate Brama/drzwi position, active ⛔ Q NIE steruje
InfoOnlyDigital Czujnik binarny (okno/drzwi) active (0/1) Tylko odczyt
InfoOnlyAnalog Czujnik analogowy (temp/wilg) value Tylko odczyt
Meter Licznik energii actual, total Tylko odczyt
Presence Czujnik obecności active, inactiveTimeout Tylko odczyt

SubControls

Niektóre kontrolki mają zagnieżdżone subkontrole. Np. IRoomControllerV2 zawiera:

  • SubControl typu Switch dla trybu komfortowego
  • SubControl typu InfoOnlyAnalog dla aktualnej temperatury
// Iteracja po kontrolkach i subkontrolkach
for (const [uuid, control] of Object.entries(structureFile.controls)) {
  console.log(`${control.name} (${control.type}) — pokój: ${structureFile.rooms[control.room]?.name}`);
  
  if (control.subControls) {
    for (const [subUuid, sub] of Object.entries(control.subControls)) {
      console.log(`  └─ ${sub.name} (${sub.type})`);
    }
  }
}

2.4 Autentykacja

Basic Auth (HTTP) — ⚠️ NIEZALECANE

# Credentials w URL — przesyłane plain text!
curl "http://admin:password@192.168.1.100/dev/sps/io/Light/state"

Problemy:

  • Hasło widoczne w logach, historii przeglądarki, snifferach
  • Brak szyfrowania na Gen.1 (HTTP only)
  • Dopuszczalne TYLKO w sieci lokalnej na Gen.1

Token-based Auth (HTTPS) — ✅ REKOMENDOWANE

Proces autentykacji token-based na Miniserver Gen.2:

const crypto = require('crypto');

// 1. Pobierz klucz publiczny Miniservera
// GET /jdev/sys/getPublicKey

// 2. Key exchange — generuj session key
// Wyślij zaszyfrowany RSA request z AES session key

// 3. Pobierz sól i klucz do hashowania
// GET /jdev/sys/getkey2/{username}
// Odpowiedź: { key: "...", salt: "..." }

// 4. Wygeneruj hash hasła
function hashPassword(password, key, salt) {
  // HMAC-SHA256 z hasłem i kluczem
  const hmac = crypto.createHmac('sha256', Buffer.from(key, 'hex'));
  hmac.update(`${password}:${salt}`);
  return hmac.digest('hex');
}

// 5. Zażądaj tokenu (zaszyfrowane AES)
// Komenda: jdev/sys/gettoken/{hash}/{username}/{permission}/{uuid}/{info}
// permission: 2 = Web (krótki), 4 = App (do 4 tygodni)
// uuid: unikatowy identyfikator klienta
// info: opis klienta (np. "Q Bridge")

// 6. Użyj tokenu do autentykacji
// Komenda: authwithtoken/{tokenHash}/{username}

Token lifecycle

// Sprawdź ważność tokenu
ws.send('jdev/sys/checktoken/{tokenHash}/{username}');

// Odśwież token (przedłuż ważność)
ws.send('jdev/sys/refreshtoken/{tokenHash}/{username}');

// Unieważnij token
ws.send('jdev/sys/killtoken/{tokenHash}/{username}');

Ważne zasady:

  • Token typu App jest ważny do 4 tygodni — wymaga regularnego refresha
  • Token typu Web wygasa po krótkim czasie — do jednorazowych operacji
  • Po wielokrotnych błędnych próbach Miniserver blokuje klienta (WebSocket close code 4003)
  • Każda komenda wysyłana po autentykacji powinna używać mechanizmu nextSalt — zmiana soli po każdej komendzie zapobiega atakom replay

Tworzenie dedykowanego użytkownika "Q"

W Loxone Config:

  1. Utwórz użytkownika Q-Agent z silnym hasłem (min. 20 znaków, generowane)
  2. Utwórz grupę Q-Access z uprawnieniami:
    • ✅ Dostęp wewnętrzny (Internal)
    • ❌ Dostęp zewnętrzny (External) — Q Bridge jest lokalny
    • ❌ Loxone Config — brak dostępu do programowania
    • ❌ FTP — niepotrzebne
    • ❌ Miniserver Backup/Update — niepotrzebne
  3. Przypisz uprawnienia per pokój/kategorię:
    • ✅ Read: wszystkie pokoje, wszystkie kategorie
    • ✅ Write: Oświetlenie, Rolety, Klimatyzacja
    • ❌ Write: Alarm, Zamki, Bramy, Konfiguracja

3. Bezpieczeństwo — KLUCZOWE

3.1 Architektura bezpieczeństwa

                    ┌─── FIREWALL ───┐
   INTERNET         │                │        SIEĆ LOKALNA
                    │   ZABLOKOWANE  │
   ❌ Nie ma        │   porty do     │    ✅ Q Bridge
   dostępu do  ────►│   Miniservera  │◄──── komunikuje się
   Miniservera      │                │       z Miniserver
                    └────────────────┘       BEZPOŚREDNIO

Fundamentalne zasady:

  1. NIGDY nie wystawiaj Miniservera na internet — żaden port forwarding, żaden tunel. Miniserver jest urządzeniem wewnętrznym.
  2. Q Bridge działa LOKALNIE na Mac mini w tej samej sieci co Miniserver. Cała komunikacja Bridge ↔ Miniserver odbywa się w LAN.
  3. Jedyne połączenia wychodzące z Bridge do internetu:
    • HTTPS do Anthropic API (Claude) — analiza i decyzje
    • HTTPS do Telegram Bot API — powiadomienia
    • WSS do Dashboard (Cloudflare Pages) — UI
  4. Zasada najmniejszych uprawnień — użytkownik Q ma read-only wszędzie gdzie to możliwe, write tylko na wybrane kontrolki.

3.2 Dedykowany użytkownik "Q"

# Konfiguracja użytkownika Q w Loxone Config
User:
  name: "Q-Agent"
  password: "<generowane 24+ znaków>"
  groups: ["Q-Access"]

Group Q-Access:
  permissions:
    # DOZWOLONE
    read_all_rooms: true        # Odczyt stanów ze wszystkich pokoi
    read_all_categories: true    # Odczyt ze wszystkich kategorii
    write_lighting: true         # Sterowanie oświetleniem
    write_blinds: true           # Sterowanie roletami
    write_climate: true          # Ustawianie temperatury
    
    # ZABRONIONE
    write_alarm: false           # ⛔ NIGDY
    write_locks: false           # ⛔ NIGDY
    write_gates: false           # ⛔ NIGDY
    loxone_config: false         # ⛔ Brak dostępu do konfiguracji
    ftp_access: false            # ⛔ Brak FTP
    miniserver_update: false     # ⛔ Brak aktualizacji
    miniserver_backup: false     # ⛔ Brak backupów
    external_access: false       # ⛔ Tylko sieć lokalna

Audit log — logowanie każdej akcji Q:

// Q Bridge — logowanie każdej wysłanej komendy
class CommandLogger {
  constructor() {
    this.logFile = './logs/q-commands.jsonl';
  }

  log(command, source, result) {
    const entry = {
      timestamp: new Date().toISOString(),
      command,
      source, // 'telegram', 'dashboard', 'ai-proactive', 'schedule'
      result, // 'success', 'denied', 'error'
      user: 'Q-Agent'
    };
    
    fs.appendFileSync(this.logFile, JSON.stringify(entry) + '\n');
    
    // Alert na komendę typu write
    if (command.includes('/On') || command.includes('/Off') || command.includes('/Pulse')) {
      this.notifyTelegram(`🏠 Q wykonał: ${command} (źródło: ${source})`);
    }
  }
}

3.3 Szyfrowanie

Warstwa Protokół Szczegóły
Bridge ↔ Miniserver WSS (TLS 1.2+) Miniserver Gen.2 obsługuje HTTPS natively
Bridge ↔ Claude API HTTPS (TLS 1.3) Anthropic API wymaga HTTPS
Bridge ↔ Telegram HTTPS (TLS 1.3) Telegram Bot API wymaga HTTPS
Dashboard ↔ Bridge WSS Cloudflare zapewnia TLS na edge
Credentials .env file Nigdy w kodzie, nigdy w repo
Token auth AES-256 + HMAC-SHA256 Szyfrowanie sesji + hashowanie tokenu 
# .env — NIGDY nie commituj do repo
LOXONE_IP=192.168.1.100
LOXONE_USER=Q-Agent
LOXONE_PASSWORD=<generowane>
LOXONE_TOKEN=<auto-managed>
CLAUDE_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_CHATS=6236262767,8706027603

3.4 Fail-safes

// Q Bridge — Command Validator
class CommandValidator {
  constructor() {
    // ⛔ BLACKLISTA — komendy NIGDY nie wykonywane przez Q
    this.BLACKLISTED_PATTERNS = [
      /alarm/i,           // Wszystko związane z alarmem
      /lock/i,            // Zamki
      /gate/i,            // Bramy
      /door.*open/i,      // Otwieranie drzwi
      /password/i,        // Zmiana haseł
      /sys\/config/i,     // Konfiguracja systemu
      /sys\/update/i,     // Aktualizacja firmware
      /sys\/reboot/i,     // Restart Miniservera
    ];

    // ⚠️ WYMAGAJĄ POTWIERDZENIA — komendy "destruktywne"
    this.CONFIRM_REQUIRED = [
      /Off$/,             // Wyłączanie czegokolwiek
      /FullDown/,         // Pełne zamknięcie rolet
      /setManualTemp/i,   // Zmiana temperatury
    ];

    // Rate limiting
    this.MAX_COMMANDS_PER_MINUTE = 30;
    this.commandHistory = [];
  }

  async validate(command, source) {
    // 1. Blacklist check
    if (this.BLACKLISTED_PATTERNS.some(p => p.test(command))) {
      logger.log(command, source, 'DENIED_BLACKLISTED');
      return { allowed: false, reason: 'Komenda na czarnej liście' };
    }

    // 2. Rate limit check
    const recentCommands = this.commandHistory.filter(
      c => Date.now() - c.time < 60000
    );
    if (recentCommands.length >= this.MAX_COMMANDS_PER_MINUTE) {
      logger.log(command, source, 'DENIED_RATE_LIMIT');
      return { allowed: false, reason: 'Przekroczono limit komend/min' };
    }

    // 3. Confirmation check
    if (this.CONFIRM_REQUIRED.some(p => p.test(command)) && source === 'ai-proactive') {
      return { allowed: false, needsConfirmation: true, reason: 'Wymaga potwierdzenia' };
    }

    this.commandHistory.push({ command, time: Date.now() });
    return { allowed: true };
  }
}

Watchdog — monitoring Bridge:

// Prosty watchdog — jeśli Bridge nie odpowie na ping w ciągu 30s, restart
// Implementowany jako osobny proces (systemd/launchd)

// launchd plist na macOS:
// ~/Library/LaunchAgents/com.q.bridge-watchdog.plist
// Restart automatyczny przy crash, max 3 próby/minutę

3.5 Monitoring i alerty

// Cotygodniowy raport bezpieczeństwa (niedzielny cron)
async function weeklySecurityReport() {
  const logs = readCommandLogs(7); // ostatnie 7 dni
  
  const report = {
    totalCommands: logs.length,
    bySource: groupBy(logs, 'source'),
    denied: logs.filter(l => l.result.startsWith('DENIED')),
    uniqueControls: new Set(logs.map(l => l.command)).size,
    peakHour: findPeakHour(logs),
    anomalies: detectAnomalies(logs), // Nietypowa aktywność
  };

  const message = `
🔒 **Raport bezpieczeństwa Q × Loxone** (tydzień ${getWeekNumber()})

📊 Komend wykonanych: ${report.totalCommands}
🚫 Odrzuconych: ${report.denied.length}
📱 Z Telegram: ${report.bySource.telegram || 0}
🤖 Proaktywnych AI: ${report.bySource['ai-proactive'] || 0}
🖥️ Z Dashboard: ${report.bySource.dashboard || 0}

${report.anomalies.length > 0 
  ? '⚠️ Wykryto anomalie:\n' + report.anomalies.map(a => `  • ${a}`).join('\n')
  : '✅ Brak anomalii'}
  `;

  await sendTelegram(DAMIAN_CHAT_ID, message);
}

4. Proaktywne funkcje AI

4.1 Uczenie się wzorców

Q zbiera dane z Miniservera i buduje profil zachowań domowników:

// Zbieranie danych — zapis każdej zmiany stanu
class PatternCollector {
  constructor(db) {
    this.db = db; // SQLite lub Supabase
  }

  async onStateChange(uuid, controlName, value, controlType) {
    await this.db.insert('state_changes', {
      timestamp: new Date().toISOString(),
      uuid,
      control_name: controlName,
      value,
      control_type: controlType,
      day_of_week: new Date().getDay(),
      hour: new Date().getHours(),
      minute: new Date().getMinutes(),
    });
  }
}

// Analiza tygodniowa — pattern recognition
async function analyzeWeeklyPatterns() {
  // Przykład: "Damian włącza światło w salonie codziennie o ~18:30"
  const lightPatterns = await db.query(`
    SELECT control_name, 
           day_of_week,
           ROUND(AVG(hour + minute/60.0), 1) as avg_time,
           COUNT(*) as occurrences,
           STDDEV(hour + minute/60.0) as time_variance
    FROM state_changes 
    WHERE control_type = 'Switch' 
      AND value = 1
      AND timestamp > datetime('now', '-7 days')
    GROUP BY control_name, day_of_week
    HAVING occurrences >= 3 AND time_variance < 1.0
  `);

  for (const pattern of lightPatterns) {
    const suggestion = {
      type: 'automation_suggestion',
      message: `Zauważyłem, że ${pattern.control_name} włączasz codziennie ok. ${formatTime(pattern.avg_time)}. Chcesz żebym robił to automatycznie?`,
      action: { control: pattern.control_name, command: 'On', time: pattern.avg_time },
    };
    
    await sendTelegram(DAMIAN_CHAT_ID, suggestion.message);
  }
}

4.2 Optymalizacja energii

// Monitoring zużycia energii
class EnergyMonitor {
  constructor(bridge, config) {
    this.bridge = bridge;
    this.kwhPrice = config.KWH_PRICE_PLN || 0.85; // PLN/kWh
  }

  async getEnergyReport(periodDays = 7) {
    // Pobierz dane z Meter controls
    const meters = this.bridge.getControlsByType('Meter');
    
    const report = {};
    for (const meter of meters) {
      const history = await this.bridge.getStatistics(meter.uuid, periodDays);
      const room = this.bridge.getRoomName(meter.room);
      
      report[room] = {
        totalKwh: history.reduce((sum, h) => sum + h.value, 0),
        costPLN: 0, // obliczone niżej
        trend: 0,   // porównanie z poprzednim okresem
      };
      report[room].costPLN = (report[room].totalKwh * this.kwhPrice).toFixed(2);
    }

    return report;
  }

  async weeklyReport() {
    const current = await this.getEnergyReport(7);
    const previous = await this.getEnergyReport(14); // porównanie

    let message = '⚡ **Raport energetyczny — ostatni tydzień**\n\n';
    
    for (const [room, data] of Object.entries(current)) {
      const prevData = previous[room];
      const trend = prevData 
        ? ((data.totalKwh - prevData.totalKwh) / prevData.totalKwh * 100).toFixed(0)
        : 'N/A';
      const emoji = trend > 10 ? '📈' : trend < -10 ? '📉' : '➡️';
      
      message += `${emoji} **${room}**: ${data.totalKwh.toFixed(1)} kWh (${data.costPLN} PLN) ${trend}%\n`;
    }

    const totalCost = Object.values(current).reduce((s, d) => s + parseFloat(d.costPLN), 0);
    message += `\n💰 **Razem**: ${totalCost.toFixed(2)} PLN`;

    await sendTelegram(DAMIAN_CHAT_ID, message);
  }
}

4.3 Komfort i zdrowie

// Circadian lighting — temperatura barwowa wg pory dnia
function getCircadianColorTemp(hour) {
  // Skala: 2700K (ciepłe, wieczór) → 6500K (zimne, dzień)
  const schedule = {
    6:  3000,  // Poranek — ciepłe, łagodne budzenie
    8:  4500,  // Poranek — coraz jaśniej
    10: 6000,  // Dzień — pełne światło dzienne
    12: 6500,  // Południe — max daylight
    16: 5500,  // Popołudnie — zaczyna się ciepić
    18: 4000,  // Wieczór — ciepłe
    20: 3000,  // Późny wieczór — relaksujące
    22: 2700,  // Sen — najcieplejsze
  };
  
  // Interpolacja między punktami
  return interpolate(schedule, hour);
}

// Monitoring jakości powietrza
class AirQualityMonitor {
  checkThresholds(sensors) {
    const alerts = [];
    
    if (sensors.co2 > 1000) {
      alerts.push(`⚠️ CO₂ w ${sensors.room}: ${sensors.co2} ppm — otwórz okno!`);
    }
    if (sensors.humidity < 40) {
      alerts.push(`💧 Wilgotność w ${sensors.room}: ${sensors.humidity}% — za sucho!`);
    }
    if (sensors.humidity > 60) {
      alerts.push(`💧 Wilgotność w ${sensors.room}: ${sensors.humidity}% — za wilgotno!`);
    }
    if (sensors.temp > 24 && sensors.room.includes('Sypialnia') && isNightTime()) {
      // WHO: optymalna temp do snu 16-19°C
      alerts.push(`🌡️ Temperatura w sypialni: ${sensors.temp}°C — WHO zaleca 16-19°C do snu`);
    }
    
    return alerts;
  }
}

4.4 Kontekstowe automatyzacje

// Integracja z pogodą
const weatherIntegration = {
  async checkAndAdjust() {
    // Pobierz pogodę z Open-Meteo (free, no key)
    const weather = await fetch(
      'https://api.open-meteo.com/v1/forecast?latitude=51.1&longitude=17.0' +
      '&current=temperature_2m,wind_speed_10m,rain,cloud_cover' +
      '&hourly=temperature_2m&forecast_days=1'
    ).then(r => r.json());

    const current = weather.current;

    // Słonecznie + gorąco → zamknij rolety na południu
    if (current.temperature_2m > 28 && current.cloud_cover < 30) {
      await bridge.send('jdev/sps/io/SouthBlinds/FullDown');
      notify('☀️ Zamykam rolety na południu — na zewnątrz jest ' + 
             Math.round(current.temperature_2m) + '°C');
    }

    // Deszcz → zamknij okna dachowe (jeśli jest aktuator)
    if (current.rain > 0) {
      await bridge.send('jdev/sps/io/RoofWindows/Close');
      notify('🌧️ Pada deszcz — zamykam okna dachowe');
    }

    // Silny wiatr → zwiń markizy
    if (current.wind_speed_10m > 40) {
      await bridge.send('jdev/sps/io/Awning/FullUp');
      notify('💨 Silny wiatr — zwijam markizy');
    }
  }
};

// Tryb wyjazd — aktywowany z kalendarza lub ręcznie
async function activateVacationMode() {
  // 1. Eco temperature
  await bridge.setAllThermostats(16);
  
  // 2. Symulacja obecności — random światła wieczorem
  schedulePresenceSimulation();
  
  // 3. Zamknij wszystkie rolety
  await bridge.send('jdev/sps/io/AllBlinds/FullDown');
  
  // 4. Wzmocniony monitoring — alert na każde otwarcie drzwi/okna
  enableEnhancedSecurity();
  
  notify('🏖️ Tryb wakacyjny aktywny. Eco mode + symulacja obecności.');
}

4.5 Scenariusze

const scenes = {
  // 🎬 Tryb filmowy
  movie: async () => {
    await bridge.send('jdev/sps/io/LivingRoomLights/5');   // Dimmer 5%
    await bridge.send('jdev/sps/io/LivingRoomBlinds/FullDown');
    await bridge.send('jdev/sps/io/KitchenLights/Off');
    notify('🎬 Tryb filmowy aktywny. Miłego seansu!');
  },

  // 🌙 Dobranoc
  goodnight: async () => {
    // Sprawdź otwarte okna
    const openWindows = bridge.getControlsByType('InfoOnlyDigital')
      .filter(c => c.name.includes('Okno') && c.value === 1);
    
    if (openWindows.length > 0) {
      notify(`🪟 Uwaga — otwarte okna: ${openWindows.map(w => w.roomName).join(', ')}`);
    }

    await bridge.send('jdev/sps/io/AllLights/Off');
    await bridge.send('jdev/sps/io/AllBlinds/FullDown');
    await bridge.setAllThermostats(18); // Obniż temp do snu
    notify('🌙 Dobranoc! Wszystko wyłączone, rolety zamknięte.');
  },

  // ☀️ Poranek
  morning: async () => {
    await bridge.send('jdev/sps/io/BedroomBlinds/FullUp');
    await bridge.send('jdev/sps/io/KitchenLights/On');
    await bridge.setAllThermostats(21);
    // Pogoda w briefingu porannym
    const weather = await getWeather();
    notify(`☀️ Dzień dobry! Na zewnątrz ${Math.round(weather.temp)}°C. ${weather.description}`);
  },

  // 👶 Tryb dziecięcy
  kidsMode: async () => {
    // Bezpieczne ustawienia w pokojach dzieci
    await bridge.send('jdev/sps/io/BrunoRoomTemp/21');
    await bridge.send('jdev/sps/io/TymekRoomTemp/21');
    await bridge.send('jdev/sps/io/BrunoNightLight/On');  // Lampka nocna
    // Zablokuj regulację temp poniżej 19°C
    notify('👶 Tryb dziecięcy aktywny. Temperatury zabezpieczone.');
  },
};

5. Istniejące biblioteki i integracje

5.1 Porównanie bibliotek

Biblioteka Język Protokół Maintenance Dla Q?
node-lox-ws-api Node.js WebSocket Aktywny ✅ Rekomendowane
lxcommunicator JS (official) WebSocket Loxone oficjalne ✅ Alternatywa
PyLoxone Python WebSocket/HTTP Aktywny (HA) ❌ (Q jest Node.js)
node-lox-structure-file Node.js Parser JSON Aktywny ✅ Do parsowania LoxAPP3
Loxone ↔ MQTT Różne MQTT bridge Community ❌ Zbędna warstwa

5.2 node-lox-ws-api — rekomendowane dla Q Bridge

// Instalacja
// npm install node-lox-ws-api

const LoxoneAPI = require('node-lox-ws-api');

const miniserver = new LoxoneAPI(
  '192.168.1.100',  // IP Miniservera
  'Q-Agent',         // Użytkownik
  'haslo123',        // Hasło
  true,              // Autoryzacja tokenowa
  'Q-Bridge'         // Nazwa klienta
);

// Event: Połączono i zaautentykowano
miniserver.on('connect_failed', () => {
  console.error('Nie udało się połączyć z Miniserver');
});

miniserver.on('authorized', () => {
  console.log('Zaautentykowano! Pobieram structure file...');
});

miniserver.on('get_structure_file', (structureFile) => {
  console.log('Structure file pobrany');
  console.log('Pokoje:', Object.keys(structureFile.rooms).length);
  console.log('Kontrolki:', Object.keys(structureFile.controls).length);
});

// Event: Zmiana stanu (UUID → wartość)
miniserver.on('update_event_value', (uuid, value) => {
  console.log(`Stan zmieniony: ${uuid} = ${value}`);
});

miniserver.on('update_event_text', (uuid, text) => {
  console.log(`Tekst zmieniony: ${uuid} = ${text}`);
});

// Wysłanie komendy
miniserver.send_command(controlUUID, 'On');

// Start połączenia
miniserver.connect();

5.3 lxcommunicator — oficjalna biblioteka Loxone

// GitHub: github.com/Loxone/lxcommunicator
// Oficjalna biblioteka od Loxone — obsługuje szyfrowanie, tokeny, binary events
const LxCommunicator = require('lxcommunicator');

const socket = new LxCommunicator.WebSocketConfig(
  LxCommunicator.WebSocketConfig.protocol,
  'uuid-q-bridge',    // unikatowy UUID klienta
  'Q-Bridge',          // device info
  LxCommunicator.WebSocketConfig.permission.APP,
  false                // Don't use visual password hash
);

5.4 PyLoxone (referencja)

Używany głównie przez integrację Home Assistant. Nie rekomendowany dla Q Bridge (który jest Node.js), ale wart znajomości:

# pip install pyloxone
# GitHub: github.com/JoDehli/PyLoxone
# Integracja z Home Assistant — mapuje entity Loxone na HA entities
# Wspiera: Switch, Dimmer, Jalousie, Climate, Sensor, Cover

5.5 Rekomendacja dla Q Bridge

Użyj node-lox-ws-api jako podstawę Q Bridge:

  • Natywny Node.js — spójny z resztą ekosystemu Q
  • Obsługuje token auth, binary events, auto-reconnect
  • Aktywnie utrzymywany, używany w Node-RED contrib
  • Parsuje LoxAPP3.json automatycznie
  • Fallback: lxcommunicator (oficjalne Loxone) jeśli node-lox-ws-api nie wystarcza

6. Dashboard (q-home.pages.dev)

6.1 Architektura

┌──────────────────────────────────────────────────┐
│            q-home.pages.dev (React)               │
│                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Pokoje    │  │ Energia  │  │ Historia     │    │
│  │ Live View │  │ Wykresy  │  │ Zdarzeń      │    │
│  │           │  │          │  │              │    │
│  │ 🔆 Salon  │  │ ⚡ 4.2kW │  │ 18:30 Light │    │
│  │ 🌡️ 21.5° │  │ 📊 Chart │  │ 18:45 Blind │    │
│  │ 🪟 Zamkn. │  │          │  │ 19:00 Temp  │    │
│  └──────────┘  └──────────┘  └──────────────┘    │
│                                                    │
│  Sterowanie: [💡 On/Off] [🔼 Rolety] [🌡️ Temp]    │
└────────────────────────┬───────────────────────────┘
                         │ WSS
                    ┌────▼────┐
                    │ Q Bridge │
                    └─────────┘

6.2 Design system

Spójny z resztą Q:

:root {
  --q-primary: #FF6B35;      /* Orange — akcje, CTA */
  --q-secondary: #004E89;     /* Navy — tła, nagłówki */
  --q-success: #2ECC71;       /* Zielony — status OK */
  --q-warning: #F39C12;       /* Żółty — uwagi */
  --q-danger: #E74C3C;        /* Czerwony — alarmy */
  --q-bg: #1A1A2E;            /* Dark background */
  --q-card: #16213E;          /* Card background */
  --q-text: #EAEAEA;          /* Main text */
}

6.3 Widoki

  1. Pokoje — kafelki z live stanem każdego pokoju (temp, światła, rolety, okna)
  2. Sterowanie — slider dimmer, przyciski on/off, pozycja rolet, target temp
  3. Energia — wykresy zużycia (Chart.js), porównanie z poprzednim tygodniem
  4. Historia — timeline ostatnich zdarzeń (komendy, zmiany stanów, alerty Q)
  5. Sceny — przyciski szybkiego dostępu: 🎬 Film, 🌙 Dobranoc, ☀️ Poranek

6.4 Deploy

# Build i deploy na Cloudflare Pages
cd q-home
npm run build
CLOUDFLARE_API_TOKEN=ucC_... CLOUDFLARE_ACCOUNT_ID=ebf8... \
  npx wrangler pages deploy dist --project-name=q-home --branch=main

7. Implementacja — fazy

Faza 0: Przygotowanie (przed kodem)

Wymagane od Damiana:

  • IP adres Miniservera w sieci lokalnej
  • Utworzenie użytkownika Q-Agent z odpowiednimi uprawnieniami
  • Lista pomieszczeń i urządzeń do kontrolowania
  • Które urządzenia Q może sterować (write) vs tylko czytać (read)

Q automatycznie:

# 1. Pobierz LoxAPP3.json
curl -u Q-Agent:password "http://MINISERVER_IP/data/LoxAPP3.json" > loxapp3.json

# 2. Parsuj i wylistuj pokoje + kontrolki
node -e "
  const s = require('./loxapp3.json');
  for (const [id, room] of Object.entries(s.rooms)) {
    console.log('Pokój:', room.name);
    const controls = Object.values(s.controls).filter(c => c.room === id);
    controls.forEach(c => console.log('  ', c.type, ':', c.name));
  }
"

Szacowany output:

Pokój: Salon
  Switch : Lampa główna
  Dimmer : Lampa narożna
  Jalousie : Rolety salon
  IRoomControllerV2 : Termostat salon
  InfoOnlyDigital : Okno salon L
  InfoOnlyDigital : Okno salon P
Pokój: Sypialnia
  Switch : Lampka nocna
  Jalousie : Rolety sypialnia
  IRoomControllerV2 : Termostat sypialnia
...

Faza 1: Bridge + Read-only (1-2 dni)

// q-bridge/index.js — Faza 1
const LoxoneAPI = require('node-lox-ws-api');
const TelegramBot = require('node-telegram-bot-api');
require('dotenv').config();

const miniserver = new LoxoneAPI(
  process.env.LOXONE_IP,
  process.env.LOXONE_USER,
  process.env.LOXONE_PASSWORD,
  true,  // token auth
  'Q-Bridge'
);

const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN);
const ALLOWED_CHATS = process.env.TELEGRAM_ALLOWED_CHATS.split(',');

let structureFile = null;
let currentStates = {}; // UUID → value

// Połączenie z Miniserver
miniserver.on('authorized', () => console.log('✅ Q Bridge połączony z Miniserver'));

miniserver.on('get_structure_file', (sf) => {
  structureFile = sf;
  console.log(`📋 Załadowano ${Object.keys(sf.controls).length} kontrolek`);
});

// Śledzenie zmian stanów
miniserver.on('update_event_value', (uuid, value) => {
  const prev = currentStates[uuid];
  currentStates[uuid] = value;
  
  // Alert: okno/drzwi otwarte
  const control = findControlByStateUUID(uuid);
  if (control && control.type === 'InfoOnlyDigital' && value === 1 && prev === 0) {
    const roomName = structureFile.rooms[control.room]?.name || '?';
    notify(`🪟 Otwarto: ${control.name} (${roomName})`);
  }
  
  // Alert: temperatura poza zakresem
  if (control && control.name.includes('Temp') && (value > 28 || value < 15)) {
    const roomName = structureFile.rooms[control.room]?.name || '?';
    notify(`🌡️ Temperatura w ${roomName}: ${value}°C!`);
  }
});

function notify(message) {
  ALLOWED_CHATS.forEach(chatId => bot.sendMessage(chatId, message));
}

miniserver.connect();

Faza 2: Sterowanie (1 dzień)

// Dodaj obsługę komend z Telegram
bot.onText(/Q,?\s+(.+)/i, async (msg, match) => {
  if (!ALLOWED_CHATS.includes(String(msg.chat.id))) return;
  
  const command = match[1].toLowerCase();
  
  // NLP via Claude — rozpoznaj intencję
  const intent = await analyzeIntent(command);
  // intent: { action: 'turnOn', room: 'salon', device: 'światło' }
  
  const control = findControl(intent.room, intent.device);
  if (!control) {
    bot.sendMessage(msg.chat.id, `Nie znalazłem "${intent.device}" w "${intent.room}" 🤔`);
    return;
  }

  // Walidacja
  const validation = await validator.validate(
    `jdev/sps/io/${control.uuid}/${intent.action}`,
    'telegram'
  );
  
  if (!validation.allowed) {
    bot.sendMessage(msg.chat.id, `⛔ ${validation.reason}`);
    return;
  }

  // Wykonaj
  miniserver.send_command(control.uuid, mapAction(intent.action));
  bot.sendMessage(msg.chat.id, `✅ ${control.name} — ${intent.action}`);
});

// Przykłady komend:
// "Q, włącz światło w salonie"    → LivingroomLight/On
// "Q, zamknij rolety"             → AllBlinds/FullDown
// "Q, ustaw 22 stopnie w sypialni" → BedroomTemp/setManualTemperature/22
// "Q, tryb filmowy"               → scenes.movie()
// "Q, dobranoc"                   → scenes.goodnight()

Faza 3: AI Intelligence (ciągłe)

// Cotygodniowa analiza wzorców (cron: niedziela 09:00)
async function weeklyAIAnalysis() {
  const weekData = await db.getWeekData();
  
  const analysis = await claude.analyze({
    prompt: `Przeanalizuj dane smart home z ostatniego tygodnia.
    Znajdź wzorce, sugeruj automatyzacje, wykryj anomalie.
    Dane: ${JSON.stringify(weekData)}
    
    Odpowiedz w formacie JSON:
    {
      "patterns": [{"description": "...", "confidence": 0.9}],
      "suggestions": [{"text": "...", "action": {...}}],
      "anomalies": [{"description": "...", "severity": "low|medium|high"}],
      "energy_insights": "..."
    }`,
  });

  // Wyślij sugestie do zatwierdzenia
  for (const suggestion of analysis.suggestions) {
    await sendTelegramWithButtons(DAMIAN_CHAT_ID, suggestion.text, [
      { text: '✅ Tak, zrób to', callback: `approve_${suggestion.id}` },
      { text: '❌ Nie, dzięki', callback: `reject_${suggestion.id}` },
    ]);
  }
}

8. Ryzyka i mitygacja

Ryzyko Prawdopodobieństwo Wpływ Mitygacja
Bridge pada Średnie Niski Loxone działa normalnie. Auto-restart via launchd. Max 30s downtime.
AI halucynuje Niskie Średni Każda komenda walidowana przez CommandValidator. Blacklista destruktywnych akcji. Potwierdzenie na Telegram.
Przejęcie Telegram Bardzo niskie Wysoki 2FA na koncie Telegram. ALLOWED_CHATS whitelist — bot ignoruje wiadomości z nieznanych chatów.
Internet pada Średnie Niski Bridge działa lokalnie. Stany cachowane. Komendy kolejkowane. Brak Claude/Telegram, ale basic automation działa.
Miniserver reboot Niskie Niski Auto-reconnect w node-lox-ws-api. Re-download structure file. Stan odtworzony.
Token wygasł Średnie Niski Auto-refresh tokenu co 3 tygodnie (przed 4-tygodniowym expiry). Alert jeśli refresh fail.
GDPR/prywatność N/A N/A Dane zostają lokalnie na Mac mini. Brak przesyłania danych osobowych do chmury. Claude dostaje tylko zanonimizowane wzorce (temperatury, czasy, bez imion).
Ktoś w sieci lokalnej Niskie Średni Miniserver wymaga autentykacji. Q-Agent ma ograniczone uprawnienia. WPA3 na WiFi.

9. Koszty

Pozycja Koszt miesięczny Uwagi
Infrastruktura $0 Mac mini już działa 24/7 jako host Q
Claude API ~$5-10 Sonnet do analizy wzorców, NLP komend (~1000 req/mies)
Cloudflare Pages $0 Free tier: unlimited bandwidth, 500 builds/mies
Telegram Bot $0 Free
Loxone API $0 API wbudowane w Miniserver, brak opłat
Biblioteki Node.js $0 Open source (node-lox-ws-api, etc.)
Supabase (opcja) $0 Free tier: 500MB DB, 50k reads/mies
RAZEM ~$5-10/mies

Appendix A: Przydatne komendy API

# Wersja Miniservera
curl -u user:pass "http://IP/dev/cfg/version"

# Public key (do token auth)
curl "http://IP/jdev/sys/getPublicKey"

# Pobierz LoxAPP3.json
curl -u user:pass "http://IP/data/LoxAPP3.json" -o loxapp3.json

# Sprawdź wersję structure file
curl -u user:pass "http://IP/jdev/sps/LoxAPPversion3"

# Włącz status updates (WebSocket)
# ws.send('jdev/sps/enablestatusupdate')

# Status PLC
curl -u user:pass "http://IP/dev/sps/status"

# Statystyki sieciowe
curl -u user:pass "http://IP/dev/lan/txp"

Appendix B: Referencje

Dokument przygotowany przez Q Agent — gotowy do implementacji.
Następny krok: Damian podaje IP Miniservera i tworzy użytkownika Q-Agent → rozpoczynamy Fazę 0.

Q Smart Home — Nakładka AI na Loxone

Wizja

Q Smart Home to inteligentna warstwa nad systemem Loxone, która zamienia "głupi" smart home w naprawdę inteligentny dom. Loxone obsługuje hardware — Q obsługuje mózg.

Architektura

┌──────────────────────────────────┐
│          Q Smart Home AI         │
│  (Claude Sonnet + rules engine)  │
├──────────────────────────────────┤
│       Q Loxone Bridge            │
│  (Node.js, WebSocket + REST)     │
├──────────────────────────────────┤
│     Loxone Miniserver            │
│  (LoxAPP3.json + Web Services)   │
├──────────────────────────────────┤
│   Hardware (czujniki, aktory)    │
│  Światła, rolety, HVAC, alarm   │
└──────────────────────────────────┘

Kluczowe funkcje

1. 🧠 Proaktywne sugestie optymalizacji

  • "Zauważyłem że codziennie o 7:30 włączasz światło w łazience — chcesz żebym to zautomatyzował?"
  • "Ogrzewanie w pokoju Bruno jest ustawione na 23°C ale WHO rekomenduje 18-20°C do snu — zmienić?"
  • "Rolety w salonie mogłyby się automatycznie opuszczać o zachodzie słońca — oszczędzisz na klimie"
  • "Zużycie energii wzrosło o 15% w tym miesiącu vs poprzedni"

2. 📊 Dashboard energetyczny

  • Zużycie energii real-time (per pomieszczenie)
  • Trendy dzienne/tygodniowe/miesięczne
  • Porównanie z poprzednimi okresami
  • Szacunkowy koszt w PLN
  • Sugestie oszczędności

3. 🌡️ Inteligentne zarządzanie klimatem

  • Uczenie się preferencji temperaturowych rodziny
  • Automatyczne dostosowanie do pogody (wttr.in API)
  • Tryb nocny: obniż temp w sypialni, podnieś rano
  • Tryb "wyjeżdżamy" — eco mode na weekend/wakacje
  • Wilgotność powietrza — alert gdy za sucho/mokro

4. 💡 Inteligentne oświetlenie

  • Sceny świetlne dopasowane do pory dnia (circadian)
  • "Film" — przyciemnij wszystko
  • "Kolacja" — ciepłe światło w kuchni/jadalni
  • Automatyczne wyłączanie gdy nikogo nie ma (czujniki ruchu)
  • Symulacja obecności (wakacje)

5. 🔒 Bezpieczeństwo

  • Alert na Telegram: "Drzwi frontowe otwarte od 10 minut"
  • Historia otwarć drzwi/okien
  • Tryb nocny: sprawdź czy wszystko zamknięte
  • Detekcja anomalii: "Okno w piwnicy otwarte o 3 w nocy"

6. 🗣️ Sterowanie głosowe (przez Q)

  • "Q, włącz światło w salonie"
  • "Q, ustaw temperaturę na 21 stopni"
  • "Q, zamknij rolety"
  • "Q, tryb filmowy"
  • Przez Telegram, HomePod, telefon

7. 📱 Dashboard mobilny (Cloudflare Pages)

  • q-home.pages.dev
  • Widok pomieszczeń z aktualnym stanem
  • Sterowanie światłami, roletami, temp
  • Historia zdarzeń
  • Wykresy energii

8. 🤖 Automatyzacje AI (ponad Loxone Config)

  • Loxone ma proste if/then — Q ma kontekst
  • "Jeśli Ewa jest w drodze do domu (GPS) + jest zima + temp < 19°C → włącz ogrzewanie"
  • "Jeśli pada deszcz + okna otwarte → wyślij alert"
  • "Jeśli nikt nie ma być w domu > 2h → tryb eco"

Integracja z Loxone API

Połączenie

http://user:pass@MINISERVER_IP/dev/sps/io/{control}/state  — odczyt
http://user:pass@MINISERVER_IP/dev/sps/io/{control}/On     — sterowanie
WebSocket: ws://MINISERVER_IP/ws/rfc6455  — real-time events
LoxAPP3.json: http://MINISERVER_IP/data/LoxAPP3.json       — pełna konfiguracja

Komendy

  • Status: /dev/sps/io/{name}/state
  • Włącz/wyłącz: /dev/sps/io/{name}/On|Off
  • Analog: /dev/sps/io/{name}/{value}
  • Pulse: /dev/sps/io/{name}/Pulse
  • Status updates (WebSocket): /dev/sps/enablestatusupdate

Wymagania od Damiana

  1. IP Miniservera Loxone w sieci domowej
  2. Login/hasło do Miniservera
  3. Lista pomieszczeń i urządzeń (lub pobiorę z LoxAPP3.json)
  4. Preferencje — temperatura, sceny świetlne, rutyny

Stack technologiczny

  • Bridge: Node.js + WebSocket client (na Mac mini 24/7)
  • AI: Claude Sonnet (analiza, sugestie, automatyzacje)
  • Dashboard: React + Tailwind na Cloudflare Pages
  • Notifications: Telegram (istniejący Q bot)
  • Voice: HomePod/Siri Bridge (istniejący)
  • Dane pogodowe: Open-Meteo/wttr.in (free, no key)

Fazy wdrożenia

Faza 1: Połączenie (1 dzień)

  • Bridge Node.js łączy się z Miniserver
  • Pobranie LoxAPP3.json — mapa urządzeń
  • Podstawowe sterowanie (światła on/off)
  • Alerty na Telegram

Faza 2: Dashboard (2-3 dni)

  • q-home.pages.dev z widokiem pomieszczeń
  • Sterowanie z telefonu
  • Historia zdarzeń

Faza 3: Inteligencja (ciągłe)

  • Analiza wzorców użytkowania
  • Proaktywne sugestie
  • Automatyzacje AI
  • Optymalizacja energii