Sigfox

Avatar
Databoom Master
Segui

 Stai cercando la configurazione del dispositivo in Databoom? Clicca QUI

Sigfox Back-End

Il Back-End Sigfox fornisce un'interfaccia web per la gestione e configurazione di dispositivi, oltre a delle API per automatizzare le operazioni. Le API sono basate sulle request HTTPS REST, come GET e POST, e il payload è in formato JSON.

 

 

Procedura di attivazione

Per poter accedere al back-end è necessario contattare Sigfox per ottenere la connettività per i moduli con i quali si vuole trasmettere sulla rete Sigfox. La procedura consiste nella creazione di un account con un'indirizzo email valido ed una password. Si procede creando un gruppo, un utente, un tipo di dispositivo e i dispositivi. E' quindi richiesto di associare ogni numero seriale e PAC con una licenza.

 

 

Login

Una volta completata la procedura di attivazione, si avranno a disposizione le credenziali per l'accesso.

Dopo aver inserito le credenziali, verrà caricata la pagina principale del back-end Sigfox, con la lista delle notizie e degli aggiornamenti. Dal menù laterale si può accedere agli eventi sulla rete e la mappa di copertura.

 

 

Device

Cliccando Device nel menù in alto, si accede alla lista dei dispositivi associati all'account.

  • L'area iniziale permette di filtrare e ricercare dispositivi;
  • L'ingranaggio, e il successivo click su "Select the columns to show/hide" permette di cambiare le colonne visualizzate;
  • Il click sul tipo di device porta alla pagina di dettaglio del tipo;
  • Il click sull'ID del dispositivo apre la sua pagina di dettaglio.

 

 

Device - Informazioni

Vengono visualizzate tutte le informazioni principali del dispositivo. Dal menù laterale si accede alle aree specifiche.

 

 

Device - Posizione

Visualizza una mappa con la posizione del device, se impostata. Cliccando sulla bandiera vengono visualizzate ulteriori informazioni quali la latitudine e la longitudine.

 

 

Device - Messaggi

  • L'area iniziale permette di filtrare e ricercare messaggi, oltre ad esportare dati in formato CSV;
  • Dal menù a tendina è possibile selezionare l'ordine di visualizzazione;
  • Sono elencati:
    • La data e ora di ricezione del messaggio;
    • Il ritardo, in secondi;
    • L'header del messaggio;
    • I dati del pacchetto;
    • La posizione;
    • I dettagli sul segnale e la ricezione;
    • Lo stato della trasmissione a seconda dell'esito della callback o la richiesta di ACK.

 

 

Device - Eventi

Un evento rappresenta il cambio di uno specifico parametro di comunicazione. Gli eventi vengono utilizzati da Sigfox per  monitorare le attività di un dispositivo e notificare gli amministratori di attività irregolari del dispositivo.

 

 

Device - Statistiche

Visualizza dei grafici sulle informazioni trasmesse:

  • Messaggi;
  • Byte;
  • Messaggi SNR ricevuti;
  • RSSI;
  • Temperatura;
  • Vdd;
  • Frequenza.

 

 

Device - Configurazione evento

E' possibile configurare gli allarmi dei device e ricevere notifiche via email quando si verificano. Le email non sono personalizzabili. Cliccando su New viene visualizzata la pagina di configurazione per impostare il tipo di evento e gli indirizzi email.

 

 

Device Type

Cliccando Device Type nel menù in alto, si accede alla lista dei tipi di dispositivo associati all'account.

  • L'area iniziale permette di filtrare e ricercare i tipi di dispositivo;
  • L'ingranaggio, e il successivo click su "Select the columns to show/hide" permette di cambiare le colonne visualizzate;
  • Il click sul gruppo porta alla pagina di dettaglio del gruppo a cui appartiene il tipo;
  • Il click sul nome del tipo apre la sua pagina di dettaglio;
  • Il click sulla riga al di fuori dei link, apre il menù a tendina. Cliccando su Edit viene visualizzata la pagina di modifica del tipo.

 

 

Device Type - Modifica

E' possibile accedere alla pagina di modifica di un tipo di dispositivo cliccando l'opzione del menù dalla lista di dispositivi oppure cliccando il pulsante Edit dalla pagina di dettaglio del tipo.

La pagina di modifica è suddivisa in tre sezioni:

  • Device type information;
  • Downlink data;
  • Display type.

Device type information

Si pùo cambiare il Nome di un tipo di device, aggiungere una descrizione, impostare un tempo (in secondi) come keep-alive e definire le email dove verranno inoltrate le callback, se impostate a tal proposito.

Downlink data block

In questa sezione va definito il tipo di downlink data mode utilizzato:

  • Direct, se il modulo Sigfox richiede un ACK al termine della trasmissione, il campo Downlink data in hexa può essere compilato con la risposta in formato esadecimale. Si possono utilizzare le variabili {time}, {tapid} e {rssi};
  • Callback, se la modalità è abilitata, una mail viene inviata automaticamente all'arrivo dei dati, mentre nessuna ACK è mandata in risposta. Se il modulo prova ad inviare un pacchetto che necessità di ACK, il processo fallirà.

Display block

In questa sezione è possibile specificare il formato del messaggio. E' possibile scegliere dalla lista fra:

  • None, non viene specificato alcun formato. Viene utilizzato per dati raw;
  • Geolocation, opzione riservata per i dispositivi compatibili con GPS;
  • String, per inoltrare del testo;
  • Test, solo a scopo di test;
  • Custom, per personalizzare il formato del frame.

Di seguito informazioni per la personalizzazione del proprio frame:

format = field_def [“ “ field_def]* ;
field_def = field_name “:” byte_index “:” type_def ;
field_name = (alpha | digit | “-” | “_”)* ;
byte_index = [digit*] ;
type_def = bool_def | char_def | float_def | uint_def ;
bool_def = “bool:” (“0” | “1” | “2” | “3” | “4” | “5” | “6” | “7”) ;
char_def = “char:” length ;
float_def = “float:” (“32”) ;
uint_def = “uint:” (“8” | “16” | “24” | “32”) [ “:little-endian” | “:big-endian” ] ;
length = number* ;
digit = “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”

Un campo è definito da l suo nome, la sua posizione nel messaggio, la sua lunghezza e il suo tipo:

  • Il nome (field_name) può contenere lettere, numeri, e i caratteri '-' e '_';
  • L'indice (byte_index) è l'offset nel messaggio, a partire da 0, dopo il quale viene letto il campo. Se omesso, la posizione utilizzata è il byte corrente per i campi booleani mentre viene utilizzato il byte successivo per gli altri tipi. Per il primo campo, l'omissione della posizione indica l'inizio del buffer del messaggio.
  • Seguono il nome del tipo e i parametri, che variano dal tipo:
    • boolean: il parametro e la posizione del bit nel byte;
    • char: il parametro  è il numero di byte da riunire in una stringa;
    • float: il parametro è la lunghezza in bit del valore. La decodifica è effettuata in accordo con lo standard IEEE 754;
    • uint: i parametri sono il numero di bit da includere nel valore, e facoltativamente l'ordine dei byte per interi multi-byte. L'ordine di default è big endian.

 

 

Device Type - Informazioni

Vengono visualizzate tutte le informazioni principali del tipo di dispositivo. Dal menù laterale si accede alle aree specifiche.

 

 

Device Type - Posizione

Visualizza tutti i moduli associati al tipo di device, se i dati di latitudine e longitudine sono specificati. Cliccando sull'indicatore vengono visualizzate ulteriori informazioni del device.

 

 

Device Type - Dispositivi associati

Visualizza tutti i moduli associati al tipo di device (stessa visualizzazione della lista di Device).

 

 

Device Type - Dispositivi trasferiti

Visualizza una lista dei dispositivi trasferiti.

 

 

Device Type - Statistiche

Visualizza dei grafici sulle informazioni trasmesse.

 

 

Device Type - Configurazione evento

E' possibile configurare gli allarmi che vengono inviati alle email indicate in questa sezione. Cliccando su New si accede alla schermata per la configurazione di un nuovo allarme.

 

 

User

Viene visualizzata la lista di utenti creati nel proprio gruppo. E' possibile creare nuovi utenti associati al gruppo o modificare utenti già presenti. Per creare un nuovo utente cliccare il pulsante New in alto a destra.

Il blocco Roles permette di specificare i privilegi dell'utente che si vuole creare. E' possibile scegliere un solo gruppo di appartenenza. Una volta effettuata la selezione viene abilitata la scelta del ruolo.

Il campo email viene utilizzato per l'invio della mail di registrazione, che permette di specificare la password d'accesso.

Cliccando su un utente è possibile modificarlo scegliendo Edit dal menù a tendina. Si possono modificare o eliminare tutti gli utenti ad eccezione del proprio.

 

 

Group

In questa sezione è possibile visualizzare solo il gruppo di appartenenza. Dal menù laterale si accede alle pagine di dettaglio.

 

 

Group - Informazioni

Visualizza tutte le informazioni del gruppo selezionato precedentemente.

 

 

Group - Utenti associati

Visualizza tutti gli utenti associati al gruppo.

 

 

Group - Tipi di dispositivo associati

Visualizza tutti i tipi di dispositivo associati al gruppo.

 

 

Group - Configurazione evento

Visualizza gli eventi in base al tipo di gruppo.

 

 

Come estrarre i dati dai server Sigfox

Callback

Il beck-end può inoltrare automaticamente degli eventi utilizzando il sistema di callback. E' possibile creare una nuova callback cliccando sul pulsante Callbacks del menù laterale nella sezione di Device Type. Una callback viene attivata quando un nuovo messaggio viene ricevuto o c'è una perdita di comunicazione.

Ci sono tre tipi diversi di callback:

  • DATA
  • SERVICE
  • ERROR

C'è un set di variabili per ogni tipo di callback. Queste variabili vengono sostituite dal loro valore quando una callback è chiamata.

Nella pagina sono elencate tutte le callback configurate. Se non è stata aggiunta alcuna callback, viene visualizzato un link alla documentazione (https://backend.sigfox.com/apidocs/callback).

Di seguito la callback per l'inoltro dei dati a Databoom, con l'API POST https://api.databoom.com/v1/sigfox/data. Nel campo header va inserito un token OAuth valido

https://api.databoom.com/v1/sigfox/data

{
  "devicetype": "sensit",
  "device": "{device}",
  "time": "{time}",
  "snr": "{snr}",
  "station": "{station}",
  "data": "{data}",
  "avgSignal": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "rssi": "{rssi}",
  "seqNumber": "{seqNumber}",
  "ack": "{ack}"
}

https://api.databoom.com/v1/sigfox/servicerepeater

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "batt": "{batt}",
  "whitelistDevices": "{whitelistDevices}",
  "repeatedMsg": "{repeatedMsg}",
  "unwantedDevices": "{unwantedDevices}",
  "unwantedMsg": "{unwantedMsg}",
  "wrongMsg": "{wrongMsg}",
  "overRegulMsg": "{overRegulMsg}"
}

https://api.databoom.com/v1/sigfox/servicegeoloc

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "radius": "{radius}",
  "seqNumber": "{seqNumber}"
}

https://api.databoom.com/v1/sigfox/servicestatus

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "temp": "{temp}",
  "batt": "{batt}",
  "seqNumber": "{seqNumber}"
}

https://api.databoom.com/v1/sigfox/serviceacknowledge

{
  "device": "{device}",
  "time": "{time}",
  "duplicate": "{duplicate}",
  "snr": "{snr}",
  "rssi": "{rssi}",
  "station": "{station}",
  "avgSnr": "{avgSnr}",
  "lat": "{lat}",
  "lng": "{lng}",
  "infoCode": "{infoCode}",
  "infoMessage": "{infoMessage}",
  "downlinkAck": "{downlinkAck}",
  "downlinkOverusage": "{downlinkOverusage}"
}

https://api.databoom.com/v1/sigfox/error

{
  "device": "{device}",
  "time": "{time}",
  "info": "{info}",
  "severity": "{severity}"
}

 

API access

Alcune feature del sito back-end Sigfox sono accessibili programmaticamente utilizzando una webservice API. Questa API utilizza il protocollo HTTP con i principi REST.

Tutti gli endpoint API restituiscono dati in formato JSON, con content-type a application/json nell'header.

Creare un accesso API è molto semplice, è sufficiente cliccare il pulsante New nella pagina Api Access accessibile dal menù laterale della sezione Group e quindi compilare il form con un nome per identificare l'accesso e un ruolo selezionato dalla lista.

Una volta salvato, vengono elencate le credenziali per connettersi all'API service.

 

 

Quando è consigliato Sigfox?

Sigfox è un protocollo con buone performance a lungo raggio. Nonostante questo è richiesto molto tempo per l'invio di un singolo pacchetto (da 6 a 12 secondi) e c'è un limite di 140 pacchetti per giorno con un payload di 12 byte per lo standard ETSI sulla banda 868MHz in Europa.

  • Sigfox non è consigliato per progetti con un ciclo regolare, che richiede l'invio di un frame ogni pochi minuti. Superare il limite di 140 pacchetti giornalieri può portare all'aumento delle commissioni o all'eliminazione della licenza da Sigfox;
  • Sigfox è consigliato per le comunicazioni a lungo raggio in città dove sono presenti le stazioni Sigfox;
  • Sigfox è sconsigliato per le comunicazioni bidirezionali. Non esiste un collegamento reale anche se sono disponibili gli acknowledgment e le callback;
  • Sigfox è sconsigliato per streaming real time. La trasmissione non è effettuata in real time poichè c'è un ritardo minimo per la ricezione dei pacchetti;
  • Sigfox è sconsigliato per la trasmissione di grosse quantità di dati. Il payload massimo è di 12 byte.

 

 

Configurazione dispositivo in Databoom

In fase di creazione di un nuovo dispositivo è possibile selezionare il tipo Sigfox. 

Il tipo di dispositivo Sigfox permette di specificare dei segnali e una funzione di trasformazione per gestire il payload inoltrato alla callback https://api.databoom.com/v1/sigfox/data

I segnali indicano quali campi del payload verranno letti come segnali, di default Databoom considera i seguenti campi: 

pressure type snr avgSignal lat lng rssi seqNumber avgSnr temp batt radius 
latitude longitude decibel variable temperature humidity counter status 
temperature0 temperature1 temperature2 temperature3 temperature4 
humidity0 humidity1 humidity2 humidity3 humidity4 
counter0 counter1 counter2 counter3 counter4 
status0 status1 status2 status3 status4 
s0 s1 s2 s3 s4 s5 s6 s7 s8 s9
Aggiungendo extra1, extra2 e extra3 come segnali al dispositivo significa che nel payload verranno ricercati quei tre campi e, se individuati, i loro valori verranno memorizzati in Databoom.
 
La funzione di trasformazione del payload viene invece applicata al campo data del payload e deve ritornare un oggetto con chiavi dei token di segnali, e come valori il loro valore. I segnali estratti da data vengono memorizzati anche se non specificati nella lista dei segnali.
 
Il seguente frammento di codice è un esempio di payload inoltrato alla callback https://api.databoom.com/v1/sigfox/data
{
  "device":"0a50ptiq3w",
  "time": 1598281290,
  "data":"{\"pm1\": 13, \"pm2\": 14, \"pm3\": 15}",
  "extra1":4,
  "extra2":5,
  "extra3":6
}

Il dispositivo impostato come nello screenshot, permette di memorizzare i valori di extra1, extra2 e extra3, mentre il campo data viene processato dalla funzione di trasformazione.

La funzione d'esempio non fa altro che convertire il contenuto di data in JSON e quindi lo ritorna come oggetto affinchè venga memorizzato.

function managePayload(payload) {
 var object = JSON.parse(payload);
 var toReturn = {};
 
 for(var k in object){
 toReturn[k] = object[k];
 }
 
 return toReturn;
}
Altre domande? Invia una richiesta

0 Commenti

Accedi per aggiungere un commento.
2022 © Copyright Databoom Srl - VAT IT 02437420223 - support@databoom.com