MeshCore logo

Installation guide

MeshCore IP Bridge

Set up a pair of Heltec WiFi LoRa 32 V4 boards, end to end, to join two separate MeshCore meshes over the internet — from unboxing to your first message crossing the link.

Hardware · In development About 45–60 minutes Firmware ipbridge-1.1.1

Overview

How it fits together

Each board sits inside its own mesh, listening on LoRa like any other node. Every packet it hears is sent, encrypted, to the board at the other end, which transmits it into its mesh. Traffic flows both ways, and duplicate packets are dropped so nothing loops.

No phone or computer stays in the path. Once set up, each board runs on its own from a USB power supply, with a status screen on the board and a web dashboard you can open from any browser on the same network.

Before you start

What you need

Hardware

  • 2 × Heltec WiFi LoRa 32 V4 boards — one for each site.
  • 2 × LoRa antennas for your region's band (915–928 MHz in New Zealand and Australia). A better antenna mounted higher helps more than anything else.
  • 2 × USB‑C data cables. Some cheap cables only carry power, and they won't work for flashing.
  • 2 × reliable 5 V USB power supplies, plus an enclosure if the board will live outdoors or in a shed.
  • A laptop or desktop with Chrome, Edge or Opera for flashing. Safari, Firefox and phones can't flash.

Network & information

  • WiFi at both sites (2.4 GHz), with each network's name and password.
  • Admin access to the router at the server site, so you can forward a port. See step 1.
  • Each mesh's radio settings: frequency, bandwidth, spreading factor and coding rate. You can read them from the radio settings of any MeshCore companion app already on that mesh.
  • A shared key (PSK): a long, random passphrase you'll enter on both boards. Make it up now and keep it somewhere safe.
Always connect the antenna before powering the board. Transmitting without an antenna can permanently damage the LoRa radio.

Step 1

1Choose the server and the client

One board listens for the connection (the server) and the other dials out to it (the client). You need to choose which end is which.

Server · listens

Where you control the router

This site needs an internet connection that can accept incoming connections: a public IP address (ideally fixed) and a router where you can forward one TCP port to the board.

Client · dials out

Anywhere with WiFi

The client just makes an outgoing connection, so it works on almost any internet connection — including 4G, Starlink and shared or hotspot WiFi. No router changes needed.

Check the server site isn't behind CGNAT. Many 4G, fixed‑wireless and Starlink plans share one public IP between customers, which blocks incoming connections. Compare the WAN IP your router shows with the IP a site like whatismyip reports. If they differ, or the WAN address starts with 100.64–100.127, ask your provider for a public or static IP, or make the other site the server.

Step 2

2Flash both boards

Do this at your desk for both boards before they go to their sites. It takes about two minutes per board.

  1. Screw the antenna onto the board.
  2. Plug the board into your computer with the USB‑C data cable.
  3. Click Flash IP Bridge firmware below and pick the serial port that appears. On macOS it looks like cu.usbmodem…; on Windows it's a COM port.
  4. Click Install, and choose Erase device when asked. Erasing is recommended for a first install.
  5. Wait for it to finish and reboot. The screen shows the < IP Bridge > status pages.
  6. Unplug it and repeat for the second board. Label the boards Server and Client so they don't get mixed up.
Your browser can’t flash over USB. Open this page in desktop Chrome or Edge. This page must be served over HTTPS to flash a board.
No port showing? Try another cable, since it's probably power‑only. If that doesn't help, hold the PRG (boot) button, tap RST, then release PRG to force the board into download mode and try again.

Step 3

3Set up the server end

Connect to the board

  1. Power the Server board, with its antenna fitted.
  2. On a phone or laptop, join the WiFi network MeshBridge‑XXXX. The password is meshbridge.
  3. In a browser, go to http://192.168.4.1. The IP Bridge dashboard opens.
  4. Tap Radio & network settings to open Bridge settings.

Fill in the settings

SettingWhat to enter on the server
NameSomething you'll recognise, e.g. Foxton Bridge.
Roleserver (fixed IP end)
WiFi — SSID / PasswordThe server site's WiFi network.
Use static IPRecommended. Tick it and give the board a fixed Node IP outside your router's DHCP range (e.g. 192.168.1.50), plus Router (e.g. 192.168.1.1) and Netmask (255.255.255.0). Leave DNS blank to use the router. You can use a DHCP reservation on the router instead.
Companion (peer) IP / domainLeave blank. The server waits for the client to connect.
PortThe TCP port the server listens on, e.g. 5000. Write it down, because the client and the router both need it.
Shared key (PSK)Your long random passphrase. It must be exactly the same on both boards.
RadioThe Mesh A settings: Freq (MHz), Bandwidth (kHz), Spreading factor, Coding rate. Leave Sync word, Preamble and CRC at their defaults unless your mesh uses something different. Set TX power within your local legal limit.
  1. Click Save & reboot. The board restarts and joins your WiFi. Its own MeshBridge‑XXXX network goes away.
  2. Check the board's screen. The IP LINK [2/4] page shows the WiFi name and the board's IP address, and should say the server is listening.
From now on, open the dashboard from any device on the server's home network by typing the board's IP address into a browser, e.g. http://192.168.1.50.

Step 4

4Open a port on the server's router

The client needs to reach the server from the internet, so the router at the server site has to pass that one port through. Every router's menus are different, but the setting is usually called Port Forwarding, Virtual Server or NAT.

  1. Log in to the router, usually at 192.168.1.1 or the address printed on it.
  2. Add a port‑forward rule. Protocol: TCP. External port: your port (e.g. 5000). Internal IP: the board's Node IP (e.g. 192.168.1.50). Internal port: the same port.
  3. Save the rule.
  4. Note your public IP address. If your provider doesn't give you a fixed one, set up a free dynamic DNS name (many routers have this built in) so the client can find the server even if the IP changes.
Only that one port is opened, and only to the bridge. Everything on the tunnel is AES‑256 encrypted with your shared key, and a board without the right key can't connect.

Step 5

5Set up the client end

  1. Power the Client board at site B, with its antenna fitted.
  2. Join its MeshBridge‑XXXX WiFi (password meshbridge) and open http://192.168.4.1.
  3. Open Radio & network settings and fill in the settings below.
SettingWhat to enter on the client
Namee.g. Site B Bridge.
Roleclient (dials out)
WiFi — SSID / PasswordSite B's WiFi network.
Use static IPOptional. DHCP is fine for the client.
Companion (peer) IP / domainThe server site's public IP or dynamic DNS name, not the server's 192.168… address.
PortThe same port as the server (e.g. 5000).
Shared key (PSK)The same passphrase as the server.
RadioThe Mesh B settings. These don't need to match Mesh A.
  1. Before saving, you can click Test connection. “TCP reachable in … ms” means the client can reach the server through the router. The test needs the client to be on the internet, so if it's still in setup mode, save first and re‑run the test from the dashboard's settings page.
  2. Click Save & reboot. The client joins WiFi and dials the server.

Step 6

6Test end to end

Check the link

  • On the dashboard, both status pills (Mesh and Peer) should be lit.
  • The Connection panel shows Link: UP, the role, the peer address and the WiFi signal.
  • On the board's screen, IP LINK [2/4] shows the peer as connected. On the server, the settings test reads “Server mode: listening on port … (peer … connected)”.

Send a real message

  1. With a MeshCore companion on Mesh A, send a message on a public channel, or send an advert.
  2. On the server's dashboard, the counter for packets sent to IP should go up. On the client's, the counter for packets injected into the mesh should go up. The live packet log shows each packet with its type (ADVERT, GRP_TXT, TXT_MSG…), its hop count and its direction (mesh->ip / ip->mesh).
  3. Check that the message arrives on a companion on Mesh B.
  4. Now reply from Mesh B and check it arrives on Mesh A. If it does, the bridge works in both directions.
You'll see some packets counted as dropped. That's normal: the bridge skips packets it has already forwarded, which is what stops them looping between the two meshes. If you've added packet filter rules, blocked packets show in the log as → air, ✕ ip or ✕ ip blocked.

Step 7

7Mount & power

  • Height beats power. Put the antenna as high as practical, clear of metal roofing and walls. At each end the bridge is only as good as its view of the local mesh.
  • Keep it in WiFi range. The board needs both a clear LoRa path and a steady WiFi signal. The BRIDGE [3/4] screen and the dashboard show the WiFi signal in dBm; better than about -70 dBm is comfortable.
  • Weatherproof it. Use a vented, sealed enclosure outdoors, with a drip loop on the cables, and keep the board out of direct sun.
  • Use steady power. Use a good-quality 5 V supply. A small UPS or power bank on the router and bridge keeps the link up through short outages.
  • Keep the settings safe. Record each board's name, role, IP, port and radio settings. Store the PSK somewhere secure.

Ongoing

Updates & maintenance

Updating firmware

  • Over WiFi: download the app image (ipbridge-1.1.1-ota.bin for v1.1.1; not firmware-merged.bin, which is the full image for the USB flasher), then on the dashboard open Firmware update, choose that file and click Upload & flash. The board reboots into the new version by itself. Don't power it off during the upload.
  • Over USB: use the browser flasher again. If you don't choose Erase device, your saved settings are kept.
  • The FIRMWARE [4/4] screen shows the installed build date, so you can confirm the update took.

Dashboard controls

ButtonWhat it does
Pause / ResumeStops forwarding in both directions without disconnecting. Useful while testing a mesh on its own.
Reset countersZeros the packet statistics.
Reconnect peerDrops and re‑establishes the tunnel, e.g. after the server's public IP changes.
Packet filterNew in v1.1.1. Choose which packets may cross the IP link, with a Bypass switch for testing. See How packet filtering works.

Support

Troubleshooting

“Could not reach companion (check IP/port/forwarding)”

The client can't open a connection to the server. Work through these checks: the server is powered and on WiFi; the port forward points at the server's current local IP (a static IP or DHCP reservation stops this changing); the port matches on both boards and in the router; the client's peer address is the server site's public IP or DNS name; and the server site isn't behind CGNAT (see step 1).

“decrypt failed (wrong PSK?)”

The boards connected, but their shared keys don't match. Re‑enter the PSK on both boards, checking capitals, spaces and any auto‑correct on your phone, then click Save & reboot.

“dns lookup failed”

The client couldn't turn the server's domain name into an IP address. Check the spelling, check that the dynamic DNS name is up to date, or try the public IP directly. If you set a static IP on the client, make sure DNS is blank (so it uses the router) or set to a working server.

“peer silent” or the link keeps dropping

The tunnel came up but has stopped hearing from the other end. This is usually weak WiFi at one board, a router rebooting, or a mobile connection dropping out. Check the WiFi signal on both dashboards and move the board or add a WiFi extender if needed. The client reconnects automatically once the path is back.

The MeshBridge‑XXXX WiFi doesn't appear

The setup network only appears while the board isn't connected to a WiFi network. If you've already saved WiFi details, the board is on that network instead, so browse to its IP address shown on the IP LINK [2/4] screen. If you can't find it on the network (for example, the WiFi password was mistyped), re‑flash it with Erase device to start fresh.

Link is UP but messages don't come through

This is almost always the radio settings. Each board must match its own mesh exactly: frequency, bandwidth, spreading factor and coding rate. Check the [1/4] radio screen, and look at the dashboard: if nothing is coming in from the mesh, the board isn't hearing its local mesh. Also check Pause isn't on, and that the antenna is fitted and in range of at least one local node.

Messages only go one way

Look at the dashboard on the end that isn't receiving. If packets arrive over IP but never reach the mesh, the problem is that board's radio settings, TX power or antenna. If nothing arrives over IP, check the counters on the sending end: that board may not be hearing its own mesh.

Some messages or channels don't cross the link

Check the Packet filter panel on both dashboards — each end has its own rules. Look for a rule with a rising “blocked” count, and check the direction setting. Click Bypass filter to confirm: if traffic flows while bypassed, it's a filter rule. See packet filtering troubleshooting.

The dashboard shows a radio error

The LoRa radio didn't start with the saved settings. Check that the frequency is in your antenna and board's band and that the other radio values are valid, then click Save & reboot. If it persists, re‑flash with erase.

Still stuck?

Take a screenshot of both dashboards (Connection panel and counters) and a photo of each board's screen, then get in touch. See Support on the main page.

Reference

Settings at a glance

SettingServerClientMust match?
Roleserver (fixed IP end)client (dials out)Opposite
Companion (peer) IP / domainblankserver's public IP / DNS—
Porte.g. 5000sameYes
Shared key (PSK)your passphrasesameYes
WiFisite A networksite B networkNo
Static IPrecommendedoptionalNo
Radio (freq, BW, SF, CR)Mesh A valuesMesh B valuesNo — each matches its own mesh

Status screen pages

PageShows
[1/4] radioFrequency, spreading factor, bandwidth and coding rate
IP LINK [2/4]WiFi network, the board's IP, peer and link state
BRIDGE [3/4]Packets sent to IP and received from the mesh, WiFi signal, uptime
FIRMWARE [4/4]Installed firmware build date
← Back to the MeshCore IP Bridge