📖 ElioKit Java SDK

Documentazione completa della libreria Java per controllare dispositivi ElioKit via MQTT.

Iniziare

L'ElioKit Java SDK permette di controllare una scheda ElioKit da qualsiasi applicazione Java. La comunicazione avviene tramite MQTT: l'SDK si connette al broker e invia/riceve messaggi JSON.

Requisiti

• Java 11 o superiore
• Maven (per la gestione delle dipendenze)
• Accesso al broker MQTT (host, porta, credenziali)
• MAC address della scheda ElioKit (ottenibile dalla pagina Configura)

Aggiungere al progetto Maven

Opzione 1: JAR locale (fat JAR con tutte le dipendenze)

📦 Scarica il JAR, poi copialo nella cartella libs/ del tuo progetto e aggiungi al pom.xml:

<dependency>
    <groupId>com.eliokit</groupId>
    <artifactId>eliokit-sdk</artifactId>
    <version>1.0.0</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/eliokit-sdk-1.0.0-all.jar</systemPath>
</dependency>

Opzione 2: Installazione locale Maven

Se hai i sorgenti dell'SDK, installalo nel repository Maven locale:

cd eliokit-java-sdk
mvn clean install

Poi nel pom.xml del tuo progetto:

<dependency>
    <groupId>com.eliokit</groupId>
    <artifactId>eliokit-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Esempio rapido

import com.eliokit.sdk.*;

public class Main {
    public static void main(String[] args) throws Exception {
        // Crea l'istanza con MAC address, broker, porta, user, password
        try (ElioKit board = new ElioKit("3485184647BC", "89.38.128.18", 1883, "mqttuser", "password")) {

            board.connect();
            Thread.sleep(2000); // attendi connessione

            // Accendi tutti i LED di rosso per 3 secondi
            board.setLed(0, LedColor.RED, 3);

            // Emetti un bip
            board.buzzer(1000, 50, 500);

            // Leggi temperatura
            double temp = board.getTemperature();
            System.out.println("Temperatura: " + temp + " °C");

            // Pronuncia un testo
            board.say("Ciao, sono ElioKit!");

            Thread.sleep(5000);
        } // disconnect automatico
    }
}

Costruttore

Connessione

Listener eventi

L'interfaccia ElioKitListener ha i seguenti metodi (tutti default, implementa solo quelli che servono):

public interface ElioKitListener {
    void onConnected();                              // connessione MQTT stabilita
    void onDisconnected(Throwable cause);             // connessione persa
    void onValuesReceived(SensorValues values);       // valori sensori ricevuti
    void onIrCodeReceived(String irCode);             // codice IR ricevuto
    void onPhotoReceived(byte[] jpegData);            // foto JPEG ricevuta
    void onMessageReceived(String topic, String payload); // messaggio generico
    void onError(String message, Throwable cause);    // errore
}

LED — setLed

Esempio:

board.setLed(0, LedColor.RED, 5);        // tutti i LED rossi per 5 secondi
board.setLed(1, LedColor.BLUE, 0);       // LED 1 blu infinito
board.setLed(0, LedColor.GREEN, 3, 50);  // tutti verdi, 3 sec, luminosità 50%

LED — Spegnimento

Buzzer

Esempio:

board.buzzer(1000, 50, 500);   // bip a 1kHz, volume 50%, durata 500ms
board.buzzer(2000, 80, 1000);  // bip a 2kHz, volume 80%, durata 1 secondo

Buzzer — Spegnimento

Vibrazione

Esempio:

board.vibrate(200);                // vibrazione singola 200ms
board.vibrate(100, 200, 5);        // 100ms vibra, 200ms pausa, 5 volte
board.vibrate(500, 500, -1);       // vibrazione continua 500ms on/off

Audio — Text-to-Speech

Esempio:

board.say("Ciao mondo!");                            // voce di default (paola)
board.say("Benvenuto a casa!", Voice.IT_PAOLA_MEDIUM);  // voce italiana Paola (enum)
board.say("Hello!", Voice.EN_US_AMY_MEDIUM);            // voce inglese Amy (enum)
board.say("Benvenuto!", "it_IT-paola-medium");           // voce italiana Paola (stringa)

Riferimento — Voci Text-to-Speech

Voci disponibili sul server Piper TTS tramite l'enum Voice. Altre voci possono essere aggiunte scaricandole da Piper Voices.

Audio — Riproduzione file

Audio — Radio

Esempio:

board.radioPlay("http://icecast.radiodeejay.it/dj.mp3");
Thread.sleep(10000);
board.radioStop();

Audio — Volume

Sensori — Lettura

Esempio:

SensorValues v = board.fetchValues();
if (v != null) {
    System.out.println("Temperatura: " + v.getTempC() + " °C");
    System.out.println("Umidità: " + v.getHumidity() + " %");
    System.out.println("Pressione: " + v.getPressure() + " mbar");
    System.out.println("Prossimità: " + v.getProximity() + " mm");
    System.out.println("Luce: " + v.getLight() + " lux");
}

Sensori — Metodi singoli (shortcut)

Ogni metodo esegue internamente un fetchValues() e restituisce il valore richiesto. Ritorna Double.NaN o 0 in caso di errore.

SensorValues — Proprietà

L'oggetto SensorValues restituito da fetchValues() contiene tutti i campi con getter:

SensorValues v = board.fetchValues();

// Ambiente
v.getTempC()          // double — temperatura °C
v.getTempF()          // double — temperatura °F (calcolata)
v.getTempOutC()       // double — temperatura esterna °C
v.getHumidity()       // double — umidità %
v.getPressure()       // double — pressione mbar
v.getAltitude()       // double — altitudine m
v.getTvoc()           // double — TVOC ppb
v.getLight()          // double — luminosità lux
v.getLightRed()       // int    — componente rossa luce
v.getLightGreen()     // int    — componente verde luce
v.getLightBlue()      // int    — componente blu luce
v.getIrLight()        // int    — luce IR

// Prossimità
v.getProximity()      // double — distanza mm

// Movimento
v.getGyroX/Y/Z()     // int    — giroscopio °/s
v.getAccelX/Y/Z()    // int    — accelerometro mG
v.getCubePosition()   // int    — faccia cubo (1-6)

// Alimentazione
v.getBatteryVoltage() // double — tensione batteria V
v.isPlugged()         // boolean — alimentato USB
v.isWirelessCharging()// boolean — ricarica wireless

// Porte digitali
v.getD1() ... v.getD5() // int — stato porte (0/1)

// Rete e posizione
v.getIp()             // String — indirizzo IP
v.getMac()            // String — MAC address
v.getLatitude()       // double — latitudine
v.getLongitude()      // double — longitudine
v.getCity()           // String — città
v.getRegion()         // String — regione
v.getCountry()        // String — paese
v.getSsid()           // String — nome rete WiFi
v.getVersion()        // String — versione firmware

Camera — Scatta foto

Camera — Scatta foto (sincrono)

Esempio:

// Foto con luminosità default
byte[] jpeg = board.takePhotoSync(2, 15000);

// Foto con luminosità aumentata (+2) — utile in ambienti bui
byte[] jpegBright = board.takePhotoSync(2, 2, 15000);

// Foto asincrona con luminosità aumentata
board.takePhoto(2, 2);  // VGA, brightness +2

if (jpeg != null) {
    java.io.FileOutputStream fos = new java.io.FileOutputStream("foto.jpg");
    fos.write(jpeg);
    fos.close();
    System.out.println("Foto salvata: " + jpeg.length + " bytes");
}

I/O — Porte digitali

Esempio:

board.setPort("D1", 1);  // porta D1 HIGH
board.setPort("D1", 0);  // porta D1 LOW

I/O — Infrarosso

I/O — Webhook

Servo Motore

Esempio Java SDK:

// Muovi servo a 90° (default GPIO39, PWM resta attivo)
board.servo(90);

// Muovi servo a 45° su GPIO 40
board.servo(45, 40);

// Muovi servo a 0°, spegne PWM dopo 2 secondi
board.servo(0, 39, 2000);

// Comando diretto MQTT (più veloce, senza programma JSON)
board.servoCommand(180);
board.servoCommand(90, 40, 1000);

Esempio JSON (programma):

// Muovi servo a 90° sul pin di default
{"do":[{"servo":{"angle":90}}]}

// Muovi servo a 45° sul GPIO 40, mantieni per 2 secondi
{"do":[{"servo":{"angle":45, "gpio":40, "duration":2000}}]}

// Muovi servo a 0° e poi a 180° con timer
{"do":[
  {"servo":{"angle":0}},
  {"task":{"id":0, "after":2, "do":[{"servo":{"angle":180}}]}}
]}

Configurazione Task

Il dispositivo ElioKit esegue diversi task FreeRTOS per gestire sensori, attuatori e comunicazione. È possibile abilitare o disabilitare i singoli task per ridurre il carico del processore. La configurazione viene salvata in memoria permanente (NVS) e applicata al successivo avvio.

Esempio — Disabilitare task non necessari:

// Disabilita camera, tvoc e servo
board.setTaskConfig("{\"camera\":0,\"tvoc\":0,\"servo\":0}");
// Il device si riavvierà automaticamente

// Leggi la configurazione corrente (sincrono)
String config = board.fetchTaskConfig();
System.out.println("Task config: " + config);
// Output: {"mqtt":1,"httpFileDownloader":1,"sdCard":1,"camera":0,...,"servo":0,...}

// Ripristina tutti i task (tutti abilitati)
board.resetTaskConfig();
// Il device si riavvierà automaticamente

Comandi seriali equivalenti (via USB):

GET_TASKS                                          → restituisce la configurazione corrente
SET_TASKS {"camera":0,"tvoc":0}                    → imposta e riavvia
RESET_TASKS                                         → ripristina default e riavvia

Listener per la configurazione task:

board.addListener(new ElioKitListener() {
    @Override
    public void onTaskConfigReceived(String taskConfigJson) {
        System.out.println("Config task: " + taskConfigJson);
    }
});
board.getTaskConfig();  // asincrono: la risposta arriva nel listener

Sistema — Riavvio

Sistema — Programmi JSON

Esempio:

// Esegui un programma che accende i LED rossi al tap
String program = "{\"do\":[{\"on\":{\"tap\":[{\"led\":{\"color\":12,\"duration\":2,\"id\":0}}]}}]}";
board.runProgram(program);

Sistema — Pulsanti virtuali

Riferimento — Tabella Colori LED

Riferimento — Risoluzioni Camera