CardMesh for MeshMonitor

Warning

CardMesh for MeshMonitor is under active development and not yet stable, features and config may still change. Give the repo a Star and Watch it to get notified when a new release lands.

CardMesh for MeshMonitor

Your pocket console for the mesh.

CardMesh is a keyboard-first pocket client for MeshMonitor, designed specifically for the M5Stack CardputerZero.

It provides a compact physical interface for accessing MeshMonitor channels, direct messages, nodes, sources, telemetry, and eventually field/deployment tools without requiring a direct connection between the CardputerZero and a Meshtastic radio.

MeshMonitor does the heavy lifting. CardMesh puts the mesh in your hand.

Project Status

Current status: Early development — v0.1.0 ships the Dashboard screen only
Latest release: v0.1.0
Repository: maxhayim/cardmeshformeshmonitor (public)

This repository is now public. The v0.1.0 .deb build has not been verified against real CardputerZero hardware or the official online emulator — see docs/DEVICE_BUILD.md for exactly what is and isn't confirmed before relying on it.

Licensing is MIT. See CONTRIBUTING.md for how to contribute and CODE_OF_CONDUCT.md / SECURITY.md for the rest of the project's community policies.

Product Name

Full Name: CardMesh for MeshMonitor
Short Name: CardMesh
Package Name: cardmesh
Executable: cardmesh
Target Platform: M5Stack CardputerZero
Backend: MeshMonitor REST API v1

Tagline

Your pocket console for the mesh.

Overview

CardMesh turns the CardputerZero into a dedicated portable console for MeshMonitor.

Instead of opening a phone, tablet, or laptop, a user should be able to pull out a CardputerZero and quickly:

Read channel messages
Send channel messages
Read direct messages
Send direct messages
View unread message counts
Browse mesh nodes
Search nodes
Inspect node details
View RSSI and SNR
View hop information
View battery and telemetry
Switch between MeshMonitor sources
Perform traceroutes
Monitor favorite nodes
Eventually perform field and deployment testing

The intended experience is closer to a:

radio control head
pager
BlackBerry
field terminal

than a miniature desktop website.

Architecture

CardMesh does not directly communicate with Meshtastic radios in the initial implementation.

Instead:

Meshtastic / MeshCore / MQTT
           │
           ▼
      MeshMonitor
           │
    REST API v1 / HTTPS
           │
           ▼
       CardMesh
           │
           ▼
    CardputerZero

MeshMonitor remains responsible for:

Radio connectivity
Meshtastic connectivity
MeshCore connectivity
MQTT connectivity
Message storage
Node databases
Telemetry
Traceroutes
Multiple sources
Network history
Server-side persistence

CardMesh acts as a lightweight remote client optimized specifically for the CardputerZero.

Core Design Principle

CardMesh should not attempt to reproduce the entire MeshMonitor web interface.

If MeshMonitor already performs a function well, CardMesh should consume that function rather than recreate it.

CardMesh focuses on:

Fast access
Keyboard navigation
Compact presentation
Field use
Messaging
Node monitoring
Multi-source access
Low-distraction operation

MeshMonitor API

CardMesh should use MeshMonitor's current source-scoped REST API.

Canonical API structure:

/api/v1/sources/{sourceId}/...

Source discovery:

GET /api/v1/sources

Examples:

GET /api/v1/sources/{sourceId}/nodes
GET /api/v1/sources/{sourceId}/messages
GET /api/v1/sources/{sourceId}/channels
GET /api/v1/sources/{sourceId}/telemetry
GET /api/v1/sources/{sourceId}/traceroutes
GET /api/v1/sources/{sourceId}/network
GET /api/v1/sources/{sourceId}/packets
GET /api/v1/sources/{sourceId}/status

CardMesh should discover available sources rather than hard-code the source ID default.

Authentication

MeshMonitor authentication should use an API token.

Requests should include:

Authorization: Bearer <API_TOKEN>

Initial CardMesh setup should request:

MeshMonitor Server
Port
HTTPS Enabled
API Token
Preferred Source

Example:

Server:
mesh.example.com

Port:
443

HTTPS:
YES

API Token:
********************************

The application should provide a Test Connection function before saving the configuration.

Recommended Technology Stack

The intended production stack is:

C++17
LVGL
CMake
libcurl
nlohmann/json
SQLite3
Debian ARM64 packaging
CardputerZero AppBuilder
GitHub Actions

Why C++ and LVGL?

Although CardputerZero runs Linux, CardMesh should behave more like a dedicated embedded application than a desktop program.

C++ and LVGL provide:

Fast startup
Low overhead
Predictable rendering
Responsive keyboard input
Small memory footprint
Minimal desktop dependencies
Good control of the 320×170 display
Alignment with the CardputerZero application ecosystem

A Python implementation may be useful for prototyping, but the intended production target is C++.

Target Display

CardputerZero display:

320 × 170

The interface should prioritize:

Text
Compact rows
Clear hierarchy
High contrast
Minimal animation
Readable fonts
Keyboard shortcuts
Fast navigation

Avoid:

Oversized buttons
Desktop-style menus
Heavy graphics
Complex maps
Large animations
Web layouts squeezed into the small screen

Development, Emulator Testing, and Release Upload Workflow

CardMesh development should use the official CardputerZero web tools as part of the normal build/test/release cycle.

Online Emulator

Primary browser-based emulator:

https://cardputer.cc/emulator/

The online emulator should be used throughout development to validate:

Application startup
320×170 layout
Keyboard-first navigation
Screen transitions
Text sizing and clipping
Dialogs and error states
Message composition UI
Node and channel lists
General usability before hardware testing

The emulator is an important development target, but it does not replace validation on a physical CardputerZero before a stable release.

Recommended loop:

Implement Feature
      ↓
Build CardMesh
      ↓
Test in CardputerZero Emulator
      ↓
Fix UI / Input / Runtime Issues
      ↓
Test on Physical CardputerZero
      ↓
Package Release .deb

CardputerZero Developer Center

Release packages will be uploaded through:

https://dev.cardputer.cc/

The CardputerZero Developer Center accepts Debian .deb application packages and is the intended submission path for CardMesh releases.

Expected release artifact:

cardmesh_<version>_arm64.deb

Example:

cardmesh_0.1.0_arm64.deb

The Developer Center uses GitHub authentication for package management and AppStore submission.

The repository is public as of v0.1.0, so the Developer Center's submission flow can clone it directly (its store-validation step does this to pull app-builder.json's store metadata) rather than relying solely on manually-uploaded .deb files.

Package Name

The intended Debian package name is:

cardmesh

The package name should be treated as permanent once CardMesh begins publishing through the CardputerZero Developer Center.

Before the first production upload, verify all Debian metadata consistently uses:

Package: cardmesh
Executable: cardmesh
Display Name: CardMesh
Architecture: arm64

Screenshots

AppStore screenshots should be captured at the CardputerZero native resolution:

320 × 170

The three below are the current Dashboard and Map screens, host-rendered at 320×170 from the real DashboardScreen/MapScreen code (tools/screenshot/) — not mockups, but also not captures from real CardputerZero hardware or the online emulator. The map is a real OpenStreetMap tile fetch (mock is only the node positions). See docs/DEVICE_BUILD.md for what that does and doesn't confirm.

Recommended screenshots for the first release:

Dashboard
Channels
Channel Chat
Nodes
Node Details
Sources

Required Development Cycle

The intended CardMesh workflow is:

GitHub Repository
maxhayim/cardmeshformeshmonitor
        ↓
Feature Branch
        ↓
Build + Automated Tests
        ↓
CardputerZero Online Emulator
cardputer.cc/emulator/
        ↓
Physical CardputerZero Testing
        ↓
Create ARM64 .deb
        ↓
GitHub Release / Release Candidate
        ↓
CardputerZero Developer Center
dev.cardputer.cc/
        ↓
AppStore Distribution

No stable CardMesh release should be considered complete until the release candidate has been tested in the emulator and, where available, on physical CardputerZero hardware.

Suggested Project Structure

cardmeshformeshmonitor/
│
├── .github/
│   ├── workflows/
│   │   ├── build.yml
│   │   ├── test.yml
│   │   └── release.yml
│   │
│   └── ISSUE_TEMPLATE/
│
├── src/
│   ├── main.cpp
│   │
│   ├── api/
│   │   ├── MeshMonitorClient.cpp
│   │   ├── MeshMonitorClient.h
│   │   ├── HttpClient.cpp
│   │   └── HttpClient.h
│   │
│   ├── models/
│   │   ├── Source.h
│   │   ├── Node.h
│   │   ├── Message.h
│   │   ├── Channel.h
│   │   ├── Telemetry.h
│   │   └── Traceroute.h
│   │
│   ├── storage/
│   │   ├── Database.cpp
│   │   ├── Database.h
│   │   ├── Settings.cpp
│   │   └── Settings.h
│   │
│   ├── sync/
│   │   ├── SyncManager.cpp
│   │   └── SyncManager.h
│   │
│   ├── input/
│   │   ├── Keyboard.cpp
│   │   └── Keyboard.h
│   │
│   └── ui/
│       ├── ScreenManager.cpp
│       ├── ScreenManager.h
│       ├── DashboardScreen.cpp
│       ├── SourcesScreen.cpp
│       ├── ChannelsScreen.cpp
│       ├── ChatScreen.cpp
│       ├── NodesScreen.cpp
│       ├── NodeDetailScreen.cpp
│       ├── DirectMessagesScreen.cpp
│       ├── TelemetryScreen.cpp
│       ├── FieldModeScreen.cpp
│       └── SettingsScreen.cpp
│
├── assets/
│   └── branding/
│       ├── logo.png
│       └── appicon.png
├── docs/
├── screenshots/
├── tests/
│
├── CMakeLists.txt
├── app-builder.json
├── .gitignore
├── README.md
└── CHANGELOG.md

Application Layers

CardMesh should maintain clean separation between:

UI
API
HTTP
Models
Storage
Configuration
Input
Synchronization

The UI should never perform raw HTTP requests directly.

Raw MeshMonitor JSON should not be parsed inside UI screens.

MeshMonitor Client

The application should expose a dedicated API client.

Conceptually:

meshMonitor.getSources();
meshMonitor.getNodes(sourceId);
meshMonitor.getChannels(sourceId);
meshMonitor.getMessages(sourceId);
meshMonitor.sendMessage(...);
meshMonitor.getTelemetry(...);
meshMonitor.requestTraceroute(...);

This abstraction should isolate the rest of CardMesh from changes in MeshMonitor's raw API structure.

Local Storage

MeshMonitor remains authoritative for mesh data.

SQLite should only store CardMesh-specific state and cache information.

Recommended database:

cardmesh.db

Possible tables:

settings
read_state
favorites
recent_nodes
cached_sources
cached_nodes
cached_channels
cached_messages
field_sessions
field_measurements

Configuration

Recommended path:

~/.config/cardmesh/config.json

Recommended permissions:

Example:

{
  "server": "mesh.example.com",
  "port": 443,
  "https": true,
  "token": "TOKEN",
  "preferredSource": "default"
}

Real credentials must never be committed to this repository.

Security

CardMesh may handle private mesh conversations and API credentials.

Requirements:

HTTPS support
TLS certificate verification enabled
API tokens never logged
API tokens never committed
Obscured token entry
Restricted configuration permissions
No analytics
No advertising
No developer-operated proxy
No external application telemetry
Direct communication with the user's configured MeshMonitor instance

First Launch

Proposed setup screen:

CARDMESH
for MeshMonitor

MeshMonitor Server
________________________

Port
443

HTTPS                  [X]

API Token
************************

[T] Test Connection

ENTER Save
ESC Cancel

Successful connection:

✓ CONNECTED

MeshMonitor found
5 sources available

ENTER Continue

Dashboard

Example:

┌──────────────────────────────┐
│ CARDMESH                 ●   │
├──────────────────────────────┤
│ SOURCE: Miami                │
│                              │
│ Nodes                  127   │
│ Active                  83   │
│ Channels                 8   │
│ Unread                   4   │
│                              │
│ [M] Messages                 │
│ [N] Nodes                    │
│ [D] Direct                   │
│ [S] Sources                  │
└──────────────────────────────┘

Connection indicators:

● Connected
○ Disconnected
↻ Connecting
! Error

Sources

Multi-source support should be implemented from the beginning.

Example:

SOURCES

> Miami Base          ●
  EOC                 ●
  Brickell            ●
  Lake Placid         ○
  MQTT Florida        ●

ENTER Select
R Refresh
ESC Back

CardMesh should remember the preferred source between launches.

Channels

Example:

CHANNELS

> Primary              2
  FloridaMesh           4
  SDGMRS                0
  LongFast              0
  Testing               1

↑↓ Select
ENTER Open
R Refresh

The number on the right represents the local unread count.

Channel Chat

Example:

FloridaMesh
──────────────────────────────

K4ABC 22:41
Testing Kendall node.

MRNODE 22:43
Copy from Tampa.

WXOP567 22:44
Testing CardMesh.

──────────────────────────────
> Message_

ENTER Send
ESC Back

Message states may include:

QUEUED
SENDING
SENT
ACK
FAILED

CardMesh should never display a message as acknowledged or delivered unless the available MeshMonitor data supports that state.

Nodes

Example:

NODES                     83

> MTEDC II          0h   NOW
  SDGMRS EOC        0h    2m
  Brickell          1h    4m
  Kendall Solar     2h   38m
  GAT562 MAX        0h   NOW

/ Search
F Favorite
ENTER Details

Potential sort options:

Last Heard
Name
Hop Count
RSSI
SNR
Favorite

Node Search

Press:

Example:

SEARCH NODES

> MTED

MTEDC I
MTEDC II
MTEDC Solar

ENTER Open
ESC Cancel

Search should operate against the locally cached node list rather than making an HTTP request for every keystroke.

Node Details

Example:

MTEDC II
──────────────────────────────

ID       !a13f829c
Status   ONLINE
Last     18 sec
Hops     DIRECT
RSSI     -87 dBm
SNR      +6.25 dB
Battery  92%
Voltage  4.12 V

[M] Message
[T] Telemetry
[R] Route
[F] Favorite

Unknown information should display:

--

Never fabricate unavailable values.

Direct Messages

Example:

DIRECT MESSAGES

> SDGMRS EOC             3
  K4ABC                  1
  Brickell               0
  MTEDC II               0

ENTER Open
N New
ESC Back

Unread Tracking

Unread state may initially be stored locally.

Store:

source_id
conversation_type
conversation_id
last_read_timestamp

Conversation types:

CHANNEL
DM

Basic logic:

message.timestamp > last_read_timestamp

This avoids requiring any modification to MeshMonitor itself.

Refresh Strategy

Initial implementation can use polling.

Suggested defaults:

Dashboard:    10 seconds
Active Chat:   3–5 seconds
Nodes:        10 seconds
Telemetry:    15–30 seconds
Background:   30 seconds

Incremental retrieval should be used whenever supported by MeshMonitor.

Avoid repeatedly downloading complete message history.

Offline Behavior

CardMesh should not crash when MeshMonitor becomes unreachable.

Example:

OFFLINE
Last sync 2m ago

Cached information should remain visible.

Users should still be able to browse:

Nodes
Channels
Previous messages
Favorites

Sending should initially be disabled while offline.

CANNOT SEND
MeshMonitor offline.

Offline message queueing is not part of the MVP.

Keyboard Controls

CardMesh should be highly keyboard-driven.

Currently implemented (v0.1.0)

Only Dashboard and Map exist so far, so this is a subset of the full plan below — note M currently means Map, not the planned Messages screen, since Messages doesn't exist yet. This will need reconciling once Messages is built.

Dashboard:
  R    Refresh
  M    Open Map
  Q    Quit

Map:
  Arrows  Pan
  +/-     Zoom
  B/Esc   Back to Dashboard
  Q       Quit

Full plan (not all implemented yet)

Possible global shortcuts:

M    Messages
N    Nodes
D    Direct Messages
S    Sources
H    Home
/    Search
R    Refresh
ESC  Back

Node details:

M    Message
T    Telemetry
R    Traceroute
F    Favorite

Keyboard shortcuts must be disabled or adjusted appropriately while the user is typing into a text field.

Error Handling

Avoid generic errors such as:

ERROR 7

Prefer descriptive messages.

Examples:

SERVER UNREACHABLE
Check Wi-Fi or server address.

AUTH FAILED
API token rejected.

SOURCE UNAVAILABLE
Selected MeshMonitor source is offline.

MESSAGE FAILED
MeshMonitor rejected transmission.

Background Architecture

Recommended logical structure:

UI THREAD
    │
    ├── LVGL rendering
    └── Keyboard input

NETWORK WORKER
    │
    ├── HTTP requests
    └── JSON parsing

SYNC MANAGER
    │
    ├── Messages
    ├── Nodes
    ├── Sources
    └── Telemetry

DATABASE
    │
    └── SQLite

Blocking HTTP calls should never execute directly inside the UI event loop.

Performance Goals

Initial targets:

Cold launch:        < 3 seconds where practical
Menu response:      < 100 ms
Keyboard response:  Immediate
Network requests:   Non-blocking UI
Idle CPU usage:     Low
Memory usage:       Comfortably within device limits

MVP — v0.1.0

The first usable version should include:

First-run setup
MeshMonitor server configuration
API token authentication
HTTPS
Connection testing
Source discovery
Source selection
Dashboard
Channels
Channel messages
Sending channel messages
Node list
Node search
Node details
Direct messages
Sending direct messages
Local unread tracking
Settings
Basic local cache
Network error handling
Automatic reconnect

MVP Acceptance Criteria

The MVP is successful when a user can:

Install CardMesh.
Open CardMesh.
Configure a MeshMonitor server.
Enter an API token.
Test the connection.
Discover MeshMonitor sources.
Select a source.
Browse channels.
Read channel messages.
Send a channel message.
Browse nodes.
Search nodes.
Inspect node information.
Browse direct conversations.
Send a direct message.
See unread indicators.
Restart without losing configuration.
Lose network connectivity without crashing.
Reconnect without restarting CardMesh.
Run correctly in the CardputerZero online emulator.
Render correctly at 320×170 without clipped critical controls or text.
Produce a valid ARM64 .deb package suitable for upload to the CardputerZero Developer Center.

MVP Non-Goals

Do not initially implement:

Direct BLE Meshtastic communication
Direct USB Meshtastic communication
Serial Meshtastic communication
Meshtastic protobuf stack
Firmware flashing
Radio configuration
Full maps
GPS navigation
VPN functionality
MeshMonitor administration
Complex historical charts
Multi-server aggregation
Full field testing

The core remote-client experience should be stable before advanced functions are added.

Roadmap

v0.1 — Core Client

Setup
Authentication
Source discovery
Channels
Messages
Nodes
Direct messages
Unread state
Local cache

v0.2 — Monitoring

Telemetry
Favorites
Node filtering
Packet information
Delivery state improvements
Better unread management

v0.3 — Radio Tools

Traceroute
Canned messages
Favorite-node dashboard
Node alerts
Source alerts

v0.4 — Field Mode

Deployment sessions
RSSI/SNR recording
Hop monitoring
Direct-vs-relayed statistics
Local field reports
Antenna comparison tools

v1.0 — Stable Release

Reliable daily operation
Mature reconnect handling
Robust caching
Stable API abstraction
Complete keyboard navigation
CardputerZero packaging
Documentation
Release automation
Stable upgrade process

Future: Telemetry

Example:

MTEDC II TELEMETRY

Battery
92%

Voltage
4.12 V

Temperature
34.2 C

Updated
18 sec ago

Historical data should initially favor compact statistics over graphs.

Example:

BATTERY 24H

Now      92%
Low      73%
High     100%

Future: Traceroute

Example:

TRACEROUTE

Target:
SDGMRS EOC

REQUESTING...

────────────

YOU
 │
 ▼
MTEDC II
 │
 ▼
SDGMRS EOC

2 HOPS

Future: Field Mode

Field Mode is intended to become one of CardMesh's primary CardputerZero-specific features.

Use cases:

Node deployment
Antenna testing
Site testing
Link validation
Field diagnostics

Example:

FIELD TEST
SDGMRS EOC

Last Heard       2 sec
RSSI             -83
SNR              +7.5
Hops             DIRECT

Packets          28
Direct           26
Relayed           2

[F1] Start
[F2] Route
[F3] Mark
[F4] Save

Future: Field Sessions

Possible session data:

session_id
start_time
end_time
selected_source
target_node
notes

Measurement data:

timestamp
node_id
rssi
snr
hop_count
last_heard
battery
voltage
latitude
longitude

Future: Antenna Comparison

Example:

ANTENNA TEST

5.8 dBi Omni
Packets      100
Direct        73%
RSSI Avg     -96
SNR Avg      +2.1

Yagi
Packets      100
Direct        96%
RSSI Avg     -81
SNR Avg      +7.8

IMPROVEMENT
RSSI         +15 dB

Future: Favorites

Example:

★ SDGMRS EOC
★ MTEDC II
★ Brickell

Favorites may eventually appear directly on the dashboard.

Future: Alerts

Potential alerts:

Favorite node online
Favorite node offline
Low battery
New direct message
Unread channel message
Source disconnected

Future: Canned Messages

Example:

1 Testing.
2 Copy.
3 Node online.
4 Testing antenna.
5 Please acknowledge.
6 Deployment complete.

Potential shortcuts:

ALT+1
ALT+2
ALT+3

MeshMonitor Virtual Node

MeshMonitor also provides a Virtual Node TCP interface.

CardMesh should not use Virtual Node for the initial implementation.

The REST API is preferred because it provides:

Authentication
Source discovery
Historical data
Node information
Telemetry
Multi-source support
MeshMonitor-specific metadata
Simpler client state management

Virtual Node may be explored later if a full Meshtastic-compatible protocol connection becomes useful.

Reference Concept

CardMesh is conceptually similar to MeshMonitor Chat for iOS by Andros, which demonstrates the usefulness of an independent client communicating with MeshMonitor instead of directly with a radio.

The architectural concept is:

Client
   │
REST API
   │
MeshMonitor
   │
Mesh Radio

CardMesh should independently implement this architecture specifically for CardputerZero.

GitHub Development Workflow

Canonical repository:

maxhayim/cardmeshformeshmonitor

Recommended workflow:

Issue / Idea
     ↓
Feature Branch
     ↓
Implementation
     ↓
Testing
     ↓
Pull Request
     ↓
Review
     ↓
Merge
     ↓
Release

Example feature branches:

feature/api-client
feature/setup-screen
feature/source-browser
feature/node-browser
feature/chat
feature/direct-messages
feature/unread-state
feature/telemetry
feature/field-mode

GitHub Actions

Future CI should perform:

Push / Pull Request
        ↓
Configure
        ↓
Compile
        ↓
Run Tests
        ↓
Cross-compile ARM64
        ↓
Produce Testable .deb

Development and release candidates should then be validated using:

Build Artifact
      ↓
CardputerZero Online Emulator
https://cardputer.cc/emulator/
      ↓
Physical CardputerZero

Tagged releases should eventually perform:

Git Tag
   ↓
Build ARM64 package
   ↓
Create SHA256
   ↓
Create GitHub Release
   ↓
Attach .deb
   ↓
Upload approved .deb to
https://dev.cardputer.cc/

Example:

v0.1.0

Artifact:

cardmesh_0.1.0_arm64.deb

The Developer Center upload should remain a deliberate release step after validation rather than automatically publishing every CI build.

Testing

Unit tests should cover:

API URL construction
Source parsing
Node parsing
Channel parsing
Message parsing
Timestamp parsing
Configuration loading
Configuration validation
Unread calculation

Integration testing should include:

200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
429 Too Many Requests
500 Server Error
Timeout
Connection refused
Invalid JSON
Empty result
Missing optional fields

Mock Development Mode

A mock API mode would allow UI development without requiring a live MeshMonitor server.

Example:

CARDMESH_MOCK=1

Suggested mock data:

5 Sources
100 Nodes
8 Channels
300 Messages
10 Direct Conversations
Telemetry
Online Nodes
Offline Nodes
Missing RSSI
Missing SNR
Missing Battery Data

Logging

Recommended log location:

~/.local/state/cardmesh/cardmesh.log

Levels:

ERROR
WARN
INFO
DEBUG

Never log:

API Tokens
Passwords
Private Credentials
Channel Keys

`.gitignore`

At minimum:

build/
dist/
*.deb
*.log

.env
.env.*
*.token

config.json
credentials.*

cardmesh.db

Real MeshMonitor credentials and private configuration must never be committed.

Development Order

Phase 1 — Application Skeleton

CardputerZero build environment
CMake
LVGL
Keyboard input
Navigation
Placeholder screens

Phase 2 — HTTP and API

HttpClient
MeshMonitorClient
HTTPS
Bearer authentication
Errors
Timeouts

Phase 3 — Setup

Server
Port
HTTPS
Token
Test connection
Persistence

Phase 4 — Sources

Retrieve sources
Select source
Remember source

Phase 5 — Nodes

Retrieve nodes
Node list
Search
Details

Phase 6 — Channels

Retrieve channels
Display channels

Phase 7 — Messaging

Retrieve messages
Render conversations
Compose messages
Send messages

Phase 8 — Direct Messages

Conversation list
New DM
Send DM

Phase 9 — Persistence

SQLite
Cache
Unread state
Favorites framework

Phase 10 — Hardening

Reconnect
Authentication failures
Network failures
Malformed responses
Empty states
API compatibility

Phase 11 — CI, Emulator Testing, and Packaging

GitHub Actions
Automated tests
ARM64 build
Generate .deb
Test release candidate in https://cardputer.cc/emulator/
Test on physical CardputerZero where available
Create GitHub release artifact
Upload approved release .deb through https://dev.cardputer.cc/

Notes for AI Coding Assistants

When using Claude, ChatGPT, Codex, or another coding assistant on this repository:

Inspect the repository before modifying it.
Treat this README and current repository structure as the working specification.
Verify current MeshMonitor API behavior before assuming endpoint response formats.
Verify current CardputerZero development requirements.
Keep networking outside the UI layer.
Keep MeshMonitor API logic behind MeshMonitorClient.
Keep raw HTTP inside HttpClient.
Do not parse API JSON inside UI screens.
Keep the UI responsive during network operations.
Optimize specifically for the 320×170 display.
Assume physical keyboard operation.
Do not commit credentials.
Keep the project buildable after major changes.
Add tests for API parsing and state logic.
Do not implement direct Meshtastic radio support unless the project architecture is intentionally changed.
Treat https://cardputer.cc/emulator/ as the primary browser-based CardputerZero UI/runtime test environment.
Validate release candidates in the online emulator before packaging them as stable releases.
Build release packages as ARM64 Debian .deb files.
Use https://dev.cardputer.cc/ as the CardputerZero release-upload and AppStore submission portal.
The GitHub repository is public as of v0.1.0; the Developer Center's submission flow clones it directly to pull app-builder.json's store metadata.

Initial Development Objective

The first major milestone is:

Build a working CardputerZero application that authenticates with MeshMonitor, discovers sources, allows source selection, displays channels, messages and nodes, and reliably sends both channel and direct messages.

Advanced field tools should not be developed until this core functionality is reliable.

Final Product Definition

CardMesh for MeshMonitor is a fast, keyboard-first pocket client and field console for MeshMonitor built specifically for the M5Stack CardputerZero.

Core architecture:

CardMesh
   │
HTTPS REST API
   │
MeshMonitor
   │
Meshtastic / MeshCore / MQTT

Development repository:

maxhayim/cardmeshformeshmonitor

Package:

cardmesh

Future release artifact:

cardmesh_<version>_arm64.deb

Core Philosophy

MeshMonitor does the heavy lifting. CardMesh puts the mesh in your hand.

License

This project is licensed under the MIT License.

See the LICENSE file for details.
Full license text: https://opensource.org/licenses/MIT

Contributing

Pull requests are welcome. Open an issue first to discuss ideas or report bugs.

Acknowledgments

MeshMonitor built by Yeraze

Discover other Community Add-ons for MeshMonitor: https://meshmonitor.org/add-ons/

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
assets/branding		assets/branding
docs		docs
screenshots		screenshots
scripts		scripts
src		src
tests		tests
third_party		third_party
tools		tools
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CMakeLists.txt		CMakeLists.txt
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
app-builder.json		app-builder.json

Latest commit

History

Folders and files

Repository files navigation

CardMesh for MeshMonitor

Project Status

Product Name

Tagline

Overview

Architecture

Core Design Principle

MeshMonitor API

Authentication

Recommended Technology Stack

Why C++ and LVGL?

Target Display

Development, Emulator Testing, and Release Upload Workflow

Online Emulator

CardputerZero Developer Center

Package Name

Screenshots

Required Development Cycle

Suggested Project Structure

Application Layers

MeshMonitor Client

Local Storage

Configuration

Security

First Launch

Dashboard

Sources

Channels

Channel Chat

Nodes

Node Search

Node Details

Direct Messages

Unread Tracking

Refresh Strategy

Offline Behavior

Keyboard Controls

Currently implemented (v0.1.0)

Full plan (not all implemented yet)

Error Handling

Background Architecture

Performance Goals

MVP — v0.1.0

MVP Acceptance Criteria

MVP Non-Goals

Roadmap

v0.1 — Core Client

v0.2 — Monitoring

v0.3 — Radio Tools

v0.4 — Field Mode

v1.0 — Stable Release

Future: Telemetry

Future: Traceroute

Future: Field Mode

Future: Field Sessions

Future: Antenna Comparison

Future: Favorites

Future: Alerts

Future: Canned Messages

MeshMonitor Virtual Node

Reference Concept

GitHub Development Workflow

GitHub Actions

Testing

Mock Development Mode

Logging

.gitignore

Development Order

Phase 1 — Application Skeleton

Phase 2 — HTTP and API

Phase 3 — Setup

Phase 4 — Sources

Phase 5 — Nodes

Phase 6 — Channels

Phase 7 — Messaging

Phase 8 — Direct Messages

`.gitignore`