On grid almost every node hears every other one, so the "wireless topology" is always a full graph. This tutorial imposes the one you ask for: a chain, a ring, a star, a grid, a random graph, or anything you draw. Every node joins one 802.11s mesh (or one IBSS), and each node is then made deaf to every node that is not its neighbour in your graph. The run checks that the filters are really in force, that exactly the right pairs reach each other (directly, or through relays), measures traffic against references taken in the same minute, and can take a link down and bring it back while a ping watches.
Read this before any number on this page. Filtering hides frames from the host, not from the radio. On
gridevery node still hears, defers to and collides with every other one on the channel, so every absolute throughput here is that of one shared channel, not of the topology you imposed. Read a flow only as a fraction of the references measured in the same run, and quote the channel busy fraction with it. Hidden-terminal effects cannot be emulated this way at all: two nodes that "cannot hear each other" here still carrier-sense each other. Onsb4the topology can be imposed by the RF matrix instead: nodes that are not linked are 63 dB apart and really cannot hear each other, so there is no contention between them and the throughput you measure is the topology's own. The same topology gives different numbers on the two; see The same topology on sb4 and grid.
grid from the released package cosmos-experiments-wifi 0.1.0-7 (parity PASS, 26.9 / 25.5 / 25.4 Mb/s, evidence evidence/wifi-trio-grid-20261108/), and before the release on grid (eight ath9k nodes, baseline.ndz: parity PASS in all three modes with the mesh backend, nft PASS, the chain-6 contention run PASS) and on sb4 (eight nodes, topology imposed by filters and by the RF matrix, parity PASS both ways). Development copy of the package, engine 0.1.0-389. Evidence: evidence/wifi-topology-grid-20261108/ and evidence/wifi-topology-sb4-20261108/ in cosmos-orchestration.This builds on WiFi Cell, which shares the node code and the radio selection. You describe a topology in a small YAML document with logical nodes (A, B, C, ...). The run measures which physical nodes in OMF_NODES hear each other, places your logical nodes on physical ones that can carry every requested link, and compiles a block list per node. Each node runs one small tool, wifi-topology-node, that the tutorial copies there. All three modes run the same tool with the same options, which come from one parameter file, and write the same result contract, so their results can be compared.
The topology is enforced by one of two backends:
mesh (default). An 802.11s mesh in which each node refuses the peer link to every blocked station. The mesh's own routing protocol, HWMP, then finds multi-hop paths around the blocks.nft. An IBSS (ad hoc) network plus an nftables rule that drops every frame from a blocked source MAC before the host sees it. This works with any radio that can join an IBSS, including Intel cards, and allows one-way links. It does no routing: only direct neighbours talk.| Where | Wi-Fi nodes in the inventory (2026-11-08): grid (about 200), sb4 (9, on the RF matrix), sb5, sb6, sb7 (2 each). bed, sb2, sb9, minicity and osc have none, and cosmos-tutorial check refuses there. grid and sb4 run the default ring of 4; on sb5-sb7 only a two-node topology fits, and a bigger one is refused on the console before any node is touched (the topology has 4 nodes, OMF_NODES only 2). topo_rfmatrix works only on sb4: elsewhere the matrix service refuses the console and so does the run |
| Nodes | at least as many as the topology has nodes (4 for the default ring); extra nodes leave the network once the topology is placed |
| Image | baseline.ndz |
| Radio | mesh: one that can be an 802.11s mesh point (on grid ath9k, ath5k, carl9170, rt2800usb; not Intel). nft: any that can join an IBSS |
| Band | 2.4 GHz channel 1 by default, 20 MHz (HT20 where the radio has HT) |
| Network | 10.99.0.0/24; node i of OMF_NODES takes .i+1 |
| Time | about 3 minutes for the default ring with one flow and one link event |
| Transmits | yes, a mesh or IBSS network for the length of the run |
| Results | contract.json: mapping, filters in force, reachability of every pair, flows against in-run references, channel busy time, the link-event timeline |
baseline.ndz and powered on.| Domains | any domain - the node checks below decide |
| Nodes | at least as many as the topology has nodes (4 for the default ring), named in OMF_NODES |
| On the console | python3, ansible-playbook, ssh, tar |
cosmos-tutorial check wifi-topology verifies, on each node:
The tutorial is installed on the console. There is nothing to download.
cosmos-tutorial check wifi-topology
cosmos-tutorial run wifi-topology # ansible
cosmos-tutorial run wifi-topology --mode manual # manual
cosmos-tutorial jupyter wifi-topology # jupyter
cosmos-tutorial run wifi-topology --mode parity # parity
cosmos-tutorial run wifi-topology --mode teardown # teardown
The nodes are named in OMF_NODES. Their order matters only for addresses (and for mapping if you give one):
export OMF_NODES="node16-20,node18-8,node13-20,node17-11"
omf load -i baseline.ndz -t $OMF_NODES -r 0
omf tell on -t $OMF_NODES
cosmos-tutorial check wifi-topology
cosmos-tutorial run wifi-topology
The topology is a YAML document, either inline in the parameters (topo_graph) or in its own file named by topo_file (relative to the parameters file):
topology:
name: chain-4
directed: false # true: [A, B] means B hears A, and not the reverse (nft backend only)
nodes: [A, B, C, D] # logical names: letters, digits, _ . -
links: [[A, B], [B, C], [C, D]]
# or, instead of nodes and links:
# generator: {type: chain|ring|star|grid|full|random, n: 4, rows: 2, cols: 3, p: 0.4, seed: 1}
mapping: auto # or {A: node17-11, B: node16-20, C: node18-8, D: node13-20}
events: # optional; seconds after the events phase starts
- {at: 5, down: [B, C]}
- {at: 20, up: [B, C]}
flows: [{from: A, to: D}] # or: all-pairs, or {to-sink: D}
chain and ring link neighbours, star links A to everyone, full links everyone, and grid links a rows × cols lattice. random draws a random spanning tree and then adds each other pair with probability p, so the graph is always connected; the same seed gives the same graph. At most 20 nodes.[A, B] and [B, A] count as one undirected link), one-way links with the mesh backend, an event that does not name a link of the topology, and a flow between nodes that are not in it.auto searches for a placement. A table places each logical node by hand, and is checked against what the nodes actually hear.topo_flow_udp_mbps sets a UDP rate. With the nft backend there is no routing, so every flow must join two neighbours linked both ways (TCP needs the return path).editor/topology-editor.html in the tutorial directory is a single page that opens in any browser with no network access. Copy it out with cosmos-tutorial copy wifi-topology, or take it from /usr/share/cosmos-experiments/wifi-topology/editor/.
topo_file, and Import reads such a file back. Node positions travel in a # layout: comment that the run ignores.physical.json and the editor draws the links the air allows in grey, and every requested link it cannot give you in red. Auto-map runs the same placement search as the run.Change any of these with cosmos-tutorial run wifi-topology --params my.yml. An unknown key or a wrong type is refused. cosmos-tutorial params wifi-topology prints the file.
| Key | Default | Meaning |
|---|---|---|
topo_backend |
mesh |
mesh = 802.11s, peer links blocked, HWMP routes around them; nft = IBSS plus a netdev ingress drop by source MAC: one-way links, any radio (Intel too), no routing (flows are one hop). |
topo_channel |
1 |
The channel every node joins on. |
topo_net_id |
cosmos-topology |
The mesh ID or IBSS SSID: 1-32 printable characters, no spaces. |
topo_regdomain |
US |
|
topo_radio |
auto |
Which radio: an index, phy or driver, or auto (the first that can take the role, in the order ath9k, ath10k_pci, mt7921e, carl9170, rt2800usb, iwlwifi, ath5k). |
topo_subnet |
10.99.0.0/24 |
Addresses on the topology network: node i of OMF_NODES takes .i+1 (a /24). |
topo_min_signal_dbm |
-80 |
A physical link needs this signal or better, both ways. |
topo_hear_secs |
8 |
How long each node listens before the filters go on. |
topo_probe_count |
10 |
Pings from every member to every other one. |
topo_idle_secs |
8 |
Channel-time sample with the topology on and no traffic. |
topo_flow_secs |
8 |
Each iperf3 flow, seconds. |
topo_flow_udp_mbps |
`` | null = TCP; a number = UDP offered at that many Mb/s. |
topo_rfmatrix |
False |
A sandbox with an RF matrix (sb4): every pair of nodes is cabled through its own attenuator (0-63 dB). true: first check that 63 dB on every pair disconnects them (nobody may hear anybody), then set every pair to topo_matrix_link_db so the topology can be placed; the matrix goes back as found at the end. |
topo_impose |
filter |
filter = the backend's MAC filter imposes the topology (the radios still hear everyone); matrix = the attenuators impose it: links at topo_matrix_link_db, every other pair at 63 dB, no filter at all (needs topo_rfmatrix: true, and links that work both ways). |
topo_matrix_link_db |
0 |
Attenuation of a link on the matrix, dB. |
topo_matrix_ports |
0 keys | Ports the switch labels cannot give (a port with no switch), as {node: port}. |
topo_matrix_take_switches |
True |
A switch set to an SDR is moved to the node's Wi-Fi for the run and put back afterwards. |
topo_file |
`` | The topology document in its own file (relative to this one), drawn and exported by editor/topology-editor.html; "" = use topo_graph below. |
topo_graph |
4 keys | The topology document itself: logical nodes and links (or a generator), mapping, flows and link events. |
Each mode does the same steps, in this order:
wifi-topology-node, with the radio code shared with WiFi Cell and Wi-Fi packet injection and sniffing, goes to /var/tmp/cosmos/wifi-topology/bin. iperf3, nftables and iw are installed if missing.wifi-topology-node join picks a radio that can be a mesh point (or an IBSS member) on the channel and replaces its interfaces with one called topo0. It then joins the mesh or IBSS at HT20 where the radio has HT (without it the mesh runs at legacy rates, about 17 Mb/s a hop on grid) and takes its address. A USB radio's new interface is renamed by udev (wlx<mac>); the tool names it back.wifi-topology-node hear lists every peer the node hears and how strongly. An IBSS member only lists a peer it has received a frame from, so in IBSS mode every node sends a few broadcast pings first.topo_min_signal_dbm or better. A one-way physical link cannot carry acknowledged traffic, so it does not count. The result is the physical graph (physical.json). mapping: auto searches for a placement of your logical nodes on physical ones such that every requested link lands on a physical link. The search is most-constrained node first, a small backtracking subgraph match with no graph library. If there is none, the run stops and says which links the air does not allow. Each placed node then gets a block list: every other member it should not hear. A node in OMF_NODES that the topology does not use leaves the network, because it would otherwise peer with everyone and relay exactly the traffic the filters exist to stop.wifi-topology-node apply enforces the block list and reads back what the kernel has in force.iw dev topo0 mpath dump) are recorded./run/wifi-topology, and remove topo0. Nothing else on the node is touched.mesh (802.11s) |
nft (IBSS) |
|
|---|---|---|
| Mechanism | iw dev topo0 station set <mac> plink_action block: the mesh peer link to that station is refused |
a netdev ingress rule drops every frame whose source MAC is blocked, before the host sees it |
| Routing | HWMP, the mesh's own routing protocol, finds paths around the blocks | none: only direct neighbours talk |
| One-way links | no (a peer link is up both ways or not at all) | yes |
| Radios | those that can be a mesh point (not Intel) | any radio that can join an IBSS |
The nft rule the tool loads, in full:
table netdev wifi_topology {
set blocked { type ether_addr; elements = { <blocked MACs> } }
chain ingress { type filter hook ingress device "topo0" priority -500; policy accept;
ether saddr @blocked counter drop
}
}
Neither mechanism touches the radio. A blocked peer's frames still reach the antenna, still occupy the channel, and still make this node wait before it transmits.
HWMP chooses paths by an airtime metric: roughly how long a frame would occupy the air on each hop, from the rate and the loss. It does not choose by hop count, so on a ring a lossy short path can lose to a clean longer one. The contract reports HWMP's hop counts beside the shortest-path (BFS) counts, and does not fail a run for a longer path.
Filtering hides frames from the host, not from the radio. On
gridevery node hears every other, so the hops of a multi-hop flow, and every other flow, take turns on one channel. Absolute throughput is that of one shared channel, not of the topology. Compare flows only as fractions of the references measured in the same run, and quote the channel busy fraction with any number. Hidden-terminal behaviour cannot be emulated this way; use thesb4RF matrix for that.
So that every number has a yardstick from the same minute of the same channel, traffic is measured three ways:
Before step 1 (topology on, no traffic) and around step 3, each radio's channel-time counters (iw dev topo0 survey dump) are read. The contract reports the busy fraction, the share of the time the channel was busy, including with traffic from outside the experiment. ath9k, ath5k and carl9170 report these counters. rt2800usb reports zeros, so treat its fraction as not reported. Intel cards report nothing, and the field is then absent rather than zero.
The shared-channel bound. If hop i alone carries rᵢ and all hops share one channel, each bit spends 1/rᵢ seconds on every hop, one hop at a time. A flow over all of them carries at most
R ≤ 1 / Σᵢ (1/rᵢ)
The contract reports each flow as a fraction of that bound (a/bound), and "every flow at once" as a fraction of the flow alone (t/alone).
Example from the 2026-11-07 hand test on grid (chain A-B-C-D on four radio types, mesh backend, HT20, TCP for 8 s; evidence/wifi-topology-grid-20261107/). Each hop alone carried 29.9, 66.5 and 69.2 Mb/s, so one flow over all three can carry at most 1 / (1/29.9 + 1/66.5 + 1/69.2) = 17.3 Mb/s. A to D over three hops carried 13.0 Mb/s, 75 % of the bound. The busy fraction was 0.13-0.19 idle (the building on channel 1) and 0.74-0.76 on every node during the flow. The 75 % and the 0.75 busy fraction are the result; the 13.0 Mb/s alone is not.
sb4's nodes are cabled to an RF matrix: every pair of ports has its own attenuator (0-63 dB), and the radios hear nothing but the cables. With topo_rfmatrix: true and topo_impose: matrix the run builds the topology out of attenuators: each link at topo_matrix_link_db (0 dB), every other pair at the maximum, 63 dB. It first checks that 63 dB on every pair really disconnects them (on 2026-11-08 no node pair heard each other at 63 dB in any run, and no non-neighbour was heard with the topology on), and puts the matrix back as found at the end. Up to nine nodes, eight while node1-2 is out.
This removes the signal itself, not just the frames. Nodes that are not neighbours do not defer to each other, so two links far apart in the topology can carry traffic at the same time, exactly as they would if they were far apart in space. On sb4 the throughput is real; on grid it is that of one shared channel, whatever topology the filters impose.
The experiment that shows it: a chain of six, A-B-C-D-E-F, with two one-hop flows at opposite ends, A→B and E→F (TCP, 15 s each). Each flow runs alone, then both at once. B and E are three hops apart, so in the topology the two flows have nothing to share.
# /usr/share/cosmos-experiments/wifi-topology/reuse6.topo.yml; name it with topo_file (an absolute path)
topology: {name: chain-6, generator: {type: chain, n: 6}}
mapping: auto
flows: [{from: A, to: B}, {from: E, to: F}]
events: []
sb4, matrix |
sb4, filter |
grid, filter |
|
|---|---|---|---|
| Non-neighbour pairs the radios still hear | 0 | 20 | 20 |
| A→B alone / together, Mb/s | 10.5 / 8.4 | 19.4 / 4.0 | 60.1 / 26.7 |
| E→F alone / together, Mb/s | 25.7 / 24.7 | 24.9 / 16.8 | 64.2 / 28.5 |
| together ÷ alone, A→B and E→F | 0.80, 0.96 | 0.20, 0.68 | 0.44, 0.44 |
sb4 2026-11-08, mesh backend, the same eight nodes and cables in both columns (evidence/wifi-topology-sb4-20261108/, runs T192530Z-dklg0g and T192835Z-o8eyt5). The two sb4 columns differ only in how the topology is imposed. With the matrix each flow kept most of its rate with the other running: E→F 96 %; A→B, an ath5k link whose rate varied by ±10 % between its own measurements, 80 %. With filters the two flows took turns on one channel: together they kept 0.88 of one channel, and the faster flow took the larger share, leaving A→B a fifth of its rate. That is the contention every number on grid carries.
grid 2026-11-08, the same topology file on eight ath9k nodes in the middle of the grid, mesh backend (evidence/wifi-topology-grid-20261108/, run T214848Z-mynm7u; an earlier run, T214256Z-o9jym3, gave 0.41 and 0.44). Each flow alone carried about 60 Mb/s, and with the other running each kept 0.44 of it: two flows that the topology puts four hops apart split one channel between them (0.88 of it together, as on sb4 with filters), and every radio's channel was 0.89-0.91 busy. The grid's links are faster than sb4's cabled ones (the radios heard each other at −52 to −26 dBm over the air, against −82 to −65 dBm through the matrix even at 0 dB, which has its own insertion loss), so compare the ratios, not the rates.
Two consequences:
sb4 with the matrix, quote absolute numbers for the topology (on a cabled channel with no fading or outside interference, so they still do not carry over to the air). The shared-channel bound 1 / Σ(1/rᵢ) is then a floor, not a ceiling, because hops that cannot hear each other transmit at once.grid, and on sb4 with filters, quote only fractions of the references in the same run, as above.grid, 2026-11-08 21:34-21:51Z, eight ath9k nodes freshly loaded with baseline.ndz, channel 1, HT20, the default parameters unless noted (evidence/wifi-topology-grid-20261108/):
| Run | Mode | Mapping | Flow A→C (2 hops): hops alone / bound / alone / together | a/bound | Busy idle / traffic | Link A-B cut at 5 s, back at 20 s | Result |
|---|---|---|---|---|---|---|---|
T213451Z-chj05x |
ansible | A, B, C, D = node10-11, 10-17, 10-7, 13-13 | 57.9, 48.8 / 26.5 / 25.1 / 22.6 Mb/s | 0.95 | 0.18-0.27 / 0.69-0.73 | longest ping gap 0.0 s (HWMP routes the long way round at once) | PASS |
| same | manual | D = node11-17 | 63.8, 54.2 / 29.3 / 25.0 / 24.9 | 0.86 | 0.19-0.26 / 0.84-0.86 | 0.0 s | PASS |
| same | Jupyter | D = node11-17 | 63.7, 51.6 / 28.5 / 24.0 / 25.4 | 0.84 | 0.20-0.24 / 0.85-0.86 | 0.0 s | PASS |
| parity | flows 22.6 / 24.9 / 25.4 Mb/s | PASS (auto mapping differed between modes; each was valid) | |||||
T214643Z-j4n8pb |
manual, nft (IBSS) |
node10-11, 10-17, 10-7, 11-17 | flow A→B (one hop: nft does no routing): 60.2 / 60.2 / 57.7 / 58.3 | 0.96 | 0.24-0.30 / 0.79-0.83 | 15.2 s gap: the link was down for 15 s and nothing routes around it | PASS |
T214848Z-mynm7u |
manual, chain-6 | see above | A→B and E→F together ÷ alone: 0.44, 0.44 | 0.99 | 0.22-0.29 / 0.89-0.91 | none | PASS |
With the default flow (A→C, two hops), topo_backend: nft is refused before anything is touched, because the nft backend does no routing and a flow must join two neighbours. Give it a one-hop flow:
topo_backend: nft
topo_graph:
topology: {name: ring-4, generator: {type: ring, n: 4}}
mapping: auto
flows: [{from: A, to: B}]
events: [{at: 5, down: [A, B]}, {at: 20, up: [A, B]}]
The first chain-6 run (T214256Z-o9jym3) failed its contract on one pair: E→A, four hops, lost all 10 probe pings while every other pair got through, with several pings taking 190-350 ms as HWMP was still finding paths. Its flows were clean (0.41, 0.44) and the rerun passed. On long mesh chains, expect the first probes of the farthest pairs to race path discovery.
sb4 (RF matrix), the same day, eight nodes (evidence/wifi-topology-sb4-20261108/): parity PASS with the topology imposed by the matrix (flows 3.6 / 5.7 / 5.7 Mb/s) and by filters (6.2 / 8.2 / 7.6 Mb/s); a 2×4 grid on all eight nodes built from attenuators alone, 0 non-neighbours heard; the nft backend on both.
What the 2026-11-07 hand test already showed (evidence/wifi-topology-grid-20261107/):
| Test | Result |
|---|---|
hear (mesh, 4 nodes) |
every node heard all three others at −18 to −51 dBm: the physical graph is complete |
apply, mesh, chain A-B-C-D |
in force on all four nodes exactly as compiled |
probe, mesh |
every pair reachable, 0 % loss; every route's next hop is a chain neighbour (D reaches A in 3 hops via C) |
apply + probe, nft (IBSS, no routing) |
exactly the chain: A-B, B-C and C-D at 0 % loss, every other pair at 100 % loss |
| traffic, mesh chain | hops 29.9 / 66.5 / 69.2 Mb/s alone; A to D 13.0 Mb/s = 75 % of the 17.3 Mb/s bound; busy 0.13-0.19 idle, 0.74-0.76 under traffic |
Change (--params my.yml) |
Question |
|---|---|
topo_graph: {topology: {generator: {type: chain, n: 5}}, flows: [{from: A, to: E}]} |
How close does a 4-hop flow come to 1/Σ(1/r)? |
generator: {type: star, n: 5}, flows: {to-sink: A} |
Four senders, one receiver in the middle: who gets through? |
topo_backend: nft, directed: true and one one-way link |
What can cross a one-way link, and what cannot (TCP needs the return path)? |
topo_flow_udp_mbps: 5 |
At a modest offered load, does the chain still lose packets? |
| The default ring, events on a chain instead | On the ring HWMP finds the long way round; on a chain the gap lasts until the link returns. How long is each gap? |
On sb4: topo_rfmatrix: true, topo_file: /usr/share/cosmos-experiments/wifi-topology/reuse6.topo.yml (shipped), then topo_impose: matrix and topo_impose: filter |
How much rate does each flow keep when the other runs, with and without real separation? |
Draw your own in the editor, load this run's physical.json |
Which of your links can the air not give you? |
The run ends with the contract table and PASS or FAIL. It passes when:
BLOCKED, and none was unseen);HWMP hop counts longer than the shortest path are reported, not failed. Events are reported, not judged. Throughput is never a pass criterion: on a shared channel it is a measurement.
cosmos-tutorial run wifi-topology --mode parity runs all three modes and compares them: the same topology, the same filters, the same flows, and all three passing. With mapping: auto, each mode may pick a different valid placement. That is reported and does not fail parity.
cosmos-tutorial run wifi-topology --mode teardown
topo_min_signal_dbm. The message lists the physical links. Lower the threshold, add nodes, or load physical.json into the editor and draw within the grey links.nft backend, or other nodes. wifi-topology-node list on the node shows which roles each radio can take.topo_hear_secs.mesh backend for multi-hop flows.rt2800usb reports zeros and Intel cards report nothing. Read the fraction from another member.iw and nftables documentation: iw help, man nft (the netdev family and the ingress hook).Package cosmos-experiments-wifi 0.1.0-9 - on every console it is released to (cosmos-tutorial list shows the installed version). The code is installed on the console in /usr/share/cosmos-experiments/wifi-topology/; the programs in its node/ subdirectory are copied to the nodes by every run, so the node image does not need to carry them. To change anything, cosmos-tutorial copy wifi-topology puts an editable copy in the current directory, and cosmos-tutorial run wifi-topology then runs that copy instead of the installed one (cosmos-tutorial which wifi-topology shows which will run). Repository (GitLab account needed, not needed to run or change it): packages/cosmos-experiments-wifi/usr/share/cosmos-experiments/wifi-topology.