Move Meshtasticator to Official Software and Add Documentation Pages (#1506)

* Move meshtasticator to official software, add docs pages.

* formatting changes and add link back

* feedback

* feedback

* redirect

docs/community/software/index.mdx

@@ -9,11 +9,9 @@ The Meshtastic ecosystem is highly extensible, and a number of community project
 
 Current community projects:
 
-- [Meshtasticator (Simulator)](/docs/community/software/community-meshtasticator) - Meshtasticator is a discrete-event and interactive simulator that mimics the radio section of the device software.
 - [Meshtastic Web API](/docs/community/software/meshtastic-web-api) - Meshtastic Web API provides a RESTful interface to interact with a Meshtastic node via a serial connection.
 - [Mesh-metrics](/docs/community/software/community-mesh-metrics) - Meshtastic repeater metrics scraper using meshtastic-cli to be ingested by node_exporter for use in Prometheus or Victoria Metrics Time series DB with a Grafana dashboard and sample alerting rules.
-- [Node-RED Messages Node](/docs/community/software/community-node-red-messages) - Node-RED node to send and receive packets / text messages from a device connected via HTTP. 
+- [Node-RED Messages Node](/docs/community/software/community-node-red-messages) - Node-RED node to send and receive packets / text messages from a device connected via HTTP.
 - [MQTT Connect for Meshtastic](https://github.com/pdxlocations/MQTT-Connect-for-Meshtastic) - A nodeless python client for communicating with Meshtastic devices over MQTT.
 
 Support for these projects should be sought from their respective authors.
-

docs/community/software/meshtasticator.mdx

@@ -1,16 +0,0 @@
----
-id: community-meshtasticator
-title: Meshtasticator
-sidebar_label: Meshtasticator (Simulator)
-sidebar_position: 1
----
-
-:::note
-
-This is a community project maintained by @GUVWAF.
-Development can be followed on [GitHub](https://github.com/GUVWAF/Meshtasticator).
-Support should be sought from the respective authors.
-
-:::
-
-Meshtasticator is a discrete-event and interactive simulator that mimics the radio section of the device software and can be used to assess the performance of your scenario, or the scalability of the protocol. Meshtasticator was created and is maintained by GUVWAF and more information on its use and setup can be found on the [Meshtasticator Github page](https://github.com/GUVWAF/Meshtasticator)

docs/software/meshtasticator/discrete-event-sim.mdx

@@ -0,0 +1,90 @@
+---
+id: discrete-event-sim
+title: Discrete Event Simulator Usage Guide
+sidebar_label: Discrete Event Simulator
+sidebar_position: 1
+description: A usage guide for simulating radio communications with configurable parameters and node behaviors.
+---
+
+The discrete-event simulator mimics the radio section of the device software. It is currently based on Meshtastic 2.1.
+
+## Usage
+
+Please `git clone` or download this repository, navigate to the Meshtasticator folder (optionally create a virtual environment), and install the necessary requirements using:
+`pip install -r requirements.txt`
+
+To start one simulation with the default configurations, run:
+`python3 loraMesh.py [nr_nodes]`
+
+If no argument is given, you first have to place the nodes on a plot. After you place a node, you can optionally set the node as a Router, change its hop limit, height (elevation), and antenna gain. These settings will automatically save when you place a new node or when you start the simulation.
+
+![Config Node](/img/software/meshtasticator/configNode.webp)
+
+If the number of nodes is given, it will randomly place nodes in the area. It ensures that each node can reach at least one other node. Furthermore, all nodes are placed at a configurable minimum distance (MINDIST) from each other.
+
+If you placed the nodes yourself, after a simulation the number of nodes, their coordinates, and configuration are automatically saved, and you can rerun the scenario with:
+`python3 loraMesh.py --from-file`
+
+If you want to change any of the configurations, adapt the file _out/nodeConfig.yaml_ before running it with the above command.
+
+For running multiple repetitions of simulations for a set of parameters, e.g., the number of nodes, run:
+`python3 batchSim.py`
+
+After the simulations are done, it plots relevant metrics obtained from the simulations. It saves these metrics in _/out/report/_ for analysis later on. See _plotExample.py_ for an example Python script to plot the results.
+
+To simulate different parameters, you will have to change the _batchSim.py_ script yourself.
+
+## Custom configurations
+
+Here we list some of the configurations, which you can change to model your scenario in _/lib/config.py_. These apply to all nodes, except those that you configure per node when using the plot.
+
+### Modem
+
+The LoRa modem ([see Meshtastic radio settings](/docs/overview/radio-settings#predefined-channels)) that is used, as defined below:
+
+| Modem | Name           | Bandwidth (kHz) | Coding rate | Spreading Factor | Data rate (kbps) |
+| ----- | -------------- | --------------- | ----------- | ---------------- | ---------------- |
+| 0     | Short Fast     | 250             | 4/8         | 7                | 6.8              |
+| 1     | Short Slow     | 250             | 4/8         | 8                | 3.9              |
+| 2     | Mid Fast       | 250             | 4/8         | 9                | 2.2              |
+| 3     | Mid Slow       | 250             | 4/8         | 10               | 1.2              |
+| 4     | Long Fast      | 250             | 4/8         | 11               | 0.67             |
+| 5     | Long Moderate  | 125             | 4/8         | 11               | 0.335            |
+| 6     | Long Slow      | 125             | 4/8         | 12               | 0.18             |
+| 7     | Very Long Slow | 62.5            | 4/8         | 12               | 0.09             |
+
+### Period
+
+Mean period (in ms) with which the nodes generate a new message following an exponential distribution. For example, if you set it to 300s, each node will generate a message on average once every five minutes.
+
+### Packet length
+
+Payload size of each generated message in bytes. For a position packet, it will be around 40 bytes.
+
+### Model
+
+This feature refers to the path loss model, i.e., what the simulator uses to calculate how well a signal will propagate. Note that this is only a rough estimation of the physical environment and will not be 100% accurate, as it depends on a lot of factors. The implemented path loss models are:
+
+- `0` set the log-distance model
+- `1` set the Okumura-Hata for small and medium-size cities model
+- `2` set the Okumura-Hata for metropolitan areas
+- `3` set the Okumura-Hata for suburban environments
+- `4` set the Okumura-Hata for rural areas
+- `5` set the 3GPP for suburban macro-cell
+- `6` set the 3GPP for metropolitan macro-cell
+
+### Broadcasts or direct messages (DMs)
+
+By default, _DMs_ is set to False, meaning it will send broadcast messages only. If you set it to True, each node will only send DMs to a random other node in the network.
+
+## Explanation
+
+A discrete-event simulator jumps from event to event over time, where an event is a change in the state of the system. It is therefore well-suited for simulating communication networks.
+
+For every node in the simulation, an instance is created that mimics the [Meshtastic logic](/docs/overview/mesh-algo). Each node runs three processes in parallel: _generateMessage_, _transmit_, and _receive_. The first creates an event by constructing a new message with a unique sequence number at a random time, taken from an exponential distribution. For now, each generated message is of the same payload size. The second and third processes model the actual transmitting and receiving behavior, respectively.
+
+The model of the LoRa physical (PHY) layer is in _/lib/phy.py_. Depending on the modem used, it calculates what the airtime of a packet is. The PHY layer uses a configurable path loss model to estimate whether nodes at a specific distance can sense each other's packets. Furthermore, it determines whether two packets collide, which depends on the frequency, spreading factor, received time, and received power of the two packets.
+
+The routing behavior is implemented in each of the processes of the node. Inside _generateMessage_, reliable retransmissions are handled if no implicit acknowledgment is received. A MeshPacket (defined in _/lib/packet.py_) is created to transfer the message. Note that there may be multiple packets created containing the same message, due to retransmissions and rebroadcasting. In _receive_, it is decided what to do on reception of a packet. A packet is flooded if its hop limit is not zero and no rebroadcast of this packet was heard before. In _transmit_, delays of the Medium Access Control (MAC) layer are called from _/lib/mac.py_. The MAC uses a listen-before-talk mechanism, including introducing (random or SNR-based) delays before transmitting a packet. When a packet is ready to be transferred over the air, it is first checked whether in the meantime still no acknowledgment was received; otherwise, the transmission is canceled.
+
+The actual communication between processes of different nodes is handled by a BroadcastPipe of [Simpy](https://simpy.readthedocs.io/en/latest/examples/process_communication.html). This ensures that a packet transmitted by one node creates events (one at the start of a packet and one at the end) at the receiving nodes.

docs/software/meshtasticator/index.mdx

@@ -0,0 +1,58 @@
+---
+id: meshtasticator
+title: Meshtasticator
+sidebar_label: Meshtasticator (Simulator)
+sidebar_position: 5
+description: Overview of Meshtasticator simulator for evaluating performance and scalability of the Meshtastic protocol using discrete-event and interactive simulations.
+---
+
+import ReactPlayer from "react-player";
+
+**Meshtasticator** is a discrete-event and interactive simulator that replicates the radio section of the device software. It helps evaluate the performance of various scenarios and the scalability of the protocol. The **Meshtasticator** simulator can be found on [Github](https://github.com/meshtastic/meshtasticator).
+
+## Discrete-Event Simulator
+
+The discrete-event simulator models the radio section of the device software to analyze its behavior. It can assess the performance of specific scenarios and the scalability of the protocol.
+
+### Getting Started
+
+For step-by-step instructions on how to use the discrete-event simulator, see the [discrete-event simulator usage guide](./discrete-event-sim).
+
+### Simulation Insights
+
+After each simulation, the tool plots node placements and schedules the timing for overlapping messages sent during the simulation.
+
+![Placement Schedule](/img/software/meshtasticator/placement_schedule.webp)
+
+The simulator allows network analysis using different parameter sets. For example, below are the results of 100 simulations, each lasting 200 seconds, with varying hop limits and node counts. As expected, the average number of nodes reached per message increases with a higher hop limit.
+
+![Reachability Hops](/img/software/meshtasticator/reachability_hops.webp)
+
+However, this improvement comes with a trade-off in **usefulness**—the proportion of received packets containing new (non-duplicate) messages decreases as rebroadcasting increases.
+
+![Usefulness Hops](/img/software/meshtasticator/usefulness_hops.webp)
+
+## Interactive Simulator
+
+The interactive simulator leverages the [Linux-native Meshtastic application](https://meshtastic.org/docs/software/linux-native), i.e., the real device software, while emulating some hardware components, including the LoRa chip. It can also run on Windows or macOS using Docker.
+
+### Setup Instructions
+
+To get started with the interactive simulator, see the [interactive simulator usage guide](./interactive-sim).
+
+### Debugging and Visualization
+
+This simulator facilitates debugging multiple communicating nodes without needing physical devices.
+
+<div style={{ maxWidth: "800px", margin: "auto" }}>
+  <ReactPlayer
+    url="/img/software/meshtasticator/interactive-sim-video.mp4"
+    controls
+    width="100%"
+    height="400px"
+  />
+</div>
+
+Additionally, because the simulator has an 'oracle view' of the network, it provides insights into the routes taken by messages.
+
+![Route Plot](/img/software/meshtasticator/route_plot.webp)

docs/software/meshtasticator/interactive-sim.mdx

@@ -0,0 +1,129 @@
+---
+id: interactive-sim
+title: Interactive Simulator Usage Guide
+sidebar_label: Interactive Event Simulator
+sidebar_position: 2
+description: A usage guide for simulating multiple Meshtastic instances with TCP-based communication and configurable pathloss models.
+---
+
+The Python script _`interactiveSim.py`_ uses the [Linux native application of Meshtastic](https://meshtastic.org/docs/software/linux-native) to simulate multiple instances of the device software. These instances communicate using TCP via the script, simulating the LoRa chip. The simulator forwards messages from the sender to all nodes within range, based on their simulated positions and the selected pathloss model (see [Pathloss Model](#pathloss-model)). **Note:** Packet collisions are not yet simulated.
+
+## Usage
+
+1. Clone or download the repository and navigate to the Meshtasticator folder.
+2. (Optional) Create a virtual environment.
+3. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+The simulator runs the Linux native application of Meshtastic firmware. You can use either [PlatformIO](https://meshtastic.org/docs/development/firmware/build) or [Docker](https://meshtastic.org/docs/software/linux-native#usage-with-docker) to run the firmware:
+
+### Using PlatformIO
+
+Select 'native' and click 'build.' Locate the generated binary file, likely in _`firmware/.pio/build/native/`_.
+
+Copy the `program` file to the directory where you'll run the Python script, or provide the path as an argument with `-p`:
+
+```bash
+python3 interactiveSim.py 3 -p /home/User/Meshtastic-device/.pio/build/native/program
+```
+
+### Using Docker
+
+The simulator pulls a Docker image that builds the latest Meshtastic firmware.
+
+Ensure the Docker SDK for Python is installed:
+
+```bash
+pip3 install docker
+```
+
+Make sure the Docker daemon or Desktop app is running. Use the `-d` argument to launch the simulator:
+
+```bash
+python3 interactiveSim.py 3 -d
+```
+
+## Running the Simulator
+
+To run the interactive simulator:
+
+```bash
+python3 interactiveSim.py [nrNodes] [-p <full-path-to-program>]
+```
+
+- **`nrNodes`** (optional): Number of instances to launch. Each instance opens a terminal and a TCP port (starting at 4403).
+- If you provide the number of nodes, they will be randomly placed; otherwise, you can manually place nodes on a plot.
+- After placing nodes, you can configure their [role](https://meshtastic.org/docs/settings/config/device#role), `hopLimit`, height (elevation), and antenna gain. Configurations are saved automatically.
+
+![Config Note](/img/software/meshtasticator/configNode.webp)
+
+## Commands During Simulation
+
+Once the simulation starts, you can issue commands (or use a predefined [script](#usage-with-script)) to send messages between nodes. Use `plot` to visualize message routes and airtime statistics:
+
+- Enter a message ID to see its route.
+- Hover over arcs for information and click to remove the overlay.
+- Two graphs display channel utilization (one-minute window) and airtime usage (hourly window) for each node.
+
+![Route Plot 2](/img/software/meshtasticator/route_plot-2.webp)
+
+## List of Commands
+
+- **`broadcast <fromNode> <txt>`**: Send a broadcast from node _fromNode_ with text _txt_.
+- **`DM <fromNode> <toNode> <txt>`**: Send a Direct Message from node _fromNode_ to node _toNode_ with text _txt_.
+- **`traceroute <fromNode> <toNode>`**: Send a traceroute request from node _fromNode_ to node _toNode_.
+- **`reqPos <fromNode> <toNode>`**: Send a position request from node _fromNode_ to node _toNode_.
+- **`ping <fromNode> <toNode>`**: Send ping from node _fromNode_ to node _toNode_.
+- **`remove <id>`**: Remove node _id_ from the current simulation.
+- **`nodes <id0> [id1, etc.]`**: Show the node list as seen by node(s) _id0_, _id1_, etc.
+- **`plot`**: Plot the routes of messages sent and airtime statistics.
+- **`exit`**: Exit the simulator without plotting routes.
+
+## Usage with Script
+
+Modify the `try` clause in _`interactiveSim.py`_ to predefine messages. Run the simulator with the `-s` argument:
+
+```bash
+python3 interactiveSim.py 3 -s
+```
+
+- After nodes exchange NodeInfo, they will begin sending messages.
+- Close the simulation manually with `Ctrl+C` or wait for the timeout.
+
+## Tips and Tricks
+
+1. **Speeding Up NodeInfo Exchange:**  
+   Disable certain modules by removing `new NodeInfoModule()` from _`src/modules/Modules.cpp`_ in the firmware.
+
+2. **Saving and Reloading Configurations:**  
+   After a simulation, node configurations are saved. You can rerun the same scenario with:
+
+   ```bash
+   python3 interactiveSim.py --from-file
+   ```
+
+   Modify the _`out/nodeConfig.yaml`_ file to adjust configurations before reloading.
+
+3. **Using the Python CLI:**  
+   You can call functions from the Node class via `sim.getNodeById(<id>)` in _`interactiveSim.py`_. Example:
+
+   ```python
+   node.setURL('<YOUR_URL>')
+   ```
+
+## Pathloss Model
+
+The simulator estimates signal propagation using a pathloss model. This is an approximation of the physical environment, so it may not be 100% accurate. The available models are:
+
+- **0**: Log-distance model
+- **1**: Okumura-Hata model (small/medium cities)
+- **2**: Okumura-Hata model (metropolitan areas)
+- **3**: Okumura-Hata model (suburban environments)
+- **4**: Okumura-Hata model (rural areas)
+- **5**: 3GPP model (suburban macro-cell)
+- **6**: 3GPP model (metropolitan macro-cell)
+
+You can modify the pathloss model and area configuration in _`lib/config.py`_. LoRa settings remain at their Meshtastic defaults unless customized during node placement.

package.json

@@ -33,6 +33,7 @@
     "react-dom": "^18.2.0",
     "react-icons": "^5.0.1",
     "react-markdown": "^9.0.1",
+    "react-player": "^2.16.0",
     "remark-deflist": "^1.0.0",
     "swr": "^2.2.5",
     "tailwindcss": "^3.4.1"

vercel.json

@@ -120,6 +120,10 @@
     {
       "source": "/docs/hardware/devices/seeed-wm1110/:path*/",
       "destination": "/docs/hardware/devices/seeed-studio/wm1110/:path*"
+    },
+    {
+      "source": "/docs/community/software/community-meshtasticator/",
+      "destination": "/docs/software/meshtasticator/"
     }
   ]
 }