BitChat Integration for MeshCore

Firmware Version: 1.14.1
Approach: Subclassing & Separate Examples Status: Production Ready - 228/228 Tests Passing

Overview

The BitChat integration enables MeshCore devices to communicate with the BitChat Android app through a bridge layer that translates between BitChat protocol and MeshCore mesh networking. This is an additive feature that preserves all existing MeshCore functionality while adding BitChat compatibility.

Key Principles

Additive, Not Substitutive: BitChat support is added alongside MeshCore, not replacing it
No Infrastructure Changes: Repeaters and room servers require no modifications
Encapsulation Strategy: BitChat messages are encapsulated in standard MeshCore packets
Backward Compatible: Existing MeshCore nodes continue to work normally
Isolated Implementation: BitChat logic in separate classes for easy future updates

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                            MeshCore Device                               │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────┐    ┌────────────────────────────────┐  │
│  │    WITH DISPLAY (Menu)      │    │     BUTTON-ONLY (T1000-E)      │  │
│  │   ┌─────────────────────┐   │    │   ┌────────────────────────┐   │  │
│  │   │   BITCHAT Page      │   │    │   │   5x Button Press      │   │  │
│  │   │  ┌─────┐  ┌─────┐   │   │    │   │   (Quintuple)          │   │  │
│  │   │  │  M  │  │  B  │   │   │    │   │  ┌──────────────────┐  │   │  │
│  │   │  │Mesh │  │BitC │   │   │    │   │  │ LED: 3 blinks    │  │   │  │
│  │   │  └──┬──┘  └──┬──┘   │   │    │   │  │ Buzzer: tone     │  │   │  │
│  │   │     └────┬───┘      │   │    │   │  └────────┬─────────┘  │   │  │
│  │   └──────────┼──────────┘   │    │   └───────────┼────────────┘   │  │
│  └──────────────┼──────────────┘    └───────────────┼────────────────┘  │
│                 │                                   │                    │
│                 └───────────────────┬───────────────┘                    │
│                                     ▼                                    │
│  ┌────────────────────────────────────────────────────────────────────┐ │
│  │                    SerialBLEInterface                               │ │
│  │  • MeshCore UART Service (6E400001-B5A3-F393-E0A9-E50E24DCCA9E)    │ │
│  │  • BitChat Service (F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C)        │ │
│  │  • Only ONE service advertised at a time                           │ │
│  │  • Auto-disconnects clients on mode switch                         │ │
│  │  • PIN auth (MeshCore) / Open access (BitChat)                    │ │
│  └────────────────────────────────┬───────────────────────────────────┘ │
│                                   │                                      │
│                       ┌───────────▼────────────┐                        │
│                       │    BitchatBridge       │                        │
│                       │  • Encapsulate         │──► MeshCore GRP/TXT    │
│                       │  • Decapsulate         │◄── BC magic header     │
│                       │  • Loop prevention     │                        │
│                       └───────────┬────────────┘                        │
│                                   │                                      │
│                       ┌───────────▼────────────┐                        │
│                       │       MyMesh           │                        │
│                       │     (MeshCore)         │                        │
│                       └───────────┬────────────┘                        │
│                                   │                                      │
│                       ┌───────────▼────────────┐                        │
│                       │     LoRa Radio         │                        │
│                       │    (SX1262/etc)        │                        │
│                       └────────────────────────┘                        │
└──────────────────────────────────────────────────────────────────────────┘

Approach: Subclassing Architecture (1.14.1)

This version uses Subclassing Architecture for cleaner integration:

┌─────────────────┐
│   BaseChatMesh  │  (MeshCore Core - unchanged)
└────────┬────────┘
         │
┌────────▼────────┐     ┌─────────────────┐
│   BitchatMesh   │◄────┤  BitchatBridge  │  (BitChat Extensions)
└────────┬────────┘     └─────────────────┘
         │
┌────────▼────────┐
│     MyMesh      │  (Application Layer)
└─────────────────┘

Benefits:

Only 2 core files modified (backward-compatible additions)
Easy migration to future MeshCore versions (1.15.0, etc.)
Comprehensive test suite (228 tests)
Zero merge conflicts

Platform Support

Feature	nRF52	ESP32
Menu-based BLE mode switching	✅	✅
Button-based BLE mode switching	✅	✅
Visual mode indicator (M/B)	✅	✅
LED/buzzer feedback (button-only)	✅	✅
BitChat BLE service	✅	✅
MeshCore UART service	✅	✅
PIN authentication (MeshCore mode)	✅	✅
Open access (BitChat mode)	✅	✅

With Display (Menu-Based)

Navigate to the BITCHAT page and press ENTER to toggle between modes. Display shows large M (MeshCore) or B (BitChat).

Button-Only (T1000-E)

Press the user button 5 times rapidly (within ~3 seconds) to toggle modes. See Button-Based Mode Switching for details.

Documentation Structure

User Documentation

Document	Description
Build Configuration	ENABLE_BITCHAT flag, build options, compilation settings
Device Compatibility	Complete list of compatible/incompatible devices
Button-Based Mode Switching	T1000-E and button-only device guide
Protocol Specification	BitChat wire protocol format
Encapsulation Format	MeshCore encapsulation header and format
Payloads	BitChat payload types and structures
BLE Service	BLE GATT service specification
Architecture	Component architecture and data flow

Developer Documentation

Document	Description
Integration Guide (1.14.1)	Complete integration guide for developers
Code Review Report	Code review findings and security analysis
Migration Guide	Porting to new MeshCore versions

Quick Start

Enable BitChat Support

Add to your platformio.ini:

build_flags =
    -D ENABLE_BITCHAT=1
    -D BLE_MODE_SWITCHING=1

Build for Target Device

# Build for Wio Tracker L1
pio run -e seeed-wio-tracker-l1

# Run test suite
pio test -e native_bitchat

Runtime Control

BitChat mode is controlled on-device via the UI or button presses:

With Display:

Navigate to BITCHAT page using LEFT/RIGHT buttons
Press ENTER to toggle between MeshCore and BitChat modes
Display shows large M (MeshCore) or B (BitChat)

Button-Only (T1000-E):

Press user button 5 times rapidly (within ~3 seconds)
LED blinks 3 times (fast=Bitchat 150ms, slow=MeshCore 500ms)
Buzzer plays acknowledgment tone (if available)

Note: The device always boots in MeshCore mode. Mode is not persisted across reboots.

Message Flow

BitChat → MeshCore

BitChat app sends MESSAGE via BLE to #mesh channel
BitchatBLEService receives and parses message
BitchatBridge formats for MeshCore with 📱 prefix
Message sent as PAYLOAD_TYPE_GRP_TXT via mesh on #mesh channel

MeshCore → BitChat

MeshCore receives group message on #mesh channel
BitchatBridge verifies channel secret matches SHA256("#mesh")
BitchatBridge detects non-BitChat origin (no 📱 prefix)
Message formatted as BitChat MESSAGE with TLV payload
Sent to BitChat app via BLE notification for #mesh channel

#mesh Channel

The #mesh hashtag channel is the primary interoperability channel between BitChat and MeshCore.

Channel Key Derivation

#mesh secret = first_16_bytes(SHA256("#mesh"))
             = 0x5B664CDE0B08B220612113DB980650F3

The channel secret is the first 16 bytes of the SHA256 hash of the UTF-8 encoded channel name string (including the # prefix).

Both BitChat Android app and MeshCore firmware derive the same channel secret using this mechanism, enabling seamless group messaging.

Known Limitations

Issue	Status	Workaround
BLE Notification Freeze	⚠️ Partial	MeshCore→BitChat notifications currently disabled on nRF52
Channel Hash Mismatch	✅ Fixed	#mesh channel verified by full 32-byte secret
Simultaneous BLE Services	❌ HW Limit	Menu-based switching (both nRF52 and ESP32)
DM Support	🚧 Planned	Basic infrastructure in place
Multiple Hashtag Channels	🚧 Planned	Currently #mesh only

Compatibility

Component	Compatibility
MeshCore Android App	✅ Full (when in MeshCore BLE mode)
BitChat Android App	✅ Full (when in BitChat BLE mode)
MeshCore Repeaters	✅ No changes required
MeshCore Room Servers	✅ No changes required
Other MeshCore Nodes	✅ Backward compatible

Future Support for Display-Less Devices

Devices without displays or buttons may receive BitChat support through:

CLI Configuration: bitchat enable command via serial
Startup Mode: Default to BitChat mode on boot
Companion App: Configure via USB/BLE from phone

Planned for future releases. Priority will be given to popular devices like:

Xiao series
Heltec Mesh Solar

Testers Wanted!

If you have any of the build-verified devices above, please test and report your results:

Flash the firmware to your device
Test core functionality:
- BLE pairing with BitChat app
- Sending/receiving messages
- Display navigation (if applicable)
- Button controls
Report results in GitHub Issues

Your feedback helps move devices from "build-verified" to "real-world tested"!

About MeshCore

MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.

🔍 What is MeshCore?

MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions., where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.

⚡ Key Features

Multi-Hop Packet Routing
- Devices can forward messages across multiple nodes, extending range beyond a single radio's reach.
- Supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic.
- Nodes use fixed roles where "Companion" nodes are not repeating messages at all to prevent adverse routing paths from being used.
Supports LoRa Radios – Works with Heltec, RAK Wireless, and other LoRa-based hardware.
Decentralized & Resilient – No central server or internet required; the network is self-healing.
Low Power Consumption – Ideal for battery-powered or solar-powered devices.
Simple to Deploy – Pre-built example applications make it easy to get started.

🎯 What Can You Use MeshCore For?

Off-Grid Communication: Stay connected even in remote areas.
Emergency Response & Disaster Recovery: Set up instant networks where infrastructure is down.
Outdoor Activities: Hiking, camping, and adventure racing communication.
Tactical & Security Applications: Military, law enforcement, and private security use cases.
IoT & Sensor Networks: Collect data from remote sensors and relay it back to a central location.

🚀 How to Get Started

Watch the MeshCore Intro Video by Andy Kirby.
Watch the MeshCore Technical Presentation by Liam Cottle.
Read through our Frequently Asked Questions and Documentation.
Flash the MeshCore firmware on a supported device.
Connect with a supported client.

For developers;

Install PlatformIO in Visual Studio Code.
Clone and open the MeshCore repository in Visual Studio Code.
See the example applications you can modify and run:
- Companion Radio - For use with an external chat app, over BLE, USB or WiFi.
- KISS Modem - Serial KISS protocol bridge for host applications. (protocol docs)
- Simple Repeater - Extends network coverage by relaying messages.
- Simple Room Server - A simple BBS server for shared Posts.
- Simple Secure Chat - Secure terminal based text communication between devices.
- Simple Sensor - Remote sensor node with telemetry and alerting.

The Simple Secure Chat example can be interacted with through the Serial Monitor in Visual Studio Code, or with a Serial USB Terminal on Android.

⚡️ MeshCore Flasher

We have prebuilt firmware ready to flash on supported devices.

Launch https://meshcore.io/flasher
Select a supported device
Flash one of the firmware types:
- Companion, Repeater or Room Server
Once flashing is complete, you can connect with one of the MeshCore clients below.

📱 MeshCore Clients

Companion Firmware

The companion firmware can be connected to via BLE, USB or WiFi depending on the firmware type you flashed.

Repeater and Room Server Firmware

The repeater and room server firmwares can be setup via USB in the web config tool.

https://config.meshcore.io

They can also be managed via LoRa in the mobile app by using the Remote Management feature.

🛠 Hardware Compatibility

MeshCore is designed for devices listed in the MeshCore Flasher

📜 License

MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.

Contributing

Please submit PR's using 'dev' as the base branch! For minor changes just submit your PR and we'll try to review it, but for anything more 'impactful' please open an Issue first and start a discussion. Is better to sound out what it is you want to achieve first, and try to come to a consensus on what the best approach is, especially when it impacts the structure or architecture of this codebase.

Here are some general principals you should try to adhere to:

Keep it simple. Please, don't think like a high-level lang programmer. Think embedded, and keep code concise, without any unnecessary layers.
No dynamic memory allocation, except during setup/begin functions.
Use the same brace and indenting style that's in the core source modules. (A .clang-format is prob going to be added soon, but please do NOT retroactively re-format existing code. This just creates unnecessary diffs that make finding problems harder)

Help us prioritize! Please react with thumbs-up to issues/PRs you care about most. We look at reaction counts when planning work.

Road-Map / To-Do

There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order:

📞 Get Support

Report bugs and request features on the GitHub Issues page.
Find additional guides and components on MeshCore Documentation.
Join MeshCore Discord to chat with the developers and get help from the community.

Version: 1.14.1
Approach: Subclassing Architecture
Test Status: 228/228 passing
Last Updated: April 2026

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
arch		arch
bin/uf2conv		bin/uf2conv
boards		boards
docs		docs
examples		examples
include		include
lib		lib
logo		logo
scripts		scripts
src		src
test		test
variants		variants
.clang-format		.clang-format
.envrc		.envrc
.gitignore		.gitignore
CNAME		CNAME
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
RELEASE.md		RELEASE.md
build.sh		build.sh
build_as_lib.py		build_as_lib.py
create-uf2.py		create-uf2.py
default.nix		default.nix
library.json		library.json
license.txt		license.txt
merge-bin.py		merge-bin.py
mkdocs.yml		mkdocs.yml
platformio.ini		platformio.ini

Latest commit

History

Folders and files

Repository files navigation

BitChat Integration for MeshCore

Overview

Key Principles

Architecture

Approach: Subclassing Architecture (1.14.1)

Platform Support

With Display (Menu-Based)

Button-Only (T1000-E)

Documentation Structure

User Documentation

Developer Documentation

Quick Start

Enable BitChat Support

Build for Target Device

Runtime Control

Message Flow

BitChat → MeshCore

MeshCore → BitChat

#mesh Channel

Channel Key Derivation

Known Limitations

Compatibility

Future Support for Display-Less Devices

Testers Wanted!

About MeshCore

🔍 What is MeshCore?

⚡ Key Features

🎯 What Can You Use MeshCore For?

🚀 How to Get Started

⚡️ MeshCore Flasher

📱 MeshCore Clients

🛠 Hardware Compatibility

📜 License

Contributing

Road-Map / To-Do

📞 Get Support

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages