Skip to content

Displays and Graphic Designer

Are you looking to control the designer during your regular work? Start with the Graphic Designer User Guide. This page is for add-on authors who want to pass their custom display resolution to the designer.

This page describes how the .newblk addon tells the ESP IDE the resolution of its own display. This allows the Graphic Designer to draw at the correct size, even if the project uses a different panel than the original 128×64 OLED.

Applies to add-ons with their own initialization block, such as SPI LCD, OLED or e-paper. It does not address the electrical connection of a specific module or its communication protocol. These are part of the driver in MicroPython.

What a designer needs to know

A Graphic Designer works with pixels. Before opening the canvas, he must know at least:

  • display width in pixels,
  • display height in pixels,
  • whether it is a monochrome profile or a profile marked as rgb or tricolor.

This data is not sent by MicroPython from the board. They are provided by the JavaScript part of the add-on directly in the browser. Therefore, before opening the designer, ESP IDE searches for the used initialization block on the Blockly workspace and obtains its profile from the registered add-on.

Important division of roles

Resolution registration only affects the designer in the ESP IDE. It does not initialize the display on the board and does not change the Python generated by the block. The initialization block must still correctly create the actual display driver in MicroPython.

How the active display is selected

ESP IDE provides window.ESPIDE_DISPLAY_TARGETS global API in later versions.

  1. The plugin registers the type of its initialization block and a function that returns the display profile.
  2. The IDE tracks the Blockly workspace. Only registered initialization blocks that are actually inserted in the project will be included in the selection.
  3. The last valid initialization block created or changed is active. The order of use is stored in the block data, so it is preserved even after saving and reopening the project.
  4. When you delete the active initialization block, the IDE will use the previous valid block. If there is no initialization block registered on the workspace, the designer will use the default profile 128 x 64 monochrome.

The mere presence of a block in the toolbox does not change anything. It's by design: the toolbox can contain OLED 128×64 and several add-ons for other displays at the same time. The designer is guided only by the block that the user actually inserted into the program.

The simplest fixed resolution addon

For a display that always has the same resolution, just add the following registration to the .newblk JavaScript section. Belongs before delimiter <!toolbox!>.

var myDisplayRoot_ = typeof window !== "undefined" ? window : this;

if (myDisplayRoot_.ESPIDE_DISPLAY_TARGETS &&
    typeof myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.register === "function") {
  myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.register(
      "my_display_init", function() {
        return {
          profileId: "my-display-84x48",
          width: 84,
          height: 48,
          mode: "mono",
          label: "My display — 84×48"
        };
      });
}

In this example:

  • myDisplayRoot_ is a safe reference to a browser global object. In ESP IDE it is normally window.
  • ESPIDE_DISPLAY_TARGETS is an API created by the ESP IDE, not a plugin variable.
  • "my_display_init" must be exactly the same text as the initialization block type in Blockly.Blocks["my_display_init"] and in the XML toolbox <block type="my_display_init">.
  • profileId is a stable internal profile identifier. Do not change it for no reason in other versions of the same panel.
  • width and height are dimensions in pixels, not physical dimensions in millimeters or inches.
  • label will be displayed to the user as the name of the selected profile.
  • mode can be mono, rgb or tricolor. If you don't specify it or use another value, the API normalizes it to mono.

The condition around the register is not unnecessary

The older ESP IDE does not yet recognize ESPIDE_DISPLAY_TARGETS. The first part of the condition checks if the API exists. The && operator will then no longer evaluate the second part if the first part is not valid. Therefore, the plugin loads without error in the older version, only the designer remains on the older 128×64 fallback.

Do not write the registration without this protection directly as window.ESPIDE_DISPLAY_TARGETS.register(...). In an older version of the IDE, the add-in would stop with an error while loading and its blocks might not be added to the toolbox.

Add-on with multiple panel options

One initialization block can offer multiple panels. In this case, the resolver must always return the profile of the currently selected panel. Keep the values in the dropdown as stable technical keys; the user translation belongs to the visible text of the item.

var MY_DISPLAY_PROFILES_ = {
  LCD_84X48: {
    width: 84, height: 48,
    profileId: "my-lcd-84x48",
    label: "LCD 84×48"
  },
  EPD_400X300: {
    width: 400, height: 300,
    profileId: "my-epd-400x300",
    label: "E-paper 400×300"
  }
};

function myDisplayProfile_(key) {
  return MY_DISPLAY_PROFILES_[key] || MY_DISPLAY_PROFILES_.LCD_84X48;
}

if (myDisplayRoot_.ESPIDE_DISPLAY_TARGETS &&
    typeof myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.register === "function") {
  myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.register(
      "my_display_init", function(block) {
        var profile = myDisplayProfile_(block.getFieldValue("PANEL"));
        return {
          profileId: profile.profileId,
          width: profile.width,
          height: profile.height,
          mode: "mono",
          label: profile.label
        };
      });
}

block.getFieldValue("PANEL") reads the current value of a dropdown field from a specific block on the workspace. This is why the resolver receives the argument block.

If changing the dropdown changes the resolution, it is advisable to explicitly mark the block as last used after the change. This little helper uses the same principle as the WeAct e-paper plugins:

function myDisplayMarkUsedLater_(block) {
  if (!myDisplayRoot_.setTimeout) return;
  myDisplayRoot_.setTimeout(function() {
    var targets = myDisplayRoot_.ESPIDE_DISPLAY_TARGETS;
    if (targets && typeof targets.markUsed === "function") {
      targets.markUsed(block);
    }
  }, 0);
}

Blockly.Blocks["my_display_init"] = {
  init: function() {
    var sourceBlock = this;
    var panelField = new Blockly.FieldDropdown(
        [["LCD 84×48", "LCD_84X48"], ["E-paper 400×300", "EPD_400X300"]],
        function(newValue) {
          myDisplayMarkUsedLater_(sourceBlock);
          return newValue;
        });
    this.appendDummyInput().appendField(panelField, "PANEL");
    // ... more initialization block inputs ...
  }
};

The deferred call via setTimeout(..., 0) will occur only after the field value change is complete. markUsed(block) writes the order of use only when the resolver for the block returns a valid profile.

For both the Display and designer blocks to work

Resolution registration is only the first part. The initialization block must generate variables that common blocks from the Display category already work with:

display = MyDisplay(...)
buffer = display.buffer
fbuf = display.fbuf

Meaning of variables:

The variable What must provide
display Physical display driver with method show() to send the image to the panel.
buffer Framebuffer byte array. Recommended source is display.buffer. It is used by the designer's live preview.
fbuf An object with the framebuf MicroPython drawing API, such as fill, pixel, line, rect, fill_rect, text, blit, and scroll.

The simplest driver inherits from framebuf.FrameBuffer. Then fbuf can be exactly the same object as display:

class MyDisplay(framebuf.FrameBuffer):
    def __init__(self, ...):
        self.buffer = bytearray(...)
        super().__init__(self.buffer, WIDTH, HEIGHT, framebuf.MONO_VLSB)
        self.fbuf = self

    def show(self):
        # Sending self.buffer to actual display.
        pass

Common drawing blocks and code from the designer draw to fbuf. The redraw block is called display.show(). If the add-in does not provide these variables or method, the profile in the designer may be the correct size, but the generated image will not be able to be drawn to the panel in the normal way.

Use existing designer block

There is no need to create a separate block for saving the graphic scene for a regular display. Use the standard block espide_display_designer from the Display category. When opened, it will automatically take over the active profile from the registered initialization block, keep the complete ESP IDE generator including dynamic layers and scene.dat support.

Manual resolution and preservation of user work

In the designer, the user can enter his own width and height. This option applies to the currently edited scene, is stored in the extension data of the scene espide.adaptive-display-v1 and takes precedence over the current display profile.

When opened, the behavior differs as follows:

  • an empty 128×64 unedited scene takes over the dimensions of the active initialization block;
  • a non-empty scene or a scene with a manually set resolution does not recalculate itself when the user later changes the initialization block;
  • the designer will show the scene values as well as the active profile and offer an explicit action to use the display profile.

This prevents unexpected clipping or displacement of already drawn objects.

The size must be between 1 and 1024 pixels on each axis, and the framebuffer for the monochrome profile must not require more than 65,535 bytes. The IDE calculates the required size as width × ceil(height / 8).

Custom block with designer button (advanced)

Use it only when the plugin really needs its own Blockly block that owns a separate scene. The standard espide_display_designer block is a better choice for most displays.

API can connect scene saving and button to custom block:

Blockly.Blocks["my_display_scene"] = {
  init: function() {
    this.appendDummyInput().appendField("custom display screen");
    if (myDisplayRoot_.ESPIDE_DISPLAY_TARGETS &&
        typeof myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.attachDesigner === "function") {
      myDisplayRoot_.ESPIDE_DISPLAY_TARGETS.attachDesigner(this, {
        buttonLabel: "Open graphic editor"
      });
    }
    this.setPreviousStatement(true, null);
    this.setNextStatement(true, null);
  }
};

attachDesigner() preserves the block's already existing mutation handlers, saves the scene in the added mutation attributes, and adds methods getDisplayDesignerScene() and setDisplayDesignerScene(). But the Python generator of the custom block is still the responsibility of the plugin author. Therefore, do not use this procedure just to set the resolution.

In the older ESP IDE, this part is also protected by a condition. The block can load but does not have an adaptive designer button.

Backward compatibility of projects and add-ons

Registering a profile does not change the built-in designer block type or basic scene format. Newer adaptive resolution information is added as scene extension data.

  • Older IDEs without ESPIDE_DISPLAY_TARGETS load the addon due to the guard condition, but use the original 128×64 designer.
  • Older IDE will retain unknown scene extension data so project can be reopened in new version.
  • If the legacy IDE does not know the addon's own block type and the addon is not installed in it, it cannot load this block. This is a common rule for every .newblk accessory, regardless of the designer.

Display Add-on Author Checklist

  • The initialization block exists in Blockly.Blocks[...], both the Python generator and the XML toolbox under the same type.
  • The plugin securely registers this type via ESPIDE_DISPLAY_TARGETS.register(...).
  • Resolver returns correct width, height, stable profileId and comprehensible label.
  • With multiple panels, the resolver reads the correct block field and changing the option marks the block as used.
  • Generated Python will create display, buffer and fbuf before drawing blocks.
  • fbuf offers the drawing API framebuf and display.show() sends the framebuffer to the actual display.
  • Commonly used built-in block espide_display_designer; add your own scene block only if you really need it.
  • Registrations and possible attachDesigner() are protected by API existence check due to older versions of ESP IDE.
  • .newblk still contains exactly one delimiter <!toolbox!>.

Related pages