dandri/HaloKeymind
1
0
Fork 0
mirror of https://github.com/mikecarper/MeshCore.git synced 2026-09-02 20:03:49 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5fc8e8e7f9a051ae7fa071004fbd2fc00e6abaab
HaloKeymind/filter_tool/index.html
T
mikecarper 818a36b8c4 deploy: 88ba5b26cb
2026-08-10 19:39:43 +00:00

1925 lines
51 KiB
HTML
Raw Blame History

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="Documentation for the open source MeshCore firmware">
<link rel="canonical" href="https://mikecarper.github.io/MeshCore/filter_tool/">
<link rel="prev" href="../faq/">
<link rel="next" href="../flood_filtering/">
<link rel="icon" href="../assets/images/favicon.png">
<meta name="generator" content="mkdocs-1.6.1, mkdocs-material-9.7.7">
<title>Filter policy playground - MeshCore Docs</title>
<link rel="stylesheet" href="../assets/stylesheets/main.ec1eaa64.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
<link rel="stylesheet" href="../_stylesheets/extra.css">
<link rel="stylesheet" href="../_stylesheets/telemetry_decoder.css">
<link rel="stylesheet" href="../_stylesheets/filter_tool.css">
<script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
</head>
<body dir="ltr">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#filter-policy-playground" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href=".." title="MeshCore Docs" class="md-header__button md-logo" aria-label="MeshCore Docs" data-md-component="logo">
<img src="../_assets/meshcore.svg" alt="logo">
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
MeshCore Docs
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
Filter policy playground
</span>
</div>
</div>
</div>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog">
<label class="md-search__overlay" for="__search"></label>
<div class="md-search__inner" role="search">
<form class="md-search__form" name="search">
<input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
<label class="md-search__icon md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg>
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg>
</label>
<nav class="md-search__options" aria-label="Search">
<button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>
</button>
</nav>
<div class="md-search__suggest" data-md-component="search-suggest"></div>
</form>
<div class="md-search__output">
<div class="md-search__scrollwrap" tabindex="0" data-md-scrollfix>
<div class="md-search-result" data-md-component="search-result">
<div class="md-search-result__meta">
Initializing search
</div>
<ol class="md-search-result__list" role="presentation"></ol>
</div>
</div>
</div>
</div>
</div>
<div class="md-header__source">
<a href="https://github.com/mikecarper/MeshCore/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
mikecarper/MeshCore
</div>
</a>
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href=".." title="MeshCore Docs" class="md-nav__button md-logo" aria-label="MeshCore Docs" data-md-component="logo">
<img src="../_assets/meshcore.svg" alt="logo">
</a>
MeshCore Docs
</label>
<div class="md-nav__source">
<a href="https://github.com/mikecarper/MeshCore/" title="Go to repository" class="md-source" data-md-component="source">
<div class="md-source__icon md-icon">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M439.6 236.1 244 40.5c-5.4-5.5-12.8-8.5-20.4-8.5s-15 3-20.4 8.4L162.5 81l51.5 51.5c27.1-9.1 52.7 16.8 43.4 43.7l49.7 49.7c34.2-11.8 61.2 31 35.5 56.7-26.5 26.5-70.2-2.9-56-37.3L240.3 199v121.9c25.3 12.5 22.3 41.8 9.1 55-6.4 6.4-15.2 10.1-24.3 10.1s-17.8-3.6-24.3-10.1c-17.6-17.6-11.1-46.9 11.2-56v-123c-20.8-8.5-24.6-30.7-18.6-45L142.6 101 8.5 235.1C3 240.6 0 247.9 0 255.5s3 15 8.5 20.4l195.6 195.7c5.4 5.4 12.7 8.4 20.4 8.4s15-3 20.4-8.4l194.7-194.7c5.4-5.4 8.4-12.8 8.4-20.4s-3-15-8.4-20.4"/></svg>
</div>
<div class="md-source__repository">
mikecarper/MeshCore
</div>
</a>
</div>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href=".." class="md-nav__link">
<span class="md-ellipsis">
Introduction
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../WiFi/" class="md-nav__link">
<span class="md-ellipsis">
WiFi and MQTT by Firmware Type
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cli_build_matrix/" class="md-nav__link">
<span class="md-ellipsis">
CLI Availability by Firmware Build
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cli_command_availability/" class="md-nav__link">
<span class="md-ellipsis">
CLI Command Availability Matrix
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../cli_commands/" class="md-nav__link">
<span class="md-ellipsis">
CLI Commands
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../companion_protocol/" class="md-nav__link">
<span class="md-ellipsis">
Companion Protocol
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../companion_radio_full/" class="md-nav__link">
<span class="md-ellipsis">
Full Companion
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../docs/" class="md-nav__link">
<span class="md-ellipsis">
Local Documentation
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../faq/" class="md-nav__link">
<span class="md-ellipsis">
Frequently Asked Questions
</span>
</a>
</li>
<li class="md-nav__item md-nav__item--active">
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
<label class="md-nav__link md-nav__link--active" for="__toc">
<span class="md-ellipsis">
Filter policy playground
</span>
<span class="md-nav__icon md-icon"></span>
</label>
<a href="./" class="md-nav__link md-nav__link--active">
<span class="md-ellipsis">
Filter policy playground
</span>
</a>
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#build-a-policy" class="md-nav__link">
<span class="md-ellipsis">
Build a policy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#payload-type-reference" class="md-nav__link">
<span class="md-ellipsis">
Payload type reference
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#current-fpf7-command-mapping" class="md-nav__link">
<span class="md-ellipsis">
Current FPF7 command mapping
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#proposed-evaluation-contract" class="md-nav__link">
<span class="md-ellipsis">
Proposed evaluation contract
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
<a href="../flood_filtering/" class="md-nav__link">
<span class="md-ellipsis">
Flood Filtering and Moderation
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../gps_tracking/" class="md-nav__link">
<span class="md-ellipsis">
GPS Tracking
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../halo_keymind_settings/" class="md-nav__link">
<span class="md-ellipsis">
Halo and Keymind Branch Settings
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../kiss_modem_protocol/" class="md-nav__link">
<span class="md-ellipsis">
MeshCore KISS Modem Protocol
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../lora_ota_automation/" class="md-nav__link">
<span class="md-ellipsis">
Scripted LoRa OTA from start to finish
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../nrf52_power_management/" class="md-nav__link">
<span class="md-ellipsis">
nRF52 Power Management
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../number_allocations/" class="md-nav__link">
<span class="md-ellipsis">
Number Allocations
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ota_easy/" class="md-nav__link">
<span class="md-ellipsis">
Easy firmware updates over LoRa
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ota_meshtower_v2_sdcard/" class="md-nav__link">
<span class="md-ellipsis">
MeshTower V2 microSD LoRa OTA
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ota_protocol/" class="md-nav__link">
<span class="md-ellipsis">
MeshCore OTA - .mota container &amp; LoRa protocol
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../ota_user_guide/" class="md-nav__link">
<span class="md-ellipsis">
Updating your node over the air (OTA) - user guide
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../packet_format/" class="md-nav__link">
<span class="md-ellipsis">
Packet Format
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../payloads/" class="md-nav__link">
<span class="md-ellipsis">
Payload Format
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../qr_codes/" class="md-nav__link">
<span class="md-ellipsis">
QR Codes
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../stats_binary_frames/" class="md-nav__link">
<span class="md-ellipsis">
Stats Binary Frame Structures
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../telemetry_decoder/" class="md-nav__link">
<span class="md-ellipsis">
Telemetry history decoder
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../terminal_chat_cli/" class="md-nav__link">
<span class="md-ellipsis">
Terminal Chat CLI
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
Table of contents
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#build-a-policy" class="md-nav__link">
<span class="md-ellipsis">
Build a policy
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#payload-type-reference" class="md-nav__link">
<span class="md-ellipsis">
Payload type reference
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#current-fpf7-command-mapping" class="md-nav__link">
<span class="md-ellipsis">
Current FPF7 command mapping
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#proposed-evaluation-contract" class="md-nav__link">
<span class="md-ellipsis">
Proposed evaluation contract
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<a href="https://github.com/mikecarper/MeshCore/edit/keymindCascade/docs/filter_tool.md" title="Edit this page" class="md-content__button md-icon" rel="edit">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg>
</a>
<h1 id="filter-policy-playground">Filter policy playground</h1>
<p>Build a forwarding policy, see its readable definition, and simulate how a
repeater handles a packet. Rules match received packet facts, then apply actions
such as dropping, scoping, rate-limiting, or retrying a flood.</p>
<p>Everything runs locally in this browser. Channel keys, packet facts, and policy
drafts are not uploaded anywhere.</p>
<div class="filter-design-warning" role="note">
<strong>Policy design preview</strong>
<p>
The phases and core conditions model current FPF7 behavior, including its
forward rows, scope rewrites, and shared blacklist. The readable policy
language, JSON, and Base64 bundle are still a prototype: current firmware
is configured with <code>set flood.*</code> commands and cannot install a
bundle from this page.
</p>
</div>
<h2 id="build-a-policy">Build a policy</h2>
<p>Start with an example or build a rule, then test the draft against packet facts
in the simulator below. The examples draw from
<a href="../flood_filtering/">Flood Filtering and Moderation</a>.</p>
<div class="filter-tool" data-filter-tool>
<div class="filter-management-safety" role="note">
<strong>Remote login and direct routes</strong>
<p>
This policy only decides whether a relay retransmits a flood. Direct
packets and local delivery are unaffected. Rules matching the login/admin
family can still reduce multi-hop remote-login reach, so the analyzer
flags them.
</p>
</div>
<div class="filter-tool-toolbar" aria-label="Policy examples">
<div class="filter-example-heading">
<strong>Example policies</strong>
<span>Choose one to load its full rules into the builder and draft.</span>
</div>
<div class="filter-example-primer" role="note">
<p>
Read each summary as <code>when</code> all conditions match,
<code>do</code> the actions. A match alone does not stop forwarding.
</p>
<div class="filter-primer-tables">
<table class="filter-primer-table">
<caption>Payload selectors</caption>
<thead>
<tr><th><code>type=</code> value</th><th>Matches</th></tr>
</thead>
<tbody>
<tr><td><a href="#payload-type-reference"><code>grp_data</code></a></td><td>Only the named payload type; see every exact type below</td></tr>
<tr><td><code>any</code></td><td>Every payload type</td></tr>
<tr><td><code>class:group</code></td><td>GRP_TXT and GRP_DATA</td></tr>
<tr><td><code>class:login</code></td><td>REQ, RESPONSE, TXT_MSG, ANON_REQ, and PATH</td></tr>
<tr><td><code>class:other</code></td><td>Every remaining payload type that is not group or login</td></tr>
</tbody>
</table>
<table class="filter-primer-table">
<caption>Other conditions and actions</caption>
<thead>
<tr><th>Field</th><th>Meaning</th></tr>
</thead>
<tbody>
<tr><td><code>hops=</code></td><td>Received hop count: <code>all</code>, <code>3+</code>, <code>2-6</code>, or <code>3</code></td></tr>
<tr><td><code>channel=</code></td><td><code>*</code> means no channel condition; a name or key authenticates one group channel</td></tr>
<tr><td><code>rx.scope=</code></td><td>Original incoming transport scope</td></tr>
<tr><td><code>path=</code></td><td>Path prefix, blacklist, bucket, or loop match</td></tr>
<tr><td><code>tempradio=</code></td><td>Temporary-radio state</td></tr>
<tr><td><code>do drop</code></td><td>Do not retransmit</td></tr>
<tr><td><code>do scope=</code></td><td>Set the outgoing transport scope</td></tr>
<tr><td><code>do rate=</code></td><td>Apply a per-minute rate and burst</td></tr>
<tr><td><code>do timing=</code></td><td>Select fast, normal, or slow scheduling</td></tr>
</tbody>
</table>
</div>
<p class="filter-primer-note">
There is no <code>class:txt</code>. Use <code>type=grp_txt</code> for
channel text or <code>type=txt_msg</code> for peer text.
</p>
</div>
<div class="filter-example-grid">
<button type="button" data-example="channel_scope">
<span>Set #BlackHole86 scope on all #rgdata group traffic</span>
<code>when type=class:group hops=all channel=#rgdata do scope=#BlackHole86 timing=fast</code>
</button>
<button type="button" data-example="blackhole">
<span>Add #BlackHole86 scope to unscoped #rgdata data</span>
<code>when type=grp_data hops=all channel=#rgdata rx.scope=none do scope=#BlackHole86 timing=fast</code>
</button>
<button type="button" data-example="scope_rewrite">
<span>Replace #usa with #BlackHole86 on #rgdata data</span>
<code>when type=grp_data hops=all channel=#rgdata rx.scope=scope:usa do scope=#BlackHole86 timing=fast</code>
</button>
<button type="button" data-example="prefix_rate">
<span>Rate-limit packets whose path starts with 860C</span>
<code>when type=any hops=all path=prefix:860C do rate=10/min burst=10</code>
</button>
<button type="button" data-example="high_traffic">
<span>Drop selected flood types at their hop limits</span>
<code>when type=control hops=1+ do drop<br>when type=req hops=3+ do drop; same for type=grp_data<br>when type=response hops=9+ do drop; same for type=anon_req and type=path</code>
</button>
<button type="button" data-example="moderation">
<span>Rate-limit Public messages from “Noisy User”</span>
<code>when type=grp_txt hops=all channel=public sender="Noisy User" do rate=5/min burst=5</code>
</button>
<button type="button" data-example="blacklist">
<span>Stop forwarding traffic from blacklisted internet gateways</span>
<code>when type=any hops=all path=blacklist do drop</code>
</button>
<button type="button" data-example="factory">
<span>Drop OTA outside temporary-radio mode and distant #wardriving</span>
<code>when type=ota hops=all tempradio=inactive do drop<br>when type=any channel=#wardriving hops=5+ do drop</code>
</button>
<button type="button" data-example="wildcards">
<span>Set #BlackHole86 scope on login and bucket-matched other traffic</span>
<code>when type=class:login hops=all do scope=#BlackHole86 timing=fast<br>when type=class:other hops=all path=bucket:2 do scope=#BlackHole86 timing=slow</code>
</button>
</div>
</div>
<div class="filter-tool-grid">
<section class="filter-panel filter-builder" aria-labelledby="filter-builder-title">
<div class="filter-panel-heading">
<div>
<p class="filter-eyebrow">Rule builder</p>
<h2 id="filter-builder-title">Create a policy rule</h2>
</div>
<button type="button" data-role="reset-form">Reset form</button>
</div>
<h3>Common match settings</h3>
<div class="filter-form-grid">
<label>
Payload type or class
<select data-field="type">
<option value="any">Any payload type</option>
<option value="class:group">Class: group text and data</option>
<option value="class:login">Class: login/admin family</option>
<option value="class:other">Class: every other payload</option>
<option value="req">REQ</option>
<option value="response">RESPONSE</option>
<option value="txt_msg">TXT_MSG</option>
<option value="ack">ACK</option>
<option value="advert">ADVERT</option>
<option value="grp_txt">GRP_TXT</option>
<option value="grp_data">GRP_DATA</option>
<option value="anon_req">ANON_REQ</option>
<option value="path">PATH</option>
<option value="trace">TRACE</option>
<option value="multipart">MULTIPART</option>
<option value="control">CONTROL</option>
<option value="ota">OTA</option>
<option value="13">Reserved type 13</option>
<option value="14">Reserved type 14</option>
<option value="raw_custom">RAW_CUSTOM</option>
</select>
</label>
<label>
Received hops
<input data-field="hops" value="all" placeholder="all, 5+, 2-6, or 3">
</label>
<label>
Channel (optional)
<input data-field="channel" placeholder="*, #rgdata, public, or key">
</label>
<label>
Original incoming scope
<input data-field="incoming" list="policy-incoming-options" value="any" placeholder="any">
<datalist id="policy-incoming-options">
<option value="any"></option>
<option value="none"></option>
<option value="scoped"></option>
<option value="allowed"></option>
<option value="unknown"></option>
<option value="scope:usa"></option>
<option value="region:west"></option>
</datalist>
</label>
<label>
Path matcher
<select data-field="path-kind">
<option value="none">No path condition</option>
<option value="prefix">Ordered 1/2/3-byte pbyte prefix</option>
<option value="blacklist">Passive blacklist</option>
<option value="bucket:1">Path bucket 1</option>
<option value="bucket:2">Path bucket 2</option>
<option value="bucket:3">Path bucket 3</option>
<option value="bucket:4">Path bucket 4</option>
<option value="bucket:5">Path bucket 5</option>
<option value="bucket:6">Path bucket 6</option>
<option value="loop:strict">Own-ID loop: strict</option>
<option value="loop:moderate">Own-ID loop: moderate</option>
<option value="loop:minimal">Own-ID loop: minimal</option>
</select>
</label>
<label>
Ordered pbyte prefix
<input data-field="path-prefix" placeholder="86, 860C, or 860C,12A4">
</label>
<label>
Decrypted sender (optional)
<input data-field="sender" maxlength="31" placeholder="Noisy User">
</label>
<label>
Temporary-radio state
<select data-field="temp-radio">
<option value="any">Either state</option>
<option value="inactive">Inactive</option>
<option value="active">Active</option>
</select>
</label>
</div>
<h3>Common actions</h3>
<p class="filter-field-help">
Choosing a phase-specific action automatically selects a compatible
phase and ACL owner. Open the advanced section to inspect or override
those choices.
</p>
<div class="filter-form-grid">
<label>
Forwarding verdict
<select data-field="verdict">
<option value="continue">No verdict change</option>
<option value="drop">Drop / do not retransmit</option>
</select>
</label>
<label>
Region-gate decision
<select data-field="scope-gate">
<option value="unchanged">Leave global gate unchanged</option>
<option value="require_allowed">Require original allowed region</option>
<option value="bypass_global">Bypass global gate for this packet</option>
</select>
</label>
<label>
Scope rewrite target
<select data-field="target-kind">
<option value="none">Do not rewrite scope</option>
<option value="scope">Regionless public scope</option>
<option value="region">Configured region</option>
</select>
</label>
<label>
Target name
<input data-field="target" placeholder="BlackHole86">
</label>
<label>
Token rate per minute (optional)
<input data-field="rate" type="number" min="1" max="65534" inputmode="numeric" placeholder="unlimited">
</label>
<label>
Burst tokens
<input data-field="burst" type="number" min="1" max="65534" inputmode="numeric" placeholder="defaults to rate">
</label>
<label>
Rewrite timing
<select data-field="timing">
<option value="inherit">Inherit normal behavior</option>
<option value="fast">Fast-track rewrite</option>
<option value="normal">Normal queue timing</option>
<option value="slow">Slow receive/transmit timing</option>
</select>
</label>
<label>
Queue priority
<select data-field="queue">
<option value="inherit">Inherit</option>
<option value="high">High</option>
<option value="normal">Normal</option>
<option value="low">Low</option>
</select>
</label>
<label>
Retry path bucket
<select data-field="retry-bucket">
<option value="none">No retry action</option>
<option value="bucket:1">Bucket 1</option>
<option value="bucket:2">Bucket 2</option>
<option value="bucket:3">Bucket 3</option>
<option value="bucket:4">Bucket 4</option>
<option value="bucket:5">Bucket 5</option>
<option value="bucket:6">Bucket 6</option>
</select>
</label>
<label>
Retry attempts
<input data-field="retry-attempts" type="number" min="1" max="10" inputmode="numeric" placeholder="1">
</label>
<label>
Decision tag (optional)
<input data-field="tag" maxlength="24" placeholder="blackhole-ingress">
</label>
</div>
<details class="filter-advanced">
<summary>Advanced execution, ownership, and flood route</summary>
<p class="filter-field-help">
Direct packets already carry a supplied path and are intentionally
outside this engine. The route condition below only distinguishes
unscoped floods from transport-scoped floods.
</p>
<div class="filter-form-grid">
<label>
Stable rule ID
<input data-field="id" value="rule-1" maxlength="32" placeholder="blackhole-rewrite">
</label>
<label>
Processing phase
<select data-field="phase">
<option value="scope_gate">1 - Incoming scope gate</option>
<option value="rewrite">2 - Scope rewrite</option>
<option value="forward">3 - Forwarding decision</option>
<option value="content">4 - Decrypted content</option>
<option value="schedule">5 - Scheduling and retry</option>
</select>
</label>
<label>
Rule owner / capability
<select data-field="owner">
<option value="scope">ACL 4 - Region/scope manager</option>
<option value="filter">ACL 5 - Filter manager</option>
<option value="admin">Administrator</option>
<option value="system">Firmware-managed system rule</option>
</select>
</label>
<label>
Priority
<input data-field="priority" type="number" min="0" max="255" inputmode="numeric" value="100">
</label>
<label>
Mode
<select data-field="mode">
<option value="active">Active</option>
<option value="shadow">Shadow - observe only</option>
<option value="disabled">Disabled</option>
</select>
</label>
<label>
Rule processing after a match
<select data-field="stop">
<option value="none">Continue to later rules</option>
<option value="phase">Skip later rules in this phase</option>
<option value="policy">Skip all later policy rules</option>
</select>
</label>
<label>
Flood route
<select data-field="route">
<option value="flood">Either flood route</option>
<option value="unscoped_flood">Unscoped flood only</option>
<option value="scoped_flood">Transport-scoped flood only</option>
</select>
</label>
</div>
</details>
<div class="filter-live-preview">
<div>
<span class="filter-preview-label">Readable policy definition</span>
<code data-role="live-command"></code>
</div>
<p data-role="live-explanation"></p>
<ul class="filter-inline-warnings" data-role="live-warnings" hidden></ul>
</div>
<div class="filter-builder-actions">
<button class="filter-primary-action" type="button" data-role="save-rule">Add rule to policy</button>
<button type="button" data-role="copy-live">Copy definition</button>
</div>
</section>
<section class="filter-panel filter-policy" aria-labelledby="filter-policy-title">
<div class="filter-panel-heading">
<div>
<p class="filter-eyebrow">Policy draft</p>
<h2 id="filter-policy-title">Rules in execution order</h2>
</div>
<button type="button" data-role="clear-policy">Clear policy</button>
</div>
<div class="filter-policy-target">
<label>
Approximate target budget
<select data-role="target-profile">
<option value="stm32">Compact STM32 - 2 KB</option>
<option value="nrf52" selected>nRF52 - 8 KB</option>
<option value="esp32">Classic ESP32 - 16 KB</option>
<option value="esp32_roomy">Roomy ESP32 - 64 KB</option>
</select>
</label>
</div>
<p class="filter-field-help">
Rules match the same immutable packet facts. Ordering is phase, then
descending priority, then stable rule ID. Drop decisions are sticky.
</p>
<div class="filter-empty-state" data-role="empty-policy">
Add a rule or load an example to start exploring.
</div>
<ol class="filter-rule-list" data-role="rule-list"></ol>
<div class="filter-policy-summary" data-role="policy-summary"></div>
<ul class="filter-inline-warnings" data-role="policy-warnings" hidden></ul>
</section>
</div>
<section class="filter-panel filter-simulator" aria-labelledby="filter-simulator-title">
<div class="filter-panel-heading">
<div>
<p class="filter-eyebrow">Immutable packet simulator</p>
<h2 id="filter-simulator-title">Explain an evaluation</h2>
</div>
<button type="button" data-role="reset-packet">Reset packet</button>
</div>
<div class="filter-packet-reader">
<div class="filter-packet-reader-heading">
<div>
<h3>Read a raw MeshCore packet</h3>
<p class="filter-field-help">
Paste an on-air packet as hexadecimal. The decoder follows the
<a href="../packet_format/">MeshCore wire format</a>, displays its
header, route, pbyte path, and clear payload envelope, then loads
only facts actually present on the wire into the simulator.
</p>
</div>
<span>Runs locally</span>
</div>
<label>
Raw packet hex
<textarea data-role="raw-packet-input" rows="3" spellcheck="false">014e912ceebb98918b86772df5dacf1bcba9e4127ffffaa8665596aa3e2903a3b1901fdc53497dfca6b5d7df2d771bea68de</textarea>
</label>
<div class="filter-builder-actions">
<button class="filter-primary-action" type="button" data-role="decode-packet">Decode and load packet</button>
</div>
<div class="filter-error" data-role="packet-decode-error" role="alert" hidden></div>
<div class="filter-packet-decode" data-role="packet-decode-result" aria-live="polite" hidden></div>
</div>
<div class="filter-form-grid filter-simulator-facts">
<label>
Received route
<select data-packet="route">
<option value="unscoped_flood">Unscoped flood</option>
<option value="scoped_flood">Transport-scoped flood</option>
</select>
</label>
<label>
Payload type
<select data-packet="type">
<option value="req">REQ</option>
<option value="response">RESPONSE</option>
<option value="txt_msg">TXT_MSG</option>
<option value="ack">ACK</option>
<option value="advert">ADVERT</option>
<option value="grp_txt">GRP_TXT</option>
<option value="grp_data" selected>GRP_DATA</option>
<option value="anon_req">ANON_REQ</option>
<option value="path">PATH</option>
<option value="trace">TRACE</option>
<option value="multipart">MULTIPART</option>
<option value="control">CONTROL</option>
<option value="ota">OTA</option>
<option value="13">Reserved type 13</option>
<option value="14">Reserved type 14</option>
<option value="raw_custom">RAW_CUSTOM</option>
</select>
</label>
<label>
Received hops
<input data-packet="hops" type="number" min="0" max="63" inputmode="numeric" value="4">
</label>
<label>
Channel
<input data-packet="channel" value="#rgdata" placeholder="blank if none">
</label>
<label>
Received pbyte path
<input data-packet="path" value="860C,12A4" placeholder="same-width IDs">
</label>
<label>
Original scope status
<select data-packet="scope-status">
<option value="none">Unscoped</option>
<option value="allowed">Allowed region</option>
<option value="unknown">Unknown or denied scope</option>
</select>
</label>
<label>
Original scope name
<input data-packet="scope-name" placeholder="usa">
</label>
<label>
Resolved region name
<input data-packet="region-name" placeholder="west">
</label>
<label>
Decrypted sender
<input data-packet="sender" placeholder="Noisy User">
</label>
<label>
Passive blacklist result
<select data-packet="blacklist">
<option value="no">No match</option>
<option value="yes">Matched</option>
</select>
</label>
<label>
Matching path buckets
<input data-packet="buckets" placeholder="1,3,6">
</label>
<label>
Own-ID loop result
<select data-packet="loop-level">
<option value="0">No loop match</option>
<option value="1">Strict only</option>
<option value="2">Moderate and strict</option>
<option value="3">Minimal, moderate, and strict</option>
</select>
</label>
<label class="filter-simulator-check">
<input data-packet="temp-radio" type="checkbox">
Temporary radio is active
</label>
</div>
<div class="filter-builder-actions">
<button class="filter-primary-action" type="button" data-role="simulate">Run policy simulation</button>
</div>
<div class="filter-error" data-role="simulation-error" role="alert" hidden></div>
<div class="filter-decision" data-role="simulation-result" hidden></div>
</section>
<section class="filter-panel filter-import" aria-labelledby="filter-import-title">
<div class="filter-panel-heading">
<div>
<p class="filter-eyebrow">Import and explain</p>
<h2 id="filter-import-title">Paste readable policy or a saved draft</h2>
</div>
</div>
<p class="filter-field-help">
Accepts one-line <code>policy set ... when ... do ...</code> definitions,
playground JSON, or a playground Base64 bundle.
</p>
<textarea data-role="import-input" spellcheck="false" placeholder="policy set rgdata-scope phase=rewrite owner=scope priority=150 when route=flood type=grp_data hops=all channel=#rgdata rx.scope=none do scope=#BlackHole86 timing=fast"></textarea>
<div class="filter-builder-actions">
<button class="filter-primary-action" type="button" data-role="explain-input">Explain input</button>
<button type="button" data-role="load-input">Load into builder</button>
</div>
<div class="filter-error" data-role="import-error" role="alert" hidden></div>
<div class="filter-explain-results" data-role="explain-results" hidden></div>
</section>
<section class="filter-panel filter-export" aria-labelledby="filter-export-title">
<div class="filter-panel-heading">
<div>
<p class="filter-eyebrow">Export</p>
<h2 id="filter-export-title">Move or save this design</h2>
</div>
</div>
<div class="filter-export-tabs" role="tablist" aria-label="Policy export format">
<button type="button" data-export-tab="dsl" aria-selected="true">Readable policy</button>
<button type="button" data-export-tab="json" aria-selected="false">Policy JSON</button>
<button type="button" data-export-tab="bundle" aria-selected="false">Playground Base64</button>
</div>
<div data-export-panel="dsl">
<p class="filter-field-help">Proposed human-readable definition. Current firmware does not accept it yet.</p>
<textarea data-role="export-dsl" readonly spellcheck="false"></textarea>
</div>
<div data-export-panel="json" hidden>
<p class="filter-field-help">Structured draft used by this page.</p>
<textarea data-role="export-json" readonly spellcheck="false"></textarea>
</div>
<div data-export-panel="bundle" hidden>
<p class="filter-field-help">Browser-playground interchange only. It is not the final packed firmware codec.</p>
<textarea data-role="export-bundle" readonly spellcheck="false"></textarea>
</div>
<div class="filter-builder-actions">
<button type="button" data-role="copy-export">Copy visible export</button>
<button type="button" data-role="download-json">Download JSON</button>
</div>
</section>
</div>
<h2 id="payload-type-reference">Payload type reference</h2>
<p>Use an exact <code>type=</code> value when a rule should match only one payload type.
The class column shows which broader selector also matches it.</p>
<table>
<thead>
<tr>
<th><code>type=</code> value</th>
<th>Payload</th>
<th>Class</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>req</code></td>
<td>Request</td>
<td><code>class:login</code></td>
</tr>
<tr>
<td><code>response</code></td>
<td>Response</td>
<td><code>class:login</code></td>
</tr>
<tr>
<td><code>txt_msg</code></td>
<td>Peer text message</td>
<td><code>class:login</code></td>
</tr>
<tr>
<td><code>ack</code></td>
<td>Acknowledgment</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>advert</code></td>
<td>Node advertisement</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>grp_txt</code></td>
<td>Group-channel text</td>
<td><code>class:group</code></td>
</tr>
<tr>
<td><code>grp_data</code></td>
<td>Group-channel datagram</td>
<td><code>class:group</code></td>
</tr>
<tr>
<td><code>anon_req</code></td>
<td>Anonymous request</td>
<td><code>class:login</code></td>
</tr>
<tr>
<td><code>path</code></td>
<td>Returned path</td>
<td><code>class:login</code></td>
</tr>
<tr>
<td><code>trace</code></td>
<td>Path trace</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>multipart</code></td>
<td>One frame in a multipart sequence</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>control</code></td>
<td>Control or discovery data</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>ota</code></td>
<td>OTA-over-LoRa data</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>13</code></td>
<td>Reserved payload type 13</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>14</code></td>
<td>Reserved payload type 14</td>
<td><code>class:other</code></td>
</tr>
<tr>
<td><code>raw_custom</code></td>
<td>Application-defined raw data</td>
<td><code>class:other</code></td>
</tr>
</tbody>
</table>
<h2 id="current-fpf7-command-mapping">Current FPF7 command mapping</h2>
<table>
<thead>
<tr>
<th>Firmware command</th>
<th>FPF7 role</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>flood.rule</code> / <code>flood.filter</code></td>
<td>Forward-phase match and action rows</td>
</tr>
<tr>
<td><code>flood.channel.data</code></td>
<td>Compatibility view over one visible <code>type=grp_data</code> forward drop row</td>
</tr>
<tr>
<td><code>flood.channel.scope</code></td>
<td>Scope-rewrite phase rows</td>
</tr>
<tr>
<td><code>flood.filter.blacklist</code></td>
<td>One shared unordered path-ID set referenced by <code>path=blacklist</code> rows</td>
</tr>
</tbody>
</table>
<p>Generalized repeaters expose 63 forward rows and commit those sections
together. The blacklist is useful
for refusing to retransmit floods associated with internet gateways dumping
bulk traffic, but a path ID is truncated and unauthenticated; it identifies a
routing pattern, not a person.</p>
<h2 id="proposed-evaluation-contract">Proposed evaluation contract</h2>
<p>The simulator uses these rules:</p>
<ol>
<li>Only flood retransmission enters the policy. Direct routing and local packet
delivery remain outside it.</li>
<li>Every matcher reads the same immutable receive-time packet facts.</li>
<li>Rules run by phase, descending priority, then stable rule ID.</li>
<li>A drop decision is sticky and cannot be undone by a later rule.</li>
<li>The first matching scope, timing, queue, and retry action in execution order
wins.</li>
<li>All matching token-bucket rate constraints remain attached to the decision.</li>
<li><code>stop=phase</code> skips later rules in that phase. <code>stop=policy</code> skips later
configurable rules, but never mandatory packet validation or radio safety.</li>
<li>Shadow rules report what they would do without changing the decision or
stopping other rules.</li>
<li>Expensive facts such as channel-key matching, decryption, and path-table
lookup are resolved once per packet and reused by every matching rule.</li>
</ol>
<p>The byte-budget display is deliberately approximate until the packed firmware
codec exists. It demonstrates why simple mappings should not reserve a maximum-
sized structure for every possible condition and action.</p>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
Made with
<a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
Material for MkDocs
</a>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<script id="__config" type="application/json">{"annotate": null, "base": "..", "features": ["content.action.edit", "content.code.copy", "search.highlight", "search.suggest"], "search": "../assets/javascripts/workers/search.2c215733.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script>
<script src="../assets/javascripts/bundle.d7400e89.min.js"></script>
<script src="../_javascript/telemetry_decoder.js"></script>
<script src="../_javascript/filter_tool.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink