Compilare un firmware custom per ESP8266 (Tasmota, ESPurna ecc.) con Atom

7 minuti di lettura
SCOPI DELLA GUIDA
  • Compilare, tramite l’ausilio del software Atom, il firmware Sonoff-Tasmota, rendendolo così installabile su un dispositivo compatibile basato su SOC ESP8266 (ITEAD Sonoff e simili)
  • Livello di difficoltà: basso
CONCETTI AFFRONTATI:
  • Compilazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI
  • un adattatore USB/TTL e relativo cavo di connessione USB (opzionale)
DISPOSITIVI FISICI UTILIZZATI:
  • Un computer (Apple, Windows o Linux).
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere effettuata da personale qualificato
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (la presente guida ha puro scopo didattico)
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere la garanzia.
Revisione guida: 1.0

ATTENZIONE: questa guida è parte della MASTERGUIDE inDomus dedicata alla riprogrammazione dei dispositivi basati su SOC ESP8266.

Abstract

Com’è noto, i dispositivi basati su SOC (System-On-A-Chip) ESP8266 (quelli della famiglia ITEAD Sonoff “Smart Home”, piuttosto che della Shelly “Home Automation Systems” e molti altri ancora) possono essere modificati in termini di firmware, ovvero nella porzione di software che ne decreta il funzionamento e ne esprime le funzioni.

ESP8266
il SOC ESP8266.

Per effettuare questa modifica firmware a grandi linee è necessario, nell’ordine:

  • collegare il computer al dispositivo (tramite un dispositivo ad hoc chiamato USB/TTL o FTDI);
  • impostare il dispositivo in modalità “flash” (una modalità specifica che consente la sovrascrittura, nella sua memoria interna);
  • caricare sul dispositivo il firmware.

Per essere “caricato” sul dispositivo, tale custom firmware dev’essere in formato binario, un unico file (solitamente con estensione “.bin“). Per dotarsi di tale file binario è necessario compilare il codice sorgente del firmware tramite, appunto, un compilatore.

Questa guida illustra in primis come installare e configurare il software gratuito Atom, mentre in seconda battuta illustra come compilare vari firmware. per SOC ESP8266.

Si parte

Installare e configurare Atom

ATOM LogoAtom è, in primis, un editor di testo molto potente e versatile. La sua particolarità sta nel fatto di essere modulare, ovvero prevede la possibilità di installare una serie di pacchetti aggiuntivi, tra i quali quelli necessari a compilare firmware/software, scrivere codice in diversi linguaggi e molto altro.

Ecco perché inDomus adotta Atom come editor preferito: non solo serve è utile a compilare firmware, come vedremo, ma è anche ottimo come editor per file di configurazione relativi agli HUB domotici e molto altro.

Atom si scarica gratuitamente (per Windows, macOS e Linux) dal sito https://atom.io/.
Una volta scaricato, installarlo come un qualunque freeware reperibile da Internet.

Per gli scopi della presente guida è necessario, una volta installato ed eseguito, installare un pacchetto aggiuntivo chiamato “platformio-ide“.

Per farlo recarsi presso:

  • su WindowsMenu: File > Settings > Install
  • su macOSMenu: Atom > Preferences > Install
  • su LinuxMenu: Edit > Preferences > Install

e nella buca di ricerca cercare, per l’appunto, “platformio-ide“. Una volta trovato il pacchetto, cliccare su “Install”.

ATOM install packages
scorri per ingrandire

Dopo l’avvenuta installazione chiudere e riaprire Atom , che a questo punto  provvederà a installare una serie di pacchetti integrativi in modo completamente automatico.

Al termine, PlatformIO chiederà di riavviare per un’ultima volta Atom.

Porta COM

Un adattatore USB/TTL (FTDI) è il semplice dispositivo che ci permette di mettere in comunicazione il nostro computer e il cuore del dispositivo basato su SOC ESP8266.

Senza bisogno, per il momento, di collegare tale dispositivo a quello da riprogrammare, provvedere invece a collegare quest’ultimo (tramite cavo USB) al nostro computer. In caso vengano richiesti dei driver, provvedere all’installazione.

Selezionare poi la voce di menu di Atom PlatformIO > Serial Monitor.
Si aprirà una finestra come segue:

Dopo un istante, nella voce “Port” verrà indicata quale porta COM il computer abbia assegnato al modulo USB/TTL.
Prenderne nota.
Scollegare ora il modulo dalla porta USB.

NOTA per gli utenti Apple: Atom dovrebbe identificare una porta diversa dalla classica COMx. Per capire come configurare la porta in questa casistica, far riferimento a questo thread. Al di lì di quanto espresso nel link, si ricordi sempre di installare il corretto driver per Mac del proprio adattatore USB/TLL.

Dopo aver installato il driver corretto, nel system report del Mac, alla voce USB, dovrà (collegando l’adattatore USB/TTL), una voce analoga a quella che segue:

FT232R on MacCompilare il firmware

Sonoff-Tasmota

Re” incontrastato tra i custom firmware dedicati ai componenti domotici basati su SOC ESP8266, Sonoff-Tasmota permette di introdurre un gran numero di funzioni e personalizzazioni, tra i quali protocolli di comunicazione aggiuntivi, gestione di sensori esterni e molto altro.

Ad ogni rilascio di nuova versione, Sonoff-Tasmota viene rilasciato già pre-compilato per tutti coloro che volessero limitarsi ad aggiornare una precedente versione già installata (utilizzando il supporto OTA – senza fili – magari usando TasmoAdmin); coloro che invece debbano installare Sonoff-Tasmota su un dispositivo per la prima volta, allora dovranno necessariamente proseguire nella lettura e dotarsi – utilizzando il compilatore di Atom – di un proprio file .bin.


Per configurare e compilare il firmware Sonoff-Tasmota esso va, innanzitutto, scaricato. È possibile farlo direttamente dalla pagina GitHub del progetto; una volta scaricato, è necessario decomprimere il file .zip dove si preferisce.

A questo punto, presso Atom, selezionare da menu la voce “File > Add Project Folder”  e poi selezionare la cartella dove si è precedentemente decompresso il file .zip contenente quindi il codice del firmware Tasmota.

A questo punto è possibile “configurare” il pacchetto software, configurazione che naturalmente finirà all’interno del file binario prodotto dalla compilazione e, con lui, sul dispositivo. Tasmota viene infatti fornito “di base”, senza personalizzazioni, le quali sono necessarie affinché, al termine della programmazione, il dispositivo basato su SOC ESP8266 possa operare correttamente.

Nello specifico, il processo è il seguente:

  • configurare il file “platformio.ini“;
  • configurare il file “sonoff/my_user_config.h“;
  • compilare il firmware.
platformio.ini

Ciò che andremo in prima battuta a personalizzare è il file “platformio.ini” .

La prima voce da configurare è “env_default“: tale voce comunica al compilatore quale porzione di codice compilare in base all’esigenze. Tale voce non può non essere configurata, pena errore in fase di compilazione.

La scelta può essere fatta in base all’elenco disponibile il quale, di default, è tutto “commentato” (tutte le righe presentano il prefisso “#“). È sufficiente rimuovere uno degli “#” (relativo alla riga di interesse) per rendere operativa, alla compilazione, la porzione di codice corrispondente.

Nell’esempio che segue configuriamo l’ambiente più tradizionale e standard, ovvero  “env_default = sonoff“:

scorri per ingrandire

Le voci commentate a seguire identificano le alternative, ovvero la compilazione o di una parte minimale del firmware (“env_default = sonoff-minimal“) oppure delle versioni complete in lingua (“env_default = sonoff-IT” è quella italiana), oppure quella standard (appunto, come suggerito sopra, “env_default = sonoff“).

Trovare poi la sezione “[core_active]” e configurarla come segue:

[core_active]
; Select one core set for platform and build_flags
platform                  = ${core_2_3_0.platform}
build_flags               = ${core_2_3_0.build_flags}
;platform                  = ${core_2_4_2.platform}
;build_flags               = ${core_2_4_2.build_flags}
;platform                  = ${core_2_5_0.platform}
;build_flags               = ${core_2_5_0.build_flags}
;platform                  = ${core_stage.platform}
;build_flags               = ${core_stage.build_flags}

questo farà sì che il firmware venga compilato utilizzando la piattaforma core di PlatformIO versione 2.3.0, quella comprovatamente più stabile (sopratutto nell’evitare continue disconnessioni Wi-Fi da parte del dispositivo, fenomeno che si presenta, talvolta, utilizzando altre versioni core superiori).

Trovare poi le seguenti voci (e appurare siano configurate come segue:

monitor_speed             = 115200
upload_speed              = 115200
upload_resetmethod        = nodemcu

Subito a seguire, identificare la voce “upload_port =“) e inserire come valore la COM che identifica , la quale può essere espressa

su Windowsupload_port = COM1
su macOS / Linuxupload_port = /dev/cu.usbserial-00000000

Configurare quindi la COM assegnata presso la voce “upload_port =“, indicando ovviamente la porta e scoperta nel passo precedente.

N.b. In caso la destinazione del file binario compilato sia un aggiornamento OTA (Over-The-Air), questo passaggio di configurazione della voce “upload_port =” può essere saltato.

Una volta completato il tutto, salvare e chiudere il file.

sonoff/my_user_config.h

Ora è necessario configurare nome e password della Wi-Fi nella quale il dispositivo dovrà entrare automaticamente all’accensione.

Aprire il file “sonoff/my_user_config.h” e trovare le voci “#define STA_SSID1” e “#define STA_PASS1“:

scorri per ingrandire

Inserire lì il nome della propria Wi-fi (nella prima voce) e la relativa password (seconda voce).

Infine, salvare e chiudere il file.

COMPILAZIONE

Ora siamo pronti per “compilare” il nostro pacchetto firmware.

Presso Atom, cliccare sul menu “Platform > Build“.
In caso vada tutto bene, la procedura dovrebbe produrre un output di questo tipo:

scorri per ingrandire

A questo punto il file (chiamato “firmware.bin“) sarà stato generato presso il file system del computer, presso il percorso “%directorycontenentetasmota/.pioevens/sonoff“.

Tale file rappresenta “il compilato” del custom firmware Sonoff-Tasmota, pronto ora ad essere installato sul dispositivo.

ESPurna

Per configurare e compilare il firmware ESPurna esso va, innanzitutto, scaricato. È possibile farlo direttamente dalla pagina GitHub del progetto; una volta scaricato, è necessario decomprimere il file .zip dove si preferisce.

A questo punto, presso Atom, selezionare da menu la voce “File > Add Project Folder”  e poi selezionare la cartella “/code” contenuta a sua volta dalla cartella dove si è precedentemente decompresso il file .zip.

A questo punto è possibile “configurare” il pacchetto software, configurazione che naturalmente finirà all’interno del file binario prodotto dalla compilazione e, con lui, sul dispositivo. Tasmota viene infatti fornito “di base”, senza personalizzazioni, le quali sono necessarie affinché, al termine della programmazione, il dispositivo basato su SOC ESP8266 possa operare correttamente.

Nello specifico, il processo è il seguente:

  • configurare il file “platformio.ini“;
  • configurare il file “espurna/config/general.h“;
  • compilare il firmware.
platformio.ini

Ciò che andremo in prima battuta a personalizzare è il file “platformio.ini” .

La prima voce da configurare è “env_default“: tale voce comunica al compilatore quale environment di codice compilare in base all’esigenze. Tale voce non può non essere configurata, pena errore in fase di compilazione.

Per decidere quale ambiente indicare è necessario scorrere il file fino alla voce

# ----------------------------_
# ESPURNA CORE BUILDS
# -----------------------------

ESPurna supporta molti, diversi tipi di dipositivi: i blocchi che seguono “ESPURNA CORE BUIDS” identificano i vari dispositivi, e la chiave inclusa dentro “[env: ]” nel blocco di proprio interesse è quella da indicare presso “env_default“.

Per esempio, il blocco che identifica il “Sonoff Basic” comincia con

[env:itead-sonoff-basic]

pertanto, per far sì che la compilazione generi un binario relativo a questo dispositivo, la voce “env_default” andrà configurata così: “env_default = itead-sonoff-basic“.

Scelto il dispositivo e quindi la chiave da inserire ala voce “env_default“, è necessario salvare e chiudere il file.

espurna/config/general.h

Ora è necessario configurare nome e password della Wi-Fi nella quale il dispositivo dovrà entrare automaticamente all’accensione.

Aprire il file “espurna/config/general.h” e trovare il seguente blocco:

// Optional hardcoded configuration (up to 2 networks)
#ifndef WIFI1_SSID
#define WIFI1_SSID                  ""
#endif

#ifndef WIFI1_PASS
#define WIFI1_PASS                  ""
#endif

e provvedere ad inserire, tra gli apici delle voci “#define WIFI1_SSID” e “#define WIFI1_PASS” rispettivamente il nome della prorpia Wi-Fi e la relativa password.

Infine è necessario salvare e chiudere il file.

COMPILAZIONE

Ora siamo pronti per “compilare” il nostro pacchetto firmware.

Presso Atom, cliccare sul menu “Platform > Build“.
In caso vada tutto bene, la procedura dovrebbe produrre un output di questo tipo:

PlatformIO ESPurna
scorri per ingrandire

A questo punto il file (chiamato “firmware.bin“) sarà stato generato presso il file system del computer, presso il percorso “%directorycontenentetasmota/.pioenvs/nome-dell-environment-compilato/firmware.bin“.

Tale file rappresenta “il compilato” del custom firmware ESPurna, pronto ora ad essere installato sul dispositivo.


ITEAD Sonoff BasicATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica ai Sonoff (e più generalmente ai dispositivi ESP8266), per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.

🔻 Clicca QUI per commentare l'articolo. 🔻