Akita vMail - Meshtastic Voice Messenger

From Akita Engineering

Akita vMail sets the standard for reliable voice communication over Meshtastic networks.
This robust application enables sending and receiving short voice messages using a connected Meshtastic device.

Engineered for resilience, Akita vMail incorporates CRC32 checksums for data integrity and a basic Acknowledgement (ACK) system for enhanced reliability of chunked messages, ensuring your voice gets through even in challenging network conditions.

Settings are configurable via config.json.

Contact

• Email: info@akitaengineering.com

License

This software is licensed under the GNU General Public License v3.0 (GPLv3).
License file not included in this package.

Akita vMail - Meshtastic Voice Messenger

From Akita Engineering

Akita vMail is a desktop application for sending and receiving short voice
messages over Meshtastic networks. The project focuses on resilience and
observability: messages include CRC32 checks for integrity and a reliable ACK
scheme for chunked transfers over lossy links.

This repository contains the application code (under akita_vmail/),
configuration defaults, and a small test suite. The GUI uses Tkinter and the
core code is written for Python 3.8+ (tested on 3.10+ as well).

Recent changes

• Implemented ACK tracking and retransmit logic for chunked messages.
• Added ack_timeout_sec configuration and getters in protocol.py.
• Improved AudioHandler to auto-stop recordings and safely close streams.
• GUI now exposes simple metrics (pending ACKs / retransmit counts) in the
  status bar for observability.

See commit history for full details.

Quickstart (developer / local run)

1. Create and activate a virtual environment (recommended):

python -m venv .venv
.venv\\Scripts\\Activate.ps1

2. Install Python dependencies:

python -m pip install --upgrade pip
python -m pip install -r akita_vmail/requirements.txt

3. Ensure a directory exists for voice files (defaults to voice_messages):

mkdir voice_messages

4. (Optional) Edit config.json in the project root to change defaults.

5. Run the application from the repository root:

python -m akita_vmail.main
# or
python akita_vmail/main.py

Notes:

• On Windows, installing pyaudio may be easier via pipwin.
• Running the GUI headlessly (in CI) requires mocking audio and Meshtastic
  dependencies; the test suite already includes test-time fakes/mocks.

Configuration

Configuration defaults live in akita_vmail/utils.py as DEFAULT_CONFIG. A
local config.json (in repository root) will be merged recursively over the
defaults when present. Use get_config() to access the cached config at
runtime; call load_config() to force a reload.

Key config sections:

• meshtastic_port_num: default app port number used when sending data
• chunking: sizes, default key, retry_count, retry_delay_sec,
  ack_timeout_sec, and receive_timeout_sec
• audio: default quality keys and sampling rates, default recording length

Running Tests

Unit tests use pytest. To run tests locally:

python -m pytest tests/ -q

The test harness includes fakes/mocks for runtime-only modules so tests run
headlessly (no audio hardware or Meshtastic device required).

Project layout

• akita_vmail/ - application package
  • main.py - application entrypoint
  • gui.py - main Tkinter app (componentized)
  • audio_handler.py - audio recording/playback/compression
  • meshtastic_handler.py - Meshtastic interface and send/receive logic
  • protocol.py - message formats, CRC, chunk helpers (config-aware)
  • utils.py - config loader, logging helpers, small GUI utilities
  • style_helper.py and _panel.py files - UI components
• voice_messages/ - runtime recordings and received messages (created at runtime)
• requirements.txt - Python dependencies
• tests/ - unit tests

Troubleshooting

• If meshtastic or pyaudio imports fail, confirm they are installed in
  the active virtual environment.
• If the Meshtastic device is not found by serial, ensure the COM port is
  correct and accessible by the running user.
• The GUI intentionally uses explicit imports for components; a missing
  component file will produce an import error at startup so the problem is
  visible immediately.

Development notes

• Use the config argument when creating handlers in code to ensure
  configuration is explicit (e.g., AudioHandler(self.log, config)).
• Prefer the protocol getters (e.g., get_chunk_sizes(config)) to avoid
  relying on import-time constants.

License & Contact

This project is published by Akita Engineering and is licensed under the
GNU GPL v3 (see LICENSE in the repository root). For questions contact
info@akitaengineering.com.