File format .newblk¶
The file .newblk is a text plugin for ESP IDE. Combines in one file:
- JavaScript part with block definition
- Python generators
Blockly.Python[...] - optional add-on metadata
- XML fragment of the toolbox
It is used for custom blocks, special toolbox categories and buttons for auxiliary actions, for example uploading the library to the processor.
The most important rule
The file must contain the delimiter <!toolbox!> exactly once. Without it, the IDE will reject the add-on. If there are more than one in the file, the parser will only take the first two parts and the rest may be lost.
How the file is split¶
.newblk has two main parts:
- JavaScript part
- XML toolbox fragment
These parts are separated by exactly this string:
<!toolbox!>
Recommended file skeleton:
/*
{
"id": "my_extensions",
"name": "My extension",
"description": "Short description of add-on",
"version": "1.0.0",
"author": "Author"
}
*/
Blockly.Blocks['my_init'] = {
init: function() {
this.appendDummyInput().appendField("My init");
this.setPreviousStatement(true, null);
this.setNextStatement(true, null);
this.setColour("#00979d");
}
};
Blockly.Python['my_init'] = function(block) {
return "print('init')\\n";
};
<!toolbox!>
<category name="My extension" colour="#00979d">
<block type="moje_init"></block>
</category>
1. Metadata header¶
Metadata is optional, but is strongly recommended for larger plugins. They are written at the beginning of the file in a block comment.
Typical Items:
id– internal add-on identifiername– display namedescription- brief descriptionversion– add-on versionauthor- authortags- Labelsscreenshots- preview imageschangelog– brief version changeexample- 6 Character Shared Sample Project Codepin_defaults– default pins by processortoolbox_mode- optional advanced toolbox behavior
Practical recommendations:
idkeep without spaces and without diacriticsidshould be unique- for larger add-ons, also fill in
versionandchangelog - if the plugin has a sample project, fill in
examplewith the code from the ESP IDE share - write metadata as close as possible to valid JSON
The parameter example is used in the add-ons catalog. If filled with a valid 6-character shared project code, the catalog will display the Open example button next to the add-on.
Sample:
"example": "AB12CD"
The code must match the normal project share code in ESP IDE, i.e. exactly 6 characters A-Z or 0-9. The shared project must be stored in the standard repository /share, just like other projects created through the sharing function.
Good practice
If you modify the add-on over time, keep id stable and only change version and changelog. The user will then more easily recognize that it is a newer version of the same add-on.
2. JavaScript part¶
The JavaScript section contains everything the IDE needs to create and handle blocks.
This typically includes:
Blockly.Blocks[...]block definitionsBlockly.Python[...]Python code generators- auxiliary functions
- library texts sent to the device
- toolbox button callbacks
The most important rules:
- each
<block type="...">used in XML must have a definition inBlockly.Blocks[...] - each block that generates code should have a corresponding
Blockly.Python[...] - A JavaScript error may prevent the entire plugin from loading
Short example:
Blockly.Blocks['moje_init'] = {
init: function() {
this.appendDummyInput().appendField("My initialization");
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¶
The delimiter is followed by an XML part. It is recommended to write it without the outer wrapper <xml>...</xml>.
Correct shape:
<category name="AHT10/AHT20" colour="#00979d">
<block type="aht_init"></block>
<block type="aht_temperature"></block>
</category>
In XML, the following are most often used:
<category>– toolbox section<block>– blocks<label>– text note in toolbox<button>– button with callback
Practical rules:
- each
typein XML must match a block name in JS - The XML fragment should be as simple and readable as possible
- use
shadowblocks for default values
4. Callbacks for toolbox buttons¶
Add-ons can display a button in the toolbox. This is useful for example for:
- uploading the library to the processor
- opening the configuration dialog
- starting the auxiliary action before the first use
Button in XML:
<button text="Upload library to device" callbackKey="upload_lib_file_pid_controller"></button>
Corresponding registration in JavaScript:
demoWorkspace.registerButtonCallback("upload_lib_file_pid_controller", async function(button) {
if (!isEditorConnected()) {
Swal.fire("Error", "The device is not connected!", "error");
return;
}
// addon custom action
});
What to watch out for:
callbackKeyin XML and the name inregisterButtonCallback(...)must be exactly the same- if there is a button in the XML without a registered callback, it will not work correctly
- use unique callback names, ideally prefixed with the plugin name
Recommended naming style:
upload_lib_file_aht20upload_lib_file_pid_controlleropen_config_moje_rozsireni
5. Pin defaults according to the processor¶
One of the most useful parts of the addon is pin_defaults. Thanks to it, one .newblk file can offer different default pins for ESP32, ESP32-C3 or RP2040.
Sample Metadata:
"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 }
}
In order for the pins to be written correctly in the toolbox, it is recommended to mark the relevant fields in the XML with the attribute 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>
Role recommendations:
- use small names without spaces
- keep the same names in
pin_defaultsanddata-pin-role - for common buses use consistent roles like
i2c_sda,i2c_scl,miso,mosi,sck,cs,rx,tx - item
defaultis good to fill almost always
How it works in practice
IDE will look at the currently selected processor. When it finds an exact match, it uses it. When it doesn't find it, it uses default. Therefore, the default is a good fuse for general or less common boards.
6. Optional toolbox modes¶
Some plugins also use toolbox_mode metadata, for example:
"toolbox_mode": "addon_only"
This is a more advanced mode for situations where the plugin is intended to function as a standalone set of blocks. This isn't usually needed for regular extensions, but it's good to know the option exists.
7. Add-ons for display and Graphic Designer¶
If the add-in initializes its own display, it is not enough to just generate the MicroPython driver. In order for the Graphic Designer to use the correct resolution, the JavaScript part must safely register the initialization block type via window.ESPIDE_DISPLAY_TARGETS.register(...).
At the same time, the initialization generator usually creates the variables display, buffer, and fbuf. Common drawing blocks and designer code draw to fbuf; the redraw block calls display.show().
The full procedure for fixed and switchable panels, active display rules, manual resolution, custom scene block and backward compatibility can be found on the Displays and Graphic Designer page.
8. The most common errors¶
The most common problems when creating an add-on:
- delimiter
<!toolbox!>is in the file more than once - delimiter appears in a comment or string and breaks the parser
- there is a block in XML that has no definition in
Blockly.Blocks[...] - the block has a definition, but it is missing
Blockly.Python[...] callbackKeyin XML does not match callback registration in JS- metadata
idconflicts with another add-on - names in
pin_defaultsdo not matchdata-pin-role - addon is imported but user does not click
Save changes
9. Minimum checklist before import¶
Before uploading the plugin to ESP IDE, check:
- the file is saved as
.newblk - delimiter
<!toolbox!>is exactly one - all blocks from XML also exist in JS
- code generating blocks have
Blockly.Python[...] - callbacks have the correct
callbackKey - pin roles are consistent
- if filled
exampleis exactly 6 characters long and corresponds to an existing shared project - after importing in the
Add-on managerwindow, click onSave changes