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

espeay esp easy domoticz script lua ssd1306 oled display remote dht22
Share on facebook
Share on twitter
Share on linkedin
Share on pinterest
Share on email
Share on whatsapp
Table of Contents
drapeau france

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:

  • Lua scripts are stored in the ~/domoticz/scripts/lua  directory
  • There are three types of script. Domoticz makes the difference from the file name.
    • Script_device_DeviceName: The name of the device must be identical, so it is forbidden to use spaces and accented or special characters
    • Script_time_NomScript.lua: The script runs every minute. The script has 10 seconds to complete. Beyond that, it is stopped by Domoticz not to penalize other scripts and the system in general.
    • Script_variable_NameVariable.lua: starts a change of the given variable.
  • They must bear the extension lua

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 ligneUnlike 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.

esp8266 Wemos D1 miniAny ESP8266 ESP-12 module, for example Wemos D1 Mini
oled ssd1306 ecran i2cOLED monochrome Display 168×64 pixels 0.96″


wemos d1 mini oled shieldOfficial OLED display shield for Wemos. Compact

About 4,40€

mini switchx3 mini switches
jumper dupontJumper Dupont

Here is the result obtained with the proposed Lua script.

 espeay esp easy domoticz script lua ssd1306 oled display remote dht22

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

Thanks for your reading

Did you like this project ? Don't miss any more projects by subscribing to our weekly newsletter!

Are you having a problem with this topic?

Maybe someone has already found the solution, visit the forum before asking your question
  1. hi, what about the code needed to init, write, draw something to OLED screen ?

    Leave a Reply

    Read more
    Recent posts on the Forum
    DIY Projects
    DIY Projects
    %d bloggers like this: