Pi-Star troubleshooting

Updated: Sep 2018, CC BY-SA
Most up-to-date version of this note:
troubleshooting.hamnotes.com
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.

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

Of course, that means that sometimes things may break or we might fall down a rabbit hole and find ourselves standing before a door we don't quite fit through. When that happens, these steps may help:

  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 a Pi-Star upgrade enough times until it says "You are already running the latest version."
  3. Apply changes – On the Pi-Star Configuration page, even if nothing there has been changed, click Apply Changes.
  4. Clear your browser's cache – Close the Pi-Star dashboard, clear your browser's cache, then restart the Pi-Star dashboard.
  5. 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.
  6. Verify Radio/Modem Type – Make sure you have selected the correct Radio/Modem Type in the General Configuration settings⩘ .
  7. 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.
  8. 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 TXCO chips. To reduce BER, try adjusting the RX Offset⩘ .
  9. 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.
  10. 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 CCS7 ID in the radio must match the CCS7 ID in Pi-Star.
    • If Pi-Star isn't connecting to your WiFi network, double check that you entered the network name and password correctly. Typos happen! Also, be aware that a space in the network name can cause problems connecting to some routers. Might help to reboot your router, too.
    • 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).
  11. 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.
  12. 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.
  13. 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.
  14. Flash a fresh image – Try using a different, good quality microSD card, and then download and flash a totally fresh Pi-Star image⩘ .
  15. Re-flash firmware – Perform a re-flash of the hotspot firmware⩘ .
  16. 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.
    • There also are more specific logs you can check in the /var/log/pi-star directory, for example, specific logs for ircDDBGateway, MMDVM, etc.
  17. 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.
  18. 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 Users 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, Adrian, M0GLJ, Craig, W1MSG, and Andrew, M1DNS.
    • 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!
    • Be detailed! When reporting an issue on the forum, the more details 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 20180804), the model and version of the modem board you're using, its firmware version, related log entries, and any other details you can think of that can help others understand the issue.