README.md

Important

📢 Meshtastic Network Management Client needs a new platform owner / maintainer 📢

More details are available in Issue #473.

Meshtastic Network Management Client

A desktop client for analyzing and managing large-scale, low-bandwidth mesh networks

👋 Introduction

This application is a desktop client for the Meshtastic Project, designed to allow users to reliably manage large, decentralized mesh networks. Currently the Meshtastic client ecosystem has strong support for managing single nodes, but minimal support for network-level management and analysis. The goal of this project is to give users confidence in their Meshtastic networks as a reliable communications infrastructure through novel algorithmic analysis and connection-level insights.

This application is built using the Tauri Framework, a modern, secure successor to the Electron Framework. This allows us to natively support Linux, macOS, and Windows within the same codebase without the performance or memory overhead of a Chromium browser. Our core application infrastructure is written in Rust due to its performance and safety, and our UI and client functionality is written in React TypeScript using Vite. This project is in early stages of development, and as such is not yet suitable for production use.

🙏 Call for Contributions

At the time of writing, this project is currently maintained by a single developer. As such, the project is looking for developers willing to contribute towards or take lead on the following major initiatives:

• Full offline map support, including region-based downloading and loading of custom maps (will require Meshtastic mirror of the OSM tile DB)
• Persisting application state across client sessions (completed)
• Rust backend testing (unit, integration, e2e, smoke)
• TS frontend testing (unit, integration, e2e, smoke)
• Adding support for remote node configuration
• Integrating UI components into the Storybook framework
• Adding support for i18n translations within the UI layer (completed)
• General reorganization of application file structure to make the project intuitive

🚀 Functionality

This project is still in early stages of development, but here's a rough roadmap of functionality we're working on. We're placing a high priority on getting our core infrastructure right, since this is the core of any robust and effective UI layer.

• 🔗 Core dataflow infrastructure
  • Serial data send/receive
  • Rust protobuf integration (.proto -> .rs)
  • Packet encode/decode
  • Device state management
• 🎨 Core UI infrastructure
  • Tauri command management
  • Tauri event management
  • Redux saga dataflow
• 🛰️ Network topology collection
  • RFC for novel packet (completed)
  • MVP protobuf changes (completed)
  • MVP firmware changes (completed)
  • Community protobuf review (completed)
  • Community firmware review (completed)
• 🤓 Algorithmic analysis
  • Infrastructure
    • Network packet collation
    • Network graph construction
    • Algorithm runners
  • UI
    • MVP algorithm runner pane
    • On-map algorithm UI
    • Automatic algorithm rerunning
• 📻 Node management
  • Node peer table
  • Network configuration (multi-device)
  • Remote node configuration
• 📌 Waypoint management
  • Managed waypoint table
  • In-channel waypoint sending
  • On-map waypoint tooltip
• 🌐 Web client parity (UI)
  • Map node view
  • Text messaging
  • Channel import/export via QR code
  • Configuration
    • Device configuration
    • Module configuration
    • Channel configuration
• 🗻 Offline map view
  • Offline map storage
  • Region-based downloading
• 📄 Network data export

📻 Hardware Requirements

This project is built on the Meshtastic hardware ecosystem, and as such this client requires that you have access to a Meshtastic radio. This may change in the future, but for the time being a physical radio is required to use this client.

I've written up some personal hardware recommendations here.

💻 Development

Prerequisites

This project is built in Rust and React TypeScript, and managed using the PNPM package manager. As such, this project requires the following programs to be installed on your development machine:

• Rust Language
• Node.js
• PNPM Package Manager

Installation

To run this project locally, follow the steps below:

1. Ensure you have Rust, Node.js, and PNPM installed (see Prerequisites)
2. Ensure that you have all Tauri dependencies installed (depends on your OS)
3. Clone this repositiory to a local directory. This can be done by running git clone https://github.com/meshtastic/network-management-client.git
4. Recursively clone our Git submodules by running git submodule update --init
5. Install all required NPM packages with pnpm i
6. Once you have completed these steps, verify your installation with the pnpm run rust:dev command. The application should compile successfully, and you should see the application open successfully. If this process fails for you, please let us know!

Recommended IDE Setup

While this project can be developed within any text editor, we recommend the Visual Studio Code editor. If using VSCode, we strongly recommend that you install the following Visual Studio Code extensions. These extensions both enforce code style and enable language and framework support for our tech stack.

• Prettier - Formatter for our UI code
• ESLint - Linter for our UI code
• rust-analyzer - Rust LSP with code linting, formatting, and quality suggestions

Some optional extensions that aren't required but we find very helpful:

• Tauri - Adds Tauri command snippets and configuration JSON validation
• GitLens - A helpful plugin for working with Git histories

Development Commands

To standardize our development flow, we utilize PNPM commands, defined in package.json. These commands can be run with the pnpm run NAME ...ARGS syntax. Our commands are broken out into two primary categories, rust:* commands and ui:* commands. The rust:* commands run the entire desktop application, where the ui:* commands only run the UI layer.

Note: We strongly recommend against using the ui:dev and ui:build commands manually. These commands are invoked internally by the rust:dev and rust:build commands, respectively. You will not be able to connect to a serial devce when running the ui:dev command, as this logic is not handled in the UI layer.

We are currently working to add support for the Storybook framework, which will allow contributors to develop UI components without running the entire desktop application.

• pnpm run rust:dev - Starts the desktop application in development mode, allowing for hot reloading of UI and Rust code

• pnpm run rust:build - Builds the desktop application in production mode for your system architecture. Currently we only use this command for testing our application's CLI argument parser.

• pnpm run rust:test - Runs backend tests on the Rust codebase directory (/src-tauri). This command also generates TypeScript client bindings in the /src-tauri/bindings directory. Add -- --show-output to show Rust println! macro calls within test suites.

• pnpm run ui:dev - Starts the UI development server, allowing for UI development in a browser environment. Note that any code that interfaces with the Rust backend will not function within this browser environment, meaning you will be unable to connect to serial devices in this context

• pnpm run ui:build: - Runs a production build on the UI code into the dist directory

• pnpm run ui:lint - Uses ESLint to check for code style errors. Note that our CI pipeline requires that this command succeeds before any changes can be merged

• pnpm run ui:format - Formats the UI codebase using Prettier and ESLint. We strongly recommend you run this before creating a PR!

• pnpm run ui:test - Runs UI test suite using Jest. Currently the project does not have a UI testing suite, but we're very open to contributions!

• pnpm run ui:preview - Runs the built UI from the dist directory. This command must be run after ui:build (deprecated)

Note: On Linux, your user may not have permission to access a given serial port. If this happens, you will likely need to add your user to the group that controls the serial port you want to access. You can find the group that controls a serial port via the ls -ld PATH_TO_PORT_HERE command. You can add your user to this group via the usermod -a -G GROUP_NAME_HERE $USER command.

❤️ Contributing

As we are still very early in development, we don't yet have a standardized framework for accepting contributions. This being said, we are very open to suggestions and/or code changes! If you're interested in contributing to this repository, we would ask that you first check our issue board to ensure your work isn't duplicating the work of others. Then, please make an issue on our board so we know what you're interested in working on. If you have any questions about the project, we would love to hear from you!