update README for version 0.1.0 release

It is time to release.

Signed-off-by: Takashi Sakamoto <[email protected]>

Author: takaswie

README.rst

@@ -2,18 +2,31 @@
 snd-firewire-ctl-services
 ========================
 
-2023/04/16
+2023/04/19
 Takashi Sakamoto
 
 Introduction
 ============
 
-This project is a sub project in Advanced Linux Sound Architecture a.k.a ALSA,
-to produce userspace service daemon for Audio and Music units on IEEE 1394 bus,
-supported by drivers in ALSA firewire stack.
+This project is a sub-project within Advanced Linux Sound Architecture a.k.a ALSA, aimed to provide
+user space service programs for Audio and Music units connected to IEEE 1394 bus, supported by
+drivers in ALSA firewire stack.
 
-Executables (binary crates)
-===========================
+The latest release is
+`version 0.1.0 <https://github.com/alsa-project/snd-firewire-ctl-services/releases/tag/snd-firewire-ctl-services%2Fv0.1.0>`_.
+
+The service programs are designed to operate digital signal processing function in the audio and
+music units connected to IEEE 1394 bus. The service programs work as
+`message broker <https://en.wikipedia.org/wiki/Message_broker>`_. ALSA control and sequencer
+applications are available as an end to communicate to the service programs. The audio and music
+units in IEEE 1394 bus is the opposite end. The service programs receives messages from both
+ends, then translates and convert the messages to send to the opposite end. The internal design of
+the programs are illustrated in ``Design note`` section.
+
+Executables for service programs
+================================
+
+The project provides the following service programs in the form of Rust binary crates:
 
 snd-firewire-digi00x-ctl-service
    For sound card bound to ALSA firewire-digi00x driver (snd-firewire-digi00x)
@@ -32,98 +45,19 @@ snd-dice-ctl-service
 snd-fireface-ctl-service
    For sound card bound to ALSA fireface driver (snd-fireface)
 
-License
-=======
-
-* Some library crates are released under MIT license. They are available in `<crates.io>`_
-  as well.
-
-  * `alsa-ctl-tlv-codec <https://crates.io/crates/alsa-ctl-tlv-codec>`_
-  * `ieee1212-config-rom <https://crates.io/crates/ieee1212-config-rom>`_
-  * `ta1394-avc-general <https://crates.io/crates/ta1394-avc-general>`_
-  * `ta1394-avc-audio <https://crates.io/crates/ta1394-avc-audio>`_
-  * `ta1394-avc-stream-format <https://crates.io/crates/ta1394-avc-stream-format>`_
-  * `ta1394-avc-ccm <https://crates.io/crates/ta1394-avc-ccm>`_
-
-* Some library crates for protocol implementation are released under GNU Lesser General
-  Public License v3.0 or later with respect to clause for reverse engineering. They are
-  available in `<crates.io>`_ as well.
-
-  * `firewire-bebob-protocols <https://crates.io/crates/firewire-bebob-protocols>`_
-  * `firewire-fireworks-protocols <https://crates.io/crates/firewire-fireworks-protocols>`_
-  * `firewire-oxfw-protocols <https://crates.io/crates/firewire-oxfw-protocols>`_
-  * `firewire-dice-protocols <https://crates.io/crates/firewire-dice-protocols>`_
-  * `firewire-digi00x-protocols <https://crates.io/crates/firewire-digi00x-protocols>`_
-  * `firewire-tascam-protocols <https://crates.io/crates/firewire-tascam-protocols>`_
-  * `firewire-motu-protocols <https://crates.io/crates/firewire-motu-protocols>`_
-  * `firewire-fireface-protocols <https://crates.io/crates/firewire-fireface-protocols>`_
-
-* The other crates are released under GNU General Public License Version 3.
-
-Dependencies
-============
-
-* Rust programming language <https://www.rust-lang.org/>
-* Cargo
-* glib `<https://developer.gnome.org/glib/>`_
-* libhinawa v2.5 or later `<https://github.com/alsa-project/libhinawa>`_
-* libhitaki v0.2 or later `<https://github.com/alsa-project/libhitaki>`_
-* alsa-gobject v0.3 or later `<https://github.com/alsa-project/alsa-gobject/>`_
-
-* The library crates enumerated in `License` section are downloaded from `<crates.io>`_ when
-  building.
-
-How to build
-============
-
-Build ::
-
-    $ cargo build
-
-Execute temporarily ::
-
-    & cargo run --bin (the executable name) -- (the arguments of executable)
-
-All of executables can print help when either ``--help`` or ``-h`` is given as an argument of
-command line. Additionally, either ``--log-level`` or ``-l`` is also available for runtime
-debugging. For further information, please refer to ``Runtime debugging`` clause.
-
-Install executables ::
-
-    $ cargo install --path (path to binary crate)
+Disclaimer
+==========
 
-The runtime crates which provide the executables are listed below:
-
-snd-firewire-digi00x-ctl-service
-    ``snd-firewire-digi00x-ctl-service`` crate locates in ``runtime/digi00x``
-snd-firewire-tascam-ctl-service
-    ``snd-firewire-tascam-ctl-service`` crate locates in ``runtime/tascam``
-snd-fireworks-ctl-service
-    ``snd-fireworks-ctl-service`` crate locates in ``runtime/fireworks``
-snd-firewire-motu-ctl-service
-    ``snd-firewire-motu-ctl-service`` crate locates in ``runtime/motu``
-snd-oxfw-ctl-service
-    ``snd-oxfw-ctl-service`` crate locates in ``runtime/oxfw``
-snd-bebob-ctl-service
-    ``snd-bebob-ctl-service`` crate locates in ``runtime/bebob``
-snd-dice-ctl-service
-    ``snd-dice-ctl-service`` crate locates in ``runtime/dice``
-snd-fireface-ctl-service
-    ``snd-fireface-ctl-service`` crate locates in ``runtime/fireface``
-
-The executable is usually installed under ``~/.cargo/bin``, while it's possible to choose the path.
-In detail, please refer to
-`manual of cargo install <https://doc.rust-lang.org/cargo/commands/cargo-install.html>`_.
-
-Uninstall executables ::
+The project provides neither GUI programs nor end-user interfaces against expectation of users,
 
-    $ cargo uninstall -p (name of runtime crate)
+The main motivation of project is to preserve the way (protocol) to operate the audio and music
+units in IEEE 1394 bus, which was defined by several vendors.
 
 Supported devices
 =================
 
-Currently below devices are supported. If you would like to add support for
-your device, please contact to developer.
+Currently below devices are supported. If you would like to add support for your device, please
+contact to developer.
 
 * snd-firewire-digi00x-ctl-service
 
@@ -138,7 +72,7 @@ your device, please contact to developer.
   * Tascam FW-1884
   * Tascam FW-1082
   * Tascam FW-1804
-  * Tascam FE-8
+  * Tascam FE-8 (work without ALSA firewire-tascam driver)
 
 * snd-fireworks-ctl-service
 
@@ -155,21 +89,29 @@ your device, please contact to developer.
 
 * snd-firewire-motu-ctl-service
 
-  * MOTU 828
-  * MOTU 896
-  * MOTU Traveler
-  * MOTU 828mkII
-  * MOTU 896HD
-  * MOTU UltraLite
-  * MOTU 8pre
-  * MOTU 4pre
-  * MOTU AudioExpress
-  * MOTU 828mk3 (FireWire only)
-  * MOTU 828mk3 (Hybrid)
-  * MOTU UltraLite mk3 (FireWire only)
-  * MOTU UltraLite mk3 (Hybrid)
-  * MOTU Traveler mk3
-  * MOTU Track 16
+  * Version 1 models
+
+    * MOTU 828
+    * MOTU 896
+
+  * Register DSP models
+
+    * MOTU Traveler
+    * MOTU 828mkII
+    * MOTU 896HD
+    * MOTU UltraLite
+    * MOTU 8pre
+    * MOTU 4pre
+    * MOTU AudioExpress
+
+  * Command DSP models
+
+    * MOTU 828mk3 (FireWire only)
+    * MOTU 828mk3 (Hybrid)
+    * MOTU UltraLite mk3 (FireWire only)
+    * MOTU UltraLite mk3 (Hybrid)
+    * MOTU Traveler mk3
+    * MOTU Track 16
 
 * snd-oxfw-ctl-service
 
@@ -242,10 +184,174 @@ your device, please contact to developer.
 
 * snd-fireface-ctl-service
 
-  * Fireface 800
-  * Fireface 400
-  * Fireface UCX
-  * Fireface 802
+  * Former models
+
+    * Fireface 800
+    * Fireface 400
+
+  * Latter models
+
+    * Fireface UCX
+    * Fireface 802
+
+Restrictions
+============
+
+Due to a lack of information about the target devices, certain restrictions are unavoidable.
+However, we welcome any assistance that can enhance the project.
+
+* snd-bebob-ctl-service
+
+  * The most of compressor, equalizer, and reverb controls are not available for Focusrite Saffire.
+  * No control is available for un-coded devices. For example, PrismSound Orpheus is the case.
+
+* snd-fireworks-ctl-service
+
+  * Some control is not available for Gibson Robot Interface Pack.
+
+* snd-dice-ctl-service
+
+  * The most of equalizer controls are not available for Focusrite Saffire Pro 24 DSP.
+  * The most of monitor parameters may not work for Alesis iO 14/26 FireWire. This may come from
+    firmware version.
+  * The channel strip dynamics, equalizer, and reverb are not available for Lexicon I-ONIX 810s.
+  * No control is available for Focusrite Saffire Pro 40 (TCD3070 ASIC).
+  * No control is available for Solid State Logic Duende Classic and Mini.
+
+* snd-firewire-digi00x-ctl-service
+
+  * Due to hardware design, the function of DSP can not be configured unless an ALSA PCM
+    application initiates isochronous communication.
+
+* snd-firewire-tascam-ctl-service
+
+  * Due to hardware design, most controls are not synchronized to hardware expectedly unless an
+    ALSA PCM application initiates isochronous communication.
+  * For console models, any event in control surface is available via port of ALSA Sequencer. The
+    event is converted to controller event with channel 0 which has the consecutive number as param
+    and event value. At present, the consecutive number is fixed and not configurable.
+
+* snd-motu-ctl-service
+
+  * Due to hardware design, most controls, including hardware metering, are not synchronized to
+    hardware expectedly for Register DSP models unless an ALSA PCM application initiates isochronous
+    communication.
+  * Due to hardware design, hardware metering may not work properly for Command DSP models unless an
+    ALSA PCM application initiates isochronous communication.
+  * The channel positionss available in the hardware meter is not adequate in all Command DSP
+    models.
+  * Sometimes, there may be an issue with initializing Command DSP models for communication. In such
+    case, the workaround is to simply restart the service program.
+  * 896 mk3 (FireWire only/Hybrid) is not supported since developer has no change to access to it..
+
+* snd-fireface-ctl-service
+
+  * The controls of latter models are not synchronized to any operation by the Remote Control or
+    the Advanced Remote Control.
+
+Support
+=======
+
+* If finding any issue, please file it to
+  `github repository <https://github.com/alsa-project/snd-firewire-ctl-services>`_.
+
+License
+=======
+
+* Some library crates are released under MIT license. They are available in `<crates.io>`_
+  as well.
+
+  * `alsa-ctl-tlv-codec <https://crates.io/crates/alsa-ctl-tlv-codec>`_
+  * `ieee1212-config-rom <https://crates.io/crates/ieee1212-config-rom>`_
+  * `ta1394-avc-general <https://crates.io/crates/ta1394-avc-general>`_
+  * `ta1394-avc-audio <https://crates.io/crates/ta1394-avc-audio>`_
+  * `ta1394-avc-stream-format <https://crates.io/crates/ta1394-avc-stream-format>`_
+  * `ta1394-avc-ccm <https://crates.io/crates/ta1394-avc-ccm>`_
+
+* Some library crates for protocol implementation are released under GNU Lesser General
+  Public License v3.0 or later with respect to clause for reverse engineering. They are
+  available in `<crates.io>`_ as well.
+
+  * `firewire-bebob-protocols <https://crates.io/crates/firewire-bebob-protocols>`_
+  * `firewire-fireworks-protocols <https://crates.io/crates/firewire-fireworks-protocols>`_
+  * `firewire-oxfw-protocols <https://crates.io/crates/firewire-oxfw-protocols>`_
+  * `firewire-dice-protocols <https://crates.io/crates/firewire-dice-protocols>`_
+  * `firewire-digi00x-protocols <https://crates.io/crates/firewire-digi00x-protocols>`_
+  * `firewire-tascam-protocols <https://crates.io/crates/firewire-tascam-protocols>`_
+  * `firewire-motu-protocols <https://crates.io/crates/firewire-motu-protocols>`_
+  * `firewire-fireface-protocols <https://crates.io/crates/firewire-fireface-protocols>`_
+
+* The other crates are for runtime and released under GNU General Public License Version 3.
+
+Dependencies
+============
+
+* Rust programming language <https://www.rust-lang.org/> v1.65 or later.
+* Cargo
+* glib `<https://developer.gnome.org/glib/>`_
+* libhinawa v2.5 or later `<https://github.com/alsa-project/libhinawa>`_
+* libhitaki v0.2 or later `<https://github.com/alsa-project/libhitaki>`_
+* alsa-gobject v0.3 or later `<https://github.com/alsa-project/alsa-gobject/>`_
+
+* The library crates enumerated in `License` section are downloaded from `<crates.io>`_ when
+  building by configurations of `Cargo.toml`.
+
+How to build
+============
+
+Build ::
+
+    $ cargo build
+
+Execute temporarily ::
+
+    & cargo run --bin (the executable name) -- (the arguments of executable)
+
+All of executables can print help when either ``--help`` or ``-h`` is given as an argument of
+command line. In the most executables, the first positional argument is the numeric identifier of
+sound card in Linux sound subsystem. For further information, please refer to ``Runtime debugging``
+clause.
+
+Install executables ::
+
+    $ cargo install --path (path to binary crate)
+
+The runtime crates which provide the executables are listed below:
+
+snd-firewire-digi00x-ctl-service
+    ``snd-firewire-digi00x-ctl-service`` crate locates in ``runtime/digi00x``
+snd-firewire-tascam-ctl-service
+    ``snd-firewire-tascam-ctl-service`` crate locates in ``runtime/tascam``
+snd-fireworks-ctl-service
+    ``snd-fireworks-ctl-service`` crate locates in ``runtime/fireworks``
+snd-firewire-motu-ctl-service
+    ``snd-firewire-motu-ctl-service`` crate locates in ``runtime/motu``
+snd-oxfw-ctl-service
+    ``snd-oxfw-ctl-service`` crate locates in ``runtime/oxfw``
+snd-bebob-ctl-service
+    ``snd-bebob-ctl-service`` crate locates in ``runtime/bebob``
+snd-dice-ctl-service
+    ``snd-dice-ctl-service`` crate locates in ``runtime/dice``
+snd-fireface-ctl-service
+    ``snd-fireface-ctl-service`` crate locates in ``runtime/fireface``
+
+The executable is usually installed under ``~/.cargo/bin``, while it's possible to choose the path.
+In detail, please refer to
+`manual of cargo install <https://doc.rust-lang.org/cargo/commands/cargo-install.html>`_.
+
+Uninstall executables ::
+
+    $ cargo uninstall -p (name of runtime crate)
+
+Runtime debugging
+=================
+
+All executables support an option for log level for debugging. When either ``-l`` or
+``--log-level`` is given with log level, they prints verbose logs to standard output.
+At present, ``debug`` is just supported for the log level.
+
+This function is implemented by `tracing <https://crates.io/crates/tracing>`_ and
+`tracing-subscriber <https://crates.io/crates/tracing-subscriber>`_ crates.
 
 Supported protocols
 ===================
@@ -271,16 +377,6 @@ Supported protocols
    * Protocol for former models of Fireface series of RME GmbH
    * Protocol for latter models of Fireface series of RME GmbH
 
-Runtime debugging
-=================
-
-All executables support an option for log level for debugging. When either ``-l`` or
-``--log-level`` is given with log level, they prints verbose logs to standard output.
-At present, ``debug`` is just supported for the log level.
-
-This function is implemented by `tracing <https://crates.io/crates/tracing>`_ and
-`tracing-subscriber <https://crates.io/crates/tracing-subscriber>`_ crates.
-
 Design note
 ===========