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
rgbortricolor.
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.
- The plugin registers the type of its initialization block and a function that returns the display profile.
- The IDE tracks the Blockly workspace. Only registered initialization blocks that are actually inserted in the project will be included in the selection.
- 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.
- 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 normallywindow.ESPIDE_DISPLAY_TARGETSis 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 inBlockly.Blocks["my_display_init"]and in the XML toolbox<block type="my_display_init">.profileIdis a stable internal profile identifier. Do not change it for no reason in other versions of the same panel.widthandheightare dimensions in pixels, not physical dimensions in millimeters or inches.labelwill be displayed to the user as the name of the selected profile.modecan bemono,rgbortricolor. If you don't specify it or use another value, the API normalizes it tomono.
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_TARGETSload 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
.newblkaccessory, 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, stableprofileIdand comprehensiblelabel. - With multiple panels, the resolver reads the correct block field and changing the option marks the block as used.
- Generated Python will create
display,bufferandfbufbefore drawing blocks. fbufoffers the drawing APIframebufanddisplay.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. .newblkstill contains exactly one delimiter<!toolbox!>.