PDF

Web Client

API Rest

Questa sezione descrive le API REST di un client web che colloquia con l'Uploader Cloud Service al fine di determinare la presenza di una nuova release ed effettuare il download. Il download viene effettuato a blocchi in modo da agevolare il dispositivo host sulla base della sua risorsa di memoria disponibile per il buffer del singolo blocco. L'host salvera' la nuova release componendo i singoli blocchi scaricati.

Il trasporto utilizzato per accedere all'Uploader Cloud Service e' HTTPS (porta 443) con credentiali BASIC AUTH fornite dall'Amministratore di Sistema per il proprio Boundary di competenza.

Le richieste sono di tipo GET ed occorre codificare l'AGENT con la convenzione:

DWLOADER-<nome_applicazione_client>

WHITE/BLACK LIST: per usufruire delle caratteristiche selelettive delle politiche di aggiornamento attraverso le liste discriminatorie, occorre formalizzare 'nome_applicazione_client' nel formato DeviceId che costituisce un identificativo univoco del Client di 13 caratteri.

Convenzione suggerita:

DeviceId = <SHORT_HEADER_DEVICE>-<UNIQUE_MACHINE_CODE>  (13 caratteri ASCII)

<SHORT_HEADER_DEVICE>  e' costituita da 3 caratteri, 
                       acronimo della Applicazione
<UNIQUE_MACHINE_CODE> codice alfanumerico univoco di 9 caratteri
                      esadecimali NIBBLEASCII maiuscolo
                      del MAC address del modulo di comunicazione

Eg.: c2g-F33575441
     cm3-F33540615
     blu-A256357EC

ovvio che il `DeviceId` diventa una dato di targa 
di produzione del Client da tracciare.

URL corrente del Universal Cloud Service: https://simogt.meshgrid.it:443

Check Release

Questa GET, nei parametri della query, fornisce la release corrente del dispositivo al Uploader Cloud Service che verifica la presenza di una nuova release per l'Applicazione richiesta. Se il payload ritorna esisto negativo l'operazione di aggiornamento si conclude qui.

Sintassi
<url_servizio>/cgi-dw/dwloader_check.cgi?
app=<application>&rel=<release>&ext=<extension>

ove
<application>: stringa ASCII di min 3, max 13 caratteri alfanumerici 
<release>    : stringa ASCII di min 3, max 13 caratteri alfanumerici 
<extension>  : stringa ASCII di 3 caratteri alfanumerici

Ritorna un contenuto di tipo: Content-Type: text/plain;charset=utf-8 col seguente payload (body of response):

Risposta positiva

ok: <nome_file_release> //indica che sul server e' presente una nuova release

Risposte negative

ko: release not changed
ko: application not found
ko: not authorized
ko: syntax error
ko: not present in white list
ko: present in black list

Per convenzione il nome file release ha la seguente forma: _.

Get Size

In caso di presenza di una nuova release, con questa GET si richiede la dimensione e numero dei blocchi in base alle risorse di memoria disponibili. I parametri della query contiene nome della nuova release e la dimensione del buffer di memoria disponibile: block_size Il dispositivo e' informato del numero dei blocchi da richiedere.

Sintassi
<url_servizio>/cgi-dw/dwloader_fstat.cgi?
file=<nome_file_release>&block_size=<dimensione_singolo_blocco>

ove
<nome_file_release>:  nel formato <application>_<release>.<extension> 
                      ritornato dalla API `Check Release`
<dimensione_singolo_blocco>: intero indicante dimensione massima 
                             blocco ricevibile (valore limite: 65535)

Ritorna un contenuto di tipo: Content-Type: text/plain;charset=utf-8 col seguente payload (body of response):

Risposta positiva

ok: #blocks=<unsigned_short>,filesize=<unsigned_long>

Risposte negative

ko: file not found
ko: not authorized
ko: syntax error

Get Block

Questa GET consente di scaricare un blocco di dimensione block_size, ad eccezione dell'ultimo blocco che puo' risultare piu' corto, indicando come parametro l'indice del blocco richiesto. La sintassi completa e' la seguente:

Sintassi
<url_servizio>/cgi-dw/dwloader_get.cgi?
file=<nome_file_release>&block_size=<dimensione_singolo_blocco>
     &block_index=<indice_blocco>

ove
<nome_file_release>:  nel formato <application>_<release>.<extension> 
                          ritornato dalla API `Check Release`
<dimensione_singolo_blocco>: intero indicante dimensione massima 
                          blocco ricevibile (valore limite: 65535)
<indice_blocco>: indice blocco file release richiesto. 
                     Valore iniziale del primo blocco: 0.
                 Valore finale richiedibile: #blocks - 1  (ove #blocks 
                                        e' ritornata dalla API `Get Size`)

Ritorna un contenuto di tipo: Content-Type: application/octet-stream col seguente payload (body of response):

Risposta positiva

ok: XXXXYYYYbinario      XXXX=index,  YYYYY=block len<= block_size  
                         (espressi in NIBBLEASCII, 4 caratteri maiuscoli)
                     binario e' il blob data ritornato in formato binario

Risposte negative

ko: limit exceeded           //indice blocco eccede i limiti (#blocks -1)
ko: file not found
ko: not authorized
ko: syntax error
ko: memory error
ko: not present in white list
ko: present in black list

Appendix: tracciati API

Esempi tracciati API

GET /cgi-dw/dwloader_check.cgi?app=eagleone&rel=E1_2_6&ext=hex HTTP/1.1
User-Agent: DWLOADER-WebClient
Authorization: Basic QfbzdEJlZDp1caXv1WRlci09MZzPODdGyQ==
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive


HTTP/1.1 200 OK
Date: Wed, 08 Jul 2020 12:41:45 GMT
Content-Length: 23
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/plain;charset=utf-8

ok: eagleone_E1_2_7.hex



GET /cgi-dw/dwloader_fstat.cgi?file=eagleone_E1_2_7.hex
    &block_size=4096 HTTP/1.1
User-Agent: DWLOADER-webclient
Authorization: Basic QfbzdEJlZDp1caXv1WRlci09MZzPODdGyQ==
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive


HTTP/1.1 200 OK
Date: Wed, 08 Jul 2020 12:39:57 GMT
Content-Length: 30
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/plain;charset=utf-8

ok: #blocks=74,filesize=302446


GET /cgi-dw/dwloader_get.cgi?file=eagleone_E1_2_7.hex&block_size=4096
    &block_index=0 HTTP/1.1
User-Agent: DWLOADER-WebClient
Authorization: Basic QfbzdEJlZDp1caXv1WRlci09MZzPODdGyQ==
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive


HTTP/1.1 200 OK
Date: Wed, 08 Jul 2020 12:43:54 GMT
Content-Length: 4108
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/octet-stream

ok: 00001000:020000040800F2
:1040000000800020817701080D7401080F740108F9
:1040100011740108137401081574010800000000F0
:1040200000000000000000000000000017740108FC
:1040300019740108000000001B7401081D740108B8
:10404000C9770108C9770108C97701082D740108EB
:10405000C9770108C9770108397401083F7401085C
:10406000457401084B740108517401085974010822
:10407000C9770108C9770108C9770108C97701081C
:10408000C9770108C97701086574010800000000BC
:10409000000000000000000000000000C9770108D7
:1040A0000000000000000000000000000000000010
:1040B000C9770108C9770108C97701087174010837
:1040C0007D7401088974010895740108C977010895
:1040D000C9770108A1740108AD740108B974010819
:1040E000C9770108C977010800000000000000003E
:1040F00000000000000000000000000000000000C0
:10410000C977010800000000C9770108C9770108D4
:10411000C5740108D1740108DD740108F174010847
:10412000C9770108C9770108C9770108C97701086B
:10413000000000000000000000000000000000007F
:10414000000000000000000000000000000000006F
:10415000000000000000000000000000000000005F
:10416000000000000000000000000000000000004F
:10417000000000000000000000000000000000003F
:10418000000000000000000000000000000000002F
:10419000000000000000000000000000000000001F
:1041A000000000000000000000000000000000000F
:1041B00000000000000000000000000000000000FF
:1041C00000000000000000000000000000000000EF
:1041D00000000000000000000000000000000000DF
:0441E0005FF8E0F1B3
:1041E80010B5054C237833B9044B13B10448AFF329
:1041F80000800123237010BDCC04002000000000C3
:10420800409E010808B5034B1BB103490348AFF3AF
:10421800008008BD00000000D0040020409E010876
:1042280010F8012B11F8013B012A28BF9A42F7D058
:10423800D01A704781F0004102E000BF83F00043CC
:1042480030B54FEA41044FEA430594EA050F08BF29
:1042580090EA020F1FBF54EA000C55EA020C7FEAED
:10426800645C7FEA655C00F0E2804FEA5454D4EB6A
:104278005555B8BF6D420CDD2C4480EA020281EA34
:10428800030382EA000083EA010180EA020281EA6C
:104298000303362D88BF30BD11F0004F4FEA0131BE
:1042A8004FF4801C4CEA113102D0404261EB4101CD
:1042B80013F0004F4FEA03334CEA133302D0524253
:1042C80063EB430394EA050F00F0A780A4F101040F
:1042D800D5F1200E0DDB02FA0EFC22FA05F2801849
:1042E80041F1000103FA0EF2801843FA05F359412F
:1042F8000EE0A5F120050EF1200E012A03FA0EFCAE
:1043080028BF4CF0020C43FA05F3C01851EBE371D7
:1043180001F0004507D54FF0000EDCF1000C7EEBF4
:1043280000006EEB0101B1F5801F1BD3B1F5001F32
:104338000CD349085FEA30004FEA3C0C04F1010451
:104348004FEA445212F5800F80F09A80BCF1004F7A
:1043580008BF5FEA500C50F1000041EB045141EAFC
:10436800050130BD5FEA4C0C404141EB010111F4FD
:10437800801FA4F10104E9D191F0000F04BF0146A8
:104388000020B1FA81F308BF2033A3F10B03B3F186
:1043980020020CDA0C3208DD02F1140CC2F10C0216
:1043A80001FA0CF021FA02F10CE002F11402D8BF74
:1043B800C2F1200C01FA02F120FA0CFCDCBF41EA40
:1043C8000C019040E41AA2BF01EB0451294330BD0F
:1043D8006FEA04041F3C1CDA0C340EDC04F11404EC
:1043E800C4F1200220FA04F001FA02F340EA0300C3
:1043F80021FA04F345EA030130BDC4F10C04C4F109
:10440800200220FA02F001FA04F340EA03002946E8
:1044180030BD21FA04F0294630BD94F0000F83F432
:10442800801306BF81F480110134013D4EE77FEA15
:10443800645C18BF7FEA655C29D094EA050F08BF61
:1044480090EA020F05D054EA000C04BF1946104642
:1044580030BD91EA030F1EBF0021002030BD5FEA86
:10446800545C05D14000494128BF41F0004130BDAE
:1044780014F580043CBF01F5801130BD01F0004502
:1044880045F0FE4141F470014FF0000030BD7FEA75
:10449800645C1ABF194610467FEA655C1CBF0B4670
:1044A800024650EA013406BF52EA033591EA030F87
:1044B80041F4002130BD00BF90F0000F04BF00217F
:1044C800704730B54FF4806404F132044FF00005B2
:1044D8004FF0000150E700BF90F0000F04BF00212B
:1044E800704730B54FF4806404F1320410F0004591
:1044F80048BF40424FF000013EE700BF42004FEA8C
:10450800E2014FEA31014FEA02701FBF12F07F4308
:1045180093F07F4F81F06051704792F0000F14BF05
:1045280093F07F4F704730B54FF4607401F0004549
:1045380021F0004120E700BF50EA010208BF7047A0
:1045480030B54FF000050AE050EA010208BF704795
:1045580030B511F0004502D5404261EB41014FF4FE
:10456800806404F132045FEA915C3FF4DCAE4FF002
:1045780003025FEADC0C18BF03325FEADC0C18BFE9
:10458800033202EBDC02C2F1200300FA03FC20FA3A
:1045980002F001FA03FE40EA0E0021FA02F1144487
:1045A80


GET /cgi-dw/dwloader_get.cgi?file=eagleone_E1_2_7.hex&
    block_size=4096&block_index=1 HTTP/1.1
User-Agent: DWLOADER-WebClient
Authorization: Basic QfbzdEJlZDp1caXv1WRlci09MZzPODdGyQ==
Accept: */*
Accept-Encoding: gzip, deflate, br
Connection: keep-alive


HTTP/1.1 200 OK
Date: Wed, 08 Jul 2020 12:47:35 GMT
Content-Length: 4108
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: application/octet-stream

ok: 000110000C1E600BF70B54FF0FF0C4CF4E06C1CEA9C
:1045B80011541DBF1CEA135594EA0C0F95EA0C0F11
:1045C80000F0DEF82C4481EA030621EA4C5123EA84
:1045D8004C5350EA013518BF52EA033541F48011B3
:1045E80043F4801338D0A0FB02CE4FF00005E1FB66
:1045F80002E506F00042E0FB03E54FF00006E1FBB0
:1046080003569CF0000F18BF4EF0010EA4F1FF04F2
:10461800B6F5007F64F5407404D25FEA4E0E6D4132
:1046280046EB060642EAC62141EA55514FEAC52043
:1046380040EA5E504FEACE2EB4F1FD0C88BFBCF5BF
:10464800E06F1ED8BEF1004F08BF5FEA500E50F170
:10465800000041EB045170BD06F0004646EA010136
:1046680040EA020081EA0301B4EB5C04C2BFD4EB68
:104678000C0541EA045170BD41F480114FF0000E61
:10468800013C00F3AB8014F1360FDEBF002001F0CF
:10469800004170BDC4F10004203C35DA0C341BDC49
:1046A80004F11404C4F1200500FA05F320FA04F01B
:1046B80001FA05F240EA020001F0004221F000414F
:1046C80010EBD37021FA04F642EB06015EEA430EC2
:1046D80008BF20EAD37070BDC4F10C04C4F12005F2
:1046E80000FA04F320FA05F001FA04F240EA0200A5
:1046F80001F0004110EBD37041F100015EEA430E76
:1047080008BF20EAD37070BDC4F1200500FA05F295
:104718004EEA020E20FA04F301FA05F243EA020314
:1047280021FA04F001F0004121FA04F220EA020023
:1047380000EBD3705EEA430E08BF20EAD37070BD69
:1047480094F0000F0FD101F00046400041EB010149
:1047580011F4801F08BF013CF7D041EA060195F02B
:10476800000F18BF704703F00046520043EB0303E5
:1047780013F4801F08BF013DF7D043EA06037047D2
:1047880094EA0C0F0CEA135518BF95EA0C0F0CD0DD
:1047980050EA410618BF52EA4306D1D181EA030123
:1047A80001F000414FF0000070BD50EA410606BF1D
:1047B8001046194652EA430619D094EA0C0F02D162
:1047C80050EA013613D195EA0C0F05D152EA0336A7
:1047D8001CBF104619460AD181EA030101F00041C5
:1047E80041F0FE4141F470014FF0000070BD41F00E
:1047F800FE4141F4780170BD70B54FF0FF0C4CF4E8
:10480800E06C1CEA11541DBF1CEA135594EA0C0F06
:1048180095EA0C0F00F0A7F8A4EB050481EA030E53
:1048280052EA03354FEA013100F088804FEA03333A
:104838004FF0805545EA131343EA12634FEA022208
:1048480045EA111545EA10654FEA00260EF00041C9
:104858009D4208BF964244F1FD0404F5407402D21B
:104868005B084FEA3202B61A65EB03055B084FEAAC
:1048780032024FF480104FF4002CB6EB020E75EBA9
:10488800030E22BFB61A754640EA0C005B084FEAD1
:104898003202B6EB020E75EB030E22BFB61A75464E
:1048A80040EA5C005B084FEA3202B6EB020E75EB99
:1048B800030E22BFB61A754640EA9C005B084FEA11
:1048C8003202B6EB020E75EB030E22BFB61A75461E
:1048D80040EADC0055EA060E18D04FEA051545EA0D
:1048E80016754FEA06164FEAC30343EA52734FEAB6
:1048F800C2025FEA1C1CC0D111F4801F0BD141EA2F
:1049080000014FF000004FF0004CB6E711F4801F93
:1049180004BF01430020B4F1FD0C88BFBCF5E06F73
:104928003FF6AFAEB5EB030C04BFB6EB020C5FEA83
:10493800500C50F1000041EB045170BD0EF0004ED8
:104948004EEA113114EB5C04C2BFD4EB0C0541EA0A
:10495800045170BD41F480114FF0000E013C90E607
:1049680045EA060E8DE60CEA135594EA0C0F08BFCB
:1049780095EA0C0F3FF43BAF94EA0C0F0AD150EACA
:1049880001347FF434AF95EA0C0F7FF425AF10465D
:1049980019462CE795EA0C0F06D152EA03353FF485
:1049A800FDAE1046194622E750EA410618BF52EA02
:1049B80043067FF4C5AE50EA41047FF40DAF52EAD6
:1049C80043057FF4EBAE12E74FF0FF3C06E000BF73
:1049D8004FF0010C02E000BF4FF0010C4DF804CD80
:1049E8004FEA410C7FEA6C5C4FEA430C18BF7FEA40
:1049F8006C5C1BD001B050EA410C0CBF52EA430C6E
:104A080091EA030F02BF90EA020F0020704710F1ED
:104A1800000F91EA030F58BF994208BF90422CBF7C
:104A2800D8176FEAE37040F0010070474FEA410C75
:104A38007FEA6C5C02D150EA013C07D14FEA430C93
:104A48007FEA6C5CD6D152EA033CD3D05DF8040B04
:104A5800704700BF8446104662468C461946634636
:104A680000E000BF01B5FFF7B7FF002848BF10F10D
:104A7800000F01BD4DF808EDFFF7F4FF0CBF012052
:104A880000205DF808FB00BF4DF808EDFFF7EAFFCE
:104A980034BF012000205DF808FB00BF4DF808ED89
:104AA800FFF7E0FF94BF012000205DF808FB00BF7E
:104AB8004DF808EDFFF7CEFF94BF012000205DF808
:104AC80008FB00BF4DF808EDFFF7C4FF34BF012015
:104AD80000205DF808FB00BF4FEA410C7FEA6C5CE0
:104AE80002D150EA013C0AD14FEA430C7FEA6C5CE0
:104AF80002D152EA033C02D14FF0000070474FF058
:104B0800010070474A0011D212F5001211D20DD5DA
:104B18006FF47873B3EB62520ED44FEAC12343F0BB
:104B2800004343EA505323FA02F070474FF0000065
:104B3800704750EA013002D14FF0FF3070474FF014
:104B48000000704780F0004002E000BF81F00041A3
:104B5800

NOTA: i tracciati sono mostrati in chiaro, in realta' sono cifrati sul canale di trasporto TLS della chiamata HTTPS

Appendix: esempi curl

curl --user username:password 
 -H "User-Agent: DWLOADER-webclient" 
     -k "https://<url_servizio>/cgi-dw/dwloader_check.cgi?
         app=eagleone&rel=E1_2_6&ext=hex"

curl --user username:password 
 -H "User-Agent: DWLOADER-webclient" 
     -k "https://<url_servizio>/cgi-dw/dwloader_fstat.cgi?
         file=eagleone_E1_2_7.hex&block_size=4096"

curl --user username:password 
 -H "User-Agent: DWLOADER-webclient" 
     -k "https://<url_servizio>/cgi-dw/dwloader_get.cgi?
         file=eagleone_E1_2_7.hex&block_size=4096&block_index=0"