Pi-Star troubleshooting

Jumping through a flaming hoop
Flaming hoop vector art
by 31moonlight31, Shutterstock

Revised: Apr 2019, CC BY-SA = open in new tab ]
Most up-to-date version: amateurradionotes.com//pi-star-troubleshooting.htm PDF: 4-Pi-Star_troubleshooting.pdf

Part of the fun of exploring a feature-rich app like Pi-Star is to kick all the tires, flip all the switches, and jump through all the flaming hoops we can find. Of course, that means that sometimes things may break or we may fall down a rabbit hole and find ourselves standing before a door we don't quite fit through. When things aren't working as expected, here are some steps that may help.

Be persistent! Troubleshooting takes time and may really test a person's patience, but I also find that persistence usually pays off: it feels great to finally figure things out, and I almost always learn some things along the way. For more about this, see 24. A real-life story about stubbornness … err … persistence.

  1. Toggle – If a feature isn't working correctly, turn it off, then back on.
  2. Update and upgrade – Run a Pi-Star update via an SSH app like Termius, which in addition to updating the dashboard binaries and the hostfiles will also update the OS. And then run Pi-Star upgrade enough times until it says "You are already running the latest version."
    • mount: / is busy – The Update process automatically switches Pi-Star into Read-Write mode, writes the updates, and then switches Pi-Star back into Read-Only mode. Occasionally, the process will fail to complete the switch back to Read-Only mode, and a message is displayed: "mount: / is busy."
      When this happens, it typically doesn't work to manually swith Pi-Star back into Read-Only mode using the "rpi-ro" command. To fix this, there's a few things that can work: re-run Pi-Star Update, run Pi-Star Upgrade (even if you're on the latest version), reboot Pi-Star, power off the hotspot and then restart it. Whenever this happens, I always re-run the Pi-Star update until it finishes normally.
    • Trouble re-opening the dashboard after updating – Sometimes after performing a Pi-Star update or a firmware update, for some reason the dashboard won't re-open in the browser when using the standard http://pi-star/ or http://pi-star.local/ URLs. When that happens, find the hotspot's IP address and use that. After the dashboard opens the first time using the IP address, the URLs should work again.
      To find the IP address, I use an Android LAN scanner app. Alternatives: the Mac app called Airport Utility, in which the app is listed under the name Pi-Star, or the Windows app called Advanced IP Scanner (full scans can take a long time, but if you limit the IP range to what your local network uses, it's quick enough).
    • Update gets stuck on the Updating DV Binaries step – After several cycles of running into this issue with Pi-Star 4.0.0-RC3, I've come to the conclusion that a lot of problem is due to the Auto AP feature, and the best way to get things sorted out is to turn off Auto AP, apply changes, reboot, turn Auto AP back on, apply changes, and reboot again.

  3. Apply changes – On the Pi-Star Configuration page, even if nothing there has been changed, click Apply Changes. I always do this after running a Pi-Star update, too.
  4. Clear your browser's cache – Close the Pi-Star dashboard, clear your browser's cache, then restart the Pi-Star dashboard.
  5. Mode disabled – If a mode is red in the dashboard's Modes Enabled section, that means an error has caused MMDVMHost to stop running. There are several likely causes, including:
    • Using a blocked frequency in the satellite range. Take a look at the frequency selected on the Configuration page. If it is highlighted red, it is in the satellite frequency range and you'll need to select a different frequency. For more info, see Change frequency below.
    • Incorrect radio/modem selected, for example, a simplex radio/modem is selected but the hardware is duplex (or vice versa). Verify your Radio/Modem Type selected in the General Configuration settings.
    • Firmware corrupted. You may need to re-flash the firmware. Make sure the firmware you're flashing matches the board. For more info, see Update or re-flash firmware below.
    • One thing you can do to troubleshoot this issue is to open the Live Logs view in a second browser tab, Apply Changes on the Configuration page, and read through the resulting logging to see if you can spot the issue.
  6. Move radio – Try moving the radio; in some cases, being too close can desense the hotspot's receiver. Also, try turning your radio off and back on.
  7. Verify Radio/Modem type – Make sure you have selected the correct Radio/Modem type in the General Configuration settings.
  8. Change frequency – Try a different frequency. To find the range to choose from, see your country's band plan (U.S. Band Plan) or the info that Ron, VE1AIC, has posted: Digital Voice frequencies.
    • Important! Avoid frequencies used for other purposes, for example, 435.0 - 438.0 and 145.8 - 146.0, used internationally for satellite communication, which can be disrupted by even low power hotspot transmissions.
    • Pi-Star reminder: Beginning with dashboard v20181216, when you change a frequency, the frequency field displays red when it is within the satellite range and green when it is safely outside that range. Pi-Star itself doesn't enforce frequency ranges; however, hotspots running firmware ZUMspot/MMDVM_HS v1.4.12 or later won't work on satellite frequencies.
    • Band plan: See your country's band plan and your local frequency use plan (for example: U.S. Band Plan and Colorado Frequency Use Plans) or the info posted by Ron, VE1AIC: Digital Voice frequencies.
    • POCSAG: The default POCSAG frequency is outside satellite frequencies, but if you changed it to a frequency in the blocked range, it can cause problems even if the POCSAG mode is not enabled.

  9. Fine tune to reduce BER – If you're experiencing high (greater than 1%) Bit Error Rate (BER) with your radio, you may have trouble with transmitting (the hotspot won't receive your transmission). This is especially a problem with some of the JumboSPOT clone boards, which have inconsistent TCXO chips. To reduce BER, try adjusting the RX Offset.
  10. Reseat and reboot – If you're using a modem mounted via a GPIO header to a Raspberry Pi or similar, remove and reseat the modem.
    • For example, if you have an MMDVM-based board connected to an RPi via the GPIO header and see "Failure to Init device" in the log lines for a Pi-Star Update, then the RPi isn't communicating with the board via the upgrade pins, 38 and 40.
    • Also, double check that you have the correct modem type selected in the General Configuration settings, and then reboot the hotspot.
    • Can't hurt to also reboot the computer you're using to navigate to the Pi-Star dashboard. And it might even help to reboot your router, too.

  11. Expand the filesystem
    [Note: For Pi-Star version 4 and above, this happens automatically as part of the first boot up.]
    Pi-Star itself takes up very little room on the microSD card, but sometimes you can run out of available space if, for example, if you have some process running that does a lot of logging. One thing you can try is expanding the filesystem so that it fills all the available space on the card. See Expanding the filesystem
  12. Double check your IDs and passwords – Ensure there are no typos and that you're using IDs correctly:
    • Double check that your callsign and CCS7 ID are correctly entered in Pi-Star General Configuration and also in your radio or codeplug. Note that if your General Configuration Node Type is set to Private, then the callsign in the radio must match the Node Callsign in Pi-Star, or he CCS7 ID in the radio must match the CCS7 ID in Pi-Star.
    • If you're having trouble connecting to Pi-Star from within a browser, make sure you're using the hostname that is entered in General Configuration settings (default = pi-star).

  13. Beware special characters – Some special characters work for directly accessing Pi-Star Admin and Configuration settings, but may not work for logging into Pi-Star via SSH.
  14. Check your WiFi settings and router – Because of all the different network setups and routers, this is a tricky area to troubleshoot, but if Pi-Star isn't connecting to your WiFi network:
    • Double check that you entered the network name and password correctly in Pi-Star. Typos happen!
    • A space in the network name can cause problems connecting to some routers.
    • Some radio/modem boards require the WPA or WPA2 security standard, and won't work with WEP.
      • Note: This is a good thing. In fact, even WPA isn't secure enough. To be safe, use WPA2, and make sure the firmware on your network devices is up to date. A good article about all of this: WiFi security.
    • Make sure your wireless network doesn't have "Wireless Isolation" enabled, which could prevent your computer and hotspot from communicating with each other.
    • Might help to reboot your router, too.
  15. Check power supply – Try using a different power supply (steady 2.5A output is key), and then perform a hotspot shutdown, power off, and restart.
  16. Do a factory reset – Back up your configuration, do a factory reset, and then restore the backed up configuration.
    Note: A factory reset sets all the configuration setting back to what they are when a fresh image is first installed, with two exceptions: your WiFi setup is retained, and if you have enabled the BrandMeister Manager module, your BrandMeister API Key is retained. It does not affect the Pi-Star update dashboard version nor the Pi-Star upgrade version.
  17. Flash a fresh image – Try using a different, good quality microSD card, and then download and flash a totally fresh Pi-Star image.
    Note: At this time, the regular Pi-Star RPi image doesn't support the new RPi 3B+ or 3A+; however, there is a Pi-Star RPi v4.0 release candidate version that does: Pi-Star Beta Downloads.
    Upgrading from V3 to V4? See Upgrading to Pi-Star V4
  18. Find out what is using the hotspot modem port – Running the findmodem command via SSH—reads directly from the hardware, not the firmware—can be helpful when troubleshooting a Nextion display connected via USB:
    sudo pistar-findmodem
    For example, running this command on a ZUMspot running on an RPi Zero W with a Nextion display plugged into the USB port shows:
    Detected Nextion (USB) : /dev/ttyUSB0 (Model: NX4832K035_011R Serial: DB682C37CB1B2932 Touch: Yes)
    For a similar setup using the MMDVM_HS_Hat by Florian, DF2ET, and Mathis, DB9MAT, running findmodem shows:
    Detected MMDVM_HS (GPIO): /dev/ttyAMA0 (MMDVM_HS_Hat-v1.4.14 20181209 12.2880MHz ADF7021 FW by CA6JAU GitID #8d77ff3)
    Detected Nextion (USB) : /dev/ttyUSB0 (Model: NX4832K035_011R Serial: DB682C37CB1B2932 Touch: Yes)

    Note: The findmodem command doesn't read info for displays plugged directly into the radio/modem board itself.
  19. Update or re-flash firmware – It's important to keep your modem board firmware update, and sometimes things can get messed up if the firmware is corrupted or the wrong firmware is flashed.
    Note: Beginning with Pi-Star dashboard v20181214, you can see in the Radio Info section which TCXO chip (12.288 or 14.7456 MHz) a ZUMspot/MMDVM_HS board is running. This info is needed to determine which firmware update to apply, for example, with the MMDVM_HS_HAT or MMDVM_HS_DUAL_HAT, there are separate firmware update script commands for the different chips.
    See Updating hotspot firmware via Pi-Star.
  20. Check live logs – Take a look at Pi-Star Live Logs view. It can be helpful to open Live Logs view in a new tab or a different browser so you can look back and forth between the dashboard to run the feature, and then the log to see if you can spot the problem.
    Hint: There's a link at the bottom of Live Logs view to download it as a text file.
    Note: There also are more specific logs you can check in the /var/log/pi-star directory, for example, specific logs for ircDDBGateway, MMDVM, etc.
  21. Take a break – At this point in troubleshooting, I usually turn everything off and walk away for a few hours or a day or two, and then return with a fresh mind to try troubleshooting again. That sometimes helps.
  22. Ask for help on the Pi-Star User Forum – Ultimately, if I'm unable to figure out how to solve an issue myself, I visit the Pi-Star User Forum or the Pi-Star Support Group and ask for help. There are some very smart, experienced people sharing their expertise there, including some of the core members of the Pi-Star team: Andy, MW0MWZ, Craig, W1MSG, and Andrew, M1DNS.
    • Be detailed – When reporting an issue on the forum, the more details you can provide, the better. In addition to the description of the issue itself, share your Pi-Star version and dashboard date (for example, v3.4.16, dashboard 20181220), the model and version of the modem board you're using, its firmware version, what steps you've already tried, any related log entries you have, and any other details you can think of that can help others understand the issue.
    • Be nice – Everyone working on Pi-Star and answering questions in the forum is a volunteer. Many of them, including the lead developer, have day jobs and are doing all of this for free in their spare time. It's all a gift!
    • Give back to the user community – If someone takes the time to answer your question and the suggested solution works, then jump back into the forum and post a reply that it did work. That let's everyone who reads your topic know that there is a valid solution. Even better, once you get a little experience with using Pi-Star, jump back into the forum and pay it forward by helping someone else.


24. A real-life story about stubbornness … err … persistence

Hint: After several cycles of the following the kind of persistent troubleshooting with Pi-Star 4.0.0-RC3 described below, I've come to the conclusion that a lot of problem is due to the Auto AP feature, and the best way to get things sorted out is to turn off Auto AP, apply changes, reboot, run an update, turn Auto AP back on, apply changes, reboot again, and run another update. Also, patience helped because sometimes the update would take several minutes to get past the Updating DV Binaries step.

Okay, now the story …

Periodically, I cycle through all my hotspots to make sure they're all up to date with the latest Pi-Star dashboard updates and version upgrades, and then I back them up. The last time I did this, I ran into a world of trouble. I'm not sure why (it was full moon … just sayin'), but every one of them got stuck during the updating process (most often on the Updating DV Binaries step) and/or got stuck—really stuck—in read-write mode. Sometimes I saw error messages about directories being locked in the wrong mode*, and some of them needed really long Raspbian OS updates. Crazy times!

I was updating hotspots running both Pi-Star 3.4.17 and 4.0.0-RC3. Some of them had been very recently updated, others hadn't been updated for a few weeks. The hotspots were a variety of combinations: several ZUMspots, an MMDVM_HS_Hat, an MMDVM_HS_Dual_Hat, and a DVMEGA, mounted on RPi 3A+, 3B+, and Zero Ws, some with Nextion displays. All of them gave me trouble.

Normally in a situation like this, after trying a few things, I would just burn a new Pi-Star image and restore from the previous backup, but this time I decided to be as stubborn … err … persistent as I could be and try to power my way through.

I ended up trying lots of different things, and it's likely that the issues I ran into were different on the various hotspots, but in the end I was able to get them all working properly again without burning a single new image.

Some of the things I tried:

As I said, in the end I got all of my hotspots updated and working correctly again. My point to sharing this story is to reiterate that persistence really can be your best friend when it comes to troubleshooting and problem solving.

UPDATE: I just tried booting up with a fresh Pi-Star 4.0.0-RC3 image on two new hotspots and ran into the same kind of trouble, so it looks like my idea that I could've just solved this by burning a new Pi-Star image and restoring from a previous backup was wishful thinking. I solved it this time by trying many of the same things as I mentioned above, plus a new one:

So it appears there may be some kind of problem with the Pi-Star 4.0.0-RC3 image. The good news is that once I was able to get past these roadblocks, everything works smoothly going forward.

[*] Here are some of the error messages I saw:
E: Could not get lock /var/lib/apt/lists/lock - open (11: Resource temporarily unavailable)
E: Unable to lock directory /var/lib/apt/lists/
E: Could not get lock /var/lib/dpkg/lock- open (11: resource temporarily unavailable)
E: Unable to lock the administration directory (/var/lib/dpkg), is another process using it?

< Pi-Star notes