Troubleshooting

This section covers common problems and how to solve them. The status line in the top bar (under the radio name) and the status bar on the Radios page usually say what is wrong.

Pairing and Connection

The radio doesn't appear when scanning

  • Check that Bluetooth is enabled on the radio. Meshtastic turns Bluetooth off when the radio is set to use Wi-Fi or Ethernet.

  • Disconnect your phone from the radio. A radio that is connected to a phone stops advertising and can't be found.

  • Move the radio closer to the display and tap Scan again.

  • Restart the radio.

"Wrong PIN" or "Pairing failed"

  • For a radio with a screen, the PIN changes on every pairing attempt: type the digits currently shown, within about 30 seconds.

  • For a radio without a screen, the PIN is fixed — 123456 unless it has been changed in the radio's Bluetooth settings (the Meshtastic app shows it).

  • If the radio was paired with this display before and has since been reset (or you tapped Forget on the display), the two no longer share the same pairing. Remove the display from the radio's paired devices (or reset the radio's Bluetooth bonds with the Meshtastic app), then pair again.

"Pairing lost — pair again"

The radio has forgotten this display (for example after a factory reset). Tap the bin icon on the Radios page to forget the radio, then scan and pair again.

"Node not found - in range and not connected to a phone?"

MeshDisplay couldn't reach the radio. It is switched off, out of range, or connected to another device. Fix the cause and tap Connect.

Messages

My message shows "not delivered"

The radio could not get the message through. Common causes:

  • For a direct message, the other node did not confirm it: it may be out of range, switched off, or too many hops away. Try again later, or ask someone nearer to relay.

  • The mesh is busy (Meshtastic limits how much each radio may transmit).

  • The message was too long for the channel's settings.

Messages stay without a tick

The radio has the message but has not been able to transmit it yet, usually because the mesh is busy or the radio is still starting. It goes out when the radio can send.

I can't type in the message box

The message box is disabled while the display is not connected to a radio (it reads Not connected to a radio). Wait for Connected in the top bar, or open the Radios page to connect.

I don't get alerts for new messages

Check Settings → Alert on direct messages and Alert on channel messages. No pop-up is shown for messages in the chat that is already open.

A channel is missing

MeshDisplay shows the channels configured on your radio. Add or enable the channel on the radio with the Meshtastic app or CLI; the display picks it up when it next connects.

Display

Screen is blank

  • The screen may have switched off after the Screen off after time: touch it.

  • Check the USB-C power supply and cable (5 V, at least 1 A).

  • Disconnect power for 10 seconds and reconnect.

Touch doesn't respond

  • Touch with a bare finger; gloves and non-conductive styluses don't register.

  • Clean the screen with a dry microfibre cloth; moisture can confuse the touch panel.

  • Disconnect power for 10 seconds and reconnect.

The picture is upside down

Turn off Settings → Rotate screen 180 and tap Restart.

Wi-Fi, Map and Updates

MeshDisplay won't join my Wi-Fi

  • MeshDisplay supports 2.4 GHz networks only.

  • Check the password: remove the network (bin icon) and add it again.

  • WPA3-only networks are not supported; use WPA2/WPA3 mixed mode.

  • Networks that need a web login page after joining (hotels, some public Wi-Fi) are not supported.

The map has no background, only a grid

  • The display is not on Wi-Fi, or the map server can't be reached. Nodes are still shown at their true positions; the background appears when the connection returns.

  • Places you have looked at before are shown from the stored copy.

A node isn't on the map

Only nodes that share their position appear. Check the status line on the map (3 of 13 nodes have a position). Position sharing is set on each node.

The node card shows no distance

Distances and directions need your own radio's position. Give your radio a position (GPS, or a fixed position in the Meshtastic app).

"Update server unreachable" / "Could not download the update"

Check the Wi-Fi connection and that outbound HTTPS (port 443) to u.topbytes.net is allowed (see Advanced Features). The display keeps its current software and retries later.

MQTT Gateway

See the status table in MQTT Gateway. In short:

  • Needs Wi-Fi — set up Wi-Fi first.

  • The radio's MQTT is not in gateway mode — turn Forward mesh traffic off and on again so MeshDisplay sets the radio up.

  • Can't reach ... — check the broker address and that outbound port 1883 (or 8883 for TLS) is allowed.

  • ... refused the login — check the username and password under Broker (on the radio).

Getting Help

If a problem persists, contact support@topbytes.net with:

  • the software version (Settings → About)

  • your radio's model and Meshtastic firmware version (also in About)

  • what the status line says, and what you were doing

If you can, connect the display to a computer and include the serial console log (see Advanced Features).