Troubleshooting

Quick answers to the most common issues. Start with the section that matches your problem.

WiFi issues

The Pi won't connect to WiFi

Work through these checks in order:

1. Is it a 2.4 GHz network? The Pi only supports 2.4 GHz WiFi. If your router broadcasts both 2.4 GHz and 5 GHz under the same name, try separating them in your router settings and connecting to the 2.4 GHz network explicitly. The 2.4 GHz network often has the same name without "5G" or "5GHz" at the end.

2. Is the country code correct? The WIFI_COUNTRY field in settings.txt must match your region. This controls which WiFi channels the Pi is allowed to use. Common codes: US, GB, SE, DE, AU, NL, FR. An incorrect code can prevent the WiFi radio from working at all.

3. Is the password correct? Double-check for typos. If your WiFi password has special characters (#, =, spaces), make sure they're entered exactly. The easiest fix is to generate a new setup from the Palpable app (Devices > Add Device) and carefully re-enter the credentials.

4. Is it WPA2? Only WPA2 Personal is supported. WPA3, WPA2 Enterprise (the kind used in offices with username/password), and open networks won't work.

The Pi is connected but my device doesn't appear in the app

1. Wait 2-3 minutes after boot -- cloud registration takes a moment
2. Pull down to refresh in the Palpable app
3. Generate a new setup from the Palpable app if the setup token might be expired
4. Check the status LED -- if it's still blinking, the Pi hasn't finished connecting

Device shows "offline"

Check the power supply

This is the most common cause. The Pi needs a proper USB-C charger:

• Use a 5V, 2.5A charger (a good phone charger usually works)
• Don't power it from a laptop USB port -- not enough current
• If the Pi reboots randomly, the charger is too weak
• Symptoms of low power: random disconnects, WiFi drops, sensors stop responding

Check the WiFi signal

• Move the Pi closer to your router
• Avoid putting it inside a metal enclosure
• Keep it away from microwaves and other sources of interference

Module not detected

If a sensor or actuator doesn't show up in the app:

1. Check the cable. Unplug and replug both ends of the Qwiic cable. The connectors are small and it's easy to get a loose connection.

2. Try a different cable. Qwiic cables can be faulty. If you have a spare, swap it.

3. Shorten the chain. If you have many modules daisy-chained, try connecting the problem module directly to the Pi (first in the chain) with a short cable.

4. Wait 30 seconds. The Pi scans for new modules every 30 seconds. A freshly-plugged module will appear on the next scan.

5. Power-cycle the Pi. Unplug the USB-C cable, wait 5 seconds, and plug it back in. This forces a fresh scan on boot.

Display not working

Nothing shows on the screen

• Check the cable connection. OLED displays are sensitive to loose Qwiic connectors. Reseat both ends.
• Wait for detection. The Pi scans for displays every 30 seconds. If you just plugged it in, give it a moment.
• Make sure you've deployed content. A freshly-connected display starts blank. Use the Display Editor or ask PAL to put something on it.

Display is flickering or garbled

• Power supply issue -- OLED displays are sensitive to voltage drops. Try a stronger charger.
• Move the display closer to the Pi in the chain -- make it the first module after the Pi.
• Reduce the chain length -- too many modules can cause timing issues on the communication bus.

Behaviors not triggering

Check that the behavior is enabled. Open your project in the app and make sure the behavior's toggle is on.

Check the cooldown. After a behavior triggers, it won't trigger again until the cooldown period passes. If you set a 5-minute cooldown on a temperature alert, it won't fire again for 5 minutes even if the temperature is still high.

Check the trigger condition. If your behavior triggers on "temperature above 30°C" but the current temperature is 29°C, it won't fire. Check the live sensor readings in the app.

Is the device online? Behaviors run on the Pi, so the Pi needs to be powered and connected.

Factory reset

If things are really stuck, you can start fresh:

Option A: Use the button

Hold the button on your Pi for 10 seconds. The device clears its settings and re-enters setup mode. You'll need to re-flash the SD card with a fresh setup generated from the Palpable app.

Option B: Re-flash the SD card

1. Power off the Pi
2. Remove the SD card
3. Format it as FAT32
4. Generate a fresh setup from the Palpable app (Devices > Add Device)
5. Extract the ZIP to the SD card
6. Insert and power on

This performs a completely clean install.

Updates

Your Pi updates itself automatically. When a new version is available, the Pi downloads it in the background and installs it on restart. If anything goes wrong during an update, the Pi automatically rolls back to the previous working version.

You don't need to do anything -- updates are hands-free.

Still stuck?

If none of the above solved your problem:

1. Note what the status LED is doing (solid, slow blink, fast blink, or off)
2. Note which modules are connected and whether they appear in the app
3. Reach out:
   • Discord (opens in a new tab) -- quickest response from the community and team
   • Email: support@palpable.technology