ardop_interface/

lib.rs

//! An Async Rust interface to the ARDOP TNC
//!
//! [Documentation](https://docs.rs/ardop_interface) |
//! [Crate](https://crates.io/crates/ardop_interface) |
//! [Git](https://github.com/cbs228/ardop_interface)
//!
//! # Introduction
//!
//! `ardop_interface` integrates with the Amateur Radio Digital
//! Open Protocol ([ARDOP](https://ardop.groups.io/g/main)) soundcard
//! modem softare. The ARDOP modem is intended to provide reliable,
//! low-speed connectivity over High Frequency (HF) radio links.
//!
//! *This crate is not ARDOP.* This crate is only an interface. With
//! this interface, and separate ARDOP modem software, you can build
//! full-featured Rust applications that communicate over the radio.
//!
//! # Minimal Example
//!
//! ```no_run
//! use std::net::SocketAddr;
//! use async_std::task;
//! use futures::prelude::*;
//!
//! use ardop_interface::tnc::*;
//!
//! fn main() {
//!    task::block_on(async {
//!         let addr = "127.0.0.1:8515".parse().unwrap();
//!         let mut tnc = ArdopTnc::new(&addr, "MYC4LL")
//!             .await
//!             .unwrap();
//!         let mut conn = tnc.connect("T4GET", 500, false, 3)
//!             .await
//!             .expect("TNC failure")
//!             .expect("Connection failed");
//!         conn.write_all(b"Hello, world!\n").await.unwrap();
//!         conn.close().await;
//!    })
//! }
//! ```
//!
//! See the
//! [`examples/`](https://github.com/cbs228/ardop_interface/tree/master/examples)
//! directory in the source code repository for a complete client
//! and server. The examples also demonstrate the `async_std` crate,
//! argument parsing, and logging.
//!
//! # The ARDOP Modem
//!
//! Like most amateur radio modems, ARDOP is designed to interface
//! with analog, single-sideband (SSB) transceivers via a sound
//! card interface. A computer—which may be a simple, single-board
//! computer—turns data into sound, and back again.
//!
//! ARDOP is designed to:
//!
//! * Automatically retry failed transmissions. This mode of
//!   operation is called *automatic repeat request* (ARQ),
//!   and it helps ensure that data reaches its final destination.
//!
//! * Use the fastest available mode for the signal-to-noise ratio
//!   and band conditions
//!
//! * Support unattended, automatic station operation
//!
//! * Perform well on the high frequency (HF) bands
//!
//! Best of all, ARDOP has an open development model. Full protocol
//! specifications are available, and open-source implementations of
//! the modem exist.
//!
//! ARDOP is intended for use by licensed radio amateurs. If you'd
//! like to get started with the hobby, you should find a club,
//! "hamfest," or "hamvention" near you!
//!
//! # The Rust Interface
//!
//! The ARDOP software has a standardized "terminal node controller"
//! (TNC) interface for clients to use. To use the TNC, clients must
//! make two simultaneous TCP connections and perform a great deal
//! of serialization and de-serialization. This crate handles many
//! of these details for you.
//!
//! This crate exposes an `async` API that many rustaceans will
//! find familiar: socket programming. The
//! [`ArqStream`](arq/index.html) object is designed
//! to mimic an async `TcpStream`. Once a connection is made,
//! data is exchanged with asynchronous reads from, and writes to,
//! the `ArqStream` object.
//!
//! The `async` API allows ARDOP to coexist with native TCP sockets,
//! GUIs, and other I/O processes while maintaining a small system
//! resource footprint.
//!
//! # Development Status
//!
//! This crate is experimental. Its API will not stabilize until
//! `ardop_interface` can be built without `unstable` features of
//! [`async_std`](https://docs.rs/async-std/).
//!
//! # Prerequisites
//!
//! Rust 1.40 or later is required.
//!
//! Obtain a compatible implementation of ARDOP. You must use
//! ARDOP software which implements protocol **version one**.
//! The ARDOP v2 specification has been withdrawn by its authors, and
//! version three is presently in development. The TNC interface on
//! which this crate depends can change during major releases.
//!
//! These instructions assume the use of John Wiseman's `ardopc`, version 1.
//! Other implementations will probably work, but this crate has not
//! been tested against them. You may be able to obtain this software at
//! <http://www.cantab.net/users/john.wiseman/Downloads/Beta/TeensyProjects.zip>
//! or from the ARDOP [forums](https://ardop.groups.io/g/users/topics).
//!
//! You will need your system's C/C++ compiler in order to build `ardopc`.
//! Debian-based distributions can install these with:
//!
//! ```bash
//! sudo apt-get install build-essential
//! ```
//!
//! Unpack the archive, `cd` into the `ARDOPC` subdirectory, and
//! run `make` to build the software. There is also a Visual Studio
//! project for Windows users. Alternatively, binary builds may be
//! available in
//! <http://www.cantab.net/users/john.wiseman/Downloads/Beta/>.
//!
//! You should now be able to invoke ARDOP as
//!
//! ```bash
//! ./ardopc PORT INDEV OUTDEV
//! ```
//!
//! where
//! * `PORT` is the desired TCP control port (typically `8515`)
//! * `INDEV` is the ALSA device name for your "`line in`"
//!   soundcard port. If your system has pulseaudio, you may use
//!   it with the `pulse` device.
//! * `OUTDEV` is the ALSA device name for your "`line out`"
//!   soundcard port. If your system has pulseaudio, you may use
//!   it with the `pulse` device.
//!
//! # Running the Examples
//!
//! The examples are not published to `crates.io.` You will need
//! to clone our source repository instead:
//!
//! ```bash
//! git clone https://github.com/cbs228/ardop_interface.git
//! ```
//!
//! To conduct a local test of ARDOP, you must run two instances
//! of the ARDOP modem. To make an acoustic channel between the
//! two the modems, place your microphone in close proximity to
//! your speakers. Alternatively, on linux, you may also use the
//! PulseAudio null sink:
//!
//! ```bash
//! pacmd load-module module-null-sink sink_name=Virtual1
//! pacmd set-default-sink Virtual1
//! pacmd set-default-source Virtual1.monitor
//! ```
//!
//! `ardopc` was designed for the ALSA sound APIs. Performance
//! may be degraded when running with pulseaudio. On some systems,
//! it may help to keep the pulseaudio volume control
//! (`pavucontrol`) program open while ardopc is running.
//!
//! Start two instances of ardopc
//!
//! ```bash
//! ./ardopc 8515 pulse pulse &
//! ./ardopc 8520 pulse pulse &
//! ```
//!
//! Build and run the `echoserver` package with
//!
//! ```bash
//! cargo run --package echoserver -- localhost:8515 MYCALL-S 200
//! ```
//!
//! Replace `MYCALL` with your callsign. The `-S` is a
//! Service Set Identifier (SSID), which is an arbitrary
//! single-character extension to your callsign.
//!
//! Now run the `echoclient` with
//!
//! ```bash
//! cargo run --package echoclient -- localhost:8520 MYCALL-C MYCALL-S 200
//! ```
//!
//! The `echoclient` will send a number of pre-programmed
//! text stanzas to the `echoserver`, which will parrot them
//! back. Both the client and server will print their progress
//! to stderr. The demo succeeds if the client prints
//!
//! ```txt
//! Echo server echoed all stanzas correctly.
//! ```
//!
//! You can also use the `echoserver` interactively via a
//! line-oriented chat program, like `ARIM`.
//!
//! When you are finished, remove the null sink if you are
//! using it.
//!
//! ```bash
//! pacmd unload-module module-null-sink
//! ```
//!
//! # Unsupported ARDOP Features
//!
//! At present, this crate only supports the ARDOP `ARQ`
//! connection-oriented protocol, which is TCP-like. ARDOP also
//! has a connectionless `FEC` protocol, which is UDP-like.
//! `ardop_interface` does not currently support FEC mode.
//!
//! The following other features are currently not implemented
//! by this crate.
//!
//! * **Rig control**: No type of rig control is presently
//!   integrated. This crate cannot provide the following
//!   functionality, at present.
//!
//!   * **Tuning**: `ardop_interface` knows nothing about your rig
//!     and cannot adjust its frequency or mode.
//!
//!   * **Keying**: This crate does not key your radio's PTT.
//!     The ARDOP TNC may be able to do this for you. `ardopc` can
//!     key transmitters over a serial connection.
//!
//!   * **Scanning**: The ARDOP frequency agility / scanning functions
//!     in `LISTEN` mode are not supported
//!
//! # Next Steps
//!
//! What sorts of protocols would you like to see on the air?
//! With a reliable, TCP-like link between stations, the
//! ionosphere is the limit!
//!
//! # Further Reading
//!
//! * [`tnc`](tnc/index.html): Main TNC command and control via the
//!   `ArdopTnc`
//! * [`arq`](arq/index.html): Reliable ARQ connections with
//!   `ArqStream`

#![recursion_limit = "128"]
#[allow(unused_imports)]
extern crate async_std;
#[macro_use]
extern crate custom_derive;
#[macro_use]
extern crate enum_derive;
#[allow(unused_imports)]
#[macro_use]
extern crate nom;
extern crate bytes;
#[macro_use]
extern crate futures;
extern crate futures_codec;
#[macro_use]
extern crate lazy_static;
#[macro_use]
extern crate log;
extern crate num;
extern crate regex;

pub mod arq;
pub mod tnc;

mod framing;
mod protocol;
mod tncio;