openHop Core

openHop 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, openHop Core communicates with LoRa modules over SPI.

openHop 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/openhop-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 openhop_env

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

# Install from PyPI
pip install openhop-core

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

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

Basic Usage

import asyncio
from openhop_core import MeshNode, LocalIdentity
from openhop_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.9+

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:

Project	Focus
Meshtastic	Casual LoRa messaging
Reticulum	Full encrypted networking stack

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

openHop Core/
├── src/openhop_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/openHop Core.git
cd openHop 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](https://github.com/openhop-dev/openHop Core/issues)
• [Discussions](https://github.com/openhop-dev/openHop Core/discussions)
• pyMC Discord
• Meshcore Discord

---

Built with ❤️ for mesh networking enthusiasts