docs: add IBSS and BATMAN-adv mesh network guide

tr/projects/gemstone-mesh/en/projects/mesh-network/overview.mdx

@@ -0,0 +1,74 @@
+---
+title: "Mesh Networking with IBSS and BATMAN-adv: What Is It?"
+description: "How the IBSS and BATMAN-adv mesh architecture works on T3 Gemstone O1, including the tested environment and addressing plan"
+---
+
+
+This project builds a two-hop wireless mesh network using three **T3 Gemstone O1** boards without requiring a central access point. The `wlan0` interfaces form a shared **IBSS (ad-hoc)** wireless cell, while **BATMAN-adv** provides Layer 2 multi-hop communication over those direct wireless adjacencies.
+
+At the end of the setup, Node 1 and Node 3 cannot reach each other directly over the IBSS subnet, but BATMAN-adv carries traffic through Node 2:
+
+```text
+Node 1  <------ IBSS ------>  Node 2  <------ IBSS ------>  Node 3
+  |                             |                             |
+192.168.100.1              192.168.100.2              192.168.100.3
+
+Node 1  <----------- no direct IBSS reachability ----------->  Node 3
+
+BATMAN-adv / bat0:
+192.168.200.1  <========= through Node 2 =========>  192.168.200.3
+```
+
+The configuration described on this page was verified bidirectionally in a real three-node test.
+
+## What are IBSS and BATMAN-adv?
+
+### IBSS
+
+**IBSS (Independent Basic Service Set)** is an IEEE 802.11 ad-hoc operating mode in which wireless stations join the same cell without an access point. In this project, the `wlan0` interface on every Gemstone board joins the same IBSS cell using an identical SSID, frequency, and fixed BSSID.
+
+IBSS provides the direct wireless adjacency layer in this setup. It is not used by itself as the multi-hop forwarding mechanism.
+
+### BATMAN-adv
+
+**BATMAN-adv** is a Layer 2 mesh component implemented in the Linux kernel. It uses the direct IBSS adjacencies and exposes a virtual mesh interface named `bat0` for upper-layer communication.
+
+The routing algorithm used in this project is **BATMAN_V**. Two `batctl` commands are especially useful when verifying the mesh:
+
+```bash
+sudo batctl n
+sudo batctl o
+```
+
+- `batctl n` shows direct BATMAN-adv neighbors.
+- `batctl o` shows originators and the selected next hop.
+
+Used together, IBSS provides the direct radio links while BATMAN-adv provides multi-hop forwarding over those links.
+
+## Tested environment
+
+| Component | Value |
+| --- | --- |
+| Hardware | 3 × T3 Gemstone O1 |
+| Operating system | Ubuntu 24.04 LTS (Noble Numbat) |
+| Architecture | aarch64 |
+| Kernel | Linux 6.12.24-ti, PREEMPT_RT |
+| Wireless interface | `wlan0` |
+| IBSS SSID | `gemstone-mesh` |
+| IBSS frequency | 2412 MHz, channel 1 |
+| Fixed IBSS BSSID | `02:12:34:56:78:9a` |
+| BATMAN-adv algorithm | `BATMAN_V` |
+| batctl | `debian-2024.0-1` |
+| BATMAN-adv | Included in the tested image; module version `2024.2` was shown during the successful test |
+
+## Addressing plan
+
+Two separate IP subnets are used so that direct IBSS reachability can be distinguished from mesh reachability.
+
+| Node | `wlan0` / IBSS IP | `bat0` / Mesh IP | `bat0` MAC |
+| --- | --- | --- | --- |
+| Node 1 | `192.168.100.1/24` | `192.168.200.1/24` | `02:ba:70:00:00:01` |
+| Node 2 | `192.168.100.2/24` | `192.168.200.2/24` | `02:ba:70:00:00:02` |
+| Node 3 | `192.168.100.3/24` | `192.168.200.3/24` | `02:ba:70:00:00:03` |
+
+The `192.168.100.0/24` subnet is used to check direct IBSS reachability, while `192.168.200.0/24` is assigned to `bat0` for mesh communication.

tr/projects/gemstone-mesh/en/projects/mesh-network/setup.mdx

@@ -0,0 +1,173 @@
+---
+title: "Mesh Networking with IBSS and BATMAN-adv: How to Set It Up"
+description: "Setting up an IBSS and BATMAN-adv mesh network on T3 Gemstone O1 using the required userspace tools and helper scripts"
+---
+
+This page explains how to start an IBSS-based wireless network and the BATMAN-adv mesh layer running on top of it across three T3 Gemstone O1 boards.
+
+The contents of the `.sh` files used for the setup are not published in this documentation. The required files must already be transferred to each Gemstone board and made executable.
+
+## Install the required tools
+
+The tested Gemstone image already includes the `batman-adv` kernel module. Install the `iw` and `batctl` userspace packages:
+
+```bash
+sudo apt install iw
+sudo apt install batctl
+```
+
+- `iw` is used to inspect the wireless interface and verify the IBSS connection.
+- `batctl` is used to inspect the BATMAN-adv mesh interface, direct neighbors, and originator table.
+
+## Transfer the setup files to each board
+
+Each T3 Gemstone O1 board must contain the following four files:
+
+```text
+ibss-up.sh
+ibss-down.sh
+bat-up.sh
+bat-down.sh
+```
+
+Transfer the files from your computer to the Gemstone board and place them in the same working directory. Then make them executable:
+
+```bash
+chmod +x ibss-up.sh ibss-down.sh bat-up.sh bat-down.sh
+```
+
+The same files are used on all three boards. The boards are distinguished by the node number passed when the scripts are executed.
+
+## 1. Start the IBSS network
+
+Run `ibss-up.sh` on each board first. Each board must use a different node number.
+
+### Node 1
+
+```bash
+./ibss-up.sh 1
+```
+
+### Node 2
+
+```bash
+./ibss-up.sh 2
+```
+
+### Node 3
+
+```bash
+./ibss-up.sh 3
+```
+
+After this step, the IBSS-side addresses are:
+
+| Node | IBSS address |
+| --- | --- |
+| Node 1 | `192.168.100.1/24` |
+| Node 2 | `192.168.100.2/24` |
+| Node 3 | `192.168.100.3/24` |
+
+Verify the IBSS state on each board with:
+
+```bash
+iw dev wlan0 info
+iw dev wlan0 link
+iw dev wlan0 station dump
+```
+
+In a successful setup, `wlan0` should operate in IBSS mode and the board should be joined to the shared `gemstone-mesh` cell.
+
+## 2. Start the BATMAN-adv mesh layer
+
+After IBSS is active on all three boards, run `bat-up.sh`. Use the same node number that was assigned during the IBSS step.
+
+### Node 1
+
+```bash
+./bat-up.sh 1
+```
+
+### Node 2
+
+```bash
+./bat-up.sh 2
+```
+
+### Node 3
+
+```bash
+./bat-up.sh 3
+```
+
+After this step, the `bat0` mesh interfaces use the following addresses:
+
+| Node | Mesh address |
+| --- | --- |
+| Node 1 | `192.168.200.1/24` |
+| Node 2 | `192.168.200.2/24` |
+| Node 3 | `192.168.200.3/24` |
+
+Verify that the mesh interface is present:
+
+```bash
+ip -br addr show bat0
+```
+
+Then inspect BATMAN-adv neighbor and forwarding information:
+
+```bash
+sudo batctl n
+sudo batctl o
+```
+
+`batctl n` shows direct BATMAN-adv neighbors, while `batctl o` shows known mesh originators and the selected next hop.
+
+## 3. Check mesh connectivity
+
+After the setup is complete, test connectivity using the `bat0` addresses.
+
+For example, from Node 1 to Node 3:
+
+```bash
+ping -c 5 192.168.200.3
+```
+
+From Node 3 to Node 1:
+
+```bash
+ping -c 5 192.168.200.1
+```
+
+Neighbor and forwarding information may take a short time to converge immediately after BATMAN-adv is started. If the first attempt does not receive a reply, wait a few seconds and repeat `batctl n`, `batctl o`, and the ping test.
+
+See the **What We Did** page for the actual three-node terminal results and the multi-hop verification chain.
+
+## Shut down the network
+
+When stopping the setup, remove the BATMAN-adv mesh layer first and then stop the IBSS configuration.
+
+Run the following on each board in this order:
+
+```bash
+./bat-down.sh
+./ibss-down.sh
+```
+
+`bat-down.sh` stops the mesh layer. `ibss-down.sh` then removes the IBSS configuration and returns the wireless interface to normal Wi-Fi operation.
+
+## Setup sequence
+
+The complete process can be summarized as follows:
+
+```text
+1. Install iw and batctl
+2. Transfer ibss-up.sh, ibss-down.sh, bat-up.sh, and bat-down.sh to each board
+3. Make the files executable
+4. Run ./ibss-up.sh <node-number> on each node
+5. Verify IBSS with iw
+6. Run ./bat-up.sh <node-number> on each node
+7. Inspect bat0, batctl n, and batctl o
+8. Test connectivity between bat0 addresses
+9. Run ./bat-down.sh and ./ibss-down.sh when finished
+```

tr/projects/gemstone-mesh/en/projects/mesh-network/verification.mdx

@@ -0,0 +1,138 @@
+---
+title: "Mesh Networking with IBSS and BATMAN-adv: What We Did"
+description: "Verification results for direct IBSS reachability and bidirectional BATMAN-adv multi-hop communication across three T3 Gemstone O1 nodes"
+---
+
+## Verify the direct IBSS topology
+
+Before starting BATMAN-adv, use the `192.168.100.x` addresses to verify which nodes are directly reachable.
+
+On Node 1:
+
+```bash
+ping -c 5 192.168.100.2
+ping -c 5 192.168.100.3
+```
+
+In the verified test, Node 2 was reachable while Node 3 was not directly reachable. Condensed terminal result:
+
+```text
+$ ping -c 5 192.168.100.2
+...
+5 packets transmitted, 5 received, 0% packet loss
+
+$ ping -c 5 192.168.100.3
+...
+Destination Host Unreachable
+...
+5 packets transmitted, 0 received, 100% packet loss
+```
+
+The reverse direction was also checked from Node 3:
+
+```bash
+ping -c 5 192.168.100.2
+ping -c 5 192.168.100.1
+```
+
+Node 3 could reach Node 2 directly but could not reach Node 1 over the IBSS subnet. This verifies that the edge nodes were not communicating through a hidden direct IBSS path.
+
+## Verify the mesh topology
+
+### Direct BATMAN-adv neighbors
+
+Display the neighbor table on each node:
+
+```bash
+sudo batctl n
+```
+
+In the test, Node 1 had only Node 2 as a direct neighbor:
+
+```text
+Neighbor              last-seen
+b0:8c:b3:c3:83:ea     ...
+```
+
+Node 2 had two direct neighbors:
+
+```text
+Neighbor              last-seen
+b0:8c:b3:c3:77:f8     ...
+b0:8c:b3:c3:75:b6     ...
+```
+
+The tested `wlan0` MAC mapping was:
+
+| Node | `wlan0` MAC |
+| --- | --- |
+| Node 1 | `b0:8c:b3:c3:75:b6` |
+| Node 2 | `b0:8c:b3:c3:83:ea` |
+| Node 3 | `b0:8c:b3:c3:77:f8` |
+
+Node 3 also had only Node 2 as its direct neighbor. The neighbor tables therefore verify the following logical topology:
+
+```text
+Node 1  <------>  Node 2  <------>  Node 3
+Node 1  <---------- X ----------->  Node 3
+```
+
+### Inspect originator and next-hop information
+
+Use the originator table to inspect the selected forwarding path:
+
+```bash
+sudo batctl o
+```
+
+In the test, Node 1 selected Node 2 as the next hop toward Node 3. Node 3 likewise selected Node 2 as the next hop toward Node 1.
+
+This is stronger evidence than a successful ping alone because it shows that the mesh layer actually selected the intermediate node as the forwarding path toward the remote endpoint.
+
+## Test end-to-end multi-hop communication
+
+From Node 1, ping the `bat0` address of Node 3:
+
+```bash
+ping -c 5 192.168.200.3
+```
+
+Condensed successful result:
+
+```text
+5 packets transmitted, 5 received, 0% packet loss
+```
+
+In the reverse direction, from Node 3 to Node 1:
+
+```bash
+ping -c 5 192.168.200.1
+```
+
+Condensed successful result:
+
+```text
+4 packets transmitted, 4 received, 0% packet loss
+```
+
+When these results are evaluated together with the failed direct `192.168.100.x` tests and the `batctl n` / `batctl o` tables, they verify that traffic between the edge nodes is forwarded through Node 2.
+
+> **Convergence note:** During the test, some initial `bat0` ping attempts failed before neighbor/originator information had stabilized. If an endpoint is not immediately reachable, inspect `sudo batctl n` and `sudo batctl o`, allow the mesh state to settle, and repeat the test.
+
+## Result
+
+A two-hop mesh path was successfully verified across three T3 Gemstone O1 boards using IBSS and BATMAN-adv. IBSS provided the direct wireless adjacencies, while BATMAN-adv provided Layer 2 multi-hop forwarding over those adjacencies.
+
+The verification chain was:
+
+1. Node 1 and Node 3 could not directly reach each other using their `192.168.100.x` IBSS addresses.
+2. Node 2 saw both edge nodes as direct BATMAN-adv neighbors.
+3. The originator tables on the edge nodes selected Node 2 as the next hop toward the remote edge node.
+4. Bidirectional communication between `192.168.200.1` and `192.168.200.3` succeeded.
+
+The following forwarding paths were therefore functionally verified:
+
+```text
+Node 1  -->  Node 2  -->  Node 3
+Node 3  -->  Node 2  -->  Node 1
+```