Naskenujete QR kód na krabičce, vyberete síť, zadáte heslo. Hotovo. Tak má vypadat první zapnutí chytrého zařízení s ESP32. Proto jsme vyvinuli Pairble, open-source komponentu, která připojí ESP32 k Wi-Fi asi za třicet sekund a bez instalace jakékoli aplikace. Uvolňujeme ji zdarma, i pro komerční výrobky.

Proč to vzniklo

Kdo někdy dělal zařízení s ESP32 pro někoho jiného než pro sebe, zná ten moment: firmware funguje, hardware funguje, a pak přijde první zákazník s otázkou „jak to připojím na Wi-Fi?“. Běžná řešení mají vždycky nějaký háček:

  • Captive portál (softAP): zákazník se musí ručně přepojit na Wi-Fi zařízení, telefon hlásí „bez internetu“ a sám se vrací na domácí síť. A když vybere síť na 5 GHz, zařízení se na ni nepřipojí.
  • Vlastní mobilní aplikace: „stáhněte si naši aplikaci“ je největší překážka, kterou můžete mezi zákazníka a výrobek postavit. Pro výrobce pak znamená údržbu dvou aplikací navíc.
  • Heslo natvrdo ve firmwaru: funguje jen vám doma.

Chtěli jsme něco, co zvládne i člověk, který nikdy nečte návod. Celý návod je teď QR kód na krabičce.

Jak to vypadá pro zákazníka

  1. Namíří fotoaparát telefonu na QR kód. Stačí běžná aplikace fotoaparátu.
  2. Objeví se karta „Nastavit Wi-Fi“. Na iPhonu se otevře App Clip, malý kousek aplikace, který se objeví z fotoaparátu a po použití zase zmizí. Android a počítač otevřou webovou stránku, která umí Bluetooth.
  3. Vybere svoji síť. Seznam nesestavuje telefon, ale samotné zařízení, takže ukáže jen sítě, na které se opravdu umí připojit.
  4. Zadá heslo. To putuje šifrovaně přes Bluetooth, zařízení se připojí a do dvaceti sekund odpoví: online, špatné heslo, nebo síť mimo dosah.
Pairble: nastavit zařízení Pairble: výběr Wi-Fi sítě Pairble: zadání hesla Pairble: zařízení je připojeno

Jak to vypadá naživo, ukazuje krátké video na YouTube. Bez hardwaru si to můžete vyzkoušet v živém demu na pairble.com.

Co dělá rozdíl v praxi

Každá z těchto vlastností vznikla proto, že se nám při nastavování skutečných zařízení něco pokazilo, a chtěli jsme, aby se to už nestalo.

  • Jen sítě, které budou fungovat. Doma máte „Novák“ a „Novák 5G“. Zařízení s čipem jen pro 2,4 GHz nabídne pouze „Novák“. Nejčastější dotaz na podporu („vybral jsem síť a nejde to“) tím zmizí.
  • Chyby, kterým člověk rozumí. Místo „Connection failed“ řekne Pairble, jestli je špatně heslo, nebo je síť mimo dosah. Překlep v hesle se opraví hned, bez restartu a bez začínání znovu.
  • Záložní cesta je součástí. Telefon bez Bluetoothu, bez internetu nebo se starým prohlížečem? Zařízení souběžně s Bluetooth otevře i vlastní Wi-Fi síť se stránkou nastavení uloženou ve flash. Druhý QR kód telefon na tuto síť rovnou připojí. Hodí se třeba na chatě bez signálu.
  • Přežije výměnu routeru. Když uložená síť přestane odpovídat, zařízení po dvou minutách samo znovu otevře nastavení a nic nevymaže. Router, který se jen restartoval, tak nic nerozbije. Po výměně routeru stačí naskenovat stejnou samolepku a vybrat novou síť.
  • Funguje i z počítače. Chrome nebo Edge na notebooku s Bluetooth zvládne totéž co telefon.
  • Deset jazyků. Stránka i App Clip se řídí jazykem telefonu: čeština, slovenština, angličtina, němčina, polština, francouzština, španělština, italština, portugalština a nizozemština.
  • Bezpečné ve výchozím stavu. Každý kus má vlastní náhodný kód, který je schovaný v QR kódu na krabičce. Připojit se k zařízení tak může jen ten, kdo ho drží v ruce a kód naskenoval. Heslo k Wi-Fi pak putuje šifrovaně (používáme ověřený protokol Espressif protocomm, na kterém stojí i oficiální nastavení Wi-Fi přes Bluetooth od Espressifu). Kód je v části webové adresy za znakem #, kterou telefon nikam neposílá, takže se nedostane do logu žádného serveru. A heslo k Wi-Fi se nikdy nezapisuje ani do logu zařízení.

Pro vývojáře: jeden příkaz a jedno volání

Pairble je komponenta pro ESP-IDF 5.1 a novější a zároveň knihovna pro Arduino (arduino-esp32 3.x, PlatformIO). Podporuje čipy ESP32, ESP32-C2, C3, C5, C6 a S3 a ve flash zabere zhruba 35 kB.

Přidání do projektu v ESP-IDF:

idf.py add-dependency "pairble/pairble"

A celý firmware, který zařízení buď připojí k uložené síti, nebo otevře nastavení:

#include "esp_log.h"
#include "pairble.h"

void app_main(void)
{
    /* Připojí se, pokud je uložená síť, jinak otevře nastavení. */
    ESP_ERROR_CHECK(pairble_start(NULL));
    /* Tato adresa patří do QR kódu na krabičce. */
    ESP_LOGI("example", "QR code: %s", pairble_setup_url());
}

V Arduinu je to stejné volání. Objekt WiFi o připojení ví, takže HTTPClient a vše ostatní funguje jako obvykle. V PlatformIO stačí do platformio.ini přidat lib_deps = pairble/pairble-arduino (s platformou pioarduino pro arduino-esp32 3.x).

#include <WiFi.h>
#include <pairble.h>

void setup()
{
    Serial.begin(115200);
    ESP_ERROR_CHECK(pairble_start(NULL));
    Serial.printf("QR code: %s\n", pairble_setup_url());
}

Pairble nesahá na nic, co si aplikace nastavila sama. Přes callback se dozvíte, kdy blikat LED (nastavení je otevřené), kdy začít vlastní práci (zařízení je online) a kdy je offline. Nastavení jde znovu otevřít podržením tlačítka, třemi rychlými zapnutími (u zařízení bez tlačítka) nebo voláním pairble_open_setup() z vlastního menu. Zařízení přitom zůstává na staré síti, dokud nová nefunguje.

Pro výrobu: samolepka a jeden příkaz na kus

V sériové výrobě je lepší mít kód vytištěný na štítku, než aby si ho každý kus vymyslel sám při prvním zapnutí. Na to je nástroj pro příkazovou řádku. Z MAC adresy odvodí jen název zařízení (třeba LAMP-BA6550), samotný kód vygeneruje náhodně (60 bitů, z MAC ani názvu ho nejde zjistit) a připraví QR kód na samolepku i soubor, kterým se kód zapíše do zařízení:

npx @pairble/cli unit --mac 20:6e:f1:ba:65:50 --prefix LAMP- --out unit-0001

K tomu vlastní Bluetooth identita (prohlížeč pak nabízí jen vaše zařízení) a vlastní prefix názvu. Adresa nastavení může zůstat pairble.com, které je zdarma i v produkci.

Licence a odkazy

Pairble je open source pod licencí Apache-2.0, zdarma i pro komerční výrobky a bez omezení počtu kusů.

Hledáme lidi, kteří chtějí Pairble vyzkoušet na skutečných výrobcích. Co vám chybí, co nefunguje, co by mělo být jinak? Otevřete issue na GitHubu nebo napište na [email protected].