Skip to content
snettingPublic

About

Offline-first radio mail over JS8Call: reliable messaging with local storage, evidence-based routing, relays, custodians, multipart recovery, and capability-aware delivery; designed for resilient communications when Internet access is unavailable.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

45 Commits

Folders and files

Repository files navigation

JS8Mail

Reliable offline-first radio mail above an unmodified JS8Call instance.

JS8Mail is intended for dependable comms when Internet access is unavailable, including emergency and disaster scenarios. It keeps the mailbox, observations, routing decisions, retries, and audit history locally, then uses JS8Call for the actual RF modem and transmission. A message can be sent direct, relayed through stations suggested by observed RF evidence, or stored with a custodian for later collection.

Long messages are split into numbered JS8Mail parts for compatible peers. The receiver displays a useful partial message, marks missing parts, and can request only those parts again. Duplicate parts and receipts are safely ignored. A standard JS8Call recipient still receives readable ordinary text; enhanced JS8Mail framing is used only after the peer capability exchange proves support.

When an enhanced client later collects a message from a custodian, it can return a rate-limited JS8Mail capability and delivery-control notification toward the original sender using the recorded reverse path when available. These automatic exchanges are shown separately in the Outbox and are not themselves final delivery proof.

The project is early development and experimental. Delivery status is therefore carefully qualified: submission to JS8Call, a hop acknowledgement, custodian storage, and end-to-end JS8Mail delivery are different facts. Routing is progressive: a short direct reachability probe comes first, then current RF evidence, selective path discovery, alternative routes, bounded retries, and time-aware backoff. An optional, separate JS8Mail route-hints service can enhance local decisions with short-lived band-scoped reports from other stations. It is enabled by default and can be switched off in the UI. It never carries message content and is never required for RF operation.

See the changelog for release notes, including the current 0.1.1 outbox, custody-route, scheduler, stored-message collection, and network route-hints safeguards.

Each Outbox row has an Open action for the complete sent or in-progress message. The detail view includes its full subject and body, priority, sending mode, delivery evidence, timestamps, retry state, attempted routes, radio outcomes, and recent delivery history. View route graph closes the detail view and jumps directly to that message's graph.

First start (recommended)

Python 3.12 or newer is required.

From the repository directory, run:

./js8mail

The launcher creates or repairs the local .venv and asks before installing the JS8Mail runtime. It then checks the usual JS8Call API endpoint and starts the daemon with sensible defaults: automatic RF handoff, API 127.0.0.1:2442, and web UI http://127.0.0.1:8765. Open that address in a browser. If JS8Call is not running or its API is not enabled, the launcher gives setup guidance; the daemon still starts and will reconnect when JS8Call becomes available.

Useful launcher commands:

./js8mail --check-only       # validate Python, the environment, and API access
./js8mail --yes              # allow first-run installation without prompting
./js8mail --tx-mode observe  # receive/observe only; no RF handoff
./js8mail --no-install       # never create or modify the local environment

To make the command available from anywhere, optionally put a symlink to this checkout's js8mail script in a directory on your PATH, such as ~/bin.

For development and tests, install the extra test dependencies explicitly:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[test]'
pytest

The local mailbox can also be started directly with explicit options:

./js8mail --host 127.0.0.1 --port 2442 --ui-port 8765 --tx-mode automatic

Network-assisted route discovery uses the JS8Mail route-hints service by default. It can be switched off in the web UI, or pointed at another service with --route-hints-url; the client remains usable if the service is unavailable:

./js8mail --route-hints-url http://js8mail.oh3spn.fi:8787

The web UI provides the final on/off switch. Route hints are advisory, band-scoped, short-lived evidence used to wake discovery; they are not proof of a usable route or delivery. No personal messages, mailbox contents, message identifiers, or delivery receipts are shared—only short-lived observations about heard stations and observed paths. Useful local claims are published every 10 minutes. Network-only paths in an outgoing-message graph are shown as purple dashed NET edges; local RF evidence takes priority.

Automatic submission hands text to JS8Call; the UI reports only delivery evidence actually observed. JS8Mail is suitable for supervised on-air use. The code is still at an early stage, so operators should monitor transmissions, use sensible power and radio settings and be ready to pause automation if anything behaves unexpectedly. Extensive testing has not revealed unexpected transmit loops, but future changes or unforeseen glitches cannot be guaranteed. Follow local licensing and band-plan rules.

JS8Call setup: enable its documented local TCP/JSON API on loopback (normally port 2442), ensure JS8Call has the correct audio input/output devices, and enable the heartbeat, relay, inbox/store-and-forward, and decode facilities you want to use. JS8Mail does not edit unknown JS8Call configuration files; the UI should be treated as setup guidance and the operator remains in control of RF transmission. Intermediate stations may not have these facilities, so the routing logic degrades to the strongest standard JS8Call behavior available. For unattended operation, first confirm that it is permitted by your local licence conditions and band plan. Always observe those conditions. If permitted, disable JS8Call's operator-idle timeout (also called My Station Idle Time or, in some builds, TxIdleWatchdog) and operating-system suspend on AC power; TCP polling cannot reset that JS8Call safety timer.

Linux is the current development platform. A portable Windows bundle can be built with PyInstaller on Windows; users of that bundle do not need to install Python or manage a virtual environment. See builds/README.md and the Windows bundle GitHub Actions workflow. The workflow produces a downloadable JS8Mail.exe artifact using the standard API and web UI ports. Windows packaging is experimental and not yet validated end-to-end with Windows JS8Call, audio devices, or a radio.

For the complete operator guide—including JS8Call setup, TCP/API configuration, the end-to-end message lifecycle, path discovery, route scoring, custody, multipart recovery, groups, airtime protection, and troubleshooting—see the JS8Mail user and operator guide.

Also see the versioned JS8Mail protocol specification, the API capability matrix, and docs/IMPLEMENTATION_PLAN.md for protocol, compatibility, and staged implementation boundaries.

About

Offline-first radio mail over JS8Call: reliable messaging with local storage, evidence-based routing, relays, custodians, multipart recovery, and capability-aware delivery; designed for resilient communications when Internet access is unavailable.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages