MeshCore logo

How-to guide

Packet filtering

Choose exactly which MeshCore traffic is allowed to cross the MeshCore IP Bridge's internet link — without changing anything on your local mesh.

New in firmware v1.1.1 Off by default Rules saved across reboots

Overview

What the filter does

Without a filter, the IP Bridge forwards every packet it hears on one mesh to the other. The packet filter adds a checkpoint on each board that decides, packet by packet, whether it may cross the internet link.

Unchanged

Your local mesh

The bridge is also a normal MeshCore repeater. A packet blocked from crossing the link is still repeated on the local mesh as usual. Filtering never makes the local mesh quieter or less reliable.

Filtered

Only the internet hop

The filter only decides what goes out over the tunnel and what comes in from it. A blocked outbound packet is never sent; a blocked inbound packet is never transmitted into the local mesh.

Off by default. With no rules, every packet crosses exactly as it did in v1.0.0. Updating to v1.1.1 changes nothing until you add a rule.

Use cases

When to use it

  • Save airtime on the far mesh. Flood adverts from a busy mesh can take up a lot of airtime on a small one. Block them from crossing and keep the messages.
  • Keep a local channel local. A #hashtag or private channel for your own area doesn't need to be heard on the other side of the country — or the world.
  • Share just one channel. Link two communities for a single shared #channel while keeping the Public channel on each side separate.
  • One‑way feeds. Let a bulletin or alerts channel flow into a mesh without anything flowing back.
  • Troubleshooting. Isolate a noisy packet type while you track down its source, then remove the rule.

Reference

Rule types

Every rule is a block rule: anything that matches a rule is stopped, and everything else crosses. Keywords aren't case‑sensitive.

By packet type

RuleBlocks
advertFlood adverts — the node announcements that spread across the whole mesh.
advert0Zero‑hop adverts — announcements meant only for nodes in direct radio range.
txtDirect (private, one‑to‑one) text messages.
grp_txtAll channel text messages, on every channel. To block just one channel, use a channel rule below.
grp_dataAll channel data packets.
ackDelivery acknowledgements.
req responseRequests to a node (e.g. login, status, telemetry) and their responses.
anon_reqAnonymous requests, such as logging in to a room server or repeater.
pathReturned‑path packets, which let two nodes learn a direct route to each other.
traceTrace packets used to test a route.
multipart control rawMultipart, control and raw/custom packets.

By channel

RuleBlocks
publicThe default MeshCore Public channel.
#nameA hashtag channel, e.g. #foxton. Type the name exactly as the channel uses it, including the # — capitals matter. No spaces or , | " \.
psk:<base64>A private channel, identified by its secret key in base64 (the key you'd share in a channel link or QR code). 16‑ or 32‑byte keys are accepted.

Up to 16 channel rules can be active at once, alongside any number of type rules.

Think before blocking plumbing. Rules such as ack, path and advert keep the mesh working across the link. Blocking ack means senders never see a message as delivered and may retry; blocking path stops nodes learning direct routes; blocking advert means new contacts on the far side won't appear in your contact list. Channel messages are unaffected by all three.

Under the hood

How channel rules match

MeshCore channel messages are encrypted, so the bridge can't read them — and doesn't need to. Each channel message carries a 1‑byte channel hash, worked out from the channel's key, followed by a short message authentication code (MAC) made with that key.

  1. When you add a channel rule, the bridge works out that channel's key: the well‑known Public key, the key derived from the #name, or the key you pasted in.
  2. For each channel message, it first compares the 1‑byte hash. Only 256 hash values exist, so different channels will sometimes share one.
  3. If the hash matches a rule, the bridge then checks the MAC using that rule's key. Only if the MAC also matches is the message blocked.
No accidental blocks. An unrelated private channel that happens to share a hash byte with a rule still crosses. The dashboard counts these as “hash look‑alikes passed (MAC check)”, and the feed shows “ch xx matches a rule but MAC differs: passed”. Messages are never decrypted — checking the MAC is enough.
The feed shows each channel message's hash, e.g. ch d9, and each channel rule chip on the dashboard shows the hash it matches. If a #name rule never gets any hits, compare the two — a different hash usually means the name's capitalisation differs from the channel's.

Reference

Direction & which end

Each board has its own rules and its own direction setting. Rules aren't copied across the link.

DirectionOn this board, rules apply to…
both waysPackets heard on the local mesh going out to the tunnel, and packets arriving from the tunnel going into the local mesh. This is the default.
mesh → IP onlyOnly what this board sends out. Traffic arriving from the other end is never filtered here.
IP → mesh onlyOnly what this board lets into its local mesh. Everything it hears locally is still sent out.
Tip

Block at the sending end

If you control both boards, block traffic where it leaves (mesh → IP). It then never uses internet bandwidth, and the other end doesn't have to discard it.

Tip

Protect your own mesh

If you only control your end, use IP → mesh rules to decide what the other side is allowed to put on your mesh's airtime.

The direction applies to all of a board's rules together. For a one‑way channel feed, block the channel in the direction you don't want — e.g. to let #alerts flow from A to B only, add it on board B with mesh → IP only, or on board A with IP → mesh only.

How to

1Set up from the dashboard

  1. Make sure the board is running v1.1.1 or later. To update, download ipbridge-1.1.1-ota.bin and upload it from the dashboard's Firmware update page, or re‑flash from the main page without erasing. Your settings are kept.
  2. Open the board's dashboard in a browser, e.g. http://192.168.1.50, and find the Packet filter panel. With no rules it reads “No rules — everything crosses (default)”.
  3. For common rules, tap a quick‑add button: + Adverts, + Zero‑hop adverts or + Public channel.
  4. For anything else, type a rule into the box — e.g. #foxton, txt or psk:… — and click Block. If the rule isn't valid, the reason appears next to the buttons.
  5. Choose the Direction: both ways, mesh → IP only, or IP → mesh only.
  6. Each rule appears as a chip showing how many packets it has blocked. Click × on a chip to remove it, or Clear all rules to start again.

Changes take effect immediately and are saved on the board straight away, so they survive a reboot or power cut. There's no need to click Save & reboot.

Bypass for A/B testing

⏸ Bypass filter temporarily lets everything through while keeping your rules. The panel shows BYPASSED while it's on. Click ▶ Re‑enable filter to switch back. Bypass isn't saved, so a reboot always turns the filter back on.

How to

2Watching it work

The dashboard's live packet log and counters show exactly what the filter is doing.

You seeMeaning
→ air, ✕ ipHeard on the local mesh and repeated there, but blocked from going out over the link. The reason shows the rule, e.g. filter: advert.
✕ ip blockedArrived from the other end but blocked from entering this mesh.
Filtered → IPCounter of packets blocked on the way out.
Filtered ← IPCounter of packets blocked on the way in.
“N blocked” on a chipHow many packets that rule has stopped.
hash look‑alikes passedChannel messages that shared a rule's hash byte but belonged to a different channel, so were allowed through.

Reset counters also zeros the per‑rule counts.

Examples

Common recipes

Stop flood adverts crossing, keep messages

On both boards: + Adverts, direction mesh → IP only.

Contacts you already have on the far side keep working. New far‑side nodes won't appear until they advert while the rule is off.

Keep each side's Public channel separate

On both boards: + Public channel, direction both ways. Hashtag channels, private channels and direct messages still cross.

Keep a local channel off the link

On your board: add #foxton (your channel name, exactly as typed in the app), direction both ways.

Only channel chat crosses

Block txt, req, response, anon_req and trace. Channel messages keep flowing; direct messages and remote admin stay on each side.

Advanced

Serial & HTTP control

USB serial or remote admin CLI

The same rules can be managed from the USB serial console, or remotely from a MeshCore app's repeater admin command line.

ipfilter                    # show rules, direction and hit counts
ipfilter add advert         # add a rule
ipfilter add #foxton
ipfilter del public         # remove a rule
ipfilter dir out            # both | out (mesh → IP) | in (IP → mesh)
ipfilter bypass 1           # 1 = bypass, 0 = filter on
ipfilter clear              # remove all rules

HTTP API

For scripting from the local network:

GET  /api/filter
POST /api/filter   {"op":"add","value":"#foxton"}
                   # op: add | del | clear | dir | bypass
A psk: rule contains a private channel's secret key. Anyone who can open the dashboard, or read the board's rules, can see it. Keep the dashboard on a network you trust.

Support

Troubleshooting

A #hashtag rule never blocks anything

The name must match the channel exactly, including capitals — #Foxton and #foxton are different channels. Compare the ch xx hash on the rule chip with the hash shown on that channel's messages in the feed. If they differ, remove the rule and re‑add it with the right spelling.

Something is blocked that shouldn't be

Click Bypass filter. If the traffic flows again, it's a rule: check which chip's blocked count goes up, and remember that grp_txt blocks every channel. Also check the other board — it has its own rules.

Direct messages cross but never show as delivered

An ack rule is probably blocking the delivery receipts on one of the boards. Remove it.

My rules disappeared after re‑flashing

Rules are stored with the board's other settings, so choosing Erase device when flashing clears them. Updating over WiFi, or flashing without erasing, keeps them. Note down your rules (the ipfilter command prints them all) before a full erase.

The dashboard has no Packet filter panel

The board is still on v1.0.0. Update it to v1.1.1 — see step 1. The FIRMWARE [4/4] screen on the board shows the installed build.

Acknowledgement

The packet filter idea comes from Mr Stone's meshcore-esp-now-filtered-bridge (MIT licence). It has been re‑implemented for the IP Bridge, with the added channel MAC check described above.

← Back to the MeshCore IP Bridge Installation guide →