Převod Arduino knihovny do `.newblk` pomocí AI¶

AI může výrazně urychlit vytvoření doplňku pro ESP IDE, ale je dobré počítat s jednou důležitou věcí: Arduino knihovna se obvykle nepřevádí 1:1. Cílem není zachovat původní C++ kód, ale převést uživatelské API knihovny do bloků a připravit funkční MicroPython řešení pro ESP IDE.

Tato stránka navazuje na Generování doplňku pomocí AI a na detailní popis Formátu souboru .newblk.

Kdy to funguje dobře¶

Převod pomocí AI bývá nejrychlejší u knihoven, které:

obsluhují jednoduché I2C senzory nebo moduly
mají malé API, například begin, read, setMode, write
obsahují krátký ukázkový .ino program
nevyžadují složité přerušení, DMA nebo přímou práci s registry

Typické vhodné případy:

teplota, vlhkost, tlak, světlo
jednoduché displeje nebo expandéry
relé moduly, bzučáky, enkodéry, převodníky

Kdy počítat s ruční úpravou¶

Ruční zásah bývá potřeba hlavně tehdy, když Arduino knihovna:

je silně navázaná na Arduino.h, Wire, SPI, Stream, Print
používá přerušení, DMA, časově kritické smyčky nebo callbacky na nízké úrovni
je velká a má desítky metod, tříd a závislostí
používá makra, šablony, PROGMEM nebo přímý přístup do registrů
počítá s jiným runtime než MicroPython

V takové situaci je lepší chtít po AI menší praktický převod: jen nejdůležitější bloky a jednoduchý MicroPython driver.

Co připravit před zadáním do AI¶

Nejlepší výsledky dostaneš, když AI dáš co nejvíc konkrétních podkladů:

odkaz na GitHub repozitář knihovny nebo ZIP se zdroji
hlavní .h a .cpp soubory
ukázkový .ino program
README s popisem zapojení a API
seznam funkcí, které chceš vystavit jako bloky
cílovou desku nebo rodinu desek
informaci, jestli chceš i upload tlačítko pro pomocný .py soubor

Doporučený postup¶

Nevybírej celou knihovnu, ale jen 3 až 6 nejdůležitějších funkcí.
Rozděl si požadované bloky na init, čtení, nastavení, případně akce.
Pokud je knihovna jen tenká obálka nad I2C nebo SPI protokolem, nech AI vytvořit přímo MicroPython driver.
Pokud je potřeba pomocný .py soubor, nech AI přidat i toolbox tlačítko pro nahrání knihovny do /lib.
Hotový výstup zkontroluj podle stránky Formát souboru .newblk.
Doplněk nahraj přes Správce doplňků a potvrď Uložit změny.
Otestuj bloky na reálném zařízení podle původního example sketch.

Co má být výsledkem¶

Dobře připravený výstup obvykle obsahuje:

jeden kompletní soubor .newblk
definice Blockly.Blocks[...]
odpovídající Blockly.Python[...]
XML toolbox fragment za jedním delimiterem <!toolbox!>
volitelně metadata s pin_defaults
volitelně tlačítko pro upload pomocného Python souboru do /lib

Hotový prompt pro AI¶

Níže je připravený prompt, který můžeš zkopírovat do ChatGPT, Claude, Copilotu nebo jiného AI nástroje. Je postavený speciálně pro převod Arduino knihovny do formátu .newblk pro ESP IDE.

Před použitím nahraď placeholdery v závorkách svými daty a pokud můžeš, přilož k promptu i zdrojové soubory knihovny.

Jsi senior vývojář doplňků pro ESP IDE (Blockly 6.20210701.0 + MicroPython).

ÚKOL:
Chci převést Arduino knihovnu do jednoho funkčního doplňku `.newblk` pro ESP IDE.
Nevytvářej Arduino C++ kód pro běh v ESP IDE. Cílové prostředí je MicroPython. Pokud původní knihovna používá Arduino API, převeď její logiku do jednoduchého MicroPython driveru nebo do malého pomocného `.py` modulu, který půjde nahrát do `/lib`.

DŮLEŽITÁ PRAVIDLA PRO ESP IDE:
- Výstup musí být jeden kompletní soubor `.newblk`.
- Soubor musí obsahovat delimiter `<!toolbox!>` přesně jednou.
- Před delimiterem je JavaScript část, za delimiterem XML toolbox fragment.
- XML část nesmí být zabalená do `<xml>...</xml>`.
- Každý `<block type="...">` v XML musí mít definici v `Blockly.Blocks[...]`.
- Každý blok, který generuje kód, musí mít `Blockly.Python[...]`.
- Statement blok vrací string s `\n`.
- Value blok vrací `[code, Blockly.Python.ORDER_ATOMIC]`.
- Importy a pomocný Python kód ukládej do `Blockly.Python.definitions_`.
- Pokud použiješ v toolboxu `<button callbackKey="...">`, musí existovat `demoWorkspace.registerButtonCallback("...", async function(button) { ... })`.
- Pokud doplněk potřebuje výchozí piny, přidej metadata `pin_defaults` a v XML používej `data-pin-role`.
- Typy bloků zapisuj explicitně jako literály, neskládej je dynamicky.
- JavaScript musí být syntakticky platný pro Blockly 6.20210701.0.

JAK MÁŠ K PROBLÉMU PŘISTOUPIT:
1. Nejdřív analyzuj Arduino knihovnu a určuj jen uživatelsky důležité části.
2. Nepřeváděj všechno. Vyber jen praktické API vhodné pro bloky.
3. Pokud něco z Arduino světa nejde převést 1:1, navrhni nejbližší smysluplnou MicroPython variantu.
4. Preferuj malé a čitelné rozhraní: například `init`, `read`, `set`, `write`, `available`, `reset`.
5. Pokud knihovna potřebuje pomocný Python modul, vlož jeho obsah do JS stringu a přidej upload tlačítko do toolboxu.
6. Pokud existuje example sketch, použij ho jako hlavní podklad pro návrh bloků.

VSTUPNÍ DATA:
- Název knihovny: {{NAZEV_KNIHOVNY}}
- Odkaz na repo nebo zdroje: {{ODKAZ_NEBO_POPIS_ZDROJU}}
- Hlavní soubory: {{SEZNAM_HLAVNICH_SOUBORU}}
- Ukázkový `.ino` program: {{UKAZKOVY_INO}}
- Jaké funkce chci vystavit jako bloky: {{SEZNAM_FUNKCI}}
- Cílové desky: {{CILOVE_DESKY}}
- Použitá sběrnice nebo rozhraní: {{I2C_SPI_UART_GPIO}}
- Doporučené výchozí piny: {{PINY_PRO_ESP32_ESP32C3_ESP32S3_RP2040}}
- Jazyk popisků bloků: čeština
- Chci upload tlačítko pro pomocný `.py` soubor: {{ANO_NE}}
- Prefix typů bloků: {{PREFIX_BLOKU}}
- Název výsledného souboru: {{NAZEV_SOUBORU}}.newblk

POŽADOVANÝ VÝSTUP:
A) Nejdřív krátce napiš:
- co bylo možné převést přímo,
- co jsi musel zjednodušit,
- co případně zůstává jako omezení.

B) Potom vrať jeden kompletní obsah souboru `.newblk` v jediném textovém bloku.

POVINNÁ STRUKTURA `.newblk`:
1. Volitelná metadata hlavička v komentáři `/* { ... } */`
2. JavaScript část s bloky, generátory a případnými callbacky
3. Přesně jeden delimiter `<!toolbox!>`
4. XML toolbox fragment

DOPORUČENÍ K NÁVRHU BLOKŮ:
- Vytvoř krátké názvy bloků, ale srozumitelné české popisky.
- Bloky navrhuj tak, aby odpovídaly běžnému použití knihovny v Arduino example.
- Pokud knihovna vrací několik hodnot, zvaž samostatné bloky pro jednotlivá čtení místo jednoho složitého bloku.
- Pokud je potřeba inicializace, přidej samostatný `init` blok.
- Pokud je potřeba import nebo vytvoření objektu, řeš to přes `Blockly.Python.definitions_`.

POŽADOVANÁ KVALITA:
- Výstup musí být prakticky použitelný v ESP IDE.
- Nepiš obecné vysvětlování navíc.
- Nevypisuj druhou alternativu řešení.
- Vrať nejlepší praktickou verzi doplňku.

Jak prompt používat co nejlépe¶

Nejlepší výsledek bývá, když k promptu nepřiložíš jen název knihovny, ale i konkrétní části zdrojáku.

Dobrá vstupní kombinace je:

README.md
jeden nebo dva hlavní .h / .cpp soubory
jeden funkční example sketch
vlastní seznam bloků, které opravdu chceš

Když AI dostane jen odkaz na repozitář bez zdrojů nebo bez příkladu použití, často navrhne příliš obecný nebo zbytečně složitý doplněk.

Jak výstup rychle zkontrolovat¶

Po vygenerování si ověř hlavně tyto body:

výstup obsahuje <!toolbox!> přesně jednou
bloky z XML opravdu existují v Blockly.Blocks[...]
bloky generující kód mají Blockly.Python[...]
pokud je v XML tlačítko, existuje i odpovídající callback
pokud jsou použité výchozí piny, sedí názvy v pin_defaults a data-pin-role
výstup je MicroPython řešení, ne Arduino C++ řešení

Typické chyby při převodu z Arduino světa¶

Nejčastější problémy jsou:

AI nechá ve výstupu #include <Arduino.h> nebo jiný Arduino kód
místo MicroPython driveru jen opíše původní C++ API
vytvoří příliš mnoho bloků najednou
v XML použije bloky, které nejsou definované v JS
zapomene na Uložit změny po nahrání doplňku přes Správce doplňků

Praktický tip¶

Když je knihovna větší, nezačínej převodem celé knihovny. Nech si nejdřív udělat malou první verzi jen pro základní inicializaci a jedno nebo dvě hlavní čtení. Jakmile ta funguje, můžeš AI zadat druhé kolo a doplnit další bloky.

Převod Arduino knihovny do .newblk pomocí AI¶