Galerie | Dokumentace | Ratatoskr IoT toolkit

K čemu to je?

Máte nějaký zdroj fotek – webovou kameru, mikrokontrolér ESP32 s kamerou, Raspberry Pi, … – a chcete fotky z něj snadno zobrazit v galerii na internetu? Přes jednoduché HTTP POST API můžete posílat fotky do galerie. K zařízení nemusí být přístup z internetu – komunikace je jen ve směru ze zařízení na server.

Galerie se ukazuje jako přehledná webová stránka, která se automaticky sama překresluje každých pět minut. V galerii můžete označovat nejlepší fotky a ty se pak ukážou ve speciální galerii s výběrem nejlepších. Přístup ke galerii může být jen pro vás (po přihlášení), nebo může galerii vidět kdokoli, komu pošlete správný odkaz.

Chcete fotky z galerie zobrazovat na displeji mikrokontroléru? Přes jednoduché HTTP GET API si může mikrokontrolér stahovat poslední nebo náhodnou fotku z galerie – a může si říct, v jakém rozlišení a v jaké maximální velikosti jí chce dostat, aby se vešla na displej i do paměti. Stejně tak tuto funkci můžete použít pro Živý obraz.

Jak galerie vypadá?

Po otevření adresy galerie se ukáže seznam obrázků. Pokud je přihlášený vlastník, má u každého možnost mazání (ikona koše). Ikonou hvězdičky je možné označit fotku pro výběr nejlepších nebo označení odebrat.

Po kliknutí na obrázek se ukáže zvětšený; kliknutím na ikony na okrajích je možné přecházet na předešlou/následující fotku, stejně tak je možné stránkovat šipkami vlevo/vpravo na klávesnici.

Jak dostat fotky do galerie?

V detailu galerie je položka Token pro API. Kód, který je v ní uveden, je potřeba pro posílání obrázků na server pomocí API.

HTTP POST API

HTTP rozhraní pro nahrávání obrázků je na adrese

https://ratatoskr.lovecka.info/app/api/image?name=jmeno_souboru.jpg

Pokud budete obrázky nahrávat z ESP32, šetříte každý takt procesoru a nezáleží vám na bezpečnosti, můžete ušetřit cca sekundu, kterou trvá navázání TLS spojení, a použít prosté http.

http://ratatoskr.lovecka.info/app/api/image?name=jmeno_souboru.jpg

V parametru name se zadává jméno souboru (či prostě jen popis) zobrazované v galerii. Jméno musí být url-encodované (tj. místo mezery +, divné znaky jako %hexa).

Každý požadavek musí obsahovat zabezpečovací token. Buď přímo v adrese za /image/ , tj. takto:

https://ratatoskr.lovecka.info/app/api/image/v3QgCi7mFqzBufZ82TFIeZTbdbHJzATC9Hdu0PIzsmUqKYAfhi7mmJzROxTszXrjlduT7gzQ4?name=jmeno_souboru.jpg

nebo v hlavičce X-Auth (doporučená metoda).

Pokud požadavek obsahuje hlavičku X-Hash, porovná se její obsah se SHA256 hashem obsahu nahraného souboru. Pokud se soubor při přenosu poškodí (což se zejména u ESP32 stává), hash nebude souhlasit a obrázek bude na serveru zahozen. Hash se zapisuje lowercase.

Z příkazové řádky (curl)

Pokud si představíme, že v aktuálním adresáři máme soubor img6.jpg, tak jeho nahrání na server uděláme následujícím příkazem curl:

curl -H "Content-type: image/jpeg" -H "X-Auth: v3QgCi7mFqzBufZ82TFIeZTbdbHJzATC9Hdu0PIzsmUqKYAfhi7mmJzROxTszXrjlduT7gzQ4" --data-binary @img6.jpg https://ratatoskr.lovecka.info/app/api/image?name=camera.jpg

Pokud známe i jeho hash, můžeme ho tam přidat:

curl -H "Content-type: image/jpeg" -H "X-Auth: v3QgCi7mFqzBufZ82TFIeZTbdbHJzATC9Hdu0PIzsmUqKYAfhi7mmJzROxTszXrjlduT7gzQ4" -H "X-Hash: 3bc1d20891915bce6f92d43819fb6b63e3bd85ea569a5d190d3d497543841113" --data-binary @img6.jpg https://ratatoskr.lovecka.info/app/api/image?name=camera.jpg

Z webové kamery (RTSP)

Pokud máte v síti IP kameru, která podává data protokolem RTSP, můžete si udělat jednoduchý skript, který stáhne jeden snímek z kamery a nahraje ho do galerie. URL pro RTSP rozhraní vaší kamery najdete v dokumentaci; níže ho upravte na řádku začínajícím URL=.

#!/bin/bash
URL="rtsp://jmeno:heslo@192.168.12.13:554/cam/realmonitor?channel=1&subtype=0"
FILE=snapshot.jpg
rm $FILE
ffmpeg -y -rtsp_transport tcp  -timelimit 10  -i $URL  -frames:v 1  $FILE
# tady mame soubor snapshot.jpg stazeny ze streamu
if [ -f $FILE ]; then
  curl -H "Content-type: image/jpeg" -H "X-Auth: v3QgCi7mFqzBufZ82TFIeZTbdbHJzATC9Hdu0PIzsmUqKYAfhi7mmJzROxTszXrjlduT7gzQ4" --data-binary @$FILE https://ratatoskr.lovecka.info/app/api/image?name=camera.jpg
else
  echo "File $FILE does not exist."
fi

Aplikace pro ESP32

Na adrese https://github.com/…32Cam-Simple najdete hotovou aplikaci pro ESP32-CAM, ESP32S3-CAM (a potenciálně i další desky). Tato aplikace periodicky pořizuje fotky a nahrává je do galerie. Vlastní obsluha komunikace se serverem je v src/net/ImageSender.h.

Z administrace aplikace

Ve stránce s nastavením galerie je dole tlačítko Nahrát obrázek. To asi nebude složité použít.

API pro načtení obrázku z galerie

K čemu to je? Můžete mít vlastní mikrokontrolér s displejem, a na něm chcete zobrazovat obrázky z galerie. Stejně tak můžete tímto způsobem použít obrázky z galerie v Živém obraze – zvolte v něm „galerie“ a v jejím nastavení zvolte „z URL“ a nastavte URL dle popisu dále.

V nastavení galerie jsou vypsané cesty ke galerii:

Tyhle dvě URL budeme následně používat.

Nejnovější fotka

Pokud změníte cestu v URL z /gallery/main/ na /gallery/latest/, dostanete poslední obrázek přidaný do galerie.

https://ratatoskr.lovecka.info/app/gallery/latest/4/VerejnyTest

Můžete přidat parametry w a h s maximálním rozměrem obrázku horizontálně a vertikálně. Bude vám vrácen obrázek v maximálně dané velikosti.

https://ratatoskr.lovecka.info/app/gallery/latest/4/VerejnyTest?w=640&h=480

Pokud máte omezenou paměť na uložení obrázku, můžete přidat parametr maxSize s maximální velikostí obrázku v byte. Aplikace se pokusí zvýšit kompresi tak, aby se obrázek vešel do dané velikosti. Parametr maxSize se vyhodnocuje jen tehdy, pokud je zároveň zadán maximální rozměr obrázku.

https://ratatoskr.lovecka.info/app/gallery/latest/4/VerejnyTest?w=640&h=480&maxSize=50000

Náhodná fotka

Pokud změníte cestu v URL z /gallery/main/ na /gallery/random/, dostanete poslední obrázek přidaný do galerie.

https://ratatoskr.lovecka.info/app/gallery/random/4/VerejnyTest

Stejně jako u /gallery/latest/ můžete přidat parametry w a h a maxSize.

https://ratatoskr.lovecka.info/app/gallery/random/4/VerejnyTest?w=640&h=480
https://ratatoskr.lovecka.info/app/gallery/random/4/VerejnyTest?w=640&h=480&maxSize=50000

Limity a omezení (FUP)

V tento okamžik platí pro běžné uživatele následující limity:

Maximální počet obrázků v jedné galerii: 100
K tomu navíc maximálně obrázků s hvězdičkou v jedné galerii: 30
Maximální počet obrázků uživatele (přes všechny galerie): 400

Pokud potřebujete více, napište mi.

Předpokládá se, že nahráváte obrázky v rozumném tempu, řekněme maximálně jeden za minutu. Při přetěžování serveru budou podniknuty odpovídající kroky.

Galerie obrázků