Zobrazení zdroje stránky POST upload

== Způsoby nahrání uživatelského programu do SDS přes web-POST ==
__NOTOC__

 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. 

[[SDS-C: SCB|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 
  NetMask:ipaddr        = síťová maska
  GwyIP:ipaddr          = ip adresa brány
  DNSIP:ipaddr          = ip adresa DNS serveru
  WebPort:number        = TCP port pro webové rozhraní
  SUDPport:number       = UDP port pro SUDP protokol
  UseDHCP:number        = použít DHCP (1=broadcast, 4=unicast), nebo statickou ip (nastav 0)
  DNSfromDHCP:flag      = DNS ip adresa z DHCP nebo statická
  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 

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.

'''POZOR'''
* Změna nastavení MAC a změna nastavení prvků kolem IP adresy, nesmí být kombinovaná ve společné zprávě (provedlo by se jen změnění MAC ale už ne IP).
* Změna nastavení MAC, a změna nastavení prvků kolem IP adresy, způsobí restart zařízení (po odeslání odpovědi o provedení změny) - počítejte s tím !

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.


== COMMAND: /share ==

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á !