MeshCore

Trace-Path Node

Contents

1. Introduction

MeshCore Trace-Path Monitor is a Node.js web dashboard developed for monitoring and analyzing routing paths inside a MeshCore network.

The system is composed of three main components.

trace.sh

The trace.sh script periodically performs MeshCore path acquisitions.

• collects network data;
• updates the live data file data/trace.json;
• optionally uploads the JSON file to the central server.

backup.sh

The backup.sh script manages the monthly archive of the collected data.

• creates a compressed copy of the live data file;
• stores the archive inside the backup/ directory;
• initializes a new trace.json file for the next month;
• optionally uploads the archive file to the central server.

Web Dashboard

The web dashboard provides the main user interface and allows you to:

• display live data;
• browse historical monthly archives;
• analyze paths through charts and statistics;
• apply time filters to simplify data analysis.

2. System Requirements

The project has been developed and tested on Linux systems.

The following environments have currently been verified:

• Debian
• Ubuntu
• Raspberry Pi OS (64 bit)

In general, the software is compatible with any Unix/Linux distribution providing Python 3 and Node.js.

Windows environments are not currently supported, since several project components rely on Unix/Linux specific tools and features.

3. Software Requirements

Before installing the project, it is recommended to update the operating system and all installed packages.

The main update commands for the currently supported Linux distributions are shown below.

Debian / Ubuntu / Raspberry Pi OS

sudo apt update
sudo apt upgrade -y

AlmaLinux / Rocky Linux / RHEL

sudo dnf update -y

Once the operating system update has been completed, you can continue with the installation of the required software components described in the following chapters.

4. Python Environment Installation

This guide assumes that the installation is performed using a dedicated user named meshcore, belonging to the group authorized to use the sudo command.

Throughout this documentation, the following project root directory will be used:

/home/meshcore/trace-mon

All paths and examples shown in this guide refer to this standard configuration.

Verify Python Installation

Before proceeding, you can verify whether Python is already installed by running:

python3 --version

The reference environment used for the development and testing of this project is based on:

• Python 3.11.2

Newer versions within the same major release should also be fully compatible.

Installing Python

If Python is not available, or if you want to install all the components required by the project, use the following commands.

Debian / Ubuntu / Raspberry Pi OS

sudo apt install -y \
python3 \
python3-venv \
python3-pip \
python3-serial

AlmaLinux / Rocky Linux / RHEL

sudo dnf install -y \
python3 \
python3-venv \
python3-pip \
python3-pyserial

Verify Installation

Once installation has been completed, verify the main components by running:

python3 --version
pip3 --version

If both commands return a valid version number, the Python environment has been successfully installed.

Next Step

In the next chapter, a dedicated Python virtual environment (.venv) will be created inside the following directory:

/home/meshcore/trace-mon

This environment will host the meshcore-cli package used by the project scripts to acquire MeshCore trace paths.

5. meshcore-cli Installation

At this point you can proceed with the installation of meshcore-cli and the Python dependencies required by the node.

All operations described in this chapter must be performed using the meshcore user.

The user should:

• be authorized to use the sudo command;
• belong to the group authorized to access the serial devices /dev/ttyUSB*;
• have the requirements.txt file available, as it is provided together with the software package.

Move to the Project Directory

All subsequent operations should be executed from the project's root directory:

cd /home/meshcore/trace-mon

Create the Python Virtual Environment

The project uses a dedicated Python virtual environment (.venv) to keep the required software components isolated from the operating system.

python3 -m venv .venv

Update pip

Before installing the required dependencies, it is recommended to update the Python package manager:

.venv/bin/pip install --upgrade pip

Install Dependencies

The file requirements.txt contains the complete list of Python packages required by the project.

In addition to meshcore-cli, all modules required for communication with the LoRa device will also be installed automatically.

.venv/bin/pip install -r ./requirements.txt

Installation Complete

At the end of the procedure, all required Python components will be available inside the .venv directory.

The project scripts use the executables contained in the virtual environment directly through absolute paths, without requiring manual activation of the Python environment.

6. Node.js Installation

The MeshCore Trace-Path dashboard is developed using Node.js and requires the npm package manager.

Before proceeding with the installation, you can verify whether Node.js is already available on the system.

Verify Installation

node -v
npm -v

If both commands return a valid version number, you can proceed directly with the project initialization.

nvm Installation

If Node.js is not installed, it is recommended to use nvm (Node Version Manager), which simplifies future updates and version management.

Install the nvm package.

At the time this guide was written, the following command could be used:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash

This is provided only as a practical reference and may not reflect the latest version of the nvm project.

If you encounter installation problems or wish to verify the latest available version, please refer to the official project documentation.

Node.js Installation

After installing nvm, use the official command to install the latest LTS (Long Term Support) version of Node.js.

nvm install --lts

Once installation has completed, verify correct operation by running:

node -v
npm -v

Project Initialization

Move to the project root directory:

cd /home/meshcore/trace-mon

Initialize the Node.js project by running:

npm init -y

This command creates the package.json file used by Node.js to manage the project and its dependencies.

Install Express

The dashboard uses the express framework to provide the web service.

Install the required module:

npm install express

Installation Complete

At the end of the procedure, the Node.js project will be properly initialized and will contain all dependencies required by the web dashboard.

The next chapter describes the installation of the node software package and the final project structure.

7. Software Package Installation

After completing the installation of the required software components, you can proceed with the installation of the MeshCore Trace-Path Node software package.

The software package is available from the Software Download section of the project's website.

Download the desired version and extract its contents into the following working directory:

/home/meshcore/trace-mon

The package contains all files required for the node operation, including:

• the trace.sh and backup.sh scripts;
• the requirements.txt file;
• the web dashboard components;
• the meshcore-trace-mon.service service file.

Once the extraction has been completed, you can continue with the project directory structure described in the next chapter.

8. Directory Structure

After completing the software installation, the project's root directory will have a structure similar to the following.

trace-mon/
|
|-- .venv/
|-- backup/
|-- data/
|-- public/
|
|-- parser.js
|-- server.js
|-- package.json

The main project directories have the following purposes.

.venv

Contains the Python virtual environment and all dependencies required to run meshcore-cli.

backup

Contains the monthly compressed archives generated by the backup.sh script.

Each archive uses a filename similar to:

trace-2026-06.json.gz

data

Contains the live data file used by the dashboard:

trace.json

This file is updated periodically by the trace.sh script.

public

Contains all static files used by the web dashboard.

public/
|
|-- app.js
|-- index.html
|-- style.css

server.js

This is the Node.js web server that exposes the dashboard and makes the collected node data available.

parser.js

Implements the data processing functions and prepares the information used by the dashboard.

package.json

This is the Node.js project configuration file and contains information about the dependencies installed through npm.

During the installation, additional directories and files required for the proper operation of the Node.js environment may also be created automatically.

9. trace.sh Example

The software package includes the trace.sh script, used to perform periodic MeshCore path acquisitions and update the live data file data/trace.json.

A simple example of the script configuration is shown below.

#!/bin/bash

cd /home/meshcore/trace-mon/data
APP="/home/meshcore/trace-mon/.venv/bin/meshcore-cli -j -s /dev/ttyUSB1 -b 115200 trace"

DATE=`/usr/bin/date +"%Y%m%d_%H%M%S"`
T_PATH="0d"

echo $DATE $T_PATH >> trace.json
$APP $T_PATH >> trace.json

/usr/bin/sleep 10
exit 0

The APP variable contains the command used to execute meshcore-cli.

Depending on the local hardware configuration, it may be necessary to modify some parameters, such as the serial port or additional command options.

To perform multiple path acquisitions during the same execution, the following block can be duplicated by changing the value of the T_PATH variable.

DATE=`/usr/bin/date +"%Y%m%d_%H%M%S"`
T_PATH="0d"

echo $DATE $T_PATH >> trace.json
$APP $T_PATH >> trace.json

The complete script provided with the package can be further customized to meet the requirements of your MeshCore network.

10. backup.sh Example

The software package includes the backup.sh script, which performs the monthly archival of the live data file.

An example of the script is shown below.

#!/bin/bash

cd /home/meshcore/trace-mon

YEAR=$(/usr/bin/date +"%Y")
MONTH=$(/usr/bin/date +"%m")
MONTH=$((10#$MONTH - 1))

if [ $MONTH -eq 0 ]; then
    MONTH=12
    YEAR=$((YEAR - 1))
fi

MONTH=$(printf "%02d" "$MONTH")
FILEOUT="trace-$YEAR-$MONTH.json"
FILEOUTZIP="trace-$YEAR-$MONTH.json.gz"

cp data/trace.json backup/$FILEOUT
/usr/bin/sleep 10
/usr/bin/gzip backup/$FILEOUT
/usr/bin/sleep 10
rm -f data/trace.json
/usr/bin/sleep 10
touch data/trace.json
/usr/bin/sleep 10
exit 0

The script automatically performs the operations required to close the current acquisition period and start the next one.

• creates a copy of the trace.json file;
• generates a compressed archive inside the backup/ directory;
• creates a new trace.json file for the next month.

11. Crontab Example

The automatic execution of the project scripts is managed through the cron service.

To edit the current user's crontab, use the following command:

crontab -e

An example configuration used by the project is shown below.

*/30 * * * * /home/meshcore/trace-mon/trace.sh > /dev/null 2>&1
2 0 1 * * /home/meshcore/trace-mon/backup.sh > /dev/null 2>&1

• trace.sh is executed every 30 minutes.
• backup.sh is executed at 00:02 on the first day of each month.

12. Startup Service Configuration

The software package already includes the meshcore-trace-mon.service file, configured for the standard installation described in this guide and normally requiring no manual modifications.

To install the service, copy the file into the system service directory:

sudo cp meshcore-trace-mon.service /etc/systemd/system/

Reload the systemd configuration:

sudo systemctl daemon-reload

Enable automatic startup of the service:

sudo systemctl enable meshcore-trace-mon

Start the service:

sudo systemctl start meshcore-trace-mon

Verify that the service is running correctly:

sudo systemctl status meshcore-trace-mon

Service Management

The following commands can be used to stop, restart or disable the service.

sudo systemctl stop meshcore-trace-mon

sudo systemctl restart meshcore-trace-mon

sudo systemctl disable meshcore-trace-mon