PiCockpit’s PiControl is a powerful feature which allows you to control your Raspberry Pi remotely from any web-browser, by simply clicking buttons. You will see the state and output of the command. New commands can be added by simply editing a JSON file on your Raspberry Pi – we’ll show you how to do it, and give you some ideas what you can build using PiControl!

How does it look like?

By default three commands are included and immediately available for your Raspi: ( power off, reboot, upgrade client)

Basic commands to control your Pi remotely using a webinterface - from any browser
This PiCockpit PiControl screenshot shows how the commands look like

What can I do with a Raspberry Pi and PiControl?

Here are some things which you can build with it. These ideas will require some research, and possibly coding and/or hardware knowledge on your part; In any case, PiCockpit’s PiControl will help you with the easy-to-use web-interface part of your project and save you tons of time making this work across the Internet 🙂

  • take a snapshot using the Raspberry Pi Camera module and have it mailed to you
  • start your Raspberry Pi Minecraft server, and stop it as well
  • Play a video using omxplayer (you can also set up an infinite loop for the video, and stop the video loop if you want to switch to another video)
  • create an easy control for a stop-motion animation camera, using the Raspberry Pi camera module
  • wake up a local computer in the same network as your Raspberry Pi with Wake on LAN functionality
  • play a sound (as a prank for Halloween, for example)
  • open a door – for example a garage door, by issuing appropriate control commands via Z-Wave, etc.
  • start the SSH service on your Raspberry Pi, and shut it down – a “knock to open” approach for improved security
  • control model trains
  • switch a relais on and off (will require two buttons, or can be done using a “toggle” button)
  • control the TV (switch channels, change volume, …) using an IR LED, for example to simulate activity while you are travelling
  • Launch a rocket from the web interface

We will publish step-by-step instructions for some of these project ideas, so you have an easy guide for getting started with PiControl and remotely controlling your Raspberry Pi.

How can I add additional remote command buttons for the Raspberry Pi with PiControl?

You can easily and securely define your own commands, by simply editing JSON files on your Raspberry Pi. This is done for security reasons – I could have written PiCockpit in a way which would allow you to add commands from the webinterface, but if someone would know your PiCockpit password, they could create any command they wished. Therefore, please follow these simple instructions to create a new JSON file on your Pi.

Note: these instructions are deliberately kept in a way which users who don’t have experience with the command line can follow. If you know how to use the command line, you might find it easier / faster to just create the file and edit it with nano.

First, you’ll need to open the file browser in super user mode (this step keeps your PiCockpit PiControl configuration files safe from any user or application wanting to tamper with them). Click on Raspberry Pi OS Menu, and here click the “Run …” command:

Raspberry Pi OS Menu, showing the run command.
The Raspberry Pi OS Menu. The Run command is near the bottom

Run pcmanfm as root (sudo pcmanfm) by typing “sudo pcmanfm” (without the quotes) in the dialog which opens, and clicking on OK:

Run command dialog on Raspberry Pi OS
The run command, preparing to run pcmanfm as root

A new window opens, showing you the contents of the /home/pi directory:

pcmanfm screenshot with super user rights
pcmanfm, the file manager running as super user

Note: you should see this icon, just under the “File” menu. It indicates that you are using pcmanfm as user root, and should therefore be extra careful (since root can edit / delete / move any file! even files which are critical for a normal system operation).

Root mode indicator

No worries, we’ll only touch the files you need here 🙂

Open the following directory on your Raspberry Pi:

/etc/picockpit-client/apps/com.picockpit/picontrol/modules

Showing the configuration directory for PiCockpit’s PiControl. Note, if you have a fresh installation of PiCockpit, you’ll only see core.json. The other modules were created by me for test and demonstration purposes (remote control experiments).

Tip: you can also copy & paste the path I’ve given above, and hit the enter key to navigate to the directory.

Raspi Berry’s helpful Raspberry Pi tips

right-click into the empty area next to the existing files, and select “New File…”.

Creating a new file with Raspbian OS
Raspberry Pi OS menu for a right-click to create a new file

Call the new file ssh-server.json:

A dialog asks for the name for the new file.
creating a new file as root user with pcmanfm
ssh-server.json is now created in this folder.

right-click the new file, to bring up the context menu. Choose “Geany”:

Context menu showing Geany the programmer's editor on Raspberry Pi OS
Geany is an editor which you can edit the file with
Geany programming editor screenshot
Geany shows the file ssh-server.json – nothing in it yet

Now you can see the new file we just created. It is empty so far.

Let’s create two new commands, one for shutting down the SSH server service, and one for starting it. Enter the following into the text field Geany shows you:

{
  "name": "SSH commands",
  "icon": "mdi-ssh",
  "handle": "ssh",
  "description": "Control the SSH server",
  "commands": {
    "ssh-stop": {
      "name": "SSH Server off",
      "icon": "mdi-server-minus",
      "description": "Shuts the SSH service down",
      "confirm": true,
      "user": "root",
      "command": ["service", "ssh", "stop"]
    },
    "ssh-start": {
      "name": "SSH Server on",
      "icon": "mdi-server-plus",
      "description": "Starts the SSH service",
      "user": "root",
      "command": ["service", "ssh", "start"]
    }
  }
}
Adding the text in Geany. Pay attention to the brackets, and document structure and the words have to be spelled correctly for it to work.

At this point we should save the file. You can do this from Geany’s file menu, for example, by selecting Save. (Or use Ctrl + S):

Geany’s file menu

At this point our new commands have not appeared in the webinterface yet. We need to restart picockpit-client for this. Click on the “Run …” command in the Raspberry Pi OS menu, and type “sudo service picockpit-client restart” into the window before clicking on OK:

restarting the picockpit-client service using the run dialog
restarting a service from the Run dialog

Now have a look at your PiControl webinterface:

PiControl webinterface for remote control screenshot
A new button to jump quickly to the new SSH commands appeared
The new commands (buttons) which we added to the webinterface to run remote commands on the Raspi!

If you’ve typed everything correctly, the new commands will appear. If you have made a mistake in your JSON file (e.g. forgot a curly bracket), PiCockpit will simply ignore the “broken” file.

You can now try the commands. If you click on the button SSH SERVER OFF, you’ll be asked whether you really want to run the command. Click on ssh server off here as well, to actually run the command (or click cancel if you don’t want to after all).

A safeguard to keep you from executing dangerous commands by accidentally clicking them

PiCockpit will now run the command, you’ll see progress information – and after it’s finished running, you’ll see the following success indicator:

PiControl has successfully run “service ssh stop” on your Pi.

If you try to connect to your Pi now using SSH, the connection will be refused:

PuTTYNG showing a fatal error.
Network error: connection refused

Start the SSH server back up by clicking “SSH SERVER ON”. Now a connection will be possible again.

Congratulations! You’ve just created your very own set of commands which you can run from the web interface.

Stay on the page while you run commands – the status will currently be cleared if you navigate away. To determine whether the SSH server is running, you could build a PiDoctor test – PiControl is simply for executing remote actions on your Pi.

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

Remember to restart the picockpit-client when you add new commands, or update commands. You can also remove commands you don’t want to have, for example if you want to remove the capability to shut your Raspberry Pi down remotely.

Explanation of the remote command syntax

The file configures a new module for PiControl. It has a .JSON syntax, please make sure that you open and end with curly braces in a correct fashion, as presented in my example.

There is a head, which configures the module itself, and the commands (in the “commands” part). They share some common entries:

name

The “name” entries are human readable names which are shown to you in the web-interface

icon

The “icon” entries are optional to decorate your buttons and module. These are Material Design Icon names, for example “mdi-ssh”.

You can check out a full list of Material Design Icons here. Simply copy the name of the icon (including the mdi- in the beginning).

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

description

The “description” entries are optional and allow you to add a bit more information for the command or module.

handle

The “handle” entry is explicit for the module, and has to be unique amongst the modules. In the case of the commands, the handle is implicit. “ssh-stop” and “ssh-start” are the two handles I’ve used for the commands in my example.

You can choose anything as a handle, as long as it does not include the characters “/”, “+”, “$”, “*”. I recommend to stick to basic downcase ASCII characters, and using the “-“. The handle is required.

Your file can, by the way, have a different file name than the handle – I encourage you to use at least related names for the file name and the handle, so you can easily identify the module .JSON file on your hard drive.

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

The commands go into the “commands” block, and have additional configuration possibilities:

confirm

If “confirm” is present, and set to true, the PiControl web interface will show a confirmation dialog before actually running the command. This is useful for making sure “dangerous” commands don’t get executed by an accidental tap or click.

user

If “user” is present, the command will be run as this particular user (as root in our example, to ensure that we have sufficient privileges).

PiControl will run commands as user “pi” by default. You can also set it to other users with less privileges than “pi“.

If you try to run GPIO commands, or play videos using omxplayer, you might have to give your new user additional capabilities. The user pi has these required privileges by default. Usually these privileges are set by adding the user to a special group.

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

command

This is the actual command which should be run on your Raspberry Pi. Note that you have to replace the spaces in the command compared to as you would run it on the command line. For example,

service ssh start

should be written as:

["service", "ssh", "start"]

PiControl also supports chaining a sequence of commands (e.g. the usual apt-get update, apt-get upgrade sequence). Check out core.json for an example of how that is being done.

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

Conclusion: PiControl for your Raspberry Pi remote control needs

Using PiCockpit and PiControl, it’s really easy to add any remote command you want to run on your Raspi, and be able to control your Pi from a webinterface. For this to work the Raspberry Pi only needs an Internet connection – you do not have to be in the same network.

What would you like to build using PiCockpit and PiControl? Comment below, and I will try to help you with your project 🙂

PiControl screenshot showing buttons to remotely control omxplayer and controlling the Chrome webbrowser using the webinterface
This PiControl screenshot shows a custom module I’ve set up: control Chrome (Chromium), run videos in a loop using omxplayer, show YouTube videos on the Pi

With great power comes great responsibility – be careful of who you give access to to your PiCockpit interface, keep your password and API keys safe. Also make sure to “protect” dangerous commands, as discussed above, so that they don’t get executed by mistakingly clicking them.

Raspi Berry’s helpful Raspberry Pi (and PiCockpit) tips

Leave a Comment