Formát souboru `.newblk`¶

Soubor .newblk je textový doplněk pro ESP IDE. V jednom souboru spojuje:

JavaScript část s definicí bloků
Python generátory Blockly.Python[...]
volitelná metadata doplňku
XML fragment toolboxu

Používá se pro vlastní bloky, speciální toolbox kategorie i tlačítka pro pomocné akce, například nahrání knihovny do procesoru.

Nejdůležitější pravidlo

Soubor musí obsahovat delimiter <!toolbox!> přesně jednou. Bez něj IDE doplněk odmítne. Pokud je v souboru víckrát, parser si vezme jen první dvě části a zbytek se může ztratit.

Jak je soubor rozdělený¶

.newblk má dvě hlavní části:

JavaScript část
XML toolbox fragment

Tyto části jsou oddělené přesně tímto řetězcem:

<!toolbox!>

Doporučená kostra souboru:

/*
{
  "id": "moje_rozsireni",
  "name": "Moje rozšíření",
  "description": "Krátký popis doplňku",
  "version": "1.0.0",
  "author": "Autor"
}
*/

Blockly.Blocks['moje_init'] = {
  init: function() {
    this.appendDummyInput().appendField("Moje init");
    this.setPreviousStatement(true, null);
    this.setNextStatement(true, null);
    this.setColour("#00979d");
  }
};

Blockly.Python['moje_init'] = function(block) {
  return "print('init')\\n";
};

<!toolbox!>

<category name="Moje rozšíření" colour="#00979d">
  <block type="moje_init"></block>
</category>

1. Metadata hlavička¶

Metadata nejsou povinná, ale u větších doplňků je silně doporučené je používat. Zapisují se na začátek souboru do blokového komentáře.

Typické položky:

id – interní identifikátor doplňku
name – zobrazovaný název
description – stručný popis
version – verze doplňku
author – autor
tags – štítky
screenshots – náhledové obrázky
changelog – stručná změna verze
example – 6znakový kód sdíleného ukázkového projektu
pin_defaults – výchozí piny podle procesoru
toolbox_mode – volitelné pokročilé chování toolboxu

Praktická doporučení:

id drž bez mezer a bez diakritiky
id by měl být unikátní
pro větší doplňky vyplň i version a changelog
pokud má doplněk ukázkový projekt, vyplň example kódem ze sdílení v ESP IDE
metadata piš co nejblíž validnímu JSONu

Parametr example se používá v katalogu doplňků. Pokud je vyplněný platným 6znakovým kódem sdíleného projektu, katalog u doplňku zobrazí tlačítko Otevřít příklad.

Ukázka:

"example": "AB12CD"

Kód musí odpovídat běžnému share kódu projektu v ESP IDE, tedy přesně 6 znaků A-Z nebo 0-9. Sdílený projekt musí být uložený ve standardním úložišti /share, stejně jako ostatní projekty vytvořené přes funkci sdílení.

Dobrá praxe

Pokud doplněk časem upravuješ, nech id stabilní a měň jen version a changelog. Uživatel pak snáz pozná, že jde o novější verzi stejného doplňku.

2. JavaScript část¶

JavaScript část obsahuje vše, co IDE potřebuje pro vytvoření a obsluhu bloků.

Typicky sem patří:

Blockly.Blocks[...] definice bloků
Blockly.Python[...] generátory Python kódu
pomocné funkce
texty knihoven posílaných do zařízení
callbacky tlačítek toolboxu

Nejdůležitější pravidla:

každý <block type="..."> použitý v XML musí mít definici v Blockly.Blocks[...]
každý blok, který generuje kód, by měl mít odpovídající Blockly.Python[...]
chyba v JavaScriptu může zabránit načtení celého doplňku

Krátký příklad:

Blockly.Blocks['moje_init'] = {
  init: function() {
    this.appendDummyInput().appendField("Moje init");
    this.setPreviousStatement(true, null);
    this.setNextStatement(true, null);
    this.setColour("#00979d");
  }
};

Blockly.Python['moje_init'] = function(block) {
  return "print('init')\\n";
};

3. XML toolbox fragment¶

Za delimiterem následuje XML část. Doporučuje se zapisovat ji bez vnějšího wrapperu <xml>...</xml>.

Správný tvar:

<category name="AHT10/AHT20" colour="#00979d">
  <block type="aht_init"></block>
  <block type="aht_temperature"></block>
</category>

V XML se nejčastěji používají:

<category> – sekce toolboxu
<block> – bloky
<label> – textová poznámka v toolboxu
<button> – tlačítko s callbackem

Praktická pravidla:

každý type v XML musí odpovídat názvu bloku v JS
XML fragment má být co nejjednodušší a čitelný
pro výchozí hodnoty používej shadow bloky

4. Callbacky pro toolbox tlačítka¶

Doplňky mohou v toolboxu zobrazit tlačítko. To je užitečné třeba pro:

nahrání knihovny do procesoru
otevření konfiguračního dialogu
spuštění pomocné akce před prvním použitím

Tlačítko v XML:

<button text="Nahrát knihovnu do procesoru" callbackKey="upload_lib_file_pid_controller"></button>

Odpovídající registrace v JavaScriptu:

demoWorkspace.registerButtonCallback("upload_lib_file_pid_controller", async function(button) {
  if (!isEditorConnected()) {
    Swal.fire("Chyba", "Zařízení není připojeno!", "error");
    return;
  }

  // vlastní akce doplňku
});

Na co si dát pozor:

callbackKey v XML a název v registerButtonCallback(...) musí být úplně stejný
pokud je v XML tlačítko bez zaregistrovaného callbacku, nebude fungovat správně
používej unikátní názvy callbacků, ideálně s prefixem názvu doplňku

Doporučený styl názvů:

upload_lib_file_aht20
upload_lib_file_pid_controller
open_config_moje_rozsireni

5. Pin defaults podle procesoru¶

Jedna z nejužitečnějších částí doplňku je pin_defaults. Díky ní může jeden .newblk soubor nabídnout jiné výchozí piny pro ESP32, ESP32-C3 nebo RP2040.

Ukázka metadat:

"pin_defaults": {
  "default": { "i2c_sda": 0, "i2c_scl": 1 },
  "ESP32":   { "i2c_sda": 21, "i2c_scl": 22 },
  "ESP32C3": { "i2c_sda": 8, "i2c_scl": 9 },
  "RP2040":  { "i2c_sda": 4, "i2c_scl": 5 }
}

Aby se piny správně propsaly do toolboxu, doporučuje se v XML označit příslušná pole atributem data-pin-role:

<block type="aht_init">
  <value name="i2c_sda">
    <shadow type="math_number">
      <field name="NUM" data-pin-role="i2c_sda">0</field>
    </shadow>
  </value>
  <value name="i2c_scl">
    <shadow type="math_number">
      <field name="NUM" data-pin-role="i2c_scl">1</field>
    </shadow>
  </value>
</block>

Doporučení pro role:

používej malé názvy bez mezer
drž stejné názvy v pin_defaults i v data-pin-role
pro běžné sběrnice používej konzistentní role jako i2c_sda, i2c_scl, miso, mosi, sck, cs, rx, tx
položku default je dobré vyplnit téměř vždy

Jak to funguje v praxi

IDE se podívá na aktuálně zvolený procesor. Když najde přesnou shodu, použije ji. Když ji nenajde, použije default. Proto je default dobrá pojistka pro obecné nebo méně obvyklé desky.

6. Volitelné režimy toolboxu¶

Některé doplňky používají i metadata toolbox_mode, například:

"toolbox_mode": "addon_only"

To je pokročilejší režim pro situace, kdy má doplněk fungovat jako samostatná sada bloků. Pro běžné rozšíření to obvykle není potřeba, ale je dobré vědět, že tato možnost existuje.

7. Nejčastější chyby¶

Nejčastější problémy při tvorbě doplňku:

delimiter <!toolbox!> je v souboru víckrát
delimiter se objeví v komentáři nebo stringu a rozbije parser
v XML je blok, který nemá definici v Blockly.Blocks[...]
blok má definici, ale chybí mu Blockly.Python[...]
callbackKey v XML neodpovídá registraci callbacku v JS
metadata id koliduje s jiným doplňkem
názvy v pin_defaults neodpovídají data-pin-role
doplněk se importuje, ale uživatel neklikne na Uložit změny

8. Minimální checklist před importem¶

Než doplněk nahraješ do ESP IDE, zkontroluj si:

soubor je uložený jako .newblk
delimiter <!toolbox!> je přesně jednou
všechny bloky z XML existují i v JS
bloky generující kód mají Blockly.Python[...]
callbacky mají správný callbackKey
pin role jsou konzistentní
pokud je vyplněný example, má přesně 6 znaků a odpovídá existujícímu sdílenému projektu
po importu v okně Správce doplňků klikneš na Uložit změny

Formát souboru .newblk¶