Leukos-Tech-SerialDevice

Sommario

[TOC]

Requisiti

Il package necessita l'installazione della libreria C++ LtSerialProtocol sulla macchina in uso per poter funzionare.

Una volta installata modificare il file _LT_PROTOCOL_DIR_ per specificarne la posizione e permettere al pkg di importarlo correttamente.

Installazione

npm install leukos-tech-serialdevice --save

Al termine dell'installazione eseguire il comando

npm install

per eseguire la build del package serialPort sulla macchina in uso e consentire la comunicazione seriale.

PROPRIETA'

[static] [Object] LtSerialDevice.deviceStata

Proprietà statica che contiene l'enumerazione dei possibili stati del dispositivo

Stato | Descrizione :-:|:- NOT_INITIALIZED | L'oggetto LtSerialDevice non è ancora stato inizializzato (lo stato subito dopo la costruzione dell'oggetto). ACQUIRING | L'oggetto sta eseguendo l'acquisizione del dispositivo (metodo .acquire()) NOT_FOUND | Nessun dispositivo seriale Leukos-Tech è stato individuato. CONNECTION_OPENED | La connessione col dispositivo seriale è stata avviata ed è attualmente in corso. CONNECTION_PAUSED | La connessione col dispositivo seriale è temporaneamente sospesa (messa in pausa). CONNECTION_RESUMED | La connessione col dispositivo seriale è stata ripristinata dopo una sospensione (pausa) ed è attualmente in corso. CONNECTION_CLOSED | La connessione col dispositivo seriale è stata chiusa.

Torna al Sommario

[Boolean] LtSerialDevice.connected

true se la connessione col dispositivo seriale è correntemente attiva.

Torna al Sommario

[Object] LtSerialDevice.deviceData

Se il dispositivo seriale Leukos-Tech è stato individuato, contiene i dati su di esso restituiti dal sistema operativo, altrimenti undefined.

Proprietà | Type | Descrizione :-: | :-: |:-: manufacturer | String | Stringa identificativa del produttore del chip del dispositivo seriale serialNumber | String | Stringa col numero seriale assegnato dal produttore della scheda pnpId | String | Plug 'N Play Identifier composto da 3 parti: [identificativo venditore]-[identificativo del prodotto]-[classe del dispositivo] vendorId | String | Stringa di 4 caratteri (ACPI ID) contenente l'identificati del venditore secondo lo standard UEFI (es. "2a03") utilizzabile per ricerche online sul sito the-sz.com productId | String | Stringa di 4 cifre identificativa del prodotto secondo lo standard UEFI (es. "0043"), utilizzabile per ricerche online sul sito the-sz.com comName | String | Percorso della porta seriale a cui il dispositivo è connesso (es. "/dev/ttyACM0") LT_PROTOCOL_VERSION | Number | Versione del protocollo LeukosTech_ByteLenProtocol in uso dal dispositivo seriale per codificare/decodificare le informazioni baudRate | Number | Velocità di trasferimento dei dati in bps (bytes al secondo) boardId | Buffer | Buffer contenente l'identificativo del chip generato via firmware (diponibile come stringa alla proprietà LtSerialDevice.serialNumber_SW)

Torna al Sommario

[String] LtSerialDevice.deviceId

Identificativo unico del dispositivo serial LeukosTech compposto da 2 parti:

"XXX-YYYY"

• XXXX - Numero Seriale Hardware (proprietà .serialNumber_HW)
• YYYY - Numero seriale Software (proprietà .serialNumber_SW)

E' undefined se l'oggetto non è stato ancora inizializzato col metodo .acquire(), o se è stato chiamato il metodo .close() con argomento (clear) true.

Torna al Sommario

[Array] LtSerialDevice.known_manufacturers

Array di stringhe contenenti i produttori di schede accreditati (utilizzato in fase di acquisizione del dispositivo).

Torna al Sommario

[Object] LtSerialDevice.parser

Istanza del parser utilizzato per la ricezione dei dati in ingresso.

E' null se l'oggetto non è stato ancora inizializzato col metodo .acquire(), o se è stato chiamato il metodo .close() con argomento (clear) true.

Torna al Sommario

[Object] LtSerialDevice.port

Contiene l'oggetto per la comunicazione con la porta seriale a cui è connesso il dispositivo Leukos-Tech.

E' null se l'oggetto non è stato ancora inizializzato col metodo .acquire(), o se è stato chiamato il metodo .close() con argomento (clear) true.

Torna al Sommario

Torna al Sommario

[LtQueue] LtSerialDevice.queue

Contiene l'oggetto che gestisce la coda dei pacchetti da inviare al dispositivo seriale.

Torna al Sommario

[String] LtSerialDevice.serialNumber_HW

Contiene il numero seriale assegnato dal produttore.

E' undefined se l'oggetto non è stato ancora inizializzato col metodo .acquire(), o se è stato chiamato il metodo .close() con argomento (clear) true.

Torna al Sommario

[String] LtSerialDevice.serialNumber_SW

Contiene il numero seriale restituito dal firmware.

E' undefined se l'oggetto non è stato ancora inizializzato col metodo .acquire(), o se è stato chiamato il metodo .close() con argomento (clear) true.

Torna al Sommario

EVENTI

'new_PKT'

Evento emesso alla ricezione di un generico pacchetto seriale. Ha come unico parametro l'LtBuffer col pacchetto.

Signature

'new_PKT', {LtBuffer} buffer

Pos | Nome | Type | Descrizione :-:|:-:|:-:|:-:|:-: 0 | pkt | LtBuffer | LtBuffer contenente il pacchetto appena ricevuto.

Torna al Sommario

METODI

[LtSerialDevice] LtSerialDevice( loggingEnabled=true, logger=console, logLevel=0 )

Costruttore dell'oggetto.

L'oggetto reso consente l'acquisizione automatica del device col metodo .acquire().

Argomenti

Pos | Nome | Type | Descrizione | Default :-:|:-:|:-:|:-:|:-: 0 | loggingEnabled | Boolean | Se true l'oggetto fornisce stringhe di debug al logger fornito. | false 1 | logger | Object | Oggetto utilizzato per il logging se loggingEnabled -> true. | console 2 | logLevel | Number | Livello di logging (0 DEBUG, 1 INFO, 2 WARN, 3 ERROR) | 0

Tipi Restituiti

Istanza di LtSerialDevice.

Torna al Sommario

[Promise] LtSerialDevice.acquire()

Avvia l'acquisizione automatica del dispositivo seriale Leukos-Tech.

Tipi Restituiti

Promise con argomento di tipo Boolean.

Risolve in true se il dispositivo è stato trovato e la connessione avviata, altrimenti in false.

Torna al Sommario

[null] LtSerialDevice.add_new_PKT_listener( listener, obj=null )

Aggiunge la funzione o metodo forniti come argomento ai listeners dell'evento "new_PKT" (ricezione di un generico pacchetto seriale).

Argomenti

Pos | Nome | Type | Descrizione | Default :-:|:-:|:-:|:-:|:-: 0 | listener | Function | Listener per l'evento "new_PKT" | 1 | logger | Object | Oggetto per fissare lo scope del listener | null

Torna al Sommario

[null] LtSerialDevice.addManifacturer( manifacturer )

Aggiunge la stringa fornita all'array LtSerialDevice.known_manifacturers, utilizzato in fase di acquisizione del dispositivo seriale.

Per avere effetto, questo metodo deve essere eseguito prima della chiamata al metodo .acquire()

Argomenti

Pos | Nome | Type | Descrizione | :-:|:-:|:-:|:-:|:-: 0 | manifacturer | String | Stringa con l'identificativo del produttore di schede che si desidera aggiungere |

Torna al Sommario

[Promise] LtSerialDevice.connection_close()

Chiude la connessione col dispositivo seriale Leukos-Tech, arrestando definitivamente il flusso dati da e verso di esso.

Dopo la chiamata a tale metodo, è necessario utilizzare nuovamente il metodo .acquire()

Torna al Sommario

[Promise] LtSerialDevice.connection_pause()

Sospende temporaneamente il flusso dei dati da e verso il dispositivo.

Eventuali dati in uscita e in ingresso verranno trattenuti nel buffer di sistema.

Tipi restituiti

Promise con argomento di tipo Boolean.

Risolve in true se il flusso dei dati viene regolarmente messo in pausa.

Torna al Sommario

[Promise] LtSerialDevice.connection_resume()

Ripristina il flusso dati da e verso il dispositivo, precedentemente sospeso col metodo LtSerialDevice.connection_pause()

Tipi restituiti

Promise con argomento di tipo Boolean.

Risolve in true se il flusso dei dati viene regolarmente ripristinato.

Torna al Sommario

[String] LtSerialDevice.toString()

Restituisce una stringa (multilinea) contenente le informazioni fondamentali sul dispositivo (se acquisito).

const LtSerialDevice = require ('leukos-tech-serialdevice');

const device = new LtSerialDevice();

console.log(device.toString());

/**
OUTPUT:

	****************************************************************************************************
	                                     LEUKOS-TECH SERIAL DEVICE
	----------------------------------------------------------------------------------------------------

	  Status Device: NOT_INITIALIZED

	  Device Id: undefined - Manufacturer: undefined
	
	****************************************************************************************************
*/

let acquired = await device.acquire();

console.log(device.toString());

/**
OUTPUT:

	****************************************************************************************************
	                                     LEUKOS-TECH SERIAL DEVICE
	----------------------------------------------------------------------------------------------------

	  Status Device: CONNECTION_RESUMED

	  Device Id: B16785QW-W5688624Q - Manufacturer: FTDI

	  Porta: /dev/ttyUSB0 - BaudaRate: 9606 - Writable: true - Readable: true
	
	****************************************************************************************************

*/

Torna al Sommario

[null] LtSerialDevice.writePkt( pkt )

Aggiunge il pacchetto fornito come argomento alla coda di trasmissione seriale in uscita.

Argomenti

Pos | Nome | Type | Descrizione | :-:|:-:|:-:|:-:|:-: 0 | pkt | LtBuffer | Istanza di LtBuffer contenente il pacchetto da trasmettere

Eccezioni sollevate

Eccezione | Causa :-:|:-: WrongArgTypeError| L'argomento fornito non risulta un'istanza di LtBuffer

Torna al Sommario

Glossario della classe

Acquisizione del dispositivo

E' la fase preliminare dell'attività della classe LtSerialDevice.

Consiste in una procedura automatizzata che consiste nell'individuazione di un dispositivo Leukos-Tech collegato alle porte seriali della macchina ove il Service è in esecuzione e nell'avvio (previa procedura di handshake) della comunicazione col dispositivo stesso.

Fasi dell'acquisizione

1. Scansione delle porte seriali del sistema, alla ricerca di dispositivi collegati.

2. Tentativo di avvio della connessione con i dispositivi trovati, per individuare quelli operanti al baudRate fissato dal protocollo LeukosTech_ByteLenProtocol.

3. Procedura di handshake con i dispositivi operanti alla giusta velocità.

4. Selezione del primo dispositivo (nell'ordine restituito dalla scansione iniziale delle porte di sistema) tra quelli che hanno completato la procedura di handshake.

Hanshake

E' la procedura con cui avviene il riconoscimento reciproco, tramite lo scambio di pacchetti prefissati stabiliti dal protocollo LeukosTech_ByteLenProtocol, tra il Service Seriale e il dispositivo seriale.

Tale procedura consente l'acquisizione automatizzata del dispositivo da parte della classe LtSerialDevice.