pyMC_Core

pyMC_Core is a Python reimplementation of MeshCore — a lightweight, portable C++ library for multi-hop packet routing using LoRa radios. Designed for Raspberry Pi and similar hardware, pyMC_Core communicates with LoRa modules over SPI.

pyMC_Core is under active development. It's compatible with the original MeshCore protocol, but not yet as optimized or elegant as its C++ counterpart.

Documentation

**Complete documentation is available at https://rightup.github.io/pyMC_core/

Quick Links

• Node Usage Guide - Guide for using MeshNode
• Examples - Working code examples
• API Reference - Detailed API documentation

Quick Start

Installation

Important: On modern Python installations (Ubuntu 22.04+, Debian 12+), you may encounter externally-managed-environment errors when installing packages system-wide. Create a virtual environment first:

# Create virtual environment
python3 -m venv pymc_env

# Activate virtual environment
# On Linux/Mac:
source pymc_env/bin/activate
# On Windows:
pymc_env\Scripts\activate

# Install from PyPI
pip install pymc-core

# For hardware support (SX1262 radios)
pip install pymc-core[hardware]

# Install all dependencies
pip install pymc-core[all]

Basic Usage

import asyncio
from pymc_core import MeshNode, LocalIdentity
from pymc_core.hardware.sx1262_wrapper import SX1262Radio

async def main():
    # Create radio (Waveshare HAT example)
    radio = SX1262Radio(
        bus_id=0, cs_pin=21, reset_pin=18,
        busy_pin=20, irq_pin=16, txen_pin=6,
        frequency=869525000, tx_power=22
    )
    radio.begin()

    # Create mesh node
    identity = LocalIdentity()
    node = MeshNode(radio=radio, local_identity=identity)
    await node.start()

    print("Mesh node started!")

asyncio.run(main())

For examples, see the documentation.

Hardware Support

Supported Radios

• Waveshare SX1262 LoRaWAN/GNSS HAT - Popular Raspberry Pi LoRa module
• HackerGadgets uConsole - All-in-one extension board with LoRa support
• FrequencyLabs meshadv-mini - Raspberry Pi hat with E22-900M22S LoRa module

Requirements

• Raspberry Pi (or compatible SBC)
• SX1262 LoRa module
• SPI interface enabled
• Python 3.8+

What is MeshCore?

MeshCore enables long-range, decentralized communication using multi-hop packet routing. Devices (nodes) forward packets through neighboring nodes to reach distant ones — no central infrastructure required.

It occupies a middle ground between:

Use Cases

• Off-grid and emergency communication
• Tactical or field mesh deployments
• IoT mesh networks
• Remote monitoring systems

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Application   │    │   MeshNode      │    │   Hardware      │
│                 │    │                 │    │                 │
│ • Text Messages │◄──►│ • Packet Routing│◄──►│ • SX1262 Radio  │
│ • Advertisements│    │ • Identity Mgmt │    │ • SPI Interface │
│ • Telemetry     │    │ • Event Service │    │ • GPIO Control  │
│ • Group Channels│    │ • Repeater Mgmt │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Security

• Ed25519/X25519 cryptographic identities
• End-to-end encryption for messages
• CRC validation for data integrity
• Secure key exchange protocols

Project Structure

pyMC_Core/
├── src/pymc_core/          # Main package
│   ├── hardware/           # Radio hardware interfaces
│   ├── node/               # MeshNode implementation
│   ├── protocol/           # Packet protocols
│   └── events/             # Event handling
├── examples/               # Working examples
│   ├── common.py           # Shared utilities
│   ├── send_flood_advert.py
│   ├── send_direct_advert.py
│   └── ...
├── docs/                   # MkDocs documentation
│   ├── docs/               # Documentation source files
│   ├── mkdocs.yml          # MkDocs configuration
│   ├── requirements.txt    # Documentation dependencies
│   └── serve-docs.sh       # Local development script
├── .github/workflows/      # GitHub Actions
│   └── deploy-docs.yml     # Documentation deployment pipeline
└── tests/                  # Unit tests

Contributing

Contributions are welcome! Please see our contributing guide for details.

Development Setup

# Clone the repository
git clone https://github.com/rightup/pyMC_Core.git
cd pyMC_Core

# Install development dependencies
pip install -e .[dev]

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Original MeshCore C++ implementation
• Waveshare and HackerGadgets for hardware support

Support

• Documentation
• Issues
• Discussions
• pyMC Discord
• Meshcore Discord

Built with ❤️ for mesh networking enthusiasts