PiDoctor Raspberry Pi System Health Monitor & Diagnostics Utility

To monitor your Raspberry Pi system’s health, you can use PiCockpit’s app PiDoctor. PiDoctor will also allow you to learn many details about your Raspberry Pi, including where it was manufactured, how much RAM it has, and so on.

Note: PiDoctor used to be stand-alone, but is now part of picockpit-client. The stand-alone version of PiDoctor (PiDoctor OS) has been discontinued, in favor of the version included in picockpit-client which has live diagnostics capabilities, and increases the number of available diagnostic modules. If you still want the historical version, scroll down to the bottom of this page and look at the FAQ.

Raspi Berry’s Historical development explanation

Using PiDoctor to diagnose your Raspberry Pi

How to run all Raspberry Pi health tests

PiDoctor, as the other PiCockpit apps is included for free for up to 5 Raspberry Pis.

  1. Log into PiCockpit (sign up if you do not have an account yet, it is free)
  2. Open the My Raspberry Pis page to access your Raspberry Pi overview
PiCockpit My Raspberry Pis overview
My Raspberry Pis overview, click on the Raspberry Pi you want to run diagnostics for
  1. Click on the Raspberry Pi you want to diagnose
The available apps for your Raspberry Pi, click on PiDoctor

4. Click on PiDoctor

You will see the following screen:

PiCockpit PiDoctor main screen for a Raspberry Pi 4 Model B
PiDoctor main control screen

5. Click on Run all Tests

Basic information (RAM and CPU) will now be displayed:

PiDoctor after having clicked on Run all tests

You can now scroll down through the page to see the test results for the individual modules, or click on any of the quick access buttons to jump to the system test module you’re interested in:

Click on the quick access buttons in PiDoctor to jump quickly to the right module

How to run an individual Raspberry Pi health check module

Each module has a button at the bottom, which allows you to run just the tests of this module. For example, have a look at the USB test:

PiDoctor USB test – click on the Run USB Test button to execute the test

There also is an “auto reload” toggle switch in the upper corner, which allows you to have the test run automatically each 10 seconds. This is useful for continuous monitoring of changes.

Available system health test modules

WLAN

screenshot of the WLAN health test module of PiDoctor

The WLAN module allows you to scan the WiFi networks in your Raspberry Pi’s neighbourhood, determine which one it is linked to, and the strength. By clicking on details, you’ll be able to see the full technical details of the network:

showing more details for a WLAN SSID (excerpt)

In the “advanced information” section, many additional commands are present which you can see the output of. Some of them will only be run if you click “Run this test”:

iwlist scanning is an on-demand test, it is only run if you click “run this test”

The search allows you to quickly find matching lines in the output:

filtering for the WLAN frequency

Network

The network module shows you your Raspberry Pi’s current IP addresses, network links, and the known neighbours.

Raspberry Pi own IP addresses & network links / known neighbors

Some additional information is available in the advanced information section:

ss -tupn and ss-tulpwn can be used to diagnose active network connections and listening ports on your Raspberry Pi

System

System is one of the most powerful and extensive Raspberry Pi system test modules in PiCockpit.

Basic system information

The first part, Basic system information, shows you some important overview information:

  • Serial number of your Raspberry Pi
  • your Raspberry Pi model
  • the SoC temperature of your Raspberry Pi (monitor the CPU temperature using this, or use PiStats to see updates every second!)
  • the GPU RAM
  • the current CPU frequency – this is useful if you are overclocking your Raspberry Pi
  • the current CPU voltage
  • status for the Raspberry Pi camera – diagnose camera issues to see if the Raspberry Pi supports and detects the camera
  • the SD card manufacturing date
Throttling and under-voltage, ARM frequency cap monitoring

Using the next part, Throttling & under-voltage, you can diagnose vital information about your Raspberry Pi:

  • is your Pi power supply strong enough? Watch out for under-voltage
  • is your Raspberry Pi running too hot? Watch out for soft temperature limit, ARM frequency cap and Throttling

In case there are issues (currently or previously), PiCockpit will show these here. For example, for the ARM frequency cap being triggered:

ARM frequency cap is currently active, and was previously active – indicating heat issues
Block devices & file systems in collapsed state

The Block devices & files systems (storage space) module is collapsed initially, but can be expanded by clicking on the arrow:

Expanded mmcblk0 view, showing all partitions

You’ll be able to see all partitions, their size, and the used space for mounted partitions. This will allow you to determine if you are running out of space on your root partition on your Raspberry Pi.

The root partition is always mounted under / – in our case the last partition, mmcblk0p7

Raspi Berry’s helpful Linux knowledge

Click on any entry to see even more details:

showing details for the root partition

Here you could click the show all toggle to show even more details (probably for interest only for people wanting to dive deep into technical details):

showing all details of a partition

Using this section you can diagnose which filesystem (fstype) a partition has, which /dev/ path it has (for example /dev/mmcblk0p1), it’s mountpoint, size, usage and label amongst other information.

Raspberry Pi revision code decoder

There are two styles of Raspberry Pi revision codes, PiCockpit can handle both. The new-style revision code will give more details:

  • Raspberry Pi model
  • Raspberry Pi model revision
  • Raspberry Pi RAM
  • Raspberry Pi processor (SoC which is used)
  • Raspberry Pi CPU
  • Manufacturer – you can find out in which country your Raspberry Pi was manufactured here

There are also some additional flags you can see in PiDoctor’s System / Raspberry Pi revision code part:

  • Overvoltage allowed
  • OTP programming allowed
  • OTP reading allowed
  • Warranty bit

The advanced information includes additional diagnostics, presented in text form:

Advanced diagnostics: check the Raspberry Pi OTP bits, lscpu, free -b, vcgencmd get_config int, vcgencmd get_config str

Video

The video module allows you to check which monitors are attached to your Raspberry Pi, and which modes (video and audio) they support. For Raspberry Pi 4 and 400, both HDMI ports are supported.

PiDoctor’s Video module allows you to inspect the TVs / displays / monitors attached to your Raspberry Pi

As you can see in the screenshot, this monitor supports audio output:

PCM supported: Max channels: 2, Max samplerate:  48kHz, Max samplesize 16 bits.

Click on CEA modes and DMT modes to expand and view the available monitor modes – this is useful for setting the Raspberry Pi screen resolution in config.txt, if you have trouble seeing the output:

the CEA modes are a list of resolutions and frequencies the monitor will be happy to work at

USB

The PiDoctor USB module will allow you to monitor which USB devices are attached to your Raspberry Pi and retrieve details about them:

PiDoctor’s USB module, showing one USB 3.0 device and three USB 2.0 devices

Click on the arrow(s) to expand the hierarchy of USB devices:

in this example, one Logitech Inc Unifyuing Receiver is attached via USB to the Raspberry Pi

Click on the device you are interested in to get more details:

PiCockpit PiDoctor shows you details for the attached USB device
details for a USB device (excerpt) – allows you to drill down deep into any particular device, find out the manufacturer, the product, the bInterfaceClass (e.g. Human Interface Device), and the device status (for example bus powered)

Software

The software module in PiDoctor will show you which PiCockpit client version you have – it is important to keep the picockpit-client up-to-date (use PiControl to update it from within PiCockpit’s webinterface).

And also, it will allow you to see the currently running processes (ps aux output) and search them by name:

PiCockpit’s PiDoctor Software test module
Searching for picockpit should show you the picockpit-client in daemon mode

Note that these results / the list of processes are not updated live – if you want them to be periodically refreshed, click on auto reload (this will reload them every 10 seconds):

Software module with enabled auto reload

There are some additional tests in advanced information:

PiDoctor Software advanced tests

You can access the output of the following commands here:

  • dmesg (Kernel message buffer)
  • vcdbg log msg
  • hostnamectl
  • vcgencmd version
  • lsmod (loaded kernel modules)
  • ps aux (raw output)

You’ll be able to search through the results quickly, by entering the text you are looking for in the search above the output of the particular advanced information output you are interested in:

dmesg, diagnostic message buffer of the kernel – is an ondemand test, click Run this test to run it

Disabling tests in PiDoctor

If you want to disable tests, for security reasons, for example, you should remove the corresponding .json definition files from 

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

Adding custom tests to PiDoctor

Adding custom tests is possible by adding additional .json module definitions. Look at the examples in the code which are present, be sure to define your own unique handles, and restart picockpit-client.

I will add more documentation for creating your own tests here, if people request me to.

Note, the custom tests will always be shown as “Advanced information”, since no custom UI has been built for them. If you require your own customisation / UI for a particular feature, please get in touch with us for a quote.

How can I get PiDoctor for my Raspberry Pi?

It’s really easy:

  1. Register for an account with picockpit.com, your web-based Raspberry Pi management platform. It’s free of charge for up to 5 Raspberry Pis
  2. Follow the installation instructions for PiCockpit. (You will create an API key and install picockpit-client on your Raspberry Pi)
  3. Now you can simply access PiDoctor from the web interface of the browser of your choice, as described on this page

FAQ

PiDoctor is not showing up under additional tools, how do I access it?

PiDoctor has been merged into PiCockpit – please install the picockpit-client on your Raspberry Pi, and access the PiDoctor app.

The classic, stand-alone PiDoctor version has been discontinued.

How can I download the EDID? It used to be available in the classic PiDoctor software.

Currently extracting the EDID is not implemented in the new PiDoctor App. A lot of output you would want the EDID for is implemented though, please have a look at the screenshots above.

For instructions, how to read your monitor’s EDID on a Raspberry Pi manually, click here.

Can I download the historical stand-alone version of PiDoctor?

You can download the last legacy stand-alone version of PiDoctor here (Version 2.1.18). The software is provided as is, without warranty of any kind.

With the historic version, you can use the same SD card with many different Pis in sequence – it will create a JSON log file for every Pi you’ve tested, extracting different data.

This blog post might come in handy as notes how to use PiDoctor legacy.

Download links:

These download links contain the same base software, based on Alpine Linux – in different formats for your convenience. When in doubt, go for the .img.zip and write the image using tools such as Etcher.

Please note the following limitations:

  • the legacy PiDoctor version does not support the Pi 4 or Pi 400 (the new version of PiDoctor, as part of the PiCockpit platform supports all Raspberry Pis and will continue to be updated)
  • the legacy version cannot be installed on an existing operating system – you need to put it on it’s own SD card
  • the online evaluation tool has been discontinued, so you will have to look at the raw JSON file yourself – unfortunately this file format is not compatible with the new PiCockpit platform v2
  • we are not able to provide unpaid support for the legacy version – however, if you want us to build a solution around it for your business & are willing to pay for consulting & development, please get in touch

Do you still have questions / need support?

Please get in touch with us, we aim to help you get started quickly with PiCockpit.