Table of Contents

Using meshcore-cli with a USB Companion Node

A quick-start guide for serial MeshCore nodes

If you’re running a USB companion node (such as a Pico-based or other serial MeshCore device), meshcore-cli gives you full control from the command line. This guide walks through installation, connecting over USB, setting US radio parameters, joining channels, and running it inside a persistent screen session.

Install meshcore-cli

Option A: Install System-Wide (Quick Method)

If you’re not using a virtual environment:

python3 -m pip install meshcore-cli --break-system-packages

⚠ On some Linux systems, --break-system-packages is required to allow pip to install outside the system-managed environment.

Option B: Install Inside a Python Virtual Environment (Recommended)

Using a virtual environment keeps your system Python clean.

python3 -m venv meshcore-env
source meshcore-env/bin/activate
pip install meshcore-cli

Whenever you want to use it later:

source meshcore-env/bin/activate

Plug in Your USB Companion Node

Connect your serial MeshCore node via USB.

On macOS

Run:

ls /dev/cu.*

Look for something like:

/dev/cu.usbmodem123456

That full path is your device address.

On Linux

Run:

ls /dev/ttyACM*

You’ll typically see something like:

/dev/ttyACM0

That is your device path.

Connect to the Node

Start meshcore-cli using the serial flag:

meshcore-cli -s /dev/cu.usbmodemXXXX

(Replace with your actual device path.)

On Linux:

meshcore-cli -s /dev/ttyACM0

Set US LoRa Radio Parameters

Immediately after connecting, configure US radio settings:

set radio 910.525,62.5,7,5,off
quit

At the time of writing, the reboot command does not appear to function correctly. Running quit ensures the settings apply properly.

Reconnect and Set Your Node Name

Open meshcore-cli again:

meshcore-cli -s /dev/cu.usbmodemXXXX

Now set your name:

set name YOURNAME

You can use emoji if you’d like.

Sending Messages

By default, you are in the Public channel.

Send a message to Public:

public Hello world!

Joining and Using Channels

Join a channel:

add_channel #asheville

Check which channels you’re in:

get_channels

This will show channel numbers assigned by your node.

Once you know the number, send a message like this:

chan 2 Hello World!

Replace 2 with your channel’s actual number.

Why Use meshcore-cli?

Controlling a node from the command line is useful for:

  • Running remote nodes over SSH
  • Managing headless devices
  • Monitoring traffic in real time
  • Automation and scripting
  • Operating on servers without Bluetooth or GUI

It’s especially powerful if your node is attached to a Linux server, Raspberry Pi, or remote machine.

Keeping meshcore-cli Running with Screen

If your node is connected to a remote machine, you can keep the CLI open using screen.

Start a session:

screen -S meshcore
meshcore-cli -s /dev/ttyACM0

Detach from screen:

Ctrl + A, then D

Reattach later:

screen -r meshcore

This allows you to:

  • SSH into your machine
  • Resume your CLI session
  • Check messages
  • Send commands
  • Disconnect without stopping the node session

Running a USB companion node with meshcore-cli gives you full low-level control of your MeshCore device. Whether you’re operating locally on macOS or remotely on Linux over SSH, the CLI provides a powerful and flexible way to interact with the mesh.

If you’re building out nodes around Asheville or experimenting with remote deployments, CLI control becomes especially valuable for stable, always-on systems.

Happy meshing!