code.octet-stream.net Git - m17rt/blob - README.TXT

   1 ==================
   2  M17 RUST TOOLKIT
   3 ==================
   4
   5 As of Dec 2024 this software is still under active development. The description that follows is not fully implemented yet.
   6
   7 M17RT is a collection of Rust crates and utilities to make it as easy to possible to implement programs that use the M17
   8 Protocol for amateur radio: <https://m17foundation.org/projects/>.
   9
  10
  11                         ┌──────────────────────────────────────┐   <.
  12                    .>   │ m17app                               │    | Fan in data from adapters to TNC
  13  High level API    |    │ - High-level API for packets/streams │    | Fan out data from radio to adapters
  14  For PC-based apps |    │ - Sound card integration             │   <.
  15                    |    │ - TCP client/server KISS             │         vv KISS ^^
  16                    .>   │ - Multithreading                     │   <.
  17                         └──────────────────────────────────────┘    | Soundmodem worker thread:
  18                                                                     | Takes a sound card, PTT,
  19                         ┌──────────────────────────────────────┐    | assembles the components
  20                    .>   │ m17core                              │    | from m17core and puts it
  21  Low level API     |    │ - M17 KISS protocol                  │    | behind a KISS interface.
  22  no_std, no heap   |    │ - TNC / CSMA                         │    |
  23  could be no-float |    │ - M17 Data Link                      │    |
  24                    .>   │ - Baseband Modem                     │   <.
  25                         └──────────────────────────────────────┘
  26
  27
  28 When you are writing an M17 packet or voice application you will target the high-level API and not concern yourself with
  29 what kind of TNC will ultimately be used. It is modular - you could use a serial KISS modem, a TCP KISS service running
  30 on another host or supplied by another program, or engage the built-in soundmodem by supplying a soundcard and PTT config.
  31 This could be configured at runtime in your program.
  32
  33 Equally, the soundmodem can also be used as an independent module with any other M17 application that expects to speak to
  34 a KISS TNC, including M17 applications that do not use this toolkit or are not written in Rust.
  35
  36 The basic structure of a program is that you will configure your TNC, use it to initialise an M17App, then add adapters to
  37 the M17App which will handle all or a subset of the traffic. They will all share the same TNC.
  38
  39 Codec2 support follows the same pattern - the m17codec2 crate will provide standard M17App stream adapters to handle both:
  40     mic -> encode -> transmit stream
  41     incoming stream -> decode -> output on sound card
  42
  43 Splitting this into a separate crate serves two purposes. This reduces the dependency count if your app does not actually
  44 use codec2. It also means you can avoid statically linking LGPL code into your Rust binary if you are relying on M17RT's
  45 permissive licence. In this situation you can probably still find a way to use codec2 but it's not going to be as simple
  46 as putting this in your Cargo.toml since Rust makes dynamic linking difficult.
  47
  48 Finally, there will be a series of utility binaries for modulation, demodulation, creating a KISS TCP server, etc. These
  49 may be useful in their own right but their primary purpose is to test and demonstrate the toolkit. User-facing programs
  50 should be their own projects that will provide proper attention to detail for their use cases.
  51
  52 =========
  53  LICENCE
  54 =========
  55
  56 Copyright 2024 Thomas Karpiniec <tom.karpiniec@outlook.com>
  57
  58 M17 Rust Toolkit is made available under the MIT Licence. See LICENCE.TXT for details.