Update READMEs with API changes

diff --git a/m17app/README.md b/m17app/README.md
index d6b548c4939446ad7db9cb996cef3a23583b42f7..30a6138b5e991b5b5635452567aab50d283f8c39 100644 (file)
--- a/m17app/README.md
+++ b/m17app/README.md
@@ -6,17 +6,18 @@ Part of the [M17 Rust Toolkit](https://octet-stream.net/p/m17rt/). This crate pr
 
 ## Creating an `M17App`
 
 
 ## Creating an `M17App`
 

-The most important type is `M17App`. This is what your program can use to transmit packets and streams, or to subscribe to incoming packets and streams. To create an `M17App` you must provide it with a TNC, which is any type that implements the trait `Tnc`. This could be a `TcpStream` to another TNC device exposed to the network or it could be an instance of the built-in `Soundmodem`.
+The most important type is `M17App`. This is what your program can use to transmit packets and streams, or to subscribe to incoming packets and streams. To create an `M17App` you must provide it with a TNC, which is any type that implements the trait `Tnc`. This could be a `TcpStream` to another TNC device exposed to the network or it could be an instance of the built-in `Soundmodem`. To connect to reflector like `mrefd` you can use the provided `ReflectorClientTnc`.

 
 ## Creating a `Soundmodem`
 
 A `Soundmodem` can use soundcards in your computer to send and receive M17 baseband signals via a radio. More generally it can accept input samples from any compatible source, and provide output samples to any compatible sink, and it will coordinate the modem and TNC in realtime in a background thread.
 
 
 ## Creating a `Soundmodem`
 
 A `Soundmodem` can use soundcards in your computer to send and receive M17 baseband signals via a radio. More generally it can accept input samples from any compatible source, and provide output samples to any compatible sink, and it will coordinate the modem and TNC in realtime in a background thread.
 

-A `Soundmodem` requires three parameters:
+A `Soundmodem` requires four parameters:

 
 * **Input source** - the signal we are receiving
 * **Output sink** - somewhere to send the modulated signal we want to transmit
 * **PTT** - a transmit switch that can be turned on or off
 
 * **Input source** - the signal we are receiving
 * **Output sink** - somewhere to send the modulated signal we want to transmit
 * **PTT** - a transmit switch that can be turned on or off

+* **Error handler** - a callback that tells you if problems occur during operation

 
 These are all traits that you can implement yourself but you can probably use one of the types already included in `m17app`.
 
 
 These are all traits that you can implement yourself but you can probably use one of the types already included in `m17app`.
 


@@ -38,14 +39,20 @@ Provided PTTs:
 * `SerialPtt` - Use a serial/COM port with either the RTS or DTR pin to activate PTT.
 * `NullPtt` - Fake device that will not control any real PTT.
 
 * `SerialPtt` - Use a serial/COM port with either the RTS or DTR pin to activate PTT.
 * `NullPtt` - Fake device that will not control any real PTT.
 

+Provided error handlers:
+
+* `StdoutErrorHandler` - Basic handler that will print events as they occur.
+* `LogErrorHandler` - Uses the common `log` facility to record the event at DEBUG level.
+* `NullErrorHandler` - Ignore errors.
+

 For `Soundcard` you will need to identify the soundcard by a string name. The format of this card name is specific to the audio library used (`cpal`). Use `Soundcard::supported_input_cards()` and `Soundcard::supported_output_cards()` to list compatible devices. The bundled utility `m17rt-soundcards` may be useful. Similarly, `SerialPtt::available_ports()` lists the available serial ports.
 
 If you're using a Digirig on a Linux PC, M17 setup might look like this:
 
 ```rust,ignore
     let soundcard = Soundcard::new("plughw:CARD=Device,DEV=0").unwrap();
 For `Soundcard` you will need to identify the soundcard by a string name. The format of this card name is specific to the audio library used (`cpal`). Use `Soundcard::supported_input_cards()` and `Soundcard::supported_output_cards()` to list compatible devices. The bundled utility `m17rt-soundcards` may be useful. Similarly, `SerialPtt::available_ports()` lists the available serial ports.
 
 If you're using a Digirig on a Linux PC, M17 setup might look like this:
 
 ```rust,ignore
     let soundcard = Soundcard::new("plughw:CARD=Device,DEV=0").unwrap();

-    let ptt = SerialPtt::new("/dev/ttyUSB0", PttPin::Rts);
-    let soundmodem = Soundmodem::new(soundcard.input(), soundcard.output(), ptt);
+    let ptt = SerialPtt::new("/dev/ttyUSB0", PttPin::Rts).unwrap();
+    let soundmodem = Soundmodem::new(soundcard.input(), soundcard.output(), ptt, StdoutErrorHandler);

     let app = M17App::new(soundmodem);
     app.start();
 ```
     let app = M17App::new(soundmodem);
     app.start();
 ```


@@ -70,7 +77,8 @@ Transmissions are made via a `TxHandle`, which you can create by calling `app.tx
 ```rust,ignore
     let payload = b"Hello, world!";
     app.tx()
 ```rust,ignore
     let payload = b"Hello, world!";
     app.tx()

-        .transmit_packet(&link_setup, PacketType::Sms, payload);
+        .transmit_packet(&link_setup, PacketType::Sms, payload)
+        .unwrap();

 ```
 
 Next let's see how to receive a packet. To subscribe to incoming packets you need to provide a subscriber that implements the trait `PacketAdapter`. This includes a number of lifecycle methods which are optional to implement. In this case we will handle `packet_received` and print a summary of the received packet and its contents to stdout.
 ```
 
 Next let's see how to receive a packet. To subscribe to incoming packets you need to provide a subscriber that implements the trait `PacketAdapter`. This includes a number of lifecycle methods which are optional to implement. In this case we will handle `packet_received` and print a summary of the received packet and its contents to stdout.


@@ -95,7 +103,7 @@ impl PacketAdapter for PacketPrinter {
 We instantiate one of these subscribers and provide it to our instance of `M17App`.
 
 ```rust,ignore
 We instantiate one of these subscribers and provide it to our instance of `M17App`.
 
 ```rust,ignore

-    app.add_packet_adapter(PacketPrinter);
+    app.add_packet_adapter(PacketPrinter).unwrap();

 ```
 
 Note that if the adapter also implemented `adapter_registered`, then it would receive a copy of `TxHandle`. This allows you to create self-contained adapter implementations that can both transmit and receive.
 ```
 
 Note that if the adapter also implemented `adapter_registered`, then it would receive a copy of `TxHandle`. This allows you to create self-contained adapter implementations that can both transmit and receive.


@@ -111,7 +119,23 @@ For our first example, let's see how to use the `m17codec2` helper crate to send
 The following line will register an adapter that monitors incoming M17 streams, attempts to decode the Codec2, and play the decoded audio on the default system sound card.
 
 ```rust,ignore
 The following line will register an adapter that monitors incoming M17 streams, attempts to decode the Codec2, and play the decoded audio on the default system sound card.
 
 ```rust,ignore

-    app.add_stream_adapter(Codec2Adapter::new());
+    // optionally call set_output_card(...) on the adapter
+    app.add_stream_adapter(Codec2RxAdapter::new()).unwrap();
+```
+
+This is how you set up to transmit Codec2 audio:
+
+```rust,ignore
+    // optionally call set_input_card(...) on the adapter
+    let mut tx = Codec2TxAdapter::new(args.callsign.clone(), reflector);
+    let ptt = tx.ptt();
+    app.add_stream_adapter(tx).unwrap();
+```
+
+Later, after you have called `start()`:
+
+```rust,ignore
+    ptt.set_ptt(true);

 ```
 
 This is how to transmit a wave file of human speech (8 kHz, mono, 16 bit LE) as a Codec2 stream:
 ```
 
 This is how to transmit a wave file of human speech (8 kHz, mono, 16 bit LE) as a Codec2 stream:


@@ -140,4 +164,4 @@ To receive:
 
 * Create an adapter that implements trait `StreamAdapter`
 * Handle the `stream_began` and `stream_data` methods
 
 * Create an adapter that implements trait `StreamAdapter`
 * Handle the `stream_began` and `stream_data` methods

-* Add it to your `M17App`
+* Add it to your `M17App` with `add_stream_adapter`

diff --git a/m17codec2/README.md b/m17codec2/README.md
index 0475c2823e17c01b109b783d85a461e91e636cec..ebf92ba4b0f969bb152a68b93cdd10674abc24f4 100644 (file)
--- a/m17codec2/README.md
+++ b/m17codec2/README.md
@@ -3,6 +3,7 @@
 Part of the [M17 Rust Toolkit](https://octet-stream.net/p/m17rt/). Pre-made adapters designed for the `m17app` crate that make it easier to work with Codec2 voice streams.
 
 * `WavePlayer` - transmit a wave file as a stream (8 kHz, mono, 16 bit LE)
 Part of the [M17 Rust Toolkit](https://octet-stream.net/p/m17rt/). Pre-made adapters designed for the `m17app` crate that make it easier to work with Codec2 voice streams.
 
 * `WavePlayer` - transmit a wave file as a stream (8 kHz, mono, 16 bit LE)

-* `Codec2Adapter` - receive all incoming streams and attempt to play the decoded audio on the default sound card
+* `Codec2RxAdapter` - receive all incoming streams and attempt to play the decoded audio on a soundcard (configurable)
+* `Codec2TxAdapter` - toggle a PTT to record audio from a microphone (soundcard also configurable), encode it, and transmit it with chosen source and destination addresses

 
 **Important licence note:** While `m17codec2` is under the MIT licence, it uses the `codec2` crate as a dependency, which will statically link LGPL code in the build. If you are distributing software in a way where LGPL compliance requires special care (e.g., dynamic linking), consider implementing your own codec2 adapters in a way that is compliant in your scenario.
 
 **Important licence note:** While `m17codec2` is under the MIT licence, it uses the `codec2` crate as a dependency, which will statically link LGPL code in the build. If you are distributing software in a way where LGPL compliance requires special care (e.g., dynamic linking), consider implementing your own codec2 adapters in a way that is compliant in your scenario.

diff --git a/m17core/README.md b/m17core/README.md
index dc13bf3d7ed888f9fdd6944052310a5f79171191..91b05d0ca42338728078cf88038bcc4933d18cde 100644 (file)
--- a/m17core/README.md
+++ b/m17core/README.md
@@ -2,7 +2,7 @@
 
 Part of the [M17 Rust Toolkit](https://octet-stream.net/p/m17rt/).
 
 
 Part of the [M17 Rust Toolkit](https://octet-stream.net/p/m17rt/).
 

-This crate includes a modulator, demodulator, TNC, M17 data link parsing and encoding, KISS protocol handling, and other protocol utilities. It can be used to create an M17 transmitter or receiver, however you will have to connect everything together yourself. If possible, consider using the higher-level crate `m17app`.
+This crate includes a modulator, demodulator, TNC, M17 data link parsing and encoding, KISS protocol handling, UDP reflector packet formats, and other protocol utilities. It can be used to create an M17 transmitter or receiver, however you will have to connect everything together yourself. If possible, consider using the higher-level crate `m17app`.

 
 `m17core` is `no_std`, does not perform any heap allocations, and its protocol implementations are non-blocking and sans-I/O.
 
 
 `m17core` is `no_std`, does not perform any heap allocations, and its protocol implementations are non-blocking and sans-I/O.