Turn a Meshtastic® node into a BBS — from zero

Absolute beginner guide • TC²-BBS • Meshtastic

Don't know what a BBS is? Never made a Python virtual environment? Don't know the difference between serial, TCP, config.ini, systemd, or a node ID? This walkthrough assumes none of that knowledge.

Raspberry Pi friendlyLinux friendlyUSB or network nodeCopy/paste commandsAutostart included

Start here Back to Projects & Guides

1. Understand it 2. What you need 3. Prepare Pi 4. Install 5. Connect radio 6. Configure 7. Run/test 8. Autostart Errors

First: this does NOT replace Meshtastic firmware.

You still need a working Meshtastic radio/node. TC²-BBS runs on a separate computer such as a Raspberry Pi or Linux PC and talks to that Meshtastic node over USB/serial or, for compatible ESP32 devices, over TCP/network.

The radioYour normal Meshtastic node handles LoRa communication.

The computerRaspberry Pi, Linux PC, macOS or Windows runs the TC²-BBS Python program.

The BBSThe Python program watches messages coming from the radio and replies with menus, mail and bulletin-board functions.

Before installing anything

WHAT YOU NEED.

A working Meshtastic nodeGet the radio working normally first. Do not troubleshoot the BBS and the radio at the same time.

A computer to run the BBSA Raspberry Pi is a natural always-on choice. The upstream project requires Python 3.x.

A way to connect the twoUSB/serial is the easiest beginner route. TCP is also supported for compatible network-connected ESP32 Meshtastic devices.

WisBlock / RAK users: the project's example configuration specifically notes that its TCP mode does not work for WisBlock. Use a supported serial/USB path instead.

Recommended beginner path

Use a Raspberry Pi or Linux computer + USB cable to the Meshtastic node. It removes a whole layer of IP-address/network troubleshooting.

Prepare the Raspberry Pi / Linux machine

UPDATE IT AND INSTALL GIT.

Open Terminal. If you're using a Raspberry Pi remotely, connect with SSH first.

sudo apt update

sudo apt upgrade

sudo apt install git

What is Git?

For this guide, think of Git as the tool that downloads the TC²-BBS project from GitHub and keeps the project files together.

Download TC²-BBS

CLONE THE PROJECT.

cd ~

git clone https://github.com/TheCommsChannel/TC2-BBS-mesh.git

cd TC2-BBS-mesh

cd ~ means “go to my home folder.” The second command downloads the project. The third moves you inside the new project folder.

Create a Python virtual environment

python -m venv venv

What the heck is a virtual environment?

It is simply a private little Python workspace for this project. It keeps TC²-BBS's Python packages separated from other software on your computer.

Activate it

source venv/bin/activate

After activation, your terminal may show (venv) at the beginning of the line. That's good.

Install the project's required Python packages

pip install -r requirements.txt

Choose how the BBS reaches your radio

USB/SERIAL OR TCP?

USB / Serial — easiestPlug the Meshtastic device into the BBS computer with a data-capable USB cable. TC²-BBS talks directly to the serial device.

TCP / NetworkThe BBS computer connects to the Meshtastic device's IP address over your local network. The upstream example says this is for ESP32 devices and not WisBlock.

Not sure?Use USB/serial first. Once the BBS works, experiment with network connections later.

If using USB/serial

Plug in the radio. Linux commonly exposes Meshtastic radios as something like /dev/ttyACM0 or /dev/ttyUSB0.

If only one compatible radio is attached, you may be able to leave the port line commented out. If multiple serial devices exist, specify the exact device port in the config.

If using TCP

You need the local IP address of the compatible Meshtastic device, for example 192.168.1.100.

Create your real config

TURN THE EXAMPLE CONFIG INTO YOUR CONFIG.

mv example_config.ini config.ini

Now open it:

nano config.ini

How nano works

Use the arrow keys to move around. When finished, press Ctrl+X, then Y, then Enter to save.

Beginner USB/serial example

[interface]
type = serial
# port = /dev/ttyACM0

If the automatic serial connection does not find the correct device, remove the # before port and enter your actual port.

Network/TCP example

[interface]
type = tcp
hostname = 192.168.1.100

Replace the example address with the real local IP address of your supported Meshtastic device.

BBS syncing is optional

The [sync] section is only needed if you want this BBS to sync mail/bulletins with other TC²-BBS nodes. You do not need it for your first local test.

[sync]
bbs_nodes = !f53f4abc,!f3abc123

Those values are Meshtastic node IDs. Separate multiple IDs with commas and no spaces.

Urgent-board allow list is optional too

The example config supports an [allow_list] section that limits who can post to the urgent board. If the section stays commented out, the upstream config says anyone can post there.

Menu items can be trimmed later

The example file lets you remove main menu, BBS menu and utility menu options. Leave the defaults alone until your basic BBS is working.

Meshtastic radio role

USE A ROLE THE PROJECT SAYS IS WORKING.

The upstream README warns that some Meshtastic device roles may initially communicate and then stop responding to BBS requests.

Roles specifically reported working by the project:

Client.

If you are troubleshooting a flaky BBS, do not start with an exotic device role. Use one of the project's known-working roles first.

First run

START THE BBS MANUALLY BEFORE AUTOMATING IT.

Make sure you're still inside the project folder and the Python virtual environment is active.

python server.py

Leave that terminal running during the first test.

How do users talk to the BBS?

From another Meshtastic node/app, send a direct message to the Meshtastic node connected to the BBS computer.

The upstream project says sending any message should return the main menu. Then you make menu selections by sending the letter or number shown in brackets — for example, send M for the Mail menu.

Success looks like this:

You DM the BBS node, it replies with a menu, and additional menu commands get responses.

Do not set up autostart until this works manually.

Make it survive reboots

SET UP THE SYSTEMD SERVICE.

VERY COMMON BEGINNER TRAP:

The included mesh-bbs.service is written for a Linux user named pi. Modern Raspberry Pi installs often use a different username. If your username is not pi, you must edit the service file first.

Find your current username:

whoami

Then edit the service:

nano mesh-bbs.service

The stock file contains these three lines:

User=pi
WorkingDirectory=/home/pi/TC2-BBS-mesh
ExecStart=/home/pi/TC2-BBS-mesh/venv/bin/python3 /home/pi/TC2-BBS-mesh/server.py

Replace every relevant pi with your actual username. For example, if whoami says meshuser:

User=meshuser
WorkingDirectory=/home/meshuser/TC2-BBS-mesh
ExecStart=/home/meshuser/TC2-BBS-mesh/venv/bin/python3 /home/meshuser/TC2-BBS-mesh/server.py

Save the file, then install and start the service:

sudo cp mesh-bbs.service /etc/systemd/system/

sudo systemctl enable mesh-bbs.service

sudo systemctl start mesh-bbs.service

Check whether it is alive

sudo systemctl status mesh-bbs.service

Live logs

journalctl -u mesh-bbs.service -f

Restart after changing config

sudo systemctl restart mesh-bbs.service

Something broke?

Troubleshooting

python -m venv venv fails

Make sure Python 3 and the venv support package are installed for your OS. On Raspberry Pi OS/Debian, a missing venv module is a common cause. Read the exact terminal error rather than repeatedly re-running the same command.

pip install -r requirements.txt fails

Confirm the virtual environment is active and that you are inside the TC2-BBS-mesh directory. Network/package errors can also occur if the Pi has no Internet connection.

The BBS cannot see my Meshtastic radio

For serial mode, verify you're using a data-capable USB cable, the radio appears as a serial device, and the config points to the correct port if more than one serial device is connected. For TCP, verify the device is a supported type and the IP address is correct.

It works for a little while and then stops responding

The upstream README specifically mentions problems with some Meshtastic device roles. Test using Client or Router_Client, which the project reports as working.

It runs manually but not after reboot

Check sudo systemctl status mesh-bbs.service. The most likely beginner mistake is leaving User=pi and /home/pi/... in the service file when your actual Linux username is something else.

I changed config.ini but nothing changed

If running manually, stop and restart python server.py. If running as the system service, use sudo systemctl restart mesh-bbs.service.

How do I see what the service is complaining about?

Run journalctl -u mesh-bbs.service -f for live logs, or journalctl -u mesh-bbs.service for previous log entries.

Once it works

THEN START PLAYING WITH THE FUN STUFF.

MailSend and receive BBS mail through Meshtastic.

Bulletin boardsPost and read persistent bulletin messages.

Channel directoryMaintain and browse channel information.

StatisticsView node, hardware and role information.

BBS synchronizationSync mail and bulletins with other TC²-BBS nodes using their node IDs.

JS8Call integrationThe configuration file includes optional JS8Call settings. Treat this as an advanced add-on after the Meshtastic BBS is stable.

Docker note

YES, THERE IS ALSO A DOCKER IMAGE.

The project README links an official Docker Hub image for TC²-BBS Meshtastic. This beginner guide intentionally uses the normal Python installation first because it exposes each moving part clearly and makes troubleshooting easier for someone starting from zero.

TC²-BBS Docker Hub ↗

Project documentation

Hardware revisions and software screens can change. Use the original project documentation alongside this walkthrough.

Open the original documentation →