Metadata-Version: 2.3
Name: msh-bot
Version: 0.1.0
Summary: A simple meshtastic bot
Author: suzana2314
Author-email: suzana2314 <rodrigosuzana@proton.me>
Requires-Dist: meshtastic>=2.7.11
Requires-Python: >=3.12
Description-Content-Type: text/markdown

<table>
  <tr>
    <td>
      
# MSH-BOT

This is a simple meshtastic bot that will reply to some given commands. It connects to a node over TCP so the node needs to be reachable on your network. The main purpose of this bot is to use it for tests in a private channel :)
</td>
    <td width="140">
      <img src="assets/thing.svg" width="120" alt="Thing logo">
    </td>
  </tr>
</table>

### Commands
```
/trace <node_id>    -> will traceroute the given node_id and return the number of hops and path, if no node_id is given it will trace route the sender
/ping               -> will just reply with the number of hops and snr and rssi values
/dist               -> will calculate the distance between the sender and the bot
/off <time>         -> program will disconnect from node for the given time (useful for maintenance on the node)
/help               -> will print an help message listing available commands
```

### Configuration

Settings live in a `config.toml` file, the bot reads the path specified in `MSHBOT_CONFIG` if set, otherwise `config.toml` in the working dir. `config.example.toml` in the repository root is a template to copy.

```toml
[node]
hostname = "192.168.1.1"    # hostname of the node
target_channel = "Example"  # the channel name where the bot will reply (please do not set in main channels like longfast), note that this is case sensitive!
dm_reply_message = "Hello!" # if this is defined the bot will respond to all dms with this message, if this is not set in the config the dm functionality is disabled!
discord_webhook_url = "https://discord.com/api/webhooks/..." # if set will send all the received and sent messages through this webhook


[mesh]
hop_limit = 4               # the bot hop limit (check your local community guide for this value)
trace_route_channel = 0     # the channel where the traceroute will run (default 0), set this as your public channel if it is not 0 so the node ids in the path are not always !ffffff
trace_route_timeout = 60    # hard timeout for trace route (default 1 min)

[offline]
offline_minutes = 30        # default value for the time the node will be offline (in case a <time> value is omitted in the /off command)
disconnect_delay = 10       # delay in seconds till the program disconnects from the node
reconnect_poll = 30         # delay in seconds to retry connection to the node
probe_interval = 60         # seconds between liveness probes, also the worst case delay before a silent drop is detected
```

`hostname` and `target_channel` are required, everything else falls back to the defaults shown above

### Install (as systemd service)

These instructions assume systemd and a dedicated service account. Adjust the paths if you prefer somewhere other than `/opt`.

I run this bot on a Pi Zero 2 W, where a container adds more overhead than it is worth for a single Python process. systemd is enough.

The projec is built with uv. Since the pi doesn't have uv installed I usually just buld the wheel on my host and copy it over to the pi.

**Build the wheel**
```sh
uv build
```

This produces something like this: `dist/msh_bot-0.1.0-py3-none-any.whl`

**Copy this to the pi**
```sh
scp dist/msh_bot-0.1.0-py3-none-any.whl <user>@<host>:/tmp/
```

**Create the user and dirs**
```sh
sudo useradd -r -s /usr/sbin/nologin msh-bot
sudo mkdir -p /opt/msh-bot /etc/msh-bot
sudo chown msh-bot:msh-bot /opt/msh-bot
```

**Install the wheel**
```sh
sudo -u msh-bot -H /usr/bin/python3 -m venv /opt/msh-bot/venv
sudo -u msh-bot -H /opt/msh-bot/venv/bin/pip install --no-cache-dir /tmp/msh_bot-0.1.0-py3-none-any.whl
```

On the pi if the `venv` command hangs don't worry it is not stuck!

**Copy config**
```sh
sudo cp config.example.toml /etc/msh-bot/config.toml
sudo chown root:msh-bot /etc/msh-bot/config.toml
sudo chmod 640 /etc/msh-bot/config.toml
```
Then edit it with your favourite editor, for example `sudo vim /etc/msh-bot/config.toml`. The file is readable by the service and by root only.

**Create the unit file**

at `/etc/systemd/system/msh-bot.service`

```ini
[Unit]
Description=MSH-BOT a simple meshtastic bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=msh-bot
WorkingDirectory=/opt/msh-bot
Environment=MSHBOT_CONFIG=/etc/msh-bot/config.toml
ExecStart=/opt/msh-bot/venv/bin/msh-bot
Restart=on-failure
RestartSec=10

NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes

[Install]
WantedBy=multi-user.target
```

**Start it**
```sh
sudo systemctl daemon-reload
sudo systemctl enable --now msh-bot.service
```


