← Kaikki artikkelit

BoothDock · Wiki

Webhookit ja API

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ä.

Järjestelmä → Automaatio: reaaliaikainen vienti, webhookit ja paikallinen API
Järjestelmä → Automaatio: reaaliaikainen vienti, webhookit ja paikallinen API

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, .bat tai .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) – http tai https, kutsutaan GET-pyynnöllä: https://oma-palvelin/hook?event_type=<tapahtuma>&param1=…&param2=…. 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

TapahtumaMilloinParametrit
session_startVieras aloittaa istunnon, moodi on valittu1: moodi (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock-moodi (photo, gif, boomerang, video, slowmo, ai)
countdown_startLähtölaskenta alkaa1: sekunnit
countdownLähtölaskennan jokainen sekunti1: edistyminen prosentteina (alkaen 0:sta)
capture_startLähtölaskenta on päättynyt, kuvaus alkaa–
file_downloadKamera on tallentanut kuvan1: tiedostonimi, 2: koko polku
processing_startKäsittely alkaajokaisesta kameran alkuperäisestä yksi tiedostonimi, viimeisenä arvona tulostustiedosto (tällä hetkellä tyhjä)
sharing_screenTulosnäyttö tulee esiin (kerran istuntoa kohden)–
printingArkki lähtee tulostimelle1: tiedosto (tällä hetkellä tyhjä), 2: kopiot, 3: tulostin
file_uploadTiedosto on saapunut Hubiin (tiedostokohtaisesti)1: polku Boxilla, 2: gallerialinkki, 3: tyyppi (print, photo, original, animation, boomerang, video), 4: albumi (tapahtuman nimi)
lead_submittedVieras on lähettänyt lomakkeen Vierastiedot (lomake) (versiosta 1.5.0)– (itse vastaukset ovat vain CSV-viennissä)
session_endIstunto 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> (tai 127.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=…, otsakkeena X-Api-Password tai muodossa Authorization: Bearer …. Vain ping toimii 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än Data.

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

KomentoVaikutus
start?mode=printAloittaa 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=printPalauttaa 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).
cancelKeskeyttää käynnissä olevan istunnon ja palaa aloitusnäyttöön.
statusPalauttaa 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=1Tulostaa viimeisimmän tuloksen uudelleen (1–10 arkkia). Videoita ei voi tulostaa.
lockscreen/showLukitsee 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/exitPoistaa 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/smsEi 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).
pingTarkistaa 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> (tai template=) – malli, vain moodissa print (kuva). Id:t saat komennolla auswahl?mode=print.
  • stil=<Id> (tai style=) – tekoälytyyli, vain moodissa ai.
  • hintergrund=<Id> (tai background=) – 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 tiedostoon lokale-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 …" – start toimii vain aloitusnäytöltä. Ensin cancel, sitten start.
  • „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.

Seuraavat vaiheet