POST upload
Způsoby nahrání uživatelského programu do SDS přes web-POST
V současné době je implementace poskytnuta ve všech SDS Druhé Produktové Řady (BIG, STSW, SMALL, MBGW). Stejný protokol je k dispozici i v SDS První Produktové Řady - ale pouze pro řadu ST ! Podmínkou je mít v SDS instalován aktuální firmware.
Výchozí způsob nahrávání uživatelských řídících programů (SDSC, FULLC) a dalších prvků (UserWEB project) do SDS, je prováděn přes proprietární UDP protokol, skrze výrobcem dodávanou aplikaci (SDSC.exe, FULLC.exe, SDSLOAD.exe).
Toto řešení ale nelze vždy všude využít - část v prostředí kde je přísný firewall co zahazuje UDP komunikaci, nebo při konfiguraci SDS které jsou za neprostupným NATem. Důvodů může být mnoho.
Jako vhodnou a bezpečnou alternativu nabízí SDS možnost nahrání své konfigurace a řídících programů (a UserWeb projektu) prostřednictvím autorizovaného HTTP POST.
Často také chcete svým zákazníkům poskytnout vlastní GUI nebo jiné vlastní prostředky na ovládání SDS - zde je přesně ta možnost jak to otevřeně a bezpečně provést (další možnost pro ovládání je S-UDP protokol, viz jiná část této wiki).
Pozn. Speciální firmware pro BIG-512 bude poskytovat HTTPS POST - nicméně protokol API atd. uvnitř komunikace s webovém serverem v SDS bude stále zcela stejné..
Co se dá přes autorizovaný POST nahrát
1. [/changeip] změna konfigurace (IP atd.) 2. [/sv] FULL-C zápis do SharedVars - pouze SDS Druhé Produktové Řady ! 3. [/newsdsc] zápis nového SDSC programu - soubor .SCB - pouze SDS První Produktové Řady ! 4. [/newfullc] zápis nového FULLC programu - soubor .FCB - pouze SDS Druhé Produktové Řady ! 5. [/newuserweb] zápis nového UserWEB projektu - soubor .UWB 6. [/firmware] nahrání nového firmware pro SDS do paměti (a následná instalace) 7. [/share] SDS-C zápis do sys[140-149] nebo do share[] - pouze SDS První Produktové Řady ! 8. [/wrdf] zápis stránky do USER DATA-FLASH
Tyto prvky jsou vybrány tak, aby bylo také možné plně skriptovat "nahrávání" SDS, bez nutnosti uživatele použít GUI a ručně klikat atd.
Text v hranatých závorkách je příkaz, ten se musí zapsat za POST - tedy např. "POST /newfullc HTTP/1.1<cr><nl>" (první celý řádek hlavičky)
Pozn. Soubory .FCB (a .UWB) vygenerujete pomocí aplikaci FULLC.exe.
Soubor .SCB (a .UWB) pomocí aplikace SDSC.exe.
Zabezpečení
Dle průmyslového standardu, je vždy potřeba se, jako klient, vhodným způsobem autorizovat vůči serveru. Metoda také musí odpovídat průmyslovému standardu a být plně auditovatelná uživatelem (proto je i zde popsána). K dispozici jsou i vzorové příklady (např. aplikace se zdrojovým kódem).
SDS tedy vždy, pro každé jednotlivé spojení, vyžaduje novou unikátní autorizaci klienta.
Pro každé spojení SDS vygeneruje unikátní 256bit SALT, který není nikdy opakován (využívá se HW-RNG v SDS), a tento SALT je platný jen po dobu tohoto jednoho spojení (pro jeden příkaz).
Klient daný SALT přijme, provede s ním kryptografické operace (průmyslový standard saltování hesla: dvojitá SHA-256 operace).
Stejné operace provede i server u sebe, a jakmile klient pošle serveru svůj výsledek, server provede ověření (porovnání svého a zaslaného výsledku).
Pouze pokud klient zašle správný výsledek, znamená to, že klient zná identické heslo, jaké je nastaveno v SDS - a tedy může se pokračovat. Jinak je spojení ukončeno. Všechny pokusy jsou logovány.
Přenos na úrovni komunikace s webovým serverem není šifrován. Pokud je potřeba úplné šifrování, je využit TLS (nižší OSI7 vrstva) - pouze speciální firmware pro BIG-512.
Soubory .FCB (.SCB) a .UWB jsou zabezpečeny už při jejich vytvoření, takže jsou chráněny nejen při přenosu tímto protokolem, ale i v klidu např. na disku (zabezpečení je šifrováním a kontrolním podpisem detekujícím jakoukoliv změnu). Proto není potřeba je dodatečně při přenosu šifrovat (mimo eventuální TLS což ale genericky šifruje celý HTTP provoz, nicméně klient vždy odesílá soubory 1:1 tak jak je čte z disku - o tento detail mi teď šlo).
Detaily
Probíhat může vždy jen jedno spojení. Je to logické, pokud se nahrává program, nelze v prostředku nahrávání začít posílat jiný (musí se počkat až se původní činnost dokončí).
V takovém případě server informuje klienty v nových spojení že je BUSY a spojení uzavře. Je na klientovi počkat a zkusit znovu (za vhodný čas).
Protokol
Jedná se o standardní komunikaci s webovým serverem, kde je implementován specifický příkazový ping-pong. Na straně klienta ji lze realizovat libovolným způsobem, buď nějakou vaší knihovnou, nebo klidně prostřednictvím vlastního lowlevel kódu nad TCP socketem... důležité je dodržet dále popsanou specifikaci komunikace.
Klient otevře spojení, pošle HTTP hlavičku s POST (a příkazem), a pak provede autorizaci, a (pokud je autorizován) tak provede kroky k nahrání programu či aktualizaci konfigurace.
HTTP POST
client <-> server
-----------------------------------------------------------------------------------------------------------------------------------
[1] open TCP connection to HTTP server | <accept>
|
-+-
[2] send POST header + command name in URI |
|
POST /command HTTP/1.1<cr><nl> |
Host: 192.168.4.250<cr><nl> |
Content-Length: 12<cr><nl> | Content-Length: raw file data size --- see note later !
<cr><nl> |
NoncePlease<cr><nl> |
|
-+-
| [3] response from server
|
| Nonce:HEXSTRING(32B)<cr><nl>
|
| or
|
| Busy:CLOSING<cr><nl>
| -> and closes the connection
|
-+-
[4] compute SHA-256 HASHes for SALTED-PWD | compute SHA-256 HASHes for SALTED-PWD
|
-+-
[5] send hash result to server |
|
Auth:SHA-256:HEXSTRING(32B)<cr><nl> |
|
-+-
| [6] response from server
|
| Auth:REJECTED<cr><nl>
| -> and closes the connection
|
| or
|
| Auth:CONTINUE<cr><nl>
|
-+-
[7] if Auth:CONTINUE, |
then |
client sends: |
START:START<cr><nl> |
|
-+-
| [8] server starts its internal process,
|
| *(a) for "newsdsc", "newfullc", "newuserweb", "firmware" commands,
| memory erase (this takes up to 45 seconds !) and client has to wait;
| once done, server sends:
|
| Erased:ReadyToWrite<cr><nl>
|
| or (for any error during the memory erase, or in presented data so far)
|
| Deny:UnableToEraseOrWrongContentLen<cr><nl>
| -> and closes the connection
|
| *(b) for the "changeip" and "sv" commands,
| server sends this:
|
| Status:ReadyToWrite<cr><nl>
|
| or (for any error in presented data so far)
|
| Deny:UnableToEraseOrWrongContentLen<cr><nl>
| -> and closes the connection
|
-+-
[9] only if the client gets the |
"Erased:ReadyToWrite" response |
(where required), |
or the "Status:ReadyToWrite" response; |
the client shall then send all |
the binary data |
|
client sends: raw binary data, do not encode | ... server receives all the data, and writes it to memory as it comes
| (server accepts binary data of size that equals to the Content-Length value)
note. Content-Length -> |
exact size of 'raw binary data' |
(do not include length of any data |
of the protocol itself) |
|
-+-
| [10] once all data are received (or during the transfer on any error), server sends:
|
| Done:result<cr><nl> -> and close connection
|
| or - (only specifically) for any mismatching data
| (again, this could happen any time during the trasnfer):
|
| Error:Rejected
|
|
----------
notes.
HEXSTRING(32B) = 64 characters, HEX16 encoded (each byte = 2 chars), fmt: 32 x "%02X" , no spaces , always uppercase
Done:result -> 'result' is textual printout of a uint32_t number
0 = OK
1..n = ERROR
Vzorový záchyt
Pro tento příklad, Heslo je nastaveno na tyto čtyři písmena:
test
Příkaz je:
/newfullc
Záchyt příkladu komunikace (wiresharkem): [C] = data od klienta, [S] = data ze serveru
[C] POST /newfullc HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Type: application/octet-stream [C] Content-Length: 2048 [C] [C] NoncePlease [S] Nonce:C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C [C] Auth:SHA-256:94419346948EC5D826E7D2AE0CF4F12CFE84EE29A37CBC48A68D3301EAD5865C [S] Auth:CONTINUE [C] START:START [S] Erased:ReadyToWrite [C] *******FCB-file-contents-1:1-sent-here---example-size:2048B******* [S] Done:0
Respektive jako hexdump z wiresharku (pro přehlednost jen do momentu kdy se začne odesílat .FCB z klienta na server):
00000000 50 4f 53 54 20 2f 6e 65 77 66 75 6c 6c 63 20 48 POST /ne wfullc H 00000010 54 54 50 2f 31 2e 31 0d 0a 48 6f 73 74 3a 20 31 TTP/1.1. .Host: 1 00000020 39 32 2e 31 36 38 2e 34 2e 32 35 30 0d 0a 43 6f 92.168.4 .250..Co 00000030 6e 6e 65 63 74 69 6f 6e 3a 20 6b 65 65 70 2d 61 nnection : keep-a 00000040 6c 69 76 65 0d 0a 43 6f 6e 74 65 6e 74 2d 54 79 live..Co ntent-Ty 00000050 70 65 3a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2f pe: appl ication/ 00000060 6f 63 74 65 74 2d 73 74 72 65 61 6d 0d 0a 43 6f octet-st ream..Co 00000070 6e 74 65 6e 74 2d 4c 65 6e 67 74 68 3a 20 32 30 ntent-Le ngth: 20 00000080 34 38 0d 0a 0d 0a 4e 6f 6e 63 65 50 6c 65 61 73 48....No ncePleas 00000090 65 0d 0a e.. 00000000 4e 6f 6e 63 65 3a 43 35 42 32 44 39 38 30 38 31 Nonce:C5 B2D98081 00000010 46 45 36 34 39 39 45 35 41 41 43 44 45 37 35 38 FE6499E5 AACDE758 00000020 35 42 46 36 46 35 34 35 45 31 33 36 32 42 42 44 5BF6F545 E1362BBD 00000030 31 42 34 41 35 45 34 39 33 34 36 30 37 38 36 36 1B4A5E49 34607866 00000040 37 44 38 39 38 43 0d 0a 7D898C.. 00000093 41 75 74 68 3a 53 48 41 2d 32 35 36 3a 39 34 34 Auth:SHA -256:944 000000A3 31 39 33 34 36 39 34 38 45 43 35 44 38 32 36 45 19346948 EC5D826E 000000B3 37 44 32 41 45 30 43 46 34 46 31 32 43 46 45 38 7D2AE0CF 4F12CFE8 000000C3 34 45 45 32 39 41 33 37 43 42 43 34 38 41 36 38 4EE29A37 CBC48A68 000000D3 44 33 33 30 31 45 41 44 35 38 36 35 43 0d 0a D3301EAD 5865C.. 00000048 41 75 74 68 3a 43 4f 4e 54 49 4e 55 45 0d 0a Auth:CON TINUE.. 000000E2 53 54 41 52 54 3a 53 54 41 52 54 0d 0a START:ST ART.. 00000057 45 72 61 73 65 64 3a 52 65 61 64 79 54 6f 57 72 Erased:R eadyToWr 00000067 69 74 65 0d 0a ite.. ... klient teď odesílá obsah .FCB, o velikosti 2048B viz Content-Length... 0000006C 44 6f 6e 65 3a 30 0d 0a Done:0..
Autorizační mechanismus
Základní popis:
HASH FUNCTION:
Nonce -> unqiue 32 bytes (represented as 64char hexstring) originated on server
(an always-random number, tied to each single TCP connection only - once closed, Nonce is invalid)
(new nonce is generated for every each new connection)
SHA-256 HASH result -> process:
1. Calculate SHA-256 hash of 'password' -> resultA[32]
2. Convert resultA[32] to a 64 character string -> textHashP[64]
3. Take 'salt' as 64 character string (exactly as it come) -> textSalt[64]
4. Concatenate textHashP with textSalt -> forHash[128]
5. Calculate SHA-256 hash of string forHash[64] -> resultH[32]
6. Convert resultH[32] to 64 character string -> transmitH[64]
7. Send transmitH[64] to server
Server and client does the same exact process, and if transmitH[64] is equal on both sides, server allows the client to continue
Doporučuji podívat se na zdrojové kódy příkladů, uvidíte sami jak jednoduchá a přímočará je implementace.
Proč se používá dvojitý hash ? Protože vám to umožní neukládat surové heslo ve vašem skriptu/programu, ale jen jeho hash. Tím se zabrání prozrazení čistého hesla při eventuálním úniku skriptu či programu. Ale tato realizace je už na vás.
Ukázky autorizace
Pro tento příklad, Heslo je nastaveno na tyto čtyři písmena:
test
Server poslal tento SALT (tedy obsah textSalt[64])
C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
textHashP[64]
9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08
textSalt[64]
C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
forHash[128]
9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08C5B2D98081FE6499E5AACDE7585BF6F545E1362BBD1B4A5E49346078667D898C
transmitH[64]
94419346948EC5D826E7D2AE0CF4F12CFE84EE29A37CBC48A68D3301EAD5865C
Tento příklad můžete použít jako referenci při odlaďování vaší implementace.
Vzorová aplikace
Kontaktujte nás pro zaslání vzorové aplikace ve formě zdrojových kódů projektu (aktuálně dostupné pro Delphi), nebo přeložené spustitelné aplikace (Win32 exe).
Vzorová aplikace má tu výhodu že je odzkoušena, můžete z ní přebrat části zdrojového kódu do své nové vlastní aplikace, a také tato vzorová aplikace zobrazuje všechny postupné kroky při komunikace se SDS, takže to můžete využít jako referenci při debugu vašeho kódu.
COMMAND: /changeip
Určeno k provedení změny konfigurace IP adres a dalších prvků, vše v jednom kroku.
Jedno volání tohoto příkazu provede hromadnou společnou změnu vámi určených položek. Položky se zapíší za sebe, vždy ve formátu "název:hodnota", každá položka je vždy zakončena <cr><nl> kombinací (klasické dva znaky).
Položky: SystPwd:text = systémové heslo HostIP:ipaddr = ip adresa zařízení SDS | (restart) NetMask:ipaddr = síťová maska | (restart) GwyIP:ipaddr = ip adresa brány | (restart) DNSIP:ipaddr = ip adresa DNS serveru | (restart) WebPort:number = TCP port pro webové rozhraní | (restart) SUDPport:number = UDP port pro SUDP protokol | (restart) UseDHCP:number = použít DHCP (1=broadcast, 4=unicast), nebo statickou ip (nastav 0) | (restart) DNSfromDHCP:flag = DNS ip adresa z DHCP nebo statická | (restart) NTPIP:ipaddr = ip adresa NTP serveru NTPofs:number = pevný GMT offset (-11 až +11 hodin) NTPuseDST:flag = daylight saving SNMPwrite:flag = povolit SNMP write SNMPread:flag = povolit SNMP read SNMPcomm:text = název SNMP komunity WebSDCnolog:flag = povolit přístup na obsah SDC přes webové rozhraní bez nutnosti se přihlásit AutoLogoff:flag = automatic user logoff SysLoc:text = system location kde: text = text ipaddr = a.b.c.d flag = 1 / 0
POZOR
- Změna nastavení prvků kolem IP adresy - označené v seznamu jako (restart), způsobí reboot zařízení (až po odeslání odpovědi o provedení požadované změny) - počítejte s tím !
Zde je uveden náhodný příklad změny několika různých prvků, může to vypadat např. takto:
HostIP:192.168.1.250<cr><nl> NetMask:255.255.255.0<cr><nl> GwyIP:192.168.1.1<cr><nl> DNSIP:192.168.1.1<cr><nl> WebPort:80<cr><nl> UseDHCP:0<cr><nl>
Jak lze vidět, změnu konfigurace lze provést hromadně pro více různých prvků - je na vás, jak to zkombinujete.
Komunikace se serverem v SDS pak, pro tento specifický příklad, vypadá takto:
[C] POST /changeip HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Length: 116 [C] [C] NoncePlease [S] Nonce:...text... [C] Auth:SHA-256:...text... [S] Auth:CONTINUE [C] START:START [S] Status:ReadyToWrite [C] HostIP:192.168.1.250 [C] NetMask:255.255.255.0 [C] GwyIP:192.168.1.1 [C] DNSIP:192.168.1.1 [C] WebPort:80 [C] UseDHCP:0 [S] Done:0
Pozor: změna potvrzená serverem (tzn. "Done:0") se provede okamžitě. Pokud si tedy změníte např. HostIP, nebo heslo atd., tak pro další komunikaci se zařízením SDS už musíte použít tyto nové hodnoty.
Pokud zapíšete nesprávnou konfiguraci, tedy takovou která má platný formát (např. formát IP adresy a.b.c.d), ale nesprávný obsah (např. omylem špatnou IP adresu), tak to SDS samozřejmě použije (protože to po něm chcete!), ale se všemi důsledky pro vás (např. se na zařízení pak "nedostanete"). Zde pomůže už jenom fyzický zásah, a to použít RSTD proceduru pro návrat do továrního nastavení.
Done:X 0 = všechny položky OK a zapsány 1 = jen některé přijaté položky byly OK a některé neplatné (tzn. provedeno "jen něco" dle platnosti) 2 = všechny položky byly neplatné (tzn. nic nezapsáno)
Dbejte důraz na návratovou hodnotu Done:X !
POZOR pro tento příkaz je aktivní omezení na hodnotu Content-Length, která je maximálně 512. Pokud budou zaslána data o velikosti větší než 512 znaků (<cr><nl> je samozřejmě započítáno), tak budou všechna data nad 512 znaků IGNOROVÁNA (zahozena) - zařízení SDS zpracuje pouze prvních až 512 příchozích bajtů datového obsahu, více ne.
COMMAND: /sv
Určeno k zápisu do sdílených proměnných programu FULL-C. Pro zařízení s SDS-C použijte jiný příkaz, viz dole..
Zápis je v textové formě, formou položek. Každá položka má jednotný formát "název:hodnota" a vždy je zakončena <cr><nl> kombinací (klasické dva znaky).
Zapisovatelné názvy jsou určeny specifikací rozhraní pro jazyk FULL-C (tedy "S00" až "S99" atd.).
Příklad:
U10:1234<cr><nl> F29:15.256<cr><nl> T99:Some text in here.<cr><nl> S69:-654321<cr><nl>
Komunikace se serverem v SDS pak, pro tento specifický příklad, vypadá takto:
[C] POST /sv HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Length: 65 [C] [C] NoncePlease [S] Nonce:...text... [C] Auth:SHA-256:...text... [S] Auth:CONTINUE [C] START:START [S] Status:ReadyToWrite [C] U10:1234 [C] F29:15.256 [C] T99:Some text in here. [C] S69:-654321 [S] Done:0
Zápis do sdílených proměnných je prováděn postupně, tak jak data přicházejí z klienta na server. Pokud je některá položka neplatná, je ignorována - ale všechny ostatní platné jsou zapsány (i v případě že tam je jedna nebo více jiných neplatných).
Done:X 0 = všechny položky OK a zapsány 1 = jen některé přijaté položky byly OK a některé neplatné (tzn. provedeno "jen něco" dle platnosti) 2 = všechny položky byly neplatné (tzn. nic nezapsáno)
POZOR pro tento příkaz je aktivní omezení na hodnotu Content-Length, která je maximálně 512. Pokud budou zaslána data o velikosti větší než 512 znaků (<cr><nl> je samozřejmě započítáno), tak budou všechna data nad 512 znaků IGNOROVÁNA (zahozena) - zařízení SDS zpracuje pouze prvních až 512 příchozích bajtů datového obsahu, více ne.
COMMAND: /newsdsc
Využito pro nahrání nového SDSC programu - ten je k dispozici formou obsahu .SCB souboru (tento soubor si vytvoříte ve SDSC.exe z vašeho zdrojového SDS-C programu).
Hodnoty Done:X --------------- 0 = vše OK, nový program je v paměti SDS a je ihned spuštěn 1 = chyba při nahrávání (ukládání) do paměti - SDS je bez programu, žádný program není spuštěn (nahrejte nový správně)
Velikost předávaného souboru, tedy Content-Length, je omezena dle typu SDS - pozor, SDSC.exe interně velikost výstupního souboru .SCB nijak neomezuje ! Modul SDS odmítne nahrát soubor, který se nevleze do instalované paměti.
COMMAND: /newfullc
Využito pro nahrání nového FULLC programu - ten je k dispozici formou obsahu .FCB souboru (tento soubor si vytvoříte ve FULLC.exe z vašeho zdrojového FULLC programu).
Hodnoty Done:X --------------- 0 = vše OK, nový program je v paměti SDS a je ihned spuštěn 1 = chyba při nahrávání (ukládání) do paměti - SDS je bez programu, žádný program není spuštěn (nahrejte nový správně)
Velikost předávaného souboru, tedy Content-Length, je omezena dle typu SDS. Například pro BIG-512 je omezení na 512kB atd.
COMMAND: /newuserweb
Využito pro nahrání nového UserWeb projektu - ten je k dispozici formou obsahu .UWB souboru (tento soubor si vytvoříte ve FULLC.exe dle standardního postupu pro sestavení UserWeb projektu).
Hodnoty Done:X --------------- 0 = vše OK, nový UserWeb je v paměti SDS 1 = chyba při nahrávání (ukládání) do paměti - SDS je bez UserWeb (nahrejte nový správně)
Velikost předávaného souboru, tedy Content-Length, je omezena dle typu SDS, specifické maximální velikosti pro UserWeb projektový soubor jsou uvedeny v popisu jednotlivých variant SDS.
COMMAND: /firmware
Využito pro nahrání nového firmware pro SDS.
Nahrát lze pouze odpovídající BIN soubor, vydaný výrobcem SDS.
Vzor očekávané komunikace (když je vše v pořádku):
[C] POST /firmware HTTP/1.1
[C] Host: 192.168.4.250
[C] Content-Type: application/octet-stream
[C] Content-Length: 424548
[C]
[C] NoncePlease
[S] Nonce:...text...
[C] Auth:SHA-256:...text...
[S] Auth:CONTINUE
[C] START:START
... SDS now erases the NVM memory block, this takes up to 45 seconds ...
[S] Erased:ReadyToWrite
[C] *******BIN-file-contents-1:1-sent-here---example-size:424548 bytes*******
[S] Done:0
Pokud nahrání proběhne jak má (včetně ihned následujícího ověření, uvnitŘ SDS, že nahraná data jsou platným firmware pro dané SDS), dojde k resetu zařízení SDS a instalaci tohoto nového firmware. Instalace se spustí okamžite po dokončení nahrávání (po odeslání "Done:0") - toto je potřeba vědět (např. pokud v SDS běží váš FULLC program, tak budu po dobu instalace vypnut, stejně tak jako např. všechny výstupy !!!).
Hodnoty Done:X --------------- 0 = vše OK, firmware nahrán do NVM a bude z ní obratem ihned instalován do SDS 1 = chyba při nahrávání (ukládání) do NVM - instalace nebude provedena 2 = jiná chyba - instalace nebude provedena
Zde je vzor komunikace - když je zasílaný soubor s firmware odmítnut (např. pošlete firmware který do daného typu SDS nepatří, tzn. firmware pro jiný typ SDS):
... (all same as previous example) [S] Erased:ReadyToWrite [C] *******BIN-file-contents-1:1-sent-here---example-size:424548 bytes******* [S] Error:Rejected
Všimněte si že místo "Done:X" je posláno "Error:Rejected" (a server ukončí spojení), a to obvykle hned po zaslání cca prvních dat z (nevhodného) bin souboru.
Upozornění: firmware lze nahrát buď přes původní UDP protokol (přes výrobcem dodanou aplikaci), nebo přes zde popsaný HTTP POST. Obě metody lze použit, ale jsou časově výlučné. Pokud zahájíte přenos přes HTTP POST, bude metoda přes UDP zablokována (až do dokončení přenosu přes HTTP POST), a naopak (pokud zahájíte přenos přes UDP, bude HTTP POST zablokován až do dokončení tohoto přenosu). V takovém případě (když už probíhá nahrávání přes UDP) vás server při požadavku odmítne pomocí "Busy:CLOSING".
Informace: nahrání nového firmware přes HTTP POST lze aktivovat kdykoliv, podmínkou je samozřejmě autorizace na začátku spojení. Naopak nahrání přes UDP protokol je potřeba nejprve aktivovat ve webovém rozhraní SDS. V případě, že už přenos firmware přes HTTP POST probíhá, bude aktivace odmítnuta chybovou hláškou na webu.
Velikost předávaného souboru, tedy Content-Length, je omezena dle typu SDS. Typicky je pro tento příkaz maximum 2 MB.
Určeno k zápisu do sdílených proměnných programu SDS-C. Pro zařízení s FULL-C použijte jiný příkaz, viz výše..
Zápis je v textové formě, formou položek. Každá položka má jednotný formát "název:hodnota" a vždy je zakončena <cr><nl> kombinací (klasické dva znaky).
Zapisovatelné názvy jsou určeny specifikací rozhraní pro jazyk SDS-C.
Zápis číselné hodnoty do sdíleného prostoru v sys[]:
I140:hodnota -> zapíše 'hodnota'do sys[140] ... I149:hodnota -> zapíše 'hodnota'do sys[149]
Zápis textového řetězce do sdíleného prostoru ve share[]:
S000:text -> zapíše 'text' do pole share na pozici 0 (a dále dle délky)
...
S054:text -> zapíše 'text' do pole share na pozici 54 (a dále dle délky)
...
S122:text -> zapíše 'text' do pole share na pozici 122 (a dále dle délky)
...
S255:text -> zapíše oříznutý 'text' do pole share na pozici 255 (nelze překročit délku pole share).
(pozor, různé SDS mají různou délku pole share[], vždy se informujte kolik se do pole skutečně "vleze").
Příklad (sys[140] zapsat hodnotu 12, sys[145] zapsat hodnotu 34, a do share[] od pozice 123 zapíšeme 'something'):
I140:12<cr><nl> I145:34<cr><nl> S123:something<cr><nl>
Komunikace se serverem v SDS pak, pro tento specifický příklad, vypadá takto:
[C] POST /share HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Length: 28 [C] [C] NoncePlease [S] Nonce:...text... [C] Auth:SHA-256:...text... [S] Auth:CONTINUE [C] START:START [S] Status:ReadyToWrite [C] I140:12 [C] I145:34 [C] S123:something [S] Done:0
Zápis do sdílených proměnných je prováděn postupně, tak jak data přicházejí z klienta na server. Pokud je některá položka neplatná, je ignorována - ale všechny ostatní platné jsou zapsány (i v případě že tam je jedna nebo více jiných neplatných).
Done:X 0 = všechny položky OK a zapsány 1 = jen některé přijaté položky byly OK a některé neplatné (tzn. provedeno "jen něco" dle platnosti) 2 = všechny položky byly neplatné (tzn. nic nezapsáno)
POZOR pro tento příkaz je aktivní omezení na hodnotu Content-Length, která je maximálně 512. Pokud budou zaslána data o velikosti větší než 512 znaků (<cr><nl> je samozřejmě započítáno), tak budou všechna data nad 512 znaků IGNOROVÁNA (zahozena) - zařízení SDS zpracuje pouze prvních až 512 příchozích bajtů datového obsahu, více ne.
COMMAND: /wrdf
Určeno k zápisu celé jedné stránky (tzn. 264B) do uživatelského prostoru v Data-Flash (DF). Číslo stránky určuje klient, spolu se zapisovanými daty.
Tento příkaz je implementován teprve v novějších verzích FW (od 02/2023+). Firmware, který nemá tento příkaz implementován, odpovídá "Deny:NOT-IMPLEMENTED-YET".
Uživatel vždy zasílá data o velikost 4 + N bajtů, kde N je 1 až 264 (maximum je 264 bajtů, což je plná velikost jedné stránky v DF). První 4 bajty určují číslo stránky (litte-endian unsigned 32bit), a ihned za tím následuje 1 až 264 bajtů jednotlivých dat pro zápis přímo do vybrané stránky v DF.
Zápis do celé stránky tak má délku dat 4 + 264 = 268 .
Číslo stránky je od 0 (= úplně první uživatelská stránka) až po maximum (např. 255 pro SDS-BIG). Číslo stránky přesně odpovídá číslům, kterým se k uživatelským stránkám přistupuje přes SDS-C respektive FULL-C funkce.
Komunikace se serverem v SDS pak, pro tento specifický příklad, vypadá takto:
[C] POST /wrdf HTTP/1.1 [C] Host: 192.168.4.250 [C] Content-Length: 268 [C] [C] NoncePlease [S] Nonce:...text... [C] Auth:SHA-256:...text... [S] Auth:CONTINUE [C] START:START [S] Status:ReadyToWrite [C] ...data... [S] Done:0
Zápis do DF je proveden ihned po obdržení všech dat, a výsledek (nebo chyba) je vrácena v položce Done:X.
Done:X 0 = do příslušné stránky v DF byl úspěšně proveden zápis 1 = nedostatečná délka zaslaných dat (minimum je: 4 + 1 B) = nic nezapsáno 2 = požadavek na zápis do DF do stránky, do které není přístup (= špatné číslo stránky) = nic nezapsáno 4 = nepovedlo se provést zápis do DF (chyba DF)
Pokud pošlete méně než 264 bajtů v rámci obsahu stránky (tedy ne úplnou stránku), je zápis proveden i v takovém případě, ale chybějící data jsou automaticky doplněna do celé velikosti (264B) hodnotou 0xFF. Vybraná stránka v DF je tedy v každém případě přepsána celá !