Skip to content

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:

  1. JavaScript part
  2. 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 identifier
  • name – display name
  • description - brief description
  • version – add-on version
  • author - author
  • tags - Labels
  • screenshots - preview images
  • changelog – brief version change
  • example - 6 Character Shared Sample Project Code
  • pin_defaults – default pins by processor
  • toolbox_mode - optional advanced toolbox behavior

Practical recommendations:

  • id keep without spaces and without diacritics
  • id should be unique
  • for larger add-ons, also fill in version and changelog
  • if the plugin has a sample project, fill in example with 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 definitions
  • Blockly.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 in Blockly.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 type in XML must match a block name in JS
  • The XML fragment should be as simple and readable as possible
  • use shadow blocks 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:

  • callbackKey in XML and the name in registerButtonCallback(...) 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_aht20
  • upload_lib_file_pid_controller
  • open_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_defaults and data-pin-role
  • for common buses use consistent roles like i2c_sda, i2c_scl, miso, mosi, sck, cs, rx, tx
  • item default is 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[...]
  • callbackKey in XML does not match callback registration in JS
  • metadata id conflicts with another add-on
  • names in pin_defaults do not match data-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 example is exactly 6 characters long and corresponds to an existing shared project
  • after importing in the Add-on manager window, click on Save changes

Related pages