Cod. SWUM_00399_it RCCL

Cod. SWUM_00399_it RCCL Libreria di comunicazione CISS Manuale utente Aggiornamento 2/9/2008

Sommario 1. Presentazione... 3 2. Installazione del prodotto... 3 3. Applicazione di esempio... 4 4. Per iniziare velocemente... 5 4.1. Preparazione del progetto di test... 5 4.2. Canale di comunicazione... 5 4.3. Gestore della comunicazione... 6 4.4. Ricezione dei dati... 7 4.5. Durante la comunicazione... 9 4.6. Distruzione degli oggetti... 9 2

1.Presentazione La libreria RCCL è un prodotto software che consente la comunicazione con gli strumenti LSI LASTEM compatibili con il protocollo proprietario CISS, in particolare con strumenti E-Log V2 e versioni successive. La libreria è utilizzabile per sviluppare applicazioni Windows in cui sia necessario eseguire il trasferimento dei dati prodotti dall acquisitore E-Log e strumenti CISS compatibili. Essa consente di ottenere tale prestazione in modo semplice e rapido. La libreria è stata sviluppata in ambiente Microsoft.NET Framework V3.0 ed è quindi fruibile dai sistemi di sviluppo ad esso compatibili. 2.Installazione del prodotto L installazione del prodotto avviene eseguendo l apposito programma di installazione Setup.exe. L installazione di default avviene nella cartella %ProgramFiles%\LSI-Lastem\CISS Communication Library. In questa cartella sono quindi create se seguenti sottocartelle: bin: contiene i file della libreria; in particolare: o LSI.RCCL.dll è il file principale della libreria, compatibile con.net 3.0; o LSIModemHlp.dll è una libreria a standard Microsoft COM (Common Object Model) per la gestione del modem tramite interfaccia TAPI; questa libreria deve essere correttamente registrata tramite l utility RegSvr32 o altro sistema equivalente, al fine di poter essere utilizzata nell applicazione dell utente; la procedura di Setup fornita da LSI LASTEM provvede a questa operazione in modo automatico; o Interop.LSIMODEMHLPLib.dll è la libreria per l interoperabilità fra COM e.net nell utilizzo della libreria LSIModemHlp.dll. doc: contiene questo documento; src: contiene le sorgenti di un applicazione di esempio; exe: applicazione di esempio già compilata e pronta all uso. 3

3.Applicazione di esempio Insieme alla libreria è fornita un applicazione di esempio, completa di codice sorgente in linguaggio C# e sviluppata tramite Microsoft Visual Studio 2008 in ambiente.net 3.0. L applicazione ha il seguente aspetto: Per comunicare con uno strumento E-Log utilizzare l applicazione nel seguente modo (meglio se all interno dell ambiente di sviluppo, utile al fine di comprenderne il funzionamento): 1) Selezionare il canale di comunicazione (Communication Channel) utilizzato per la connessione allo strumento, fra i tre disponibili; in base al canale utilizzato impostarne i relativi parametri d utilizzo; 2) Eseguire la connessione del canale di comunicazione premendo il bottone Connect; 3) Richiedere i valori istantanei allo strumento premendo il bottone Get nella sezione Instantaneous Values; verificare nella sezione Communication Statistics se i dati fluiscono regolarmente; al termine della comunicazione la lista dei valori istantanei dovrebbe elencare tutte le misure programmate nello strumento e il corrispondente ultimo valore acquisito o calcolato; in questa sezione, spuntando la casella Auto si ottiene la comunicazione automatica e continua con lo strumento; 4) Richiedere le informazioni anagrafiche dello strumento premendo il bottone Get della sezione Instrument Registry; 5) Richiedere le informazioni statistiche sul funzionamento dello strumento premendo il bottone Get della sezione Instrument Clock & Statistics; in questa sezione, spuntando la casella Auto si ottiene la comunicazione automatica e continua con lo strumento; inoltre premendo il bottone Sync Clock si ottiene la sincronizzazione dell orologio interno dello strumento con la data/ora indicata a fianco del bottone; la sincronizzazione avviene in modo 4

soft (graduale, ma solo per differenze non superiori a un ora) se prima dell invio del comando si spunta la casella Soft update; spuntando infine la casella PC clock si ottiene l aggiornamento automatico del testo di selezione dell ora con la data/ora di sistema del PC; 6) Richiedere la valutazione della dimensione dei dati elaborati da trasferire, in base ad una certa data/ora d inizio specificabile, premendo il bottone Predicted size is nella sezione Elaborated Values; volendo quindi richiedere i dati elaborati premere il bottone Get nella stessa sezione; al termine della comunicazione la relativa casella di testo dovrebbe riempirsi con i dati ricevuti. 4.Per iniziare velocemente Facendo riferimento all applicazione di esempio, si danno qui di seguito le indicazioni per ottenere in modo rapido un programma in grado di comunicare con lo strumento E-Log e di scaricarne i dati acquisiti; altri dettagli sulla libreria potranno essere appresi dalla documentazione di riferimento, contenuta nel file RCCL.chm. La libreria è stata sviluppata con linguaggio C# e con lo stesso saranno di seguito proposti gli esempi per il suo utilizzo. Gli esempi di codice riportati nel seguito del documento non pretendono di essere un corso esaustivo di programmazione, anzi richiedono una discreta conoscenza e capacità di programmazione in ambiente.net con linguaggio C#. 4.1.Preparazione del progetto di test Nell ambiente di sviluppo si crei una nuova applicazione Windows Form; in essa si agganci il riferimento alla libreria LSI.RCCL.dll. Nella finestra principale dell applicazione è ora possibile inserire le istruzioni per il riferimento alle classi di oggetti che verranno di seguito utilizzati: using LSI_Lastem.Lib2.Communications2; using LSI_Lastem.Lib2.CISS2.BaseServices; using LSI_Lastem.Lib2.CISS2.ELogComm.Data.V2; using LSI_Lastem.Lib2.CISS2.ELogComm.V2; 4.2.Canale di comunicazione Per prima cosa è necessario indicare alla libreria quale tipo di canale di comunicazione utilizzare; essa è in grado di utilizzare linee seriali, modem o connessioni TCP. In questo esempio verrà utilizzata una connessione seriale. Per creare un canale di comunicazione seriale possiamo utilizzare una struttura di configurazione di tipo CommunicationParameters, in cui sono specificati sia i parametri di utilizzo del canale di comunicazione (tipo di canale, velocità di comunicazione, numero di porta seriale, etc.), sia i parametri del protocollo di comunicazione verso lo strumento (indirizzo di rete, numero di tentativi di connessione, tempo di timeout attesa risposta, etc.). Volendo utilizzare altri tipi di canali di comunicazione, sarà necessario impostare gli elementi di questa struttura ad altri valori; la parte di gestione della comunicazione rimarrà comunque identica, quale che sia stata la scelta del tipo di canale utilizzato. 5

CommunicationParameters cp = new CommunicationParameters(); cp.setelogdefaults(); L istruzione SetElogDefaults imposta in un colpo solo tutti i parametri di default corretti per l uso del protocollo verso uno strumento E-Log. E necessario quindi impostare i parametri rimanenti, in questo caso l uso di una seriale nr. 1 con velocità 9600 bps: cp.ccp.commchanneltype = CommChannelTypes.Serial; cp.ccp.comport = 1; cp.ccp.speed = 9600; Ora è possibile utilizzare l istruzione seguente per la creazione del canale di comunicazione: ccb = CommChannelBase.Factory(cp); L oggetto ccb è definito a livello di classe, in quanto deve rimanere istanziato per tutta la sua durata: private CommChannelBase ccb; Sarà utile conoscere lo stato di connessione o disconnessione del canale di comunicazione; allo scopo sarà generato un evento, agganciabile con l istruzione: ccb.connectedevent += new CommChannelBase.ConnectedEventHandler(ccb_ConnectedEvent); Ora è possibile chiedere al canale di comunicazione di eseguire la connessione (apertura della porta seriale): ccb.connect(); 4.3.Gestore della comunicazione L avvenuta connessione avverrà ricevendo l evento nel metodo ccb_connectedevent. In questo metodo potrà avvenire la creazione, se non già fatto in altra parte del programma, dell oggetto di classe ELogCommManager, che svolge il compito primario del programma, cioè di eseguire la comunicazione con lo strumento; l oggetto sarà creato passando la struttura cp.pcp creata in precedenza, oppure creandone una locale, secondo necessità: ProtocolCommunicationParameters pcp = new ProtocolCommunicationParameters(); pcp.setelogdefaults(); ecm = new ELogCommManager((CommChannelBase)sender, pcp); L oggetto ecm include tutta una serie di capacità, in parte acquisite dalla gerarchia di classi cui deriva, in parte da metodi in esso contenuti. Tra le funzionalità disponibili ve ne sono alcune che richiedono, per il loro corretto funzionamento, di conoscere la configurazione attuale dei parametri che regolano il funzionamento dello strumento (impostazione delle misure, delle elaborazioni, etc.); queste informazioni sono necessarie alle funzioni di decodifica dei dati acquisiti ed elaborati dalle misure. ELogCommManager è in grado di provvedere autonomamente, e solo quando necessario, a richiedere allo strumento i dati di configurazione, ma questa è un operazione costosa sia in termini di tempo che di flusso dati (si pensi al costo necessario in caso di utilizzo di canali di 6

comunicazione di tipo telefonico). Per questo motivo è possibile indicare ad ELogCommManager di utilizzare un oggetto di gestione della persistenza della configurazione, in grado cioè di sfruttare le informazioni già ricevute in una sessione precedente di comunicazione e già memorizzate in qualche modo nel sistema locale (PC), senza che sia necessario scaricarle nuovamente dallo strumento. Un implementazione standard dell oggetto di gestione della persistenza è già disponibile nella libreria RCCL; essa è disponibile come classe BasicConfigInfosPersister, ed è proprio un oggetto di questo tipo che viene passato a ELogCommManager tramite l istruzione: ecm.configinfospersister = new BasicConfigInfosPersister(); Il meccanismo di gestione dell oggetto BasicConfigInfosPersister da parte di ELogCommManager è completamente trasparente, ovvero i dati di configurazione sono resi persistenti nel PC e riletti sono nei momenti più opportuni ed in modo automatico. Infine è necessario collegarsi agli eventi dell oggetto ELogCommManager, al fine di gestirne le funzionalità in modo asincrono: ecm.datareceivedevent += new CommHelper.DataReceivedEventHandler(ecm_DataReceivedEvent); ecm.bindatareceivedevent += new CommHelper.BinDataReceivedEventHandler(ecm_BinDataReceivedEvent); ecm.commsequenceterminatedevent += new ELogCommManager.CommSequenceTerminatedEventHandler(ecm_CommSequenceTerminatedEve nt); 4.4.Ricezione dei dati Ora tutto è pronto per comandare l inizio della comunicazione; per esempio volendo ricevere i dati istantanei dallo strumento (ultimi valori acquisiti o calcolati dalle misure), si può usare il metodo: ecm.getcalcvalues(); Il metodo GetCalcValues, come del resto tutti i metodi di richiesta dati implementati in RCCL, è asincrono, cioè la sua chiamata si conclude in modo molto veloce, ancor prima della conclusione effettiva della comunicazione con lo strumento. Ciò è utile per gestire senza particolari problemi (blocchi) l interfaccia dell applicazione, ma sarà però necessario porre una serie di vincoli alle operazioni consentite all utente quando la comunicazione non è ancora terminata (per esempio la chiamata a un altro metodo di comunicazione deve essere impedita, poiché si otterrebbe da parte della libreria un eccezione del tipo Protocol is busy). Al termine dell operazione di comunicazione si potranno avere due possibilità: la comunicazione è terminata con successo oppure la comunicazione è fallita. Nel primo caso sarà possibile procedere all utilizzo dei dati ricevuti, nel secondo sarà opportuno indicare all utente la motivazione dell insuccesso, affinché egli abbia la possibilità di porvi in qualche modo rimedio. In questo caso sarà necessario valutare l accaduto tramite il metodo agganciato all evento CommSequenceTerminatedEventHandler. Per utilizzare i dati ricevuti è necessario inserire il seguente codice nel metodo appeso all evento DataReceivedEvent: 7

CISSCalcValues ccv = (CISSCalcValues)e.DataReceived; I dati ricevuti sono inviati al metodo tramite un oggetto derivato da EventArgs, che contiene a sua volta un oggetto derivato da CISSBaseData e specializzato per contenere esattamente i dati trasportati nella specifica comunicazione con lo strumento. Nel caso dei dati istantanei delle misure, esso è del tipo CISSCalcValues; questo oggetto ha tutta una serie di metodi e proprietà di semplice utilizzo per il recupero dei valori delle misure. Lo stesso sistema è applicabile per l utilizzo di altri dati trasportati in modalità ASCII dal protocollo CISS; fra questi vi sono gli stati statistici di funzionamento dello strumento (CISSStatistics), i dati anagrafici (CISSRegistry), ed altri ancora. Le elaborazioni delle misure, memorizzate nella memoria storica dello strumento, sono però trasportate in modo binario (in quanto potenzialmente molto voluminose), perciò è necessario adottare un altro sistema. Più sopra, fra gli eventi registrati nell oggetto ecm, si trova pure quello di tipo BinDataReceivedEvent. Il metodo agganciato a questo evento è in grado di utilizzare i dati ricevuti in modo binario, come le elaborazioni. Andando per ordine, dapprima è necessario richiedere alla libreria di eseguire la comunicazione con lo strumento per ricevere le elaborazioni. Lo strumento è in grado di mantenere in memoria una grande quantità di dati e sarebbe perciò sconveniente ogni volta riceverne tutto il contenuto. E possibile perciò specificare alla libreria RCCL di ricevere i dati a partire da una data/ora specificata, fino ad arrivare al dato ultimo disponibile nello strumento, quello temporalmente più giovane. Utilizzare quindi il metodo: ecm.getelaborations(fromdt); L oggetto fromdt passato è di tipo DateTime e contiene la data/ora della prima elaborazione richiesta. La metodica di memorizzazione dei dati da parte dello strumento potrebbe determinare l invio di qualche elaborazione di poco precedente alla data specificata, garantendo però di inviare comunque i dati elaborati dalla data/ora richiesta e quelli successivi. La gestione dei dati da parte dell applicazione dovrà tenere conto di questo aspetto e produrre quindi un filtro sui dati in eccesso ricevuti ma non richiesti al fine applicativo. Al termine della comunicazione sarà richiamato il metodo agganciato all evento BinDataReceivedEventHandler, e qui sarà possibile utilizzare i dati ricevuti: List<ElabDataRow> edrc = (List<ElabDataRow>)e.DataReceived; Le elaborazioni sono contenute in una lista di oggetti ElabDataRow, ognuno rappresentante di un evento di elaborazione e contenente uno o più elementi elaborati. Se, per esempio, lo strumento è configurato con due misure, e ognuna di esse produce ogni 10 minuti elaborazioni statistiche di tipo Min, Ave, Max, ogni oggetto ElabDataRow conterrà 6 valori numerici corrispondenti ad un evento di elaborazione di 10 minuti, di cui è pure indicata la data/ora, in ordine come configurato nello strumento, cioè Misura1(Min, Ave, Max), Misura2 (Min, Ave, Max). 8

4.5.Durante la comunicazione Alcune comunicazioni richiedono tempo per essere portate a termine, specie se avvengono utilizzando canali di comunicazione lenti. Per dare l opportunità all utente dell applicazione di avere la sensazione che tutto proceda per il meglio, è possibile fornire in tempo reale la statistica della comunicazione in corso. Essa è disponibile interrogando l oggetto che incapsula il canale di comunicazione; la proprietà ecm.commchannellayer.statistics contiene informazioni utili allo scopo, facilmente presentabili attraverso l interfaccia utente dell applicazione. 4.6.Distruzione degli oggetti Gli oggetti che includono il canale e il protocollo di comunicazione possono mantenere in uso risorse preziose del sistema, per esempio le linee di comunicazione seriale. Al termine del loro utilizzo è perciò consigliabile determinarne la distruzione per mezzo del metodo Dispose disponibile. Prima della disposizione dell oggetto è inoltre opportuno scollegarsi dagli eventi prima connessi, per evitarne comunque la ricezione in quanto potenzialmente innescati dalle funzionalità asincrone della libreria. ecm.datareceivedevent -= new CommHelper.DataReceivedEventHandler(ecm_DataReceivedEvent); ecm.bindatareceivedevent -= new CommHelper.BinDataReceivedEventHandler(ecm_BinDataReceivedEvent); ecm.commsequenceterminatedevent -= new ELogCommManager.CommSequenceTerminatedEventHandler(ecm_CommSequenceTerminatedEve nt); ecm.dispose(); ccb.connectedevent -= new CommChannelBase.ConnectedEventHandler(ccb_ConnectedEvent); ccb.dispose(); 9