Skip to content

Getting Started

Jump to bottom
bclml edited this page Oct 12, 2026 · 6 revisions

Getting Started

What you need

  • Windows 10 or 11 and Python 3 (Linux and macOS: see below)
  • A LoRa node running MeshCore Companion firmware (USB, Bluetooth or WiFi/TCP). Repeater and Room-server firmware cannot chat - flash the Companion build.
  • The packages in requirements.txt (meshcore-cli, pyserial, tkintermapview, pillow): pip install -r requirements.txt, or with uv: uv sync then uv run mcIRC.py

Install

  1. Download the latest release from https://github.com/bclml/mcIRC/releases (or clone the repo) into its own folder.
  2. pip install -r requirements.txt (with uv instead: uv run mcIRC.py installs what it needs and starts the app)
  3. Double-click Run_GUI.bat. It finds Python on your PC, installs the packages on the first start, and opens mcIRC without a console window; if Python is missing it says so and opens the download page. For a desktop icon with the logo use Tools > Create desktop shortcut (or double-click Make_Shortcut.bat).

Linux and macOS (experimental, edition 0.1.0)

The same code runs there but has had far less testing, so please report problems (Help > Report a bug).

  1. Python 3 with Tk: Debian/Ubuntu sudo apt install python3-tk, Fedora sudo dnf install python3-tkinter, macOS brew install python-tk (or the python.org installer).
  2. pip install -r requirements.txt (or uv run mcIRC.py)
  3. Linux USB: sudo usermod -aG dialout $USER (some distros: uucp), then log out and in. Ports look like /dev/ttyUSB0 / /dev/ttyACM0. macOS USB: /dev/cu.usbserial-....
  4. Start with ./Run_GUI.sh (Linux), double-click Run_GUI.command (macOS; first time chmod +x Run_GUI.sh Run_GUI.command), or python3 mcIRC.py.

Known differences: macOS ignores button colours (unread private buttons are less obvious), right-click is Control-click on a one-button mouse, sounds use afplay / canberra-gtk-play / paplay.

Try it without a radio

python mcIRC.py --demo

Demo mode uses made-up nodes and messages and never transmits.

Connect your node

  1. Open Options > Connect and choose how your node is connected: USB, Bluetooth or WiFi.

    connect-usb

  2. Press Scan for devices...: mcIRC lists the nodes it finds on USB and Bluetooth. Pick yours and press OK; the Connect page is filled in for you.

    device-scan

  3. Press OK, then File > Connect (or the green button on the toolbar).

Details for each connection, the Bluetooth PIN and your node's settings: Connecting Your Radio.

Only one program can use the radio at a time: close other MeshCore apps and the console bot (Run_Agent.bat) first. mcIRC itself only runs one copy.

Next: Chatting.

mcIRC is MIT licensed - https://github.com/bclml/mcIRC

Home

Using mcIRC

Addons

Help

Clone this wiki locally