Da appassionato di domotica, faccio ampio ricorso all’illuminazione smart. Ma quando ho dovuto installare un controller per l’illuminazione in ogni stanza, a volte anche più di uno, sono andato incontro a un problema di budget. I controller smart in commercio sono piuttosto costosi. Così ho deciso di usare una stampante 3D, aggiungere qualche componente elettronico e costruire un gran bel controller personalizzato a un prezzo irrisorio.

Ho progettato un piccolo macro pad che utilizza switch per tastiera meccanica, una scheda ESP32, un encoder rotativo per la regolazione della luminosità e un display OLED compatto per visualizzare l’illuminazione attiva in quel momento. L’encoder rotativo dispone anche di un pulsante integrato: premendolo si attiva la modalità di regolazione della luminosità del display per regolare la luminosità dell’OLED, mentre cliccandoci di nuovo si torna al normale controllo dell’illuminazione.

Per assicurarmi che non fosse solo l’ennesima noiosa scatola di plastica, ho deciso di combinare diversi materiali Prusament Woodfill per creare delle belle combinazioni di colori che si abbinassero al piano in legno della mia scrivania. Ho avuto la possibilità di provare una delle unità beta della Prusa CORE One+ INDX, quindi ho approfittato delle sue funzionalità multimateriale. Tuttavia, è possibile stampare facilmente questo progetto su una Original Prusa XL, una stampante dotata di MMU3, o anche su una macchina standard a strumento singolo senza alcuna funzionalità multimateriale. In tal caso, sarà necessario sostituire manualmente i filamenti alcune volte durante la stampa, ma è assolutamente fattibile, anche se è prevedibile un maggiore spreco. Grazie all’uso dell’INDX, ho ottenuto quasi zero sprechi di filamento: un grande vantaggio per il progetto, dato che ho risparmiato materiale che ora posso usare per stampare altri macropad o altre cose.

Hardware

Per rendere questo progetto accessibile, tutti i componenti elettronici si possono acquistare con pochi euro. Ovviamente, si può anche omettere il display e l’encoder e limitarsi ai pulsanti, oppure ridurre il numero di tasti.

Come “cervello” del macropad, si può usare quasi qualsiasi scheda di sviluppo ESP32 o simile, purché abbia un numero sufficiente di ingressi e una connessione Wi-Fi. Le schede di alta qualità di marchi come Adafruit (come la compatta QT Py ESP32-S3 o la classica Feather ESP32-S3) o SparkFun (la Thing Plus ESP32-S3) sono la scelta perfetta per questo progetto. Nel mio caso, prima di fare acquisti online, ho rovistato a fondo nel mio infinito cassetto dei pezzi di ricambio e ho trovato una scheda simile, una Xiao ESP32-C3 di Seeed Studio, quindi ho deciso di usarla per questo progetto.

Per quanto riguarda i tasti, ho deciso di optare per gli switch meccanici Blue. Potrebbe essere una scelta un po’ di nicchia, e i tasti normali funzionerebbero perfettamente, ma usare gli switch meccanici mi piace proprio per quella sensazione e quel suono clicky così appaganti.

Ecco una breve lista di ciò che serve per la versione descritta in questo articolo:

Stampa 3D e personalizzazione del design

È ora il momento di preparare i modelli 3D per la stampa. Potete crearli voi stessi con un software di modellazione 3D come Fusion, oppure scaricare i file già pronti per questo progetto da Printables.

Importare i file in PrusaSlicer. Per un risultato pulito ed elegante, è possibile stampare il telaio in un unico colore utilizzando Prusament Woodfill Linden Light. Ma dato che la fantasia non ha limiti, è possibile realizzare anche varianti molto colorate, perfette per la cameretta dei bambini, come ad esempio uno stile ispirato agli Avengers. Successivamente, aggiungere modificatori SVG con simboli semplici ai tasti e alla manopola rotante facendo clic con il tasto destro del mouse sul modello in PrusaSlicer e selezionando Aggiungi modificatore > SVG. Se desiderate una guida più dettagliata su come applicare i modificatori SVG, consultate il nostro articolo sugli accessori fai da te per giochi sensoriali. Scegliere un Prusament Chocolate Brown Woodfill più scuro per i pulsanti e utilizzare lo stesso Linden Light brillante per i simboli crea un contrasto davvero piacevole. Grazie alla stampa multimateriale su una stampante come la Prusa CORE One+ INDX o Original Prusa XL, il risultato è incredibilmente preciso, senza alcuna contaminazione cromatica e con uno spreco ridotto al minimo. Il modo migliore per stampare i tasti è posizionarli a faccia in giù sul piano di stampa. Nell’immagine qui sotto, sono capovolti a faccia in su solo per mostrare i disegni SVG. Una volta stampati tutti i pezzi, è il momento di montarli.

Montaggio e cablaggio

Per prima cosa, installare gli switch della tastiera meccanica semplicemente spingendoli attraverso le aperture del telaio finché non scattano in posizione. Poi, installare il display, l’encoder rotativo e l’ESP32, inserendo il suo connettore USB-C nell’apertura predisposta sul lato del telaio in modo che sia rivolto verso l’esterno. Mentre il display e l’encoder si fissano abbastanza saldamente da soli, fissare l’ESP32 richiede un po’ più di attenzione. Ho usato un semplice distanziale stampato che basta far scorrere tra la parete del telaio e la scheda per bloccarla in posizione, assicurando che l’ESP32 non venga spinto all’indietro quando si collega il cavo USB-C.

La configurazione occupa in totale undici pin: sei interruttori, l’encoder (2 pin per la rotazione, 1 per l’interruttore) e il display I2C (2 pin per dati/clock). Il numero corrisponde perfettamente a quello degli ingressi digitali disponibili sulla mia scheda ESP32. Di seguito è riportato lo schema di cablaggio creato con Wokwi, un ottimo simulatore gratuito che funziona direttamente nel browser.
Wokwi include anche un simulatore integrato, che consente di collegare tutti i componenti e scrivere codice di prova per verificare che il cablaggio sia corretto prima di assemblare l’unità fisica.

Attenzione quando si osserva la scheda: l’etichetta fisica stampata sul PCB (D0-D10) differisce quasi sempre dai registri interni (GPIO) utilizzati nel codice. Ecco la mappatura hardware che ho usato per il mio ESP32:

5V / 5V0 – VCC (Linea di alimentazione condivisa sia per il display OLED che per l’encoder rotativo)

GND – GND (Messa a terra comune per tutti i componenti e i tasti meccanici)

D0 (GPIO interno 2) – Tasto 1

D1 (GPIO interno 3) – Tasto 2

D2 (GPIO interno 4) – Tasto 3

D3 (GPIO interno 5) – Tasto 4

D4 (GPIO interno 6) – OLED SDA (linea dati)

D5 (GPIO interno 7) – OLED SCL (linea di clock)

D6 (GPIO interno 21) – CLK encoder (Pin di rotazione A)

D7 (GPIO interno 20) – DT encoder (Pin di rotazione B)

D8 (GPIO interno 8) – Encoder SW (Pulsante integrato nell’encoder)

D9 (GPIO interno 9) – Tasto 5

D10 (GPIO interno 10) – Tasto 6

Per i primi test, puoi collegare tutto usando dei connettori Dupont, come ho fatto io. Tuttavia, lo spazio all’interno del telaio è limitato e questi connettori non sono abbastanza sicuri per l’uso quotidiano. Per garantire un’affidabilità al 100% e un montaggio pulito, consiglio vivamente di saldare tutto in posizione.

Configurazione del software (ESPHome)

Ora che tutto è collegato, è ora di mettersi a programmare 😎! Collegare l’ESP32 a un PC o a un Mac è semplicissimo. Basta collegarlo al computer usando un cavo USB-C, scaricare i tool necessari e caricare il codice sulla scheda tramite terminale. Su Mac, si può usare Python e il suo pacchetto ESPHome, installato tramite il gestore di pacchetti Python pip con il comando pip3 install esphome.

Una volta completata l’installazione, creare due file YAML: keyboard.yaml e secrets.yaml. Il file keyboard.yaml contiene tutto il codice per l’ESP32, mentre il file secrets.yaml memorizza in modo sicuro le credenziali Wi-Fi. Sarà inoltre necessario un file di font. In questo progetto ho utilizzato il font Nunito della libreria Google Fonts. È possibile trovarlo qui: https://fonts.google.com/specimen/Nunito. Scaricare ed estrarre il file, copiare il font in versione normale (Nunito-Regular.ttf) nella stessa cartella degli altri file e rinominarlo font.ttf.

Nota: questo codice è stato scritto appositamente per la scheda Seeed Studio XIAO ESP32-C3. Se utilizzate una scheda ESP32 diversa, dovrete modificare il parametro board: e le mappature dei pin GPIO in base al vostro hardware specifico. Se non siete sicuri di come fare, non esitate a chiedere al vostro assistente AI preferito di darvi una mano! 🙂

Ecco il file completo keyboard.yaml. Non lasciatevi intimidire dalle lunghe sezioni contrassegnate come lambda:. Queste gestiscono la logica di fondo, come la conversione dei dati grezzi di luminosità in percentuali (%) e la formattazione del testo sullo schermo OLED.

esphome:
  name: keyboard
  on_boot:
    priority: -100
    then:
      - sensor.rotary_encoder.set_value:
          id: rotary_knob
          value: 10
      - sensor.template.publish:
          id: ha_knob
          state: 10
      - binary_sensor.template.publish:
          id: ha_service_mode
          state: false

esp32:
  board: seeed_xiao_esp32c3

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

captive_portal:

api:
  on_client_connected:
    - lambda: |-
        id(ha_service_mode).publish_state(id(service_mode));
        id(ha_active_key_sensor).publish_state(id(active_text));
  services:
    - service: set_display_text
      variables:
        new_text: string
      then:
        - lambda: |-
            id(active_text) = new_text;
            id(ha_active_key_sensor).publish_state(new_text);
            id(oled_display).update();

logger:
  baud_rate: 115200

i2c:
  sda: 6
  scl: 7

globals:
  - id: active_text
    type: std::string
    initial_value: '"OFF"'
  - id: service_mode
    type: bool
    initial_value: 'false'
  - id: saved_light_steps
    type: int
    initial_value: '10'
  - id: display_steps
    type: int
    initial_value: '10'

script:
  - id: block_feedback_script
    mode: restart
    then:
      - delay: 800ms

font:
  - file: "font.ttf"
    id: font_large
    size: 14
  - file: "font.ttf"
    id: font_sub
    size: 10

text_sensor:
  - platform: template
    name: "Active Key"
    id: ha_active_key_sensor

sensor:
  - platform: template
    name: "Rotary Knob"
    id: ha_knob

  - platform: rotary_encoder
    id: rotary_knob
    pin_a: 21
    pin_b: 20
    min_value: 0
    max_value: 10
    resolution: 2
    on_value:
      then:
        - lambda: |-
            if (isnan(x)) return;
            if (id(service_mode)) {
              if (x == 0) id(rotary_knob).set_value(1);
              id(oled_display).set_contrast(id(rotary_knob).state / 10.0);
            } else {
              if (x == 0 and id(ha_light_state).state) id(rotary_knob).set_value(1);
              id(block_feedback_script).execute();
              id(ha_knob).publish_state(id(rotary_knob).state);
            }
        - component.update: oled_display

  - platform: homeassistant
    id: ha_light_brightness
    entity_id: light.office
    attribute: brightness
    on_value:
      then:
        - lambda: |-
            if (not id(service_mode) and not id(block_feedback_script).is_running() and not isnan(x)) {
              int steps = round((x / 255.0) * 10.0);
              id(rotary_knob).set_value(steps);
              id(ha_knob).publish_state(steps);
            }
        - component.update: oled_display

binary_sensor:
  - platform: template
    name: "Service Mode"
    id: ha_service_mode

  - platform: status
    id: ha_connection_status

  - platform: homeassistant
    id: ha_light_state
    entity_id: light.office
    filters:
      - delayed_off: 500ms
    on_state:
      then:
        - lambda: |-
            if (not x) {
              if (not id(service_mode)) {
                id(rotary_knob).set_value(0);
                id(ha_knob).publish_state(0);
              } else {
                id(saved_light_steps) = 0;
              }
              id(active_text) = "OFF";
              id(ha_active_key_sensor).publish_state("OFF");
              id(oled_display).update();
            }

  - platform: gpio
    name: "Encoder Press"
    pin: {number: 8, mode: INPUT_PULLUP, inverted: true}
    on_press:
      then:
        - lambda: |-
            float current_state = isnan(id(rotary_knob).state) ? 10.0 : id(rotary_knob).state;
            if (not id(service_mode)) {
              id(saved_light_steps) = (int)current_state;
              id(service_mode) = true;
              id(rotary_knob).set_value(id(display_steps));
              id(ha_service_mode).publish_state(true);
            } else {
              id(display_steps) = (int)current_state;
              id(service_mode) = false;
              id(rotary_knob).set_value(id(saved_light_steps));
              id(ha_knob).publish_state(id(saved_light_steps));
              id(ha_service_mode).publish_state(false);
            }
        - component.update: oled_display

  - platform: gpio
    name: "Key 1"
    pin: {number: 2, mode: INPUT_PULLUP, inverted: true}
  - platform: gpio
    name: "Key 2"
    pin: {number: 3, mode: INPUT_PULLUP, inverted: true}
  - platform: gpio
    name: "Key 3"
    pin: {number: 4, mode: INPUT_PULLUP, inverted: true}
  - platform: gpio
    name: "Key 4"
    pin: {number: 5, mode: INPUT_PULLUP, inverted: true}
  - platform: gpio
    name: "Key 5"
    pin: {number: 9, mode: INPUT_PULLUP, inverted: true}
  - platform: gpio
    name: "Key 6"
    pin: {number: 10, mode: INPUT_PULLUP, inverted: true}

display:
  - platform: ssd1306_i2c
    id: oled_display
    model: "SSD1306 128x32"
    address: 0x3C
    rotation: 180
    lambda: |-
      if (id(service_mode)) {
        it.print(0, 0, id(font_large), "DISPLAY");
      } else {
        it.print(0, 0, id(font_large), id(active_text).c_str());
      }
      
      if (id(ha_connection_status).state) {
        it.print(82, 0, id(font_sub), "HA: OK");
      } else {
        it.print(82, 0, id(font_sub), "HA: --");
      }
      
      it.printf(0, 19, id(font_sub), "Int: %.0f%%", isnan(id(rotary_knob).state) ? 0.0 : id(rotary_knob).state * 10.0);
      
      if (wifi::global_wifi_component->is_connected()) {
        it.print(75, 19, id(font_sub), "Wi-Fi: OK");
      } else {
        it.print(75, 19, id(font_sub), "Wi-Fi: --");
      }

La password del Wi-Fi si trova in un file separato secrets.yaml. Createlo e modificatelo inserendo le vostre credenziali:

wifi_ssid: "my_wi-fi"
wifi_password: "my_secret_password"

A questo punto, è possibile compilare e caricare il codice sul proprio ESP32 utilizzando il comando python3 -m esphome run keyboard.yaml. Ricordarsi di eseguire questo comando dall’interno della cartella in cui si trova il file YAML. Quando richiesto dal terminale, digitare il numero corrispondente alla porta USB collegata e premere Invio.

Se il caricamento è andato correttamente, nel terminale dovrebbe apparire il log di comunicazione tra il computer e l’ESP32 e il display dovrebbe accendersi.

Tra le altre cose, il display mostra anche informazioni sullo stato della connessione Wi-Fi, che dopo pochi secondi dovrebbe indicare “OK”. Sul display è inoltre presente una riga “HA”, che rappresenta lo stato della connessione a Home Assistant. Per ora non è necessario preoccuparsi di questo stato. Non appena avremo configurato tutto in HA, dovrebbe apparire “OK”.

Se nei log compaiono le informazioni e il display le mostra, significa che l’ESP32 è stato aggiornato correttamente e si può procedere alla configurazione di Home Assistant. È possibile lasciare l’ESP32 collegato a una porta USB del computer oppure utilizzare un qualsiasi alimentatore USB da muro standard da 5 V per alimentare il macropad.

Configurazione di Home Assistant

1. Aggiungere l’ESP32 a Home Assistant

Grazie all’integrazione nativa con ESPHome, Home Assistant dovrebbe riconoscere automaticamente il nuovo macropad.

• Andate su Impostazioni > Dispositivi e servizi nella dashboard di Home Assistant.
• Cercare nella parte superiore della scheda Integrazioni. Si dovrebbe vedere un dispositivo ESPHome appena rilevato denominato keyboard.
• Fare clic su Configura e seguire le istruzioni visualizzate sullo schermo per aggiungerlo alla configurazione.
• Nota: Se non compare automaticamente, cliccare su Aggiungi integrazione nell’angolo in basso a destra, cercare ESPHome e inserire l’indirizzo IP locale del proprio ESP32.

Una volta aggiunto, Home Assistant carica automaticamente tutti i tasti meccanici, l’encoder rotativo e l’interruttore della modalità di servizio.

2. Creazione dell’helper del gruppo Light

Per garantire che questo progetto rimanga elegante e universale, vogliamo evitare di specificare direttamente nel codice modelli di lampadine smart fisici. Creiamo invece un helper Gruppo luci. In questo modo, se sostituite le vostre lampadine, basterà aggiornare questo gruppo e la vostra automazione rimarrà completamente inalterata.

• Andare su Impostazioni > Dispositivi e servizi e cliccare sulla scheda Assistenti in alto.
• Cliccare su + Crea assistente nell’angolo in basso a destra.
• Scorrere verso il basso, selezionare Gruppo, quindi scegliere Gruppo luci.
• Assegnare un nome all’helper Office (questo genererà automaticamente l’ID entità richiesto: light.office).
• Sotto Membri, selezionare le luci smart fisiche effettive che desiderate controllare tramite il macropad.
• Fare clic su Invia / Crea.

Una volta collegato il Macropad e preparato il nostro gruppo luci, possiamo ora integrare il tutto con il nostro script principale di automazione.

• Andare su Impostazioni > Automazioni e scene e cliccare su Crea automazione.
• Selezionare Crea nuova automazione, poi cliccare sui tre puntini nell’angolo in alto a destra e scegliere Modifica in YAML.
• Cancellare il codice predefinito, incollare lo script qui sotto e cliccare su Salva.

In questa guida ho associato i sei tasti meccanici all’attivazione di semplici scenari cromatici (blu, verde, rosso, ecc.), ma è possibile personalizzarli per attivare qualsiasi scenario, sia esso semplice o avanzato.

alias: Light Office - Master Control
description: Master Control for Macropad
triggers:
  - entity_id: binary_sensor.keyboard_key_1
    to: "on"
    id: press_k1
    trigger: state
  - entity_id: binary_sensor.keyboard_key_2
    to: "on"
    id: press_k2
    trigger: state
  - entity_id: binary_sensor.keyboard_key_3
    to: "on"
    id: press_k3
    trigger: state
  - entity_id: binary_sensor.keyboard_key_4
    to: "on"
    id: press_k4
    trigger: state
  - entity_id: binary_sensor.keyboard_key_5
    to: "on"
    id: press_k5
    trigger: state
  - entity_id: binary_sensor.keyboard_key_6
    to: "on"
    id: press_k6
    trigger: state
  - entity_id: sensor.keyboard_rotary_knob
    id: knob_rotation
    trigger: state
conditions:
  - condition: state
    entity_id: binary_sensor.keyboard_service_mode
    state: "off"
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: knob_rotation
        sequence:
          - action: light.turn_on
            metadata: {}
            target:
              entity_id: light.office
            data:
              brightness_pct: "{{ (trigger.to_state.state | int(10)) * 10 }}"
      - conditions:
          - condition: trigger
            id: press_k1
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: Blue
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 4
                    - 51
                    - 255
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: Blue
      - conditions:
          - condition: trigger
            id: press_k2
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: Green
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 0
                    - 249
                    - 0
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: Green
      - conditions:
          - condition: trigger
            id: press_k3
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: Red
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 255
                    - 0
                    - 0
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: Red
      - conditions:
          - condition: trigger
            id: press_k4
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: Yellow
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 255
                    - 255
                    - 0
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: Yellow
      - conditions:
          - condition: trigger
            id: press_k5
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: Purple
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 255
                    - 0
                    - 255
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: Purple
      - conditions:
          - condition: trigger
            id: press_k6
        sequence:
          - choose:
              - conditions:
                  - condition: state
                    entity_id: sensor.keyboard_active_key
                    state: White
                sequence:
                  - action: light.turn_off
                    target:
                      entity_id: light.office
            default:
              - action: light.turn_on
                target:
                  entity_id: light.office
                data:
                  brightness_pct: 100
                  rgb_color:
                    - 255
                    - 255
                    - 255
              - action: esphome.keyboard_set_display_text
                data:
                  new_text: White
mode: restart

L’editor YAML in Home Assistant ha questo aspetto:

Prove e conclusioni

Una volta caricato tutto, è il momento di provare il macropad. Premete un tasto e la scena di illuminazione dovrebbe cambiare immediatamente. Ruotate l’encoder rotativo e l’intensità della luce varierà. Il display OLED dovrebbe inoltre visualizzare correttamente la scena attualmente selezionata.

Se tutto funziona alla perfezione, non resta che stampare la copertura inferiore e incastrarla in posizione. Grazie al design a incastro, rimane saldamente in sede senza bisogno di colla o viti. Dato che nella mia versione di prova ho mantenuto il cablaggio con ingombranti connettori Dupont, avevo bisogno di un po’ più di spazio all’interno, quindi ho realizzato un pezzo inferiore leggermente più alto. Il lato positivo è che ho approfittato di questa situazione per mescolare nuovamente diversi materiali Prusament Woodfill e creare una bella striscia di transizione. Se decidete di saldare i vostri componenti, potete snellire il file della copertura inferiore per ridurre significativamente l’altezza del macropad.

Anche se io uso questo macropad solo per controllare l’illuminazione, potete mapparlo su qualsiasi funzione della vostra casa smart. Con Home Assistant che gestisce la logica, basta premere un tasto o ruotare l’encoder per regolare le tapparelle, avviare un robot aspirapolvere o attivare un’automazione Spotify per fare un “Rickroll” ai vostri ospiti. Non ci sono limiti!

E una volta realizzato il vostro primo progetto di questo tipo, è difficile non guardarsi intorno in casa alla ricerca di altri spazi in cui una stampante 3D e qualche componente elettronico possano essere d’aiuto.

Buona stampa!