Dataplicity Developer Hub

Dataplicity Documentation

Here you'll find announcements for new features and comprehensive guides to help you integrate Dataplicity into your Raspberry Pi projects.

Get Started    Announcements

Remotely access Pi desktop

With Dataplicity Remote Shell you can access the terminal on your Pi from outside firewalls. Now with Dataplicity Wormhole, VNC and Websockify, you can access the desktop on your Pi from behind a firewall too!

Prerequisites

For the purposes of this guide, we'll assume that you have your Pi powered up, connected to the internet and have Dataplicity installed (see Getting started with Dataplicity). We'll also assume you are familiar with running sudo.

Make sure to free up port 80

If you have been going through other tutorials for wormhole you might have an application or a service already running on port 80. Make sure that nothing is running on port 80 prior to following the instructions in this article.

Overview

VNC (Virtual Network Computing) is a well established method of sharing the desktop from one device to another on the same network.

On the target device, a VNC server (in this guide we'll use 'tightvnc') is installed, and you'll use a VNC client (in this case 'noVNC') to access the device.

The VNC server will typically listen on port 5901 and will speak a protocol incompatible with standard web traffic (HTTPS). In this example we use 'websockify' to translate this traffic into websockets for transport over Dataplicity Wormhole, and we use noVNC to make the whole system accessible from your web browser.

Setup TightVNC

Open a Terminal window on your Pi and make sure you're at the pi@raspberrypi prompt. From there, install and run the 'tightvncserver' software package:

sudo apt-get install tightvncserver
tightvncserver

The first time you run TightVNC server, you'll be asked to choose a password. Write it down when you enter it. Entering a view-only password is optional, so you can either input one or just type 'N' (no) to omit this.

Create a script to start VNC

The command to run VNC manually is quite long and tedious, so we can create a script to save typing. At the Pi terminal, use a text editor to create a script called 'vnc.sh':

nano vnc.sh

This will create a file called vnc.sh and open it in the 'nano' text editor.

Add the file contents:

#!/bin/sh
vncserver :1 -geometry 1920x1080 -depth 24 -dpi 96

To save and exit nano, type Ctrl+X and Enter twice.

Next, make the script executable and run it:

chmod +x vnc.sh
./vnc.sh

If TightVNC is already running, you'll get a warning

You may get an 'already running as :1' message if VNC is already running. Since at this point we're just happy that it's running you can safely ignore the warning.

Configure TightVNC server to start at boot

VNC is most convenient when it starts automatically at boot, so we'll start by making an "init-script" in a text editor.

We need superuser permission to add a system start script, so switch to superuser:

sudo su

Create a file called 'vncboot' in the system init directory:

cd /etc/init.d/
nano vncboot

Copy the following script into the text editor:

#! /bin/sh
# /etc/init.d/vncboot

### BEGIN INIT INFO
# Provides: vncboot
# Required-Start: $remote_fs $syslog
# Required-Stop: $remote_fs $syslog
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Start VNC Server at boot time
# Description: Start VNC Server at boot time.
### END INIT INFO

USER=pi
HOME=/home/pi

export USER HOME

case "$1" in
 start)
  echo "Starting VNC Server"
  #Insert your favoured settings for a VNC session
  su - $USER -c "/usr/bin/vncserver :1 -geometry 1280x800 -depth 16 -pixelformat rgb565"
  ;;

 stop)
  echo "Stopping VNC Server"
  /usr/bin/vncserver -kill :1
  ;;

 *)
  echo "Usage: /etc/init.d/vncboot {start|stop}"
  exit 1
  ;;
esac

exit 0

To save and exit nano, type Ctrl+X and Enter twice.

Make the new init script executable and add it to the system boot list:

chmod 755 vncboot
update-rc.d vncboot defaults

You may optionally reboot your Pi at this point to check it's working.

Install the noVNC client on your Pi

NoVNC is available from GitHub, and to install it you'll need 'git'. At the root prompt (or via sudo) type:

apt-get install git websockify

Then to download noVNC:

git clone git://github.com/kanaka/noVNC

We're nearly there. When you start NoVNC on your Pi for the first time, you'll be asked to download and install websockify automatically. Do this.

Lastly, run the NoVNC mini-webserver (as root):

cd noVNC
./utils/launch.sh --vnc 127.0.0.1:5901 --listen 80

If you want to be able to launch websockify automatically as part of the boot process please add the following command at the end of /etc/rc.local file.

sudo nano /etc/rc.local

# start novnc server
sudo /home/pi/noVNC/utils/launch.sh --vnc 127.0.0.1:5901 --listen 80 &

Port 80 not available

If you've run one of the other examples which involved installing the NGINX web server, you might get an error which indicates port 80 is already in use. You'll first need to make this port available to websockify. The easiest way to do this is to stop NGINX by typing service nginx stop at the terminal.

If all goes well, you'll see the following output:

You can quit the NoVNC mini-webserver with Ctrl-C anytime, but you'll need to restart it by re-running launch.sh as above (or you can build your own init script for it!).

Your Pi is now ready.

Enable Wormhole

If you haven't already done so, log in to your Dataplicity account and go to the device (e.g. the Pi) you want to link to. At the top of the page will be a link to 'Activate Wormhole'.

Click the orange 'Activate Wormhole' link

Click the orange 'Activate Wormhole' link

Press it and enable Wormhole.

The link will contain your device ID. If you visit the link, you'll see a list of NoVNC-related files.

Visit the link as per below, but note you'll need to substitute <your-device-id> with the appropriate device ID of your device.

https://<your-device-id>.dataplicity.io/vnc.html?host=<your-device-id>.dataplicity.io&port=443

For example if your device ID is ABCDABCD, your link would be https://ABCDABCD.dataplicity.io/vnc.html?host=ABCDABCD.dataplicity.io&port=443

You should be presented with a dialogue box that asks for a password. This is the VNC password you configured earlier in this guide. The 'Token' box may be left blank.

...and there's your Pi's desktop.

Sweet :-)

Security considerations

Don't forget that when you switch on Wormhole, you are placing the web service hosted on your Pi directly on the wider internet. That's actually the point, but what it means is that you need to take special care with what you put online.

In this case VNC opens port 5901 and the noVNC mini-webserver opens port 80 on your Pi. While you've already put a password on your VNC connection, you only need to have them listening on localhost for Wormhole to work. It is not necessary to open these ports directly from your Pi to the wider world, and if your Pi is running on a public network it would be advisable to close them by installing a firewall.

We've put together some basic tips for Securing Wormhole - well worth a read.