# 🤖 MeshCore Bot

This script is a command bot that connects to a [MeshCore](https://github.com/meshcore-dev/MeshCore) companion radio device via USB serial connection and responds to commands received in private channels.

> [!IMPORTANT]
> To prevent spam in public channels, this bot only responds in private channels!

The bot is also able to fetch and log status data (uptime, TX air time, last SNR, noise floor...) from a repeater node.
The status data is logged to a Comma-Separated Values (CSV) file.
The interval at which the status data is fetched can be configured.
This bot is ideal for testing MeshCore setup with repeater and distance of communication.

| Client | Bot |
|--------|-----|
| ![Screenshot: Client](https://github.com/Cyclenerd/meshcore-bot/raw/master/img/screenshot-client.jpg) | ![Screenshot: Bot Log](https://github.com/Cyclenerd/meshcore-bot/raw/master/img/screenshot-bot.png) |

## Installation

1.  **Node.js**: Make sure you have Node.js installed. You can download it from [https://nodejs.org/](https://nodejs.org/) or install it via a software package manager:

    macOS using Homebrew:

    ```bash
    brew install node
    ```

    Debian and Ubuntu based Linux distributions:

    ```bash
    sudo apt install nodejs npm
    ```

1.  **Clone**: Clone this repo:

    ```bash
    git clone "https://github.com/Cyclenerd/meshcore-bot.git"
    cd "meshcore-bot"
    ```

1.  **Dependencies**: In the directory run:

    ```bash
    npm ci --production
    ```

## Usage

To run the bot use the following command:

```bash
node meshcore-bot.js --port [SERIAL_PORT] --repeater-public-key-prefix [REPEATER_PUBLIC_KEY_PREFIX] --repeater-password [REPEATER_PASSWORD] --repeater-interval [STATUS_INTERVAL_MINUTES] --csv [CSV_FILE]
```

-   `--port` or `-s` (optional): The serial port of the MeshCore device. Defaults to `/dev/cu.usbmodem1101`.
-   `--repeater-public-key-prefix` or `-r` (optional): The public key prefix of a repeater node to fetch status from. If provided, this feature is enabled.
-   `--repeater-password` or `-p` (optional): The password for the repeater. By default, this is an empty string.
-   `--repeater-interval` or `-i` (optional): The interval in minutes at which status data is retrieved from the repeater. The default value is `15`.
-   `--csv` or `-c` (optional): The CSV file in which the repeater's status data is to be logged. If this file is specified, the data will be logged in this file.

### Examples

**Basic:**

```bash
node meshcore-bot.js --port "/dev/ttyUSB0"
```

**With Repeater Status:**

```bash
node meshcore-bot.js \
--port "/dev/ttyUSB0" \
--repeater-public-key-prefix "935c6b694200644710a374c250c76f7aed9ec2ff3e60261447d4eda7c246ce5d" \
--repeater-password "your-password" \
--repeater-interval 30
```

This will connect to the device on `/dev/ttyUSB0` and fetch status data from the specified repeater every 30 minutes.

**With Repeater and CSV Logging:**

```bash
node meshcore-bot.js \
--port "/dev/ttyUSB0" \
--repeater-public-key-prefix "935c6b694200644710a374c250c76f7aed9ec2ff3e60261447d4eda7c246ce5d" \
--repeater-password "your-password" \
--repeater-interval 30 \
--csv "status.csv"
```

This will do the same as the previous example, but it will also log the status data to `status.csv`.

Example CSV:

```csv
timestamp,batt_milli_volts,curr_tx_queue_len,noise_floor,last_rssi,n_packets_recv,n_packets_sent,total_air_time_secs,total_up_time_secs,n_sent_flood,n_sent_direct,n_recv_flood,n_recv_direct,err_events,last_snr,n_direct_dups,n_flood_dups
2025-09-12T19:06:07Z,3969,0,-111,-59,2029,1749,1399,700263,1672,77,1514,359,0,28,0,98
2025-09-12T19:08:32Z,3969,0,-110,-60,2033,1753,1401,700407,1676,77,1515,362,0,28,0,98
```

### Commands

-   `.ping`: The bot will respond with "PONG! 🏓 (*hop count*)".
-   `.date`: The bot will respond with the current date and time in ISO format.

## License

All files in this repository are under the [Apache License, Version 2.0](https://github.com/Cyclenerd/meshcore-bot/blob/master/LICENSE) unless noted otherwise.