BITXml LED. Protocollo di Communicazione M2M Low End Devices. Rel

Transcript

1 BITXml LED Protocollo di Communicazione M2M Low End Devices Rel Ultima revisione:

2 Revisioni Data Ver. Autori Note 16/02/ Andrea Villa Definizione della struttura e inizio stesura 19/02/ Luca Giuliani Revisione interna 20/02/ Andrea Villa Ristrutturazione e aggiunta di contenuti 27/02/ Andrea Villa Contenuti, restyling, watermark 28/02/ Luca Giuliani WBXML, revisione 02/03/ Andrea Villa Bozza di schema XML, revisione 03/03/ Andrea Villa Release per discussione e feedback 04/03/ Andrea Villa XML Schema di <ps-o> e <user-io> 23/03/ Giuliani, Grotto, Separazione livelli, revisione finale Villa 29/09/ Macchi - Generazione ackstate a fronte di errori semantici nella richiesta getstate - Supporto getproperty su singola proprieta (protocollo esteso, omologazione a getstate) - Introdotto attributo opzionale id a state, che qualifica lo stato (protocollo esteso, utilizzato nella generazione spontanea di stati, corrispondente al nome dell evento) - Definizione della semantica per setstate con nessuna specifica di porta - Aggiornamento codici di errore supportati (tratti da BiTXml full) 21/10/ Macchi Inserimento degli attributi altitude, speed, satellites, timestamp nel valore di posizione ps-o 26/10/ Macchi Raffinamento impiego del protocollo HLDC: calcolo ed immagazzinamento del CRC, dettaglio dell impiego del byte di controllo nell header (gestione S ed R, codifica eventi spontanei) 30/11/ Macchi Introdotto attributo autoget per il comando setstate, che forza il ritorno di un valore state al posto di ackstate, contenente i valori di tutte le porte utilizzate in fase di esecuzione di setstate che siano anche porte di output (ovvero, porte IO) 2/12/ Macchi Supporto elemento error nel valore properties (usato quando e necessario comunicare a getproperties su una singola proprieta che tale operazione ha fallito) 31/01/ Macchi Supporto elementi multipli a-io, d-io, p-o, s-io, user-io in getstate per la selezione di un insieme di porte (rende obsoleto attributo id) BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 2 di 31

3 Abstract Il presente documento propone una sintesi dei requisiti emersi in merito al progetto BiTXml over LabVIEW, e una versione preliminare della specifica del protocollo BiTXml LED (Low-End Device). BiTXml LED è un sottoinsieme di BiTXml adatto a trasportare i comandi di lettura e scrittura delle porte fra un asset remoto e un BiTX Gateway. I messaggi sono in formato BiTXml codificato in base alla specifica WBXML, in modo da ridurre l uso della banda e agevolare il parsing dei messaggi. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 3 di 31

4 Sommario REVISIONI... 2 ABSTRACT... 3 SOMMARIO INTRODUZIONE BITXML LED DEFINIZIONI IDENTIFICAZIONE DEL GATEWAY MANAGER DEFINIZIONE DELLE PORTE Porta DIGITALE Porta ANALOGICA Porta POSIZIONE Porta SERIALE Porta USER DEFINIZIONE DEI MESSAGGI BiTXml LED Base BiTXml LED Esteso CODIFICA WAP BINARY XML Codici tag (tag space) Codici attributi (attribute space) ESEMPI State Setstate Ackstate TRAMATURA PER IL TRASPORTO SU UNA GENERICA LINEA SERIALE (FISICA O VIRTUALE) Esempi RIFERIMENTI APPENDICE A: WBXML INTERI TOKENS Token dell applicazione Global tokens TAG E ATTRIBUTI HEADER APPENDICE B: SCHEMA XSD BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 4 di 31

5 1. Introduzione BiTX è un ecosistema M2M (Machine-to-Machine) basato sul protocollo BiTXml (1). L architettura del sistema, illustrata nella Figura 1, è suddivisa in tre livelli per distinguerne più chiaramente le parti. Il livello front-end è solitamente costituito da applicazioni custom, che offrono interfacce per il monitoraggio e il controllo del sistema. Il livello del middleware contiene l infrastruttura adibita alla gestione dati e al controllo degli asset remoti. L ultimo livello contiene i dispositivi, o asset, remoti, che vengono configurati e controllati tramite il protocollo BiTXml. I dispositivi più prestanti (high-end) implementano in modo completo le funzionalità di BiTXml, e si interfacciano direttamente con il controller BiTX. Gli altri devono invece interfacciarsi con un Gateway Manager (GM). Front-End Applicazioni Gateway Manager BITXml LED Gateway Manager BITX l BITX Middleware Adattatore BITXml LED Protocollo ad hoc BITXml LED BITX l Remote Asset custom Asset BITXml LED Asset BITXml ready LabVIEW targets Telit, Wavecom, Sierra Wireless devices Piattaforme con Java/.NET/C++ Siemens TC-65 Low-End Devices D i Figura 1 - Architettura BITX High-End BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 5 di 31

6 Il GM è un componente software che può essere montato su un dispositivo fisico, oppure virtualizzato nel controller. Il GM da un lato comunica con il controller usando BiTXml, e dall altro deve leggere e scrivere le porte di I/O del dispositivo. A questo scopo proponiamo il protocollo BiTXml LED (Low-End-Device), che codifica in modo efficiente un sottoinsieme di BiTXml per la comunicazione tra GM e asset remoto. La Figura 2 riassume le principali funzionalità di un Gateway Manager. Lettura e scrittura delle porte I/O Gateway Manager Config. monitor BITXml Porte I/O Dispositivo remoto Condition monitor History monitor BITX Controller Command interpreter BiTXml Server Figura 2 - Componenti di un Gateway Manager Il monitor della configurazione gestisce la fase di inizializzazione del gateway, in base alle istruzioni impartite dal controller nel messaggio di <init>. Il monitor delle condizioni analizza periodicamente lo stato delle porte, e genera degli eventi al verificarsi di determinate condizioni, definite dal controller nel messaggio di <init>. L history monitor esegue periodicamente il logging dello stato delle porte del dispositivo. Il Server BiTXml, infine, è in grado di eseguire comandi direttamente impartiti dal controller, ad esempio <getstate> e <gethistory>. Quando il gateway è configurato con un server BiTXml, si parla di configurazione connected. Se il server non è presente, il gateway è detto detached. Tutte queste funzioni richiedono la lettura o la modifica delle porte di I/O del dispositivo remoto. Occorre pertanto sviluppare un protocollo che consenta al gateway di conoscere lo stato del dispositivo, ed eseguire operazioni di scrittura delle porte di I/O. Nel seguente capitolo, definiamo il protocollo BiTXml LED, un sottoinsieme di BiTXml adatto a trasportare lo stato delle porte tra il gateway BiTX e l asset remoto. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 6 di 31

7 2. BiTXml LED BiTXml LED è un protocollo di livello applicativo per la comunicazione punto-punto tra un gateway manager e un asset remoto. La Figura 3 mostra la pila protocollare. Si assume che il protocollo di trasporto sia affidabile e full-duplex, come, ad esempio, TCP/IP. I messaggi BiTXml LED sono definiti in XML e codificati nel formato binario WBXML prima di essere trasmessi(2). Questo formato facilita il parsing dei messaggi su dispositivi low-end, e ne riduce la dimensione. Per maggiore chiarezza, il protocollo viene prima descritto in formato XML testuale. Le istruzioni relative alla codifica WBXML sono illustrate infine nella Sezione 2.5. BITXml LED WBXML BITXml LED WBXML H BiTXml HTTP BiTXml HTTP Protocollo di trasporto affidabile Protocollo di trasporto affidabile TCP/IP TCP/IP BITXml LED Device BITX Gateway BITX Controller M Figura 3 - Pila protocollare 2.1 Definizioni Asset remoto elemento base dell architettura BiTX, dotato di una interfaccia formata da un certo numero di porte di I/O Controller Componente principale del middleware che configura e controlla gli asset remoti, direttamente o attraverso un gateway manager Gateway Manager (GM) Componente del middleware che agisce da intermediario tra il controller e un asset remoto Porta generico componente dell interfaccia che l asset remoto rende visibile al gateway. 2.2 Identificazione del Gateway Manager Il GM è identificato da un codice id-device che viene comunicato dal dispositivo remoto. Il controller BiTX ha un database che associa ciascun codice alla corretta configurazione delle porte. Quando il GM non è connesso ad alcun dispositivo, esso adotta un id-device generico. I valori validi di un id-device sono definiti come NMTOKEN di XML 1.0, ossia stringhe alfanumeriche prive di spazi (sono ammessi anche i simboli., :, -, _ ). 2.3 Definizione delle porte Un dispositivo remoto è dotato di un certo numero di porte di I/O, identificate da un codice identificativo id-port. Anche l identificatore delle porte è una stringa xsd:nmtoken. La coppia (id-device, id-port) deve essere univoca nel sistema. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 7 di 31

8 Esistono diversi tipi di porte: porte digitali, analogiche, posizione GPS e porte definite dall applicazione (user-io). Segue una rassegna dei tipi di porta supportati in BiTXml LED Porta DIGITALE In BiTXml LED una porta digitale è rappresentata da un elemento <d-io>, che può contenere i due stati logici. Il contenuto è di tipo xsd:boolean, e può assumere i valori 0, 1 (oppure true, false). Esempio di porte digitali: <d-io id= dig1 >true</d-io> <d-io id= dig2 >0</d-io> Porta ANALOGICA Una porta analogica ha come contenuto un valore numerico (xsd:double): <a-io id= analog1 >15.5</a-io> Porta POSIZIONE Porta per rappresentare coordinate geografiche: <ps-o id= gpsloc longitude= (-)dddmm.ssss latitude= (-)ddmm.ssss altitude= dddd.ddddd speed= dddd.dddd satellites= dd timestamp= ddddddddddddd /> La porta <ps-o> è ristretta alle sole operazioni di lettura, e la sua implementazione è opzionale Porta SERIALE Rappresenta un dispositivo di comunicazione seriale. <s-io id= COM1 > (value) </s-io> (value) può essere uno dei seguenti: <error> (xsd:string) </error> <binary> (xsd:hexbinary) </binary> <text> (xsd:string) </text> L implementazione della porta seriale è opzionale Porta USER Il valore di una porta <user-io> può essere definito in modo molto flessibile: <user-io id= user1 > (value) </user-io> (value) può essere uno dei seguenti <error> (xsd:string) </error> <binary> (xsd:hexbinary) </binary> <text> (xsd:string) </text> <xml> (xsd:any)* </xml> L implementazione della porta user è opzionale. 2.4 Definizione dei messaggi Tutti i messaggi scambiati sono trasmessi in modo unicast, ovvero la comunicazione avviene tra due enti singoli: un Gateway Manager e un Asset Remoto. BiTXml LED definisce due livelli di funzionalità: Livello base: l asset si limita a rispondere ai comandi del gateway. Livello esteso: oltre alle funzionalità del livello base, l asset ospita processi di notifica periodica e monitoraggio di condizioni. Le sottosezioni seguenti illustrano i due livelli in modo dettagliato. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 8 di 31

9 2.4.1 BiTXml LED Base BiTXml LED base definisce i meccanismi di base per la lettura e la scrittura delle porte I/O. Il modello di comunicazione è puramente client-server, dove il gateway ha ruolo di client mentre l asset ha ruolo di server. I messaggi sono documenti XML, aventi lo schema specificato in Appendice B, che questa sezione presenta in forma discorsiva. Tutti i messaggi hanno l elemento radice <bitxmlled>, che indica come attributo la versione del protocollo. Il contenuto di <bitxml-led> caratterizza il tipo di messaggio specifico che, in BiTXml LED Base, può essere uno dei seguenti elementi: <getstate> Richiesta di lettura dello stato (Sezione ) <state> Risposta alla richiesta <getstate> (Sezione ), alla richiesta <setstate> (Sezione )oppure evento spontaneo <setstate> Richiesta di modifica dello stato (Sezione ) <ackstate> Risposta alle richieste <setstate> e <getstate> (Sezione ) Lettura delle porte: <getstate> e <state> Il GM invia al dispositivo un comando <getstate>, a cui corrisponde un messaggio <state> di risposta. <getstate> ha un attributo opzionale id, che può essere usato per richiedere la lettura di una specifica porta. La risposta <state> contiene lo stato delle porte richieste, definite come visto nella Sezione 2.3. gatewa y asset <getstate <state> Segue una coppia di richiesta e risposta, a titolo di esempio. Richiesta: <?xml version= 1.0?> <getstate id-device= 1234 /> Risposta: <?xml version= 1.0?> <state id-device= 1234 > <a-io id= an1 >12.5</a-io> <d-io id= dig1 >true</d-io> </state> Figura 4 - Sequenza di lettura delle porte I/O BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 9 di 31

10 In caso di errore semantico rilevato (ad esempio, identificatore della porta scorretto), non verra effettuato l accesso ad alcuna porta, ed il messaggio ritornato sara <ackstate> contenente la codifica dell errore. A titolo di esempio: Richiesta: <?xml version= 1.0?> <getstate id-device= 1234 id= unknown-port /> Risposta: <?xml version= 1.0?> <ackstate id-device= 1234 > <error id= unknown-port code= 1002 /> </ackstate> gatewa y asset <getstate <ackstate In caso di errore in fase di esecuzione del reperimento dei valori delle porte, nel valore di ritorno <state> verra inserito, per ciascuna porta non leggibile, un corrispondente elemento <error> Richiesta: <?xml version= 1.0?> <getstate id-device= 1234 id= my-port /> Risposta: Figura 5 - Sequenza di lettura delle porte I/O errore semantico <?xml version= 1.0?> <state id-device= 1234 > <error id= my-port code= 1006 /> </state> Scrittura delle porte: <setstate> e <ackstate> Il GM invia al dispositivo un comando <setstate>, a cui corrisponde un messaggio <ackstate> di risposta. Il messaggio <setstate> contiene una o più porte del dispositivo, indicanti il valore da impostare. Il messaggio <ackstate> è vuoto in caso di successo, altrimenti contiene uno o più <error>. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 10 di 31

11 gatewa y asset <setstate <ackstate Richiesta: <?xml version= 1.0?> <setstate id-device= 1234 > (<a-io> <d-io> <user-io>)* </setstate> <setstate> può contenere una o più porte, ciascuna contenente il valore da impostare. Il messaggio <setstate> vuoto può essere usato dal gateway per controllare se l asset è connesso. Risposta: <?xml version= 1.0?> <ackstate id-device= 1234 > (<error>)* </ackstate> Il contenuto di <ackstate> può essere vuoto, oppure un elenco di <error>. Un <error> ha il seguente formato: <error code= codice-errore id= nomeporta /> Qualora l elemento <setstate> contenga l attributo autoget valorizzato a uno, verra ritornato un valore <state> al posto di <ackstate>, contenente i valori di tutte le porte di tipo IO utilizzati per l esecuzione del comando. Gli elementi <error> sono inseriti nel messaggio <ackstate> o <state> per segnalare errori nella richiesta e indicarne la causa. I codici di errore usati sono un sottoinsieme dei codici già definiti in BiTXml, e sono riassunti nella Tabella 1. Tabella 1 Codici di errore di <ackstate> Figura 6 - Sequenza di scrittura delle porte I/O Codice Descrizione 1000 Porta sconosciuta 1003 Valore non valido. (Ad esempio, scrittura di una stringa di testo su una porta analogica) 1004 Id porta duplicato (comando setstate) 1005 Comando sulla porta non valido (scrittura di unaporta read-only, lettura di una porta write-only) 1009 Comando non valido. (errore generale) In caso di messaggio <setstate> vuoto, verra ritornato un messaggio <ackstate> contenente l elenco di tutte le porte scrivibili (codificato come elementi <error>). <?xml version= 1.0?> BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 11 di 31

12 <ackstate id-device= 1234 > <error code= 0 id= port1 /> <error code= 0 id= port2 /> <error code= 0 id= port3 /> </ackstate> Vedere anche la Sezione per i codici di errore relativi alle properties BiTXml LED Esteso BitXml LED Esteso, la cui implementazione è opzionale, include tutto il livello base, e aggiunge all asset ulteriori funzionalità: la notifica periodica dello stato e il monitoraggio di condizioni definite sul valore delle porte I/O. Il protocollo definisce inoltre un meccanismo per la configurazione delle proprietà dell asset. Le proprietà sono parametri che il gateway può leggere e scrivere da remoto, come definito nella Sezione BiTXml LED Esteso definisce i seguenti messaggi, che vengono approfonditi nella Sezione <getproperties> Lettura delle proprietà dell asset <properties> Risposta a <getproperties> <setproperty> Modifica di una proprietà dell asset <ackproperty> Riscontro a <setproperty> Questi quattro messaggi si aggiungono a quelli validi per il livello base, già trattati nella Sezione Notifica dello stato Lo stato del dispositivo viene trasmesso dall asset al Gateway Manager in un messaggio <state>. Il messaggio <state> viene inviato nei seguenti casi: Periodicamente, con frequenza definita dall applicazione. Al verificarsi di una certa condizione monitorata. Le condizioni che determinano la notifica sono anche esse definite dall applicazione: per esempio, la commutazione di una porta digitale o l attraversamento di una soglia. Il messaggio <state>, definito in modo analogo al livello base, contiene lo stato delle porte. Non è obbligatorio che nel tag <state> siano contenute tutte le porte dell Asset. Una applicazione può così decidere di notificare lo stato di una porta in risposta ad un evento, ed escluderla dalla notifica periodica. Ad un messaggio <state> spontaneo puo essere associato un identificatore (attributo opzionale id) che identifica lo stato, caratterizzandolo come evento. <?xml version= 1.0?> <state id-device= 1234 id= DeviceFailure > <d-io id= sensor1 >1</d-io> <a-io id= threshold1 >3.78</a-io> </state> BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 12 di 31

13 Proprietà dell asset Le proprietà sono rappresentate dall elemento <property>, e identificate, come le porte, da un attributo di tipo NMTOKEN. <property id= nomeprop > (valore) </property> Il formato del (valore) e la rispettiva semantica sono liberamente definiti dal costruttore di asset. Una <property> può essere usata per configurare, ad esempio, la frequenza di notifica dello stato, oppure la soglia di un allarme. Il gateway legge la configurazione delle proprietà dell asset con uno scambio di messaggi <getproperties> e <properties>, come mostra il diagramma della Figura 7. gatewa y asset <getpropertie <properties> L asset invia l elenco delle sue <property> nel messaggio <properties>, come nel seguente esempio. Richiesta: <?xml version= 1.0?> <getproperties id-device= 1234 /> Risposta: <?xml version= 1.0?> <properties id-device= 1234 > (<property>)* </properties> Figura 7 - Sequenza di lettura delle proprietà dell'asset L elemento properties è sempre vuoto quando l asset implementa solo le funzionalità base di BiTXml LED (Sezione 2.4.1). La configurazione di una proprietà dell asset può essere modificata dal gateway usando il messaggio <setproperty>, cui l asset risponde con <ackproperty>: gatewa y asset <setproperty <ackproperty Figura 8 - Sequenza di scrittura di una proprietà dell'asset BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 13 di 31

14 <setproperty> ha come attributo il nome della proprietà interessata, e contiene il nuovo valore da attribuire alla property. L esito dell operazione è riscontrato da un messaggio <ackproperty>. Richiesta: <?xml version= 1.0?> <setproperty id-device= 1234 id= UpdateFreq >10s</setproperty> Abbiamo ipotizzato che la proprietà UpdateFreq sia stata definita dal costruttore di asset per regolare la frequenza di aggiornamento dello stato. Risposta: <?xml version= 1.0?> <ackproperty id-device= 1234 > (<error>)* </properties> <ackproperty> è normalmente vuoto, oppure contiene uno o più <error>, definiti come segue: <error code= codice-errore id= nomeprop /> Gli elementi <error> sono inseriti nel messaggio <ackproperty> in modo analogo a quanto visto per <ackstate> nella Sezione La Tabella 2 elenca i codici relativi al sottosistema delle property. Tabella 2 Codici di errore di <ackproperty> Codice Descrizione 1011 Valore non valido 1013 Nome di proprieta sconosciuta 1014 La property è disponibile in sola lettura Un gateway può attivare o disattivare i processi di notifica automatica dello stato dell asset impostando la proprietà predefinita AutoUpdate. <property id= AutoUpdate > (xsd:boolean) </property> Il contenuto è un valore booleano che indica se i processi di notifica automatica sono attivi o meno. La proprietà AutoUpdate è assente negli asset che dispongono solo delle funzionalità del livello base. Osserviamo, infine, che la configurabilità dell asset e la presenza di processi di notifica periodica e monitoraggio di condizioni avvicinano l Asset BiTXml LED alla funzionalità di un gateway BiTXml. Questo consente di integrare un asset BiTXml LED senza la mediazione di un BiTX gateway completo. 2.5 Codifica Wap Binary XML Per rendere più efficiente l uso del canale di comunicazione, ci proponiamo di codificare i messaggi BiTXml LED usando il protocollo WBXML. Gli aspetti fondamentali di WBXML sono trattati in Appendice A, mentre le specifiche complete sono reperibili in (2). Si osservi che una implementazione di BiTXml-LED può direttamente operare sui messaggi codificati senza ricostruire l XML. Si consiglia inoltre di semplificare la generazione dei file WBXML, per esempio evitando la stringtable, ma solo stringhe inline e i soli tag precodificati nella specifica. Inoltre verranno fissate in modo rigido la versione di WBXML (1.1), il document public identifier (0x01) e il set di caratteri (UTF-8). Questo consentirà la creazione di parser più BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 14 di 31

15 semplici che tengano conto di queste assunzioni e non debbano decodificare tutte le possibili rappresentazioni previste da WBXML Codici tag (tag space) Lo spazio dei tag contiene codici a 6 bit che rappresentano un elemento XML. I due bit più significativi sono usati per indicare la presenza di attributi e/o di contenuto. Tabella 3 Codici per la codifica dei tag Codice tag Nome elemento 0x05 <bitxml-led> 0x06 <getstate> 0x07 <state> 0x08 <setstate> 0x09 <ackstate> 0x0A <getproperties> 0x0B <properties> 0x0C <setproperty> 0x0D <ackproperty> 0x0E <a-io> 0x0F <d-io> 0x10 <p-o> 0x11 <s-io> 0x12 <user-io> 0x13 <error> 0x14 <binary> 0x15 <text> 0x16 <xml> 0x17 <property> Codici attributi (attribute space) Tabella 4 Codici per la codifica degli attributi Codice attributo Nome attributo 0x05 version 0x06 id 0x07 id-device 0x08 code 0x09 latitude 0x0A longitude 0x0B altitude 0x0C speed 0x0D satellites 0x0E timestamp 0x0F autoget 2.6 Esempi Presentiamo alcuni esempi di codifica WBXML dei messaggi BiTXml LED. La corrispondenza tra XML e WBXML è evidenziata dal colore e dall indentazione, puramente per ragioni di chiarezza State <?xml version="1.0" encoding="utf-8"?> <state id-device="12345 > <a-io id="x">12.5</a-io> <d-io id="y" >1</d-io> BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 15 di 31

16 </state> Codifica WBXML: 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0xC7 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0xCE 0x06 0x03 0x78 0x00 0x01 0x03 0x31 0x32 0x2E 0x35 0x00 0x01 0xCF 0x06 0x03 0x79 0x00 0x01 0x03 0x31 0x00 0x01 0x01 0x Setstate <?xml version="1.0" encoding="utf-8"?> <setstate id-device="12345 > <a-io id="x">12.5</a-io> <d-io id="y" >1</d-io> </setstate> Codifica WBXML: 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0xC8 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0xCE 0x06 0x03 0x78 0x00 0x01 0x03 0x31 0x32 0x2E 0x35 0x00 0x01 0xCF 0x06 0x03 0x79 0x00 0x01 0x03 0x31 0x00 0x01 0x01 0x Ackstate <?xml version="1.0" encoding="utf-8"> <ackstate id-device="12345 /> Codifica WBXML: 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0x89 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0x Tramatura per il trasporto su una generica linea seriale (fisica o virtuale) Il trasferimento di messaggi su una linea seriale orientata al carattere richiede un qualche meccanismo robusto di identificazione dell inizio e della fine dei messaggi, così da permettere la sincronizzazione del flusso informativo all avviamento o in evento di disconnessione temporanea. In sostanza, è buona norma definire un protocollo equivalente ad un livello 2 della pila ISO/OSI che definisca il formato delle trame entro cui veicolare il protocollo applicativo, BiTXml-LED codificato in WBXML nella fattispecie. Data la struttura di WBXML, che non dispone di una signature ben precisa all inizio del documento, si è pensato di fare ricorso al protocollo standard HDLC (High-level Data Link Control) per effettuare la tramatura dei messaggi WBXML. HDLC fa iniziare ogni trama con un flag costituito dall ottetto (0x7E). All interno della trama non potrà mai essere contenuto tale byte. Nel caso di trasmissione su linee dati fisiche si ricorre al cosiddetto bit stuffing che ogni 5 uni consecutivi presenti nel flusso informativo aggiunge uno zero. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 16 di 31

17 Quando HDLC è trasportato su linee orientate al trasferimento di byte completi e non singoli bit (come UART, RS-232, RS-485, connessioni TCP, ) si preferisce ricorrere al byte stuffing che definisce il concetto di control escape costituito dal carattere 0x7D. Ogniqualvolta il messaggio da trasmettere contenga il carattere 0x7D o il carattere 0x7E viene inviato un byte 0x7D seguito dal carattere da inviare con il bit 5 invertito. In pratica, 0x7D diventa 0x7D 0x5D, e 0x7E diventa 0x7D 0x5E. L uso di HDLC con bytestuffing o comunque di protocolli HDLC derivati è estremamente diffuso e sta alla base di classici protocolli di tunnelizzazione quali SLIP o PPP. Tabella 5 - Struttura della trama HDLC Flag Indirizzo Controllo Dati FCS Flag 8 bit 8 bit 8 bit 0 o più bit a multipli di 8 16 bit 8 bit FSC contiene il codice CRC-16 (CRC-CCITT) calcolato su Indirizzo, Controllo e Dati. Per convenzione, viene assegnato l indirizzo 0 al gateway manager, e un indirizzo diverso da 0 al dispositivo controllato. I due byte componenti il CRC calcolato vengono immagazzinati in formato big endian. Il campo di controllo assume un valore diverso a seconda del tipo di trama. Le trame dati sono dette I-Frame, le trame di controllo sono dette S-Frame. Nella nostra implementazione, useremo solo trame dati, in cui il byte di Controllo è strutturato come segue. 0 Numero di sequenza invio (S) Poll/Final Numero di sequenza ricezione (R) 1 bit 3 bit 1 bit 3 bit l primo campo definisce il tipo. '0' indica un frame 'I'. (S) indica il numero di sequenza del frame spedito, mentre (R) indica l ultimo numero di sequenza ricevuto dal device indicato. Poiche sono disponibili 3 bit per i numeri di sequenza, viene usata un aritmetica modulo 7 per tali numeri (dunque da 0 a 6 decimali), mentre qualunque codifica di sequenza contenente il valore 7 in (S) o in (R) indica un evento spontaneo asincrono (che come tale non va sequenzializzato). Il campo Poll/Final è un solo bit con due usi. È chiamato Poll se viene usato dalla stazione primaria per chiedere una risposta alle stazioni secondarie, invece Final quando viene usato da una stazione secondaria per indicare una risposta al termine della trasmissione. Ha significato solo se impostato a 1. Il bit Poll/Final è usato per forzare una risposta. In BiTXml-LED sarà impostato solo quando il GM invia un comando al dispositivo Esempi Vediamo come tradurre in trame i 3 esempi di documenti WBXML visti nel paragrafo precedente. Si suppone che i 3 messaggi arrivino in sequenza. Per semplicità non saranno implementati algoritmi di ACK o di ARQ supponendo che il link sottostante sia affidabile. Per questo i sequence numbers serviranno semplicemente per meglio associare le risposte alle interrogazioni, non per gestire meccanismi di ritrasmissione. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 17 di 31

18 state Flag indirizzo destinazione (GM) byte di controllo: N(S)=1; N(R)=1; POLL/FINAL=0 0x7E 0x00 0x11 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0xC7 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0xCE 0x06 0x03 0x78 0x00 0x01 0x03 0x31 0x32 0x2E 0x35 0x00 0x01 0xCF 0x06 0x03 0x79 0x00 0x01 0x03 0x31 0x00 0x01 0x01 0x01 CRC CRC 0x7E setstate flag indirizzo destinazione (Asset) byte di controllo: N(S)=2; N(R)=1; POLL/FINAL=1 0x7E 0x01 0x29 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0xC8 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0xCE 0x06 0x03 0x78 0x00 0x01 0x03 0x31 0x32 0x2E 0x35 0x00 0x01 0xCF 0x06 0x03 0x79 0x00 0x01 0x03 0x31 0x00 0x01 0x01 0x01 CRC CRC 0x7E ackstate flag indirizzo destinazione (GM) byte di controllo: N(S)=2; N(R)=2; POLL/FINAL=0 0x7E 0x00 0x22 0x01 0x01 0x6A 0x00 0x85 0xC5 0x03 0x31 0x2E 0x30 0x00 0x01 0x89 0x07 0x03 0x31 0x32 0x33 0x34 0x35 0x00 0x01 0x01 CRC CRC 0x7E BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 18 di 31

19 Riferimenti 1. BiTXml M2M Communication Protocol. [Online] 2. WAP Binary XML Content Format. [Online] BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 19 di 31

20 Appendix A: WBXML In questa appendice presentiamo una breve descrizione della specifica WBXML del Wireless Application Protocol Forum, ora confluito in Open Mobile Alliance (OMA). WBXML definisce una rappresentazione binaria compatta del linguaggio XML. Il formato XML binario è studiato per ridurre la dimensione dei documenti XML che vengono trasmessi su canali a banda ridotta, senza perdita di funzionalità o di informazione semantica. Il formato mantiene la struttura dell XML, elementi e attributi, mentre vengono rimosse le meta-informazioni riguardanti il DTD o lo schema. Interi Gli interi in WBXML sono tutti inseriti secondo una codifica a lunghezza variabile chiamata mb_u_int32. Essa codifica a gruppi di 7 bit, big endian. Il bit più significativo di ogni byte vale 0 se è l ultimo byte della sequenza, 1 in caso contrario. Esempi: 33 (0x21) 0x21; 1027 (0x403) 0x88 0x03; (0x1E240) 0x87 0xA2 0x40 Tokens Un documento WBXML è una sequenza di elementi detti token. Esistono due categorie di token: i token dell applicazione e i token globali. Token dell applicazione I token dell applicazione sono definiti dall utente. Ciascun token occupa un byte. Esistono due spazi di codici separati, uno per identificare gli elementi (tag space) e uno per gli attributi (attribute space). Tag code space Bit 7 Indica se il tag ha attributi Bit 6 Indica se il tag ha contenuto Bit 5 0 Codice del tag Attribute code space 0x00 0x7F 0x7F 0xFF Codici degli attributi (a partire da 0x05). Codici per rappresentare il valore assegnabile ad un attributo (a partire da 0x85). Global tokens Hanno lo stesso significato sia in tag space, sia in attribute space. 0x00 - SWITCH_PAGE cambia pagina per i token successivi. Deve essere seguito da un u_int8 rappresentante la nuova pagina. 0x01 - END chiude il tag corrente o la lista attributi del tag corrente. 0x02 - ENTITY characted entity. Deve essere seguito da un mb_u_int32 rappresentante il codice del carattere da inserire secondo la codifica scelta nell header del documento WBXML. 0x03 - STR_I stringa inline. Deve essere seguito da una stringa (con terminatore null). 0x04 - LITERAL consente l inserimento di un tag nuovo vuoto non definito nella specifica WBXML corrente. Deve essere seguito da un mb_u_int32 che rappresenta l offset del nome del tag all interno della stringtable. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 20 di 31

21 0x44 - LITERAL_C consente l inserimento di un tag nuovo con sottotag. Deve essere seguito da spiazzamento nella stringtable. Vedi 0x04. 0x80 - EXT_T_0 intero inline. Deve essere seguito da un mb_u_int32. Significato dipendente dall applicazione. 0x81 - EXT_T_1 intero inline. Deve essere seguito da un mb_u_int32. Significato dipendente dall applicazione. 0x82 - EXT_T_2 intero inline. Deve essere seguito da un mb_u_int32. Significato 0x83 - STR_T dipendente dall applicazione. stringa contenuta nella stringtable. Deve essere seguito da un mb_u_int32 rappresentante lo spiazzamento della stringa voluta all interno della stringtable. 0x84 - LITERAL_C consente l inserimento di un tag nuovo vuoto con attributi. Deve essere seguito da spiazzamento nella stringtable. Vedi 0x04. 0xC3 - OPAQUE 0xC4 - LITERAL_AC Tag e attributi sequenza binaria di significato dipendente dall applicazione. Deve essere seguito da un mb_u_int32 rappresentante la lunghezza, quindi da tutti i dati binari contenuti nel tag. consente l inserimento di un tag nuovo con attributi e sottotag. Deve essere seguito da spiazzamento nella stringtable. Vedi anche 0x04 (LITERAL). Se un tag contiene attributi (bit 7 impostato) al token di inizio tag deve seguire la lista attributi, uno dopo l altro, senza alcun terminatore tra il valore di uno e l inizio di un altro. La lista attributi è conclusa da un token 0x01 (END). Header L header WBXML è costituito dai seguenti campi: VERSION 1 byte: numero di versione. Numero di versione primario diminuito di 1 nel nibble più significativo, numero secondario di versione nel nibble meno significativo. Esempio: 0x01 = versione 1.1. DOCUMENT PUBLIC IDENTIFIER mb_u_int32: identificativo pubblico rappresentante lo schema usato nel documento. 1 = identificativo sconosciuto. Se 0 deve essere seguito da un ulteriore mb_u_int32 rappresentante l indirizzo in stringtable del nome completo del document-type XML. CHARSET mb_u_int32: numero della tabella di codici secondo la codifica IANA. Esempi: 0x03 = US-ASCII; 0x04 = ISO ; 0x6A = UTF-8. STRING TABLE LENGTH mb_u_int32: lunghezza in byte della stringtable (immediatamente seguente). Può essere zero. STRING TABLE Segue la stringtable, se presente Dopo la tabella delle stringhe, inizia il corpo del documento WBXML, a partire dal tag di radice de documento. BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 21 di 31

22 Appendix B: Schema XSD <?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns:xsd=" targetnamespace=" xmlns=" elementformdefault="qualified"> <xsd:documentation>xml Schema of BiTXml LED protocol, version 1.0</xsd:documentation> <xsd:element name="bitxml-led"> <xsd:documentation>root element</xsd:documentation> source=" <xsd:complextype> <xsd:choice maxoccurs="1" minoccurs="1"> <xsd:element name="getstate"> <xsd:documentation>status read request</xsd:documentation> source=" <xsd:complextype> <xsd:sequence minoccurs="0" maxoccurs="unbounded"> <xsd:choice> <xsd:element name="a-io" type="a-io_rtype" /> <xsd:element name="d-io" type="d-io_rtype" /> <xsd:element name="p-o" type="p-io_rtype" /> <xsd:element name="ps-o" type="p-io_rtype" /> <xsd:element name="s-io" type="s-io_rtype" /> <xsd:element name="user-io" type="user-io_rtype" /> </xsd:choice> </xsd:sequence> <xsd:attribute name="id" type="port_id" use="optional"> <xsd:documentation>port ID</xsd:documentation> source=" <xsd:attribute name="id-device" type="xsd:nmtoken" use="required"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:element name="error" type="error_type"> <xsd:documentation>error response</xsd:documentation> source=" <xsd:element name="state" type="state_type"> <xsd:documentation>status update message</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 22 di 31

23 <xsd:element name="setstate" type="setstate_type"> <xsd:documentation>status change request</xsd:documentation> source=" <xsd:element name="ackstate" type="ackstate_type"> <xsd:documentation>status change acknowledgement</xsd:documentation> source=" <xsd:element name="getproperties"> <xsd:documentation>read asset properties</xsd:documentation> source=" <xsd:complextype> <xsd:attribute name="id-device" type="xsd:nmtoken" use="required"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:attribute name="id" type="xsd:nmtoken" use="optional"> <xsd:documentation>property identifier</xsd:documentation> source=" <xsd:element name="properties"> <xsd:documentation>asset property list</xsd:documentation> source=" <xsd:complextype> <xsd:choice minoccurs="0" maxoccurs="unbounded"> <xsd:element name="property"> <xsd:documentation>asset property </xsd:documentation> source=" <xsd:complextype> <xsd:simplecontent> <xsd:extension base="xsd:anysimpletype"> <xsd:attribute name="id" use="required" type="xsd:nmtoken"/> </xsd:extension> </xsd:simplecontent> <xsd:element name="error" type="error_type" /> </xsd:choice> <xsd:attribute name="id-device" type="xsd:nmtoken" use="required"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:element name="setproperty"> <xsd:documentation>request property value change</xsd:documentation> BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 23 di 31

24 source=" <xsd:complextype> <xsd:simplecontent> <xsd:extension base="xsd:string"> <xsd:attribute name="id-device" type="xsd:nmtoken" use="required"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:attribute name="id" type="xsd:nmtoken" use="required"/> </xsd:extension> </xsd:simplecontent> <xsd:element name="ackproperty" type="ackprop_type"> <xsd:documentation>property change acknowledgement</xsd:documentation> source=" </xsd:choice> <xsd:attribute name="version" type="bitxml_version_type" use="optional" default="1.0"> <xsd:documentation>bitxml protocol version ID</xsd:documentation> source=" <xsd:complextype name="state_type"> <xsd:choice maxoccurs="unbounded" minoccurs="0"> <xsd:element name="a-io" type="a-io_type"> <xsd:documentation>analog port</xsd:documentation> source=" <xsd:element name="d-io" type="d-io_type"> <xsd:documentation>digital port</xsd:documentation> source=" <xsd:element name="p-o" type="p-o_type"> <xsd:documentation>gps location port</xsd:documentation> source=" <xsd:element name="user-io" type="user-io_type"> <xsd:documentation>user-defined IO</xsd:documentation> source=" <xsd:element name="s-io" type="s-io_type"> <xsd:documentation>serial port IO</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 24 di 31

25 <xsd:element name="error" type="error_type"> <xsd:documentation>error response</xsd:documentation> source=" </xsd:choice> <xsd:attribute name="id-device" use="required" type="xsd:nmtoken"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:attribute name="id" use="optional" type="xsd:nmtoken"> <xsd:documentation>state identifier</xsd:documentation> source=" <xsd:complextype name="setstate_type"> <xsd:choice maxoccurs="unbounded" minoccurs="0"> <xsd:element name="a-io" type="a-io_type"> <xsd:documentation>analog port</xsd:documentation> source=" <xsd:element name="d-io" type="d-io_type"> <xsd:documentation>digital port</xsd:documentation> source=" <xsd:element name="user-io" type="user-io_type"> <xsd:documentation>user-defined IO</xsd:documentation> source=" <xsd:element name="s-io" type="s-io_type"> <xsd:documentation>serial port IO</xsd:documentation> source=" </xsd:choice> <xsd:attribute name="id-device" use="required" type="xsd:nmtoken"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:attribute name="autoget" use="optional" type="xsd:boolean"> <xsd:documentation>auto get enablement:if true, a state is expected as response, otherwise ackstate</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 25 di 31

26 <xsd:complextype name="ackstate_type"> <xsd:choice minoccurs="0" maxoccurs="unbounded"> <xsd:element name="error" type="error_type"> <xsd:documentation>error response</xsd:documentation> source=" </xsd:choice> <xsd:attribute name="id-device" type="xsd:nmtoken"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:complextype name="ackprop_type"> <xsd:choice minoccurs="0" maxoccurs="unbounded"> <xsd:element name="error" type="error_type"> <xsd:documentation>error response</xsd:documentation> source=" </xsd:choice> <xsd:attribute name="id-device" type="xsd:nmtoken"> <xsd:documentation>device ID code</xsd:documentation> source=" <xsd:complextype name="error_type"> <xsd:attribute name="code" type="error_code"> <xsd:documentation>error code</xsd:documentation> source=" <xsd:attribute name="id" type="xsd:nmtoken"> <xsd:documentation>error source ID</xsd:documentation> source=" <xsd:simpletype name="error_code"> <xsd:restriction base="xsd:nonnegativeinteger"> <xsd:enumeration value="0"> <xsd:documentation>no error</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1"> <xsd:documentation>generic error</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1000"> BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 26 di 31

27 <xsd:documentation>unknown port id error</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1001"> <xsd:documentation>err_invportsysid</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1002"> <xsd:documentation>err_invporttype</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1003"> <xsd:documentation>invalid value</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1004"> <xsd:documentation>duplicated port id</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1009"> <xsd:documentation>invalid operation</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1013"> <xsd:documentation>invalid property name</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1014"> <xsd:documentation>invalid property value</xsd:documentation> </xsd:enumeration> <xsd:enumeration value="1015"> <xsd:documentation>property is read-only</xsd:documentation> </xsd:enumeration> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="port_id"> <xsd:restriction base="xsd:nmtoken"/> </xsd:simpletype> <xsd:complextype name="a-io_type"> <xsd:simplecontent> <xsd:extension base="xsd:double"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" </xsd:extension> </xsd:simplecontent> <xsd:complextype name="a-io_rtype"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 27 di 31

28 <xsd:complextype name="d-io_type"> <xsd:simplecontent> <xsd:extension base="non_empty_boolean"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" </xsd:extension> </xsd:simplecontent> <xsd:complextype name="d-io_rtype"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" <xsd:simpletype name="bitxml_version_type"> <xsd:restriction base="xsd:string"> <xsd:pattern value="\d\.\d"/> <xsd:enumeration value="1.0"> <!--xsd:appinfo source=" </xsd:enumeration> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="non_empty_boolean"> <xsd:restriction base="xsd:boolean"> <xsd:pattern value="0"/> <xsd:pattern value="1"/> </xsd:restriction> </xsd:simpletype> <xsd:complextype name="p-o_type"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" <xsd:attribute name="latitude" type="lat_type" use="required"> <xsd:documentation>latitude in (+ -)ddmm.ssss format</xsd:documentation> source=" <xsd:attribute name="longitude" type="long_type" use="required"> <xsd:documentation>longitude in (+ -)dddmm.ssss format</xsd:documentation> source=" <xsd:attribute name="altitude" type="xsd:double" use="optional"> <xsd:documentation>altitude in meters</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 28 di 31

29 <xsd:attribute name="speed" type=" xsd:double" use="optional"> <xsd:documentation>speed in knots</xsd:documentation> source=" <xsd:attribute name="satellites" type="xsd:nonnegativeinteger" use="optional"> <xsd:documentation>number of visible satellites</xsd:documentation> source=" <xsd:attribute name="timestamp" type="xsd:nonnegativeinteger" use="optional"> <xsd:documentation>position fix UTC time stamp</xsd:documentation> source=" <xsd:complextype name="p-io_rtype"> <xsd:attribute name="id" type="port_id" use="required"> <xsd:documentation>port ID</xsd:documentation> source=" <xsd:simpletype name="lat_type"> <xsd:restriction base="xsd:string"> <xsd:pattern value="\+?\d\d\d\d\.\d\d\d\d"/> <xsd:pattern value="-\d\d\d\d\.\d\d\d\d"/> <xsd:pattern value="error"/> </xsd:restriction> </xsd:simpletype> <xsd:simpletype name="long_type"> <xsd:restriction base="xsd:string"> <xsd:pattern value="\+?\d\d\d\d\d\.\d\d\d\d"/> <xsd:pattern value="-\d\d\d\d\d\.\d\d\d\d"/> <xsd:pattern value="error"/> </xsd:restriction> </xsd:simpletype> <xsd:complextype name="user-io_type"> <xsd:choice minoccurs="1" maxoccurs="1"> <xsd:element name="text" type="xsd:string"> <xsd:documentation>string port value</xsd:documentation> source=" <xsd:element name="error" type="xsd:string"> <xsd:documentation>error reading user port</xsd:documentation> source=" <xsd:element name="binary" type="xsd:hexbinary"> <xsd:documentation>binary type content</xsd:documentation> source=" BITXml è un marchio registrato di Your Voice S.p.A. Milano - Pagina 29 di 31