BoothDock Studio voi ilmoittaa muille ohjelmille istunnon jokaisesta vaiheesta (webhookit) ja antaa muiden ohjelmien ohjata itseään (paikallinen API). Molemmat löydät ylläpito-osiosta kohdasta Järjestelmä → Automaatio.
BoothDock Studion versiossa 1.4.0 ja sitä vanhemmissa webhookien nimi on siellä vielä ”Laukaisimet”.
Webhookit ovat käytettävissä Windowsissa ja versiosta 1.5.10 alkaen myös iPadissa, iPhonessa ja Macissa. Paikallinen API on versiosta 1.4.0 alkaen käytettävissä myös iPadissa, iPhonessa ja Macissa, reaaliaikainen vienti versiosta 1.5.2 alkaen.
Tyypillisiä käyttötapoja: valot tai DMX lähtölaskennan tahdissa, striimin overlay, laskuri sisäänkäynnillä – tai Stream Deck Boxin kaukosäätimenä.

Webhookien määrittäminen
Täytä kenttä Osoite (URL), Windowsissa myös kenttä Ohjelma – tai molemmat. Jokaisen tapahtuman kohdalla Box kutsuu kaikkea, mitä on täytetty:
- Ohjelma (vain Windows) –
.exe,.battai.cmd. Kutsu:ohjelma <tapahtuma> <param1> <param2> …. Jokainen arvo tulee omana argumenttinaan, vaikka se sisältäisi välilyöntejä. Ohjelma käynnistyy ilman ikkunaa, omassa kansiossaan. PowerShell-skriptin (.ps1) käynnistät sen eteen laitetun pienen.bat-tiedoston kautta. - Osoite (URL) –
httptaihttps, kutsutaan GET-pyynnöllä:https://oma-palvelin/hook?event_type=<tapahtuma>¶m1=…¶m2=…. Arvot ovat URL-koodattuja; osoitteessasi jo olevat parametrit säilyvät.
iPadissa, iPhonessa ja Macissa on vain osoite. Siellä http:// toimii vain lähiverkossa (IP-osoite tai .local) – Shelly, WLED ja Tasmota Wi-Fi-verkossa siis toimivat. Internetin osoitteet tarvitsevat https://.
Istunto ei koskaan odota webhookiasi: ohjelma ja kutsu kulkevat rinnalla, ja yksi kutsu saa kestää enintään 5 sekuntia. Lähetä testi lähettää heti tapahtuman session_start – näin tarkistat yhteyden aloittamatta istuntoa.
Ohjelman ja osoitteen voi määrittää vain suoraan Boxilla, ei Hubin kautta: ohjelmapolku on oikeus suorittaa jotain tietokoneella.
Oma osoite tapahtumakohtaisesti
Versiosta 1.5.10 alkaen voit kohdassa Oma osoite tapahtumakohtaisesti (valinnainen) antaa jokaiselle tapahtumalle lisäksi oman osoitteen – esimerkiksi Wi-Fi-verkon Shelly-pistorasialle, WLEDille tai Tasmotalle, joka kytkeytyy lähtölaskennan tai kuvauksen aikana. Esimerkki tapahtumalle countdown_start: http://192.168.1.50/relay/0?turn=on.
Box kutsuu tätä osoitetta yllä olevan ohjelman ja osoitteen lisäksi, pelkkänä GET-pyyntönä ilman lisättyjä arvoja. Aiempi osoite ja olemassa olevat skriptit toimivat ennallaan. countdown tulee joka sekunti; file_upload-tapahtumassa Box kutsuu omaa osoitetta kerran istuntoa kohden (yleistä osoitetta edelleen tiedostoittain).
Tapahtumat
| Tapahtuma | Milloin | Parametrit |
|---|---|---|
session_start | Vieras aloittaa istunnon, moodi on valittu | 1: moodi (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock-moodi (photo, gif, boomerang, video, slowmo, ai) |
countdown_start | Lähtölaskenta alkaa | 1: sekunnit |
countdown | Lähtölaskennan jokainen sekunti | 1: edistyminen prosentteina (alkaen 0:sta) |
capture_start | Lähtölaskenta on päättynyt, kuvaus alkaa | – |
file_download | Kamera on tallentanut kuvan | 1: tiedostonimi, 2: koko polku |
processing_start | Käsittely alkaa | jokaisesta kameran alkuperäisestä yksi tiedostonimi, viimeisenä arvona tulostustiedosto (tällä hetkellä tyhjä) |
sharing_screen | Tulosnäyttö tulee esiin (kerran istuntoa kohden) | – |
printing | Arkki lähtee tulostimelle | 1: tiedosto (tällä hetkellä tyhjä), 2: kopiot, 3: tulostin |
file_upload | Tiedosto on saapunut Hubiin (tiedostokohtaisesti) | 1: polku Boxilla, 2: gallerialinkki, 3: tyyppi (print, photo, original, animation, boomerang, video), 4: albumi (tapahtuman nimi) |
lead_submitted | Vieras on lähettänyt lomakkeen Vierastiedot (lomake) (versiosta 1.5.0) | – (itse vastaukset ovat vain CSV-viennissä) |
session_end | Istunto päättyy – valmis, keskeytetty, vanhentunut tai poistettu | – |
Esimerkki .bat-tiedostosta, joka kirjaa jokaisen tapahtuman: echo %DATE% %TIME% %* >> "%~dp0tapahtumat.log"
Paikallinen API
Muut ohjelmat ohjaavat Boxia HTTP:n kautta – esimerkiksi Stream Deck, oma skripti tai 360°-ohjaus puhelimesta.
- Käyttöönotto: Järjestelmä → Automaatio → Ota API käyttöön. Oletuksena API on pois päältä. Portti 1500, muutettavissa.
- Osoite:
http://localhost:1500/api/<komento>(tai127.0.0.1). Oletuksena Box ottaa vastaan pyyntöjä vain tältä tietokoneelta. - Salasana: 16 merkkiä, näkyy samassa osiossa – kopioi se tai luo uusi. Välitä se muodossa
?password=…, otsakkeenaX-Api-Passwordtai muodossaAuthorization: Bearer …. Vainpingtoimii ilman. - Vastaus: aina HTTP 200 ja JSON, esimerkiksi
{"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Onnistuiko pyyntö, näkyy kentästäIsSuccessful, virheen syy kentästäErrorMessage. Jotkin komennot palauttavat lisäksi kentänData.
Täydellinen kutsu: http://localhost:1500/api/start?mode=print&password=OMA-SALASANA
Ohjaus verkosta (puhelin, tabletti, 360°)
Kytke lisäksi päälle Käytettävissä myös verkosta. Silloin Box ottaa vastaan pyyntöjä laitteilta samassa Wi-Fi-/LAN-verkossa – ei koskaan internetistä.
- Osoite puhelimelle: näkyy tilarivillä, esimerkiksi
http://192.168.1.20:1500. Sen alla oleva esimerkki näyttää silloin heti oikean osoitteen. - Ilman IP-osoitteen syöttämistä: Box ilmoittautuu verkossa itse (mDNS/Bonjour, palvelutyyppi
_boothdock._tcp, nimi „BoothDock" ja tietokoneen nimi). Sitä etsivät sovellukset löytävät sen automaattisesti. - Esto: jos laite lähettää väärän salasanan kymmenen kertaa kymmenessä minuutissa, se estetään 15 minuutiksi. Tätä tietokonetta itseään ei koskaan estetä.
- Vain omassa verkossa: salasana kulkee verkossa salaamattomana. Käytä verkkotoimintoa vain omassa, suojatussa Wi-Fi-verkossasi – ei tapahtumapaikan avoimessa vieras-Wi-Fissä.
- Palomuuri: asennus luo sallintasäännön, vain yksityisille verkoille. Jos tilarivillä näkyy palomuurivaroitus, asenna BoothDock Studio uudelleen tai salli se Windowsissa kohdassa „Salli sovellus palomuurin läpi". Jos Windows käsittelee Wi-Fi-verkkoa julkisena, laitteet eivät pääse sisään – valitse verkon ominaisuuksista profiiliksi Yksityinen.
Komennot
| Komento | Vaikutus |
|---|---|
start?mode=print | Aloittaa istunnon. Moodit: print (kuva), gif, boomerang, slowmo (360°; ilman 360°:ta boomerang), video, ai. Toimii vain aloitusnäytöltä, vain käyttöön otetulla moodilla eikä silloin, kun Box on lukittu. Mallin, tyylin ja taustan kanssa: katso alta. |
auswahl?mode=print | Palauttaa kentässä Data, mitä tässä moodissa voi valita: vorlagen (Id ja nimi; tyhjä, jos vain yksi malli on sallittu – se on silloin kentässä vorgabeVorlage), hintergruende mallikohtaisesti ja moodissa ai myös stile (1.5.13 alkaen). |
cancel | Keskeyttää käynnissä olevan istunnon ja palaa aloitusnäyttöön. |
status | Palauttaa kentässä Data: vierastila päällä/pois, nykyinen näyttö, moodi, lukittu kyllä/ei – 1.5.13 alkaen myös sperrgrund (manuell tai zeitfenster) ja oeffnetUm. |
print?count=1 | Tulostaa viimeisimmän tuloksen uudelleen (1–10 arkkia). Videoita ei voi tulostaa. |
lockscreen/show | Lukitsee Boxin tekstillä „Hetkinen – jatketaan pian." tai omalla tekstilläsi ja kuvallasi (katso „Lukitusnäyttö“ alta). Ylläpitokulma pysyy käytettävissä. 1.5.13 alkaen lukitus säilyy myös sovelluksen uudelleenkäynnistyksen yli. |
lockscreen/exit | Poistaa lukituksen – 1.5.13 alkaen myös aikaikkunan lukituksen, seuraavaan vaihtumiseen asti. |
share/email?email=… | Lähettää viimeisimmän tuloksen sähköpostitse – vaatii Hub-pariutuksen ja tuloksen toiminnon ”Saa sähköpostilla” (Järjestelmä → Käyttö → Tuloksen toiminnot (vieras); 1.4.0:aan asti kytkimen ”Kuva sähköpostitse (vieras)” kohdassa Ulkoasu → Näytöt). |
share/sms | Ei ole olemassa; vastaus kertoo sen rehellisesti (IsSuccessful: false). |
createtestevent?name=… | Luo testitapahtuman ja aktivoi sen. Data sisältää kentät eventId ja eventName. Ilman nimeä tapahtuma saa päivämäärän sisältävän nimen. Vain vierastilan ulkopuolella (versiosta 1.5.4). |
deletetestevent?eventId=… | Poistaa API:n kautta luodun testitapahtuman – ei koskaan muita tapahtumia. Vain vierastilan ulkopuolella (versiosta 1.5.4). |
ping | Tarkistaa ilman salasanaa, toimiiko API. |
Jos Box ei vastaa 15 sekunnin kuluessa, takaisin tulee IsSuccessful: false ja selitys.
Istunnon aloittaminen mallilla, tyylillä ja taustalla
Versiosta 1.5.13 alkaen start ottaa valinnan suoraan mukaan – Box ohittaa silloin juuri nämä valintanäytöt:
vorlage=<Id>(taitemplate=) – malli, vain moodissaprint(kuva). Id:t saat komennollaauswahl?mode=print.stil=<Id>(taistyle=) – tekoälytyyli, vain moodissaai.hintergrund=<Id>(taibackground=) – rajauksen tausta, malliin sopiva.
Esimerkki: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=OMA-SALASANA
Tuntematon tai sopimaton Id ei käynnistä istuntoa: IsSuccessful on false, ja ErrorMessage kertoo syyn. Tietosuojasuostumuksen ja vieraiden tietolomakkeen Box näyttää edelleen itse – ne koskevat Boxin edessä olevaa vierasta, eikä niitä voi hoitaa etukäteen API:n kautta.
Lukitusnäyttö
Kohdassa Tapahtumat → Lukitusnäyttö (1.5.13 alkaen) määrität, mitä lukittu Box näyttää: oman tekstin, oman kuvan ja – aikaikkunan kanssa – suuren lähtölaskennan avautumiseen.
- Aikaikkuna tapahtumakohtaisesti: Asetuksilla Avautuu klo ja Sulkeutuu klo Box on lukittu ennen alkua ja lopun jälkeen.
- Avaus laitteella: Jos ylläpitäjän PIN on asetettu (Järjestelmä → Suojaus), lukitusnäytössä näkyy pieni lukko. PIN-koodin tietävä avaa Boxin. Ennen alkua avattuna se pysyy auki loppuun asti.
- Etänä: Hubissa kohdassa Kopit lukitset ja avaat jokaisen Boxin, joka sitä tukee (Studio 1.5.13 alkaen). Sama onnistuu BoothDock Stationin kautta ja komennoilla
lockscreen/show/lockscreen/exit.
Käynnissä olevaa istuntoa eivät keskeytä Hubin lukitus eikä aikaikkuna – Box lukittuu heti, kun vieras on valmis.
Reaaliaikainen vienti
Samalla välilehdellä: jokainen valmis tiedosto tallentuu heti Boxiin itseensä (Paikallinen kopio) – myös ilman Hubia, lajiteltuna tapahtuman ja tyypin mukaan (tulosteet, alkuperäiset, GIFit, videot – kunkin voi kytkeä pois erikseen). Tätä kopiota ei koskaan poisteta automaattisesti. Kohdassa USB-tikku / toinen kansio lisäät toisen kohteen: Kirjoita automaattisesti USB-tikulle kirjoittaa jokaiselle liitetylle tikulle, Täydennä puuttuvat tiedostot kirjoittaa jälkikäteen sen, mikä syntyi ilman tikkua. Vaihtoehtoisesti annat kohdan Kiinteä toinen kansio (etusijalla), esimerkiksi pilvikansion (OneDrive, Dropbox). Jos vieras poistaa istuntonsa Boxilla, myös kopiot poistuvat. iPadissa ja iPhonessa: Tiedostot-sovelluksessa kohdassa ”Omassa iPadissa › BoothDock Studio › Export”. BoothDock Studio 1.5.3:ssa ja vanhemmissa on sen sijaan vain Vientikansio.
Käynnistys kaukosäätimellä
Samalla välilehdellä opetat näppäimen kohdassa Käynnistys kaukosäätimellä. Esitysohjaimet, USB-painikkeet ja jalkakytkimet lähettävät yleensä välilyönnin; se on esiasetettu. Kohdassa Käynnistää valitset, mitä näppäin käynnistää aloitusnäytöllä: Kuin kosketus (tavallinen kulku) tai suoraan jokin moodi, esimerkiksi 360° alustalla. BoothDock Studio 1.4.0:ssa ja sitä vanhemmissa versioissa näppäin on käytettävissä vain 360°:lle, katso 360° / Hidastus.
Ongelmanratkaisu
- Mitään ei tapahdu: Näkyykö lokissa jotain? Webhookit kirjoittavat tiedostoon
webhooks.log(1.4.0:aan asti:ausloeser.log), API tiedostoonlokale-api.log– molemmat kansiossa%LocalAppData%\Boothdock Studio\logs(Windows). Hylätyt pyynnöt (väärä salasana, vieras laite) kirjataan sinne enintään kerran minuutissa. - „Invalid password." – kopioi salasana uudelleen; painikkeen Uusi salasana jälkeen vanha ei enää kelpaa.
- „The booth is not on the start screen …" –
starttoimii vain aloitusnäytöltä. Ensincancel, sittenstart. - „Too many failed attempts …" – laite on lähettänyt väärän salasanan liian monta kertaa. Odota 15 minuuttia ja tarkista salasana.
- Puhelin ei tavoita Boxia, tietokoneella kaikki toimii: lähes aina syynä on Windowsin palomuuri tai julkiseksi merkitty Wi-Fi-verkko – katso yllä. Tilarivi ilmoittaa molemmista tapauksista.