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

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