Skip to main content...

W0CHP.radio

How to Get Help With WPSD, the Right Way

We frequently see user help questions starting with “it doesn’t work”, and no other details. We can’t help without more information. This document is intended to inform you how to ask for help in a way that the WPSD community can effectively help you.

Table of Contents:

Do Your Homework First

We implore you to read the official documentation and FAQs before reporting an issue. I cannot stress how many times folks have reported issues, when they are already covered in the documentation. Additionally, we have an official WPSD User Manual you should also read/check.

After exhausting the documents above, you might want to post your issue to get help…

But before you post your issue in the WPSD Facebook and Discord support mediums, search in those mediums first.

What a Good Issue Report Contains

When posting your issue in the Facebook group or Discord server, follow guidelines outlined below, so that experienced users can actually and effectively help you…

  • What you are trying to do
  • What you expected to see (or happen)
  • What you actually saw (or what happened)
  • What is the configuration of your WPSD system and/or your rig
  • What recent changes you made (if anything)
  • What version #/hash you are running (in the top-right corner of the dashboard), or better, run: wpsd-version from command line.
  • The WPSD operating system version/disk image you’re using; e.g. Bullseye, Bookworm, etc. (details of this can be found in Admin -> System Details, under the “Operating System” section of the data table).
  • What mode(s) are you using/trying to use
  • What the various or relevant log files indicate in Admin -> Log Viewer
  • What steps you took in troubleshooting thus far (this one is important!)

A Bad Issue Report Example

“I tried to TX/RX on BM TG 3100 and it doesn’t work. Will somebody help me?”

A Good Issue Report Example

“I installed the WPSD RaspberryPi disk image, and restored all of the config files from my old setup. I am trying to TX/RX on DMR using BrandMeister, Talkgroup 3100, but I’m unsuccessful.

I ensured that my BrandMeister security key is entered in the BrandMeister config section.

No other changes have been made to my system after restoring the previous config files.

I do see that DMRGateway doesn’t seem to start since the DMR status panel mentions “Service Not Started”. Here are the last 20 lines from the DMRGateway log file showing the error. And here are the contents of my DMRGateway config file.

My hotspot is running version # 4220ac03f9.”

Providing Log Files

Frequently, you will be asked to provide log file information which enables us to help you. It’s best to inspect these BEFORE asking for help, because you’ll be likely be asked anyway!

Log files can be viewed “live”, from the Log Viewer page:

Admin -> Log Viewer

However, sometimes these logs won’t display anything or update if there is an issue starting the respective service. In this case, you can click the “Download This Log”/“Download All Logs” button on the Log Viewer page which will download a zip file with all relevant logs inside. Please provide the log file for the service you’re having an issue with.

We recommend pasting logs in a Pastebin type online service.

Screenshots of Logs or Photos of Computer Monitors Are Not Acceptable

  • Don’t send screenshots of logs. We need the actual log text output.
  • Don’t take photos or videos of your computer monitor with your mobile devices and post them; take a proper screenshot of what you are trying to show us on your screen. Please don’t ask us how to take screenshots. Research it.
  • Posting screenshots of logs or photos/videos of computer monitors will result in the post being removed immediately.

Providing Config Files

You may be asked to provide a copy of the relevant config file(s) for your issue. We will need the actual files, not screenshots of your configuration (your post/issue will be deleted if screenshots are submitted).

If you don’t know where the config files are or how to access them, you can easily download them from the dashboard:

Admin -> Advanced -> Backup/Restore -> Download Configuration

This will download a zip file with all of the relevant config files. You will likely be asked to provide a specific config file(s) from that zip archive.

We recommend pasting config files in a Pastebin type online service.

Sometimes, you will be specifically asked for screenshots of your configuration page.

Never Say These Things

“This worked fine in Pi-Star”

“It only works when I revert back to Pi-Star”

Just…don’t. Never say those things.

There are HUGE differences between WPSD software and Pi-Star, so the comparison and argument that “it works in Pi-Star”, is actually invalid…

Many of these differences are due to my software using up-to-date back-end software and many other enhancements, which is typically not compatible with Pi-Star; especially when config files are migrated over. It’s easier and more successful to begin the configuration from scratch when using my software if you run into issues.

These types of posts/statements, etc., are aggressively removed and bear other consequences. Just…don’t. It’s one of the rules.

Also, do not ever say “it works with my OpenSpot”. OpenSpots are ironically, proprietary and are not open source. I and the other WPSD developers do not have/use them. Do not talk about them! There is zero valid comparison.

How to NOT Get Help

  1. By not following the complete guidelines listed above
  2. By not doing any troubleshooting before you ask for help, and by not sharing the troubleshooting steps you took; and the results of your troubleshooting.

Manage Your Expectations

WPSD is a project, not a product with some company behind it. It’s free and open source, and support is provided (also for free) by the WPSD community. If you don’t exhibit any effort into the troubleshooting and/or researching issues on your own, and expect others to simply solve your problem for you; you very likely will not receive help. You are expected to help us to help you; and we’re happy to, provided you put in the effort.

Document Version: 9bb3a7b -- Last Revision: 6/10/2024
Permanent Link: <https://w0chp.radio/documents/how-to-get-wpsd-help-the-right-way/>