Lucas Vogel

This is a full tutorial to get electron running on a raspberry pi 3B+, and how to make it stable, fullscreen, disable the screensaver, hide the cursor and launch automatically on boot.

If you just search for a simple way to show a website on a raspberry and nothing more, you might want to look into specialized kiosk distros for rasberry pi.

What if you where given a Raspberry Pi 3B+ and the task to display your software? It needs to be very flexible, robust, and easily interchangeable. I had this task. Normally, there are distros that are specially designed to display a software, and they are great, mostly. However in ths scenario we had a wild enterprise wifi setup and various other scripts running in the background, that we could not get running on those other distros. Frustrated, we came back to the standard Debian on a raspberry pi, and started to implement it on our own. So lets get started.

Download and install node

This is somewhat a more complicated part than it has to be. A lot of tutorials say that you can just install node with the standard package manager, however this did not work for us, because it installed the wrong version.

What you want is a node version for ARMv7, downloaded from the node website.

Link to Node download page

If you are unsure, you can use the following command to find out what Version you need:

uname -m

Then, unpack ist with the following command:

tar -xzf node-....tar.gz

then, to install it, copy it into your home folder:

cd node-v.... (the unpacked node folder)
sudo cp -R * /usr/local/

now you should be able to check your node and npm version:

node -v
npm -v

If this works, then congratullations! Node is correctly installed. Now to start with electron, you need a npm repo.

Setting up the electron app

To get started, follow the electron quickstart guide.

Link to Electron Quickstart Guide

If you then have your Electron App, you have to modify some parts in your code to make it fullscreen. In your main Javascript File (where you specify mainWindow = new BrowserWindow...) you have to add these lines:

 mainWindow = new BrowserWindow({
     ...
    frame:false //Possibly not working in future versions, possibly not required
  })

  mainWindow.setKiosk(true); //important

We did put our electron folder on the desktop.

Make electron stable

Well this is easy, right? There is just a function that does what you need. But what if your electron app crashes? This is not uncommon, especially if your application runs for a long time. Chromium sometimes behaves weirdly. We had a memory leak, but it was that small, that it only crashed after 4-10 days. Yes, days. Try to find that.

You may think that you can just reload the page. But that would be to clever, and it does not work. Instead, you can fix that by adding the following code in your main JS-File:

mainWindow.webContents.on('crashed', (e) => {
    app.relaunch();
    app.quit()
});

Make electron start automatically on boot

this is a weird one, especially because there are multiple ways to execute a piece of code on start. The best way we found was the following (on a Raspberry Pi): We will start the node start command, but with a specific path.

Edit the folowing file (for example, with nano):

sudo nano /etc/xdg/lxsession/LXDE-pi/autostart

There, you can add the following code as a new line:

npm start --prefix path/to/your/directory

or if this does not work, you can use

node /home/pi/.../index.js &

Just remember to modify it to use your own path to your electron folder.

So that is basically it! If this suits your needs, then great!

Disabling the Screensaver

To disable the screensaver and screen blanking, follow these steps:

Disable the screensaver

Hiding the cursor

However, we where unhappy that the cursor is not hidden. This was made intentionally by the developers, and they may have had a good reason for it, I just cannot understand it.

So all the tutorials didn’t work. One (not so clean way) of fixing it, is to set it via Javascript on the shown page. You may be able to inject this code with Electron into the website, or just add it to the website itself, but either way, it uses the same code:

function hideCursor(){
    document.body.style.cursor = "none"; 
}
setTimeout(hideCursor,1000);

this will automatically hide the cursor, if it is inside the body element. You could also hook this to window.onload.

So that’s it! Thanks for following the guide. You should now have a fullscreen electron app, that runs on a rasbperry pi 3B+, starts automatically, restarts when crashed, and hides the cursor.

Electron Kiosk App on Raspberry Pi 3B+