DIY Projects

Domoticz: Lua script to create a remote OLED display with ESP Easy

In the previous tutorial we saw how to create a remote display for the Jeedom home server using an OLED screen configured with the ESP Easy firmware. Impossible not to explain how to do the same with Domoticz! We have to do with the constraints of the firmware ESP Easy, except to develop its own plugin (everything is explained here), we will have to drive the display directly using HTTP requests from Domoticz.

The Lua scripts

I’m not going to do a tutorial on Lua scripts (unless you insist ;-)), there are already very good on the internet like that of We just need to make a few quick reminders:

The full Wiki about the Lua scripts is here.

How to create the Lua script (SSH)

For a reason that still escapes me (bug?), It does not seem possible to edit the scripts present in the directory scripts from the event manager. It will therefore have to be created on a text editor then download the file in FTP or edit the script directly on the Domoticz server in SSH using nano. I opted for this solution in order not to encounter problems encoding (UTF-8) and end-of-line characters. If you’re new to Linux, follow this guide to learn more about SSH.

Log in to Domoticz in SSH (using putty on Windows, from Terminal on MacOS and Linux). Place yourself in the scripts directory.

Trick. For Mac users, the tilde (~) is obtained with the key combination ALT + N. Thank you Steve!


Open a new script called script_device_outside.lua . Here, we will send on the remote screen the temperature of an external sensor that works with the firmware MySensors.

Some elements of Lua language before starting

Before starting the script, here are some elements of language that can be used for other scripts

Lets you comment on a line. for example

– this is a comment

print() Displays a message in the log (Log) accessible from the Settings menu. Example

print(“Add a message to the log”)

chaine=”%20″ To create a variable containing a string, simply declare it and assign a value to it. for example




Concatenates strings of characters (also a variable containing a string). for example

BaseurlESP..’oled,1,3,Temp’.. space

fin de ligne Unlike many languages (C ++, Javascript …), there is no end-of-line character. Be careful, then, to encode the file!


Lets you know if a device has changed state or value. Useless in a _device script since it is just triggered when the Device changes.

if () then


The if loop in lua


Retrieves the value of the specified Device.

Encode special characters with the corresponding ASCII code

We will therefore have to manage ourselves the encoding of special characters. It is best to create a variable for each character that will be used in the HTTP request sent to ESP8266. Here are a few, you should all find them here.

-- Codes ASCII URL :

It is also used to create the base of the URL that is always identical. It will suffice to change the IP address that corresponds to your ESP8266.

-- Variables
baseurlESPEasy = ""

All Lua scripts for Domoticz must return a commandArray that contains the commands to run. We take advantage of this to display in the log that the script has just executed.

commandArray = {}
print ("Update ESP Easy Oled Display")

A series of HTTP requests must be sent to ESP Easy. To do this, simply add a command in the commandArray array for each HTTP request. To start, delete the screen

commandArray[1]={['OpenURL'] = baseurlESPEasy..'oledcmd,clear' }

Now we update line by line the screen. For example, we write on line 3 and column 1, Temp: 19.5 * C. The string is assembled by replacing spaces and special characters with the ASCII code.

The degree (°) does not work (or I have not yet found how to do it!).

commandArray[2]={['OpenURL'] = baseurlESPEasy..'oled,3,1,Temp'['Exterieur']'*C' }

Finally, you can force the screen to be turned on with the command oledcmd, on.

commandArray[5]={['OpenURL'] = baseurlESPEasy..'oledcmd,on' }

The script must return an array commandArray

return commandArray

And here is the script in its entirety that you just paste into the file.

-- Codes ASCII URL :
-- Variables
baseurlESPEasy = ""

commandArray =  {}

print ("Update ESP Easy Oled Display")
commandArray[1]={['OpenURL'] = baseurlESPEasy..'oledcmd,clear' }
commandArray[2]={['OpenURL'] = baseurlESPEasy..'oled,1,1,**''Domoticz''**' }
commandArray[3]={['OpenURL'] = baseurlESPEasy..'oled,3,1,Temp'['Exterieur']'*C' }
commandArray[4]={['OpenURL'] = baseurlESPEasy..'oled,7,1,projetsdiy'..point..'fr' }
commandArray[5]={['OpenURL'] = baseurlESPEasy..'oledcmd,on' }

return commandArray

Save the script with CTRL + X then Y. As soon as the Device is updated, the remote display will also be updated. If nothing happens, go to the log to see if there is an error in the script.

Why not use Blocky?

It must be possible but Blocky is a bit blocked (pardon blocked) to do that. Unlike Jeedom, which knows how to encode the URL on the fly (replace spaces and special characters with their ASCII code), with Domoticz you have to do everything yourself. This is not a problem in itself, but with Blocky, it can quickly become a galley.

Prepare display OLED SSD1306 remote

Also a small stitch to remind you how to wire and configure a miniature monochrome OLED display (SSD1306).

Here, I suggest you add a button to turn on the screen for a while (here 10 seconds). It can be interesting to turn off the screen or simply by ecology. We will put a refresh time very long, or at least greater than the frequency of refreshing the data sent by Domoticz. This is necessary to prevent the display from being reset by ESP Easy. As ESP Easy does not have the data to display (they are sent by Domoticz directly), the screen will simply turn black.

The OLED screen connects to the I2C bus. By default, the GPIO4 pins (SDA, D2 of the ESP8266) and GPIO5 (SCL, D1 of EP8266) are used.

Any ESP8266 ESP-12 module, for example Wemos D1 Mini
OLED monochrome Display 168×64 pixels 0.96″


Official OLED display shield for Wemos. Compact

About 4,40€

x3 mini switches
Jumper Dupont

Here is the result obtained with the proposed Lua script.

Click to rate this post!
[Total: 0 Average: 0]
Exit mobile version