Introduction

What is PiConsole

PiConsole is a way to communicate between any device and your Raspberry Pi, even while you're away. You can enter commands to inquire about the status of the Pi, or run files, for example.

Connection

PiConsole v1 uses WebSocket (WS) to communicate to the Raspberry Pi. This method was abandoned in v1.1 in favor of a HTTP-based API.

Usage

Using PiConsole is easy. After setting up, you will be good to go. The web page will now always provide a gateway to your Raspberry Pi from a distance, as long as the Pi is powered and the script is running.

Script

You will need to following script running on your Pi to start receiving commands from PiConsole:

Script - V1.2Script - V1.1Script - V1

This script will start a server on your Raspberry Pi using Flask. The resulting URL for communication will be [YOUR-PI-IP]:57988/piconsole

PiConsole uses port 57988, which is in the private range of ports. The port number is specified to avoid problems with other applications you are running.

Setup

Enable Port Forwarding in your router settings. You have to create a Port Forwarding rule for the port 57988.

(optional): If you want to use a domain, create an A record pointing to your router's external IP

So for example, if you were to set such an A record for 'example.com', you would go to http://example.com:57988/ to access your server.

Run the script on your Raspberry Pi.

Cronjobs

Consider using a cronjob to automatically run the script on startup.

This way, if you reboot your Pi, it automatically runs the script, so you don't have to worry about downtime.

  • Open command prompt and enter: crontab -e
  • At the end of the cronjob file, add the following line:
    • @reboot /usr/bin/python3 /path/to/your/python/script.py > /path/to/logfile.log 2>&1
  • Replace the paths with valid filepaths leading to your script and log file.
  • Save the cronjob file and ensure it works by rebooting. The script will run in the background, so access your URL to test if the script ran.
  • Remember, PiConsole first waits 10 seconds before spinning up the server. This is done to make sure your Pi is fully started up to avoid problems. So your URL will only work after ~10 seconds after reboot.

    • Usage

    Postman

    We have created a Postman Collection to get you started. Click the button below:

    Postman Collection v1.2Postman Collection v1.1

    Make sure to replace the 'url' variable in the collection with your own domain (the {{url}} in the request path).

    To make the request on the web, you can press Postman's 'Code' button and select PHP - cURL.

    Commands

    PiConsole uses various predefined commands to communicate with the Raspberry Pi and gather information efficiently. It is important to check you have the right version's command list, because versions may miss or contain deprecated commands compared to the latest version.

    Command List

    status
    Checks if the Raspberry Pi is online or offline.
    Response: "Online" if reachable, "Offline" otherwise.

    temperature
    Retrieves and displays the current CPU temperature.
    Response: "Current temperature: [Temperature] °C".

    diskusage
    Provides details about disk usage (total, used, free space).
    Response: "Disk usage: [Usage Details]".

    memoryusage
    Provides details about memory (RAM) usage.
    Response: "Memory usage: [Usage Details]".

    ls
    Lists files and directories in the current directory.
    Response: "Listing files: [File List]".

    cat [filename]
    Displays the contents of a specified file.
    Response: "Contents of [filename]: [File Content]".

    networkinfo
    Provides network information (IP addresses, MAC addresses, etc.).
    Response: "Network information: [Network Details]".

    update
    Updates software packages.
    Response: "Software updated successfully" or "Failed to update software".

    reboot
    Initiates a reboot of the Raspberry Pi.
    Response: "Rebooting the Raspberry Pi...".

    shutdown
    Initiates a shutdown of the Raspberry Pi.
    Response: "Shutting down the Raspberry Pi...".

    ssh
    Provides the command to connect to the Raspberry Pi via SSH.
    Response: "To connect via SSH, use: ssh username@raspberry_ip".

    run [filename]
    Executes a specified Python file and displays the output.
    Response: "Output of [filename]: [Execution Output]" or "Error running [filename]: [Error Message]".

    Commands per version

    Commands - V1.2Commands - V1.1

    Endpoints

    /

    This is the root of your server. When using PiConsole, it will simply display "Running PiConsole [version number]".

    /piconsole

    This is the piconsole endpoint. This endpoint handles responding to commands. This endpoint is used to retrieve and send data to your Pi.

    /console

    When running the PiConsole script with the debug variable set to true, which is the case by default, you will have access to this page. It is a built-in Werkzeug/Flask python console, allowing you to enter Python code in the context of the application.

    Versions

    Overview

    Version # Date Method Changes
    v1.2 17/08/2023 HTTP API Added 'uptime', 'externalscript' & 'version' commands
    v1.1 16/08/2023 HTTP API Switched to HTTP API.
    v1.0 14/08/2023 Websocket (WS)