Documentation
Troubleshooting
Overview

Troubleshooting

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


Wi-Fi issues

The board won't connect to Wi-Fi

Work through these checks in order:

1. Is it a 2.4 GHz network? The Pi Zero 2 W and ESP32 boards only use 2.4 GHz Wi-Fi. If your router uses one name for both 2.4 GHz and 5 GHz, try splitting them in your router settings and choosing the 2.4 GHz one. It is often the name without "5G" or "5GHz" at the end.

2. Is the country right? Each saved network has a country, which decides which Wi-Fi channels the board may use. A wrong country can keep the board off your network. Check it under Settings → Wi-Fi (tap the network to edit it).

3. Is the password right? Double-check for typos, especially special characters and spaces. Fix it under Settings → Wi-Fi, then set the board up again.

4. What kind of network is it? Home networks with a password (WPA2) work. Networks that ask for a username as well (common at offices and schools) won't.

The board is on, but it doesn't appear in the app

  1. Give it time. A Raspberry Pi's first setup takes several minutes; the app shows how long to expect.
  2. Check the Pi's light. See what the light means during setup.
  3. Start again. If the app offers Start setup again, use it. On a Pi, that means new setup files on the card.

Board shows "offline"

Check the power supply

On a Raspberry Pi this is the most common cause:

  • Use a 5V, 2.5A supply (on the Pi Zero 2 W, in the PWR IN port)
  • Don't power a Pi from a laptop USB port
  • Random restarts, Wi-Fi drops and sensors that stop responding are all signs of weak power

Check the Wi-Fi signal

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

Did the Wi-Fi change?

If the board lost its network, the app says so on the board's page and offers Reconnect. See Changing Wi-Fi after setup.

💡

Testing Wi-Fi on a Raspberry Pi? Unplug any USB data cable first. A data cable plugged into the Pi can disturb its 2.4 GHz Wi-Fi and make a good board look like a bad one.


Module not detected

A module that doesn't appear, stops answering, or sends numbers that don't change has its own page, organized by what the app shows you: Module troubleshooting.


Display not working

Nothing shows on the screen

  • Check the cable. Displays are sensitive to loose Qwiic connectors. Reseat both ends.
  • Give it a moment. A newly plugged display usually appears within a few seconds.
  • Put something on it. A new display starts blank. Use the Display Editor or ask PAL to put something on it.

Display is flickering or garbled

  • Power: displays are sensitive to voltage drops. Try a stronger power supply.
  • Move the display closer to the board in the chain.
  • Shorten the chain.

A project isn't doing anything

Is it running? Open the project and check the control at the top. A project starts only when you press Run.

Is the board online? On an ESP32 board, scripts need the connection. On a Raspberry Pi or the UNO Q they keep running offline, but you won't see new readings in the app until the board is back.

Is the condition met? If the project reacts to "above 30°C" and it's 29°C, nothing happens yet. Check the live readings in the app.

Ask PAL. Open the project, tap Ask PAL and say what you expected: "Why didn't the buzzer go off?" PAL can check the board, its modules and the script.


Starting over

Open the board in the app and go to Manage:

  • Re-flash card (Raspberry Pi): makes fresh setup files for a new or erased microSD card, for the same board.
  • Start fresh / unlink: releases the board, so you can set it up again or give it to someone else.
  • Return this board to Arduino (UNO Q): puts Arduino's own system back.
  • Delete device: removes the board from your account.

Updates

When an update is ready, the app offers it on the board's Software page. It installs over the air, alongside the version that works now. If the new version doesn't start, the board goes back to the version that worked.


Still stuck?

  1. On a Raspberry Pi, note what the light is doing
  2. Note which modules are connected and whether they appear in the app
  3. Reach out: