Update the README

README.md

@@ -58,6 +58,9 @@ as long as the resulting abbreviation is unambiguous.
 
 There is a dedicated `--help` option for every subcommand.
 
+Yakut may also be invoked via its alias **`y`** as long as this name does not conflict with another installed program.
+
+
 ## Compiling DSDL
 
 Suppose we have our custom DSDL namespace that we want to use.
@@ -110,6 +113,7 @@ $env:YAKUT_PATH="$env:YAKUT_COMPILE_OUTPUT"
 So that you say simply `yakut compile path/to/my_namespace`
 knowing that the outputs will be always stored to and read from a fixed place unless you override it.
 
+
 ## Communicating
 
 Commands that access the network need to know how to do so.
@@ -172,82 +176,85 @@ consider configuring it as the default via environment variables as shown earlie
 
 Next there are practical examples (configuring the transport is left as an exercise to the reader).
 
+### Subscribing to subjects
+
+Subscribe to subject 33 of type `uavcan.si.unit.angle.Scalar.1.0` as shown below;
+notice how we specify the subject-ID before the data type name.
+You will see output if there is a publisher on this subject (see the next section).
+
+```bash
+$ export UAVCAN__UDP__IFACE=127.63.0.0
+$ yakut sub 33:uavcan.si.unit.angle.Scalar.1.0
+---
+33:
+  _metadata_:
+    timestamp: {system: 1608987583.298886, monotonic: 788272.540747}
+    priority: nominal
+    transfer_id: 0
+    source_node_id: 42
+  radian: 2.309999942779541
+
+---
+33:
+  _metadata_:
+    timestamp: {system: 1608987583.298886, monotonic: 788272.540747}
+    priority: nominal
+    transfer_id: 1
+    source_node_id: 42
+  radian: 2.309999942779541
+```
+
 ### Publishing messages
 
-Publishing two messages synchronously twice (four messages total);
-notice how we specify the subject-ID before the data type name:
+Publishing two messages synchronously twice (four messages total):
 
 ```bash
 export UAVCAN__UDP__IFACE=127.63.0.0
 export UAVCAN__NODE__ID=42
-yakut pub 33:uavcan.si.unit.angle.Scalar.1.0 'radian: 2.31' uavcan.diagnostic.Record.1.1 'text: "2.31 rad"' -N2
+yakut pub -N2 33:uavcan.si.unit.angle.Scalar.1.0 'radian: 2.31' uavcan.diagnostic.Record.1.1 'text: "2.31 rad"'
 ```
 
 We did not specify the subject-ID for the second subject, so Yakut defaulted to the fixed subject-ID.
 
 The above example publishes constant values which is rarely useful.
 You can define arbitrary Python expressions that are evaluated by Yakut before publication.
 Such expressions are entered as strings marked with YAML tag `!$`.
-There may be an arbitrary number of such expressions in a YAML string,
-and their results may be arbitrary as long as the final structure can initialize the specified message type.
-In the following example, we define an array of three elements, where the first and last elements are evaluated
-dynamically (try it):
+There may be an arbitrary number of such expressions in a YAML document,
+and their results may be arbitrary as long as the final structure can initialize the specified message.
+The following example will publish a sinewave with frequency 1 Hz, amplitude 10 meters:
 
 ```bash
-yakut pub 33:uavcan.primitive.array.Real64.1.0 'value: [!$ 1+n+t*0.1, 123456, !$ time()]'
+yakut pub -T 0.01 1234:uavcan.si.unit.length.Scalar.1.0 '{meter: !$ "sin(t * pi * 2) * 10"}'
 ```
 
-At least the following symbols are available for use in expressions (see `yakut pub --help` for the full list):
-
-- Variables:
-  - `n :int` --- message index starting from 0.
-  - `t :float` --- time delta since first message.
+Notice that we make use of variables like `t` or standard functions like `sin` in the expression.
+You will see the full list of available symbols and functions if you run `yakut pub --help`.
 
-- HID controller access functions (more on this below):
-  - `A(controller, axis :int) -> float` --- read controller axis value normalized into `[-1, +1]` or `[0, +1]`,
-    depending on the type of controller (unipolar or reversible).
-  - `B(controller, button :int) -> bool` --- read controller push button state (true if currently pressed).
-  - `T(controller, toggle :int) -> bool` --- read controller toggle switch state.
+One particularly important capability of this command is the ability to read data from connected
+joysticks or MIDI controllers.
+It allows the user to control UAVCAN processes or equipment in real time, simulate sensor feeds, etc.
+Function `A(x,y)` returns the normalized value of channel `y` from connected controller `x`
+(for full details see `yakut pub --help`);
+likewise, there is `B(x,y)` for push buttons and `T(x,y)` for toggle switches.
+The next example shows how to publish 3D angular velocity setpoint, thrust setpoint, and the arming switch state,
+allowing the user to control these parameters interactively:
 
-- The following Python standard library modules are wildcard-imported:
-  - [random](https://docs.python.org/library/random.html) (e.g., `random()`)
-  - [time](  https://docs.python.org/library/time.html)   (e.g., `monotonic()`)
-  - [math](  https://docs.python.org/library/math.html)   (e.g., `sin(x)`)
+```bash
+yakut pub -T 0.1 \
+    5:uavcan.si.unit.angular_velocity.Vector3.1.0 'radian_per_second: !$ "[A(1,0)*10, A(1,1)*10, (A(1,2)-A(1,5))*5]"' \
+    6:uavcan.si.unit.power.Scalar.1.0 'watt: !$ A(2,10)*1e3' \
+    7:uavcan.primitive.scalar.Bit.1.0 'value: !$ T(1,5)'
+```
 
-- The following modules are imported:
-  - [pyuavcan](https://github.com/UAVCAN/pyuavcan/)
+The list of available controllers and how their axes are mapped can be seen using `yakut joystick`,
+as shown in the video:
 
 [![yakut joystick](https://img.youtube.com/vi/YPr98KM1RFM/maxresdefault.jpg)](https://www.youtube.com/watch?v=YPr98KM1RFM)
 
-[![yakut publish](https://img.youtube.com/vi/DSsI882ZYh0/maxresdefault.jpg)](https://www.youtube.com/watch?v=DSsI882ZYh0)
-
-
-### Subscribing to subjects
-
-Subscribe to subject 33 of type `uavcan.si.unit.angle.Scalar.1.0`
-to receive messages published by the above command:
+Here is an example where a MIDI controller is used to interactively change the frequency and amplitude of a sinewave:
 
-```bash
-$ export UAVCAN__UDP__IFACE=127.63.0.0
-$ yakut sub 33:uavcan.si.unit.angle.Scalar.1.0
----
-33:
-  _metadata_:
-    timestamp: {system: 1608987583.298886, monotonic: 788272.540747}
-    priority: nominal
-    transfer_id: 0
-    source_node_id: 42
-  radian: 2.309999942779541
+[![yakut publish](https://img.youtube.com/vi/DSsI882ZYh0/maxresdefault.jpg)](https://www.youtube.com/watch?v=DSsI882ZYh0)
 
----
-33:
-  _metadata_:
-    timestamp: {system: 1608987583.298886, monotonic: 788272.540747}
-    priority: nominal
-    transfer_id: 1
-    source_node_id: 42
-  radian: 2.309999942779541
-```
 
 ### Invoking RPC-services
 
@@ -283,6 +290,7 @@ $ yakut call 42 123:sirius_cyber_corp.PerformLinearLeastSquaresFit.1.0 'points:
   y_intercept: 0.0
 ```
 
+
 ## Monitoring the network
 
 The command `yakut monitor` can be used to display *all* activity on the network in a compact representation.
@@ -306,6 +314,7 @@ In the latter case it will actively query other nodes using the standard introsp
 Some transports, UAVCAN/UDP in particular, require special privileges to run this tool due to the security
 implications of low-level packet capture.
 
+
 ## Updating node software
 
 The file server command can be used to serve files,

yakut/cmd/publish/_cmd.py

@@ -74,7 +74,6 @@ def load(what: Sequence[ExpressionContextModule]) -> Dict[str, Any]:
     ExpressionContextModule("scipy.spatial", "https://docs.scipy.org/doc/scipy/reference/spatial.html"),
 ]
 
-# TODO: update/extend the examples
 _EXAMPLES = """
 Example: publish constant messages (no embedded expressions, just regular YAML):
 
@@ -88,7 +87,7 @@ def load(what: Sequence[ExpressionContextModule]) -> Dict[str, Any]:
     yakut pub -T 0.01 1234:uavcan.si.unit.length.Scalar.1.0 '{meter: !$ "sin(t * pi * 2) * 10"}'
 
 Example: as above, but control the frequency of the sinewave and its amplitude using sliders 10 and 11
-of the first connected HID controller (use `yakut joystick` to find connected HID controllers and their axis mappings):
+of the first connected controller (use `yakut joystick` to find connected controllers and their axis mappings):
 
 \b
     yakut pub -T 0.01 1234:uavcan.si.unit.length.Scalar.1.0 '{meter: !$ "sin(t * pi * 2 * A(1,10)) * 10 * A(1,11)"}'
@@ -144,8 +143,8 @@ def load(what: Sequence[ExpressionContextModule]) -> Dict[str, Any]:
 {Executor.SYM_DTYPE}: Type[pyuavcan.dsdl.CompositeType] --- message class.
 
 {Executor.SYM_CTRL_AXIS}: (controller,axis:int)->float ---
-read the normalized value of `axis` from HID `controller` (e.g., joystick or MIDI fader).
-To see the list of available HID controllers and determine their channel mapping, refer to `yakut joystick --help`.
+read the normalized value of `axis` from `controller` (e.g., joystick or MIDI fader).
+To see the list of available controllers and determine their channel mapping, refer to `yakut joystick --help`.
 
 {Executor.SYM_CTRL_BUTTON}: (controller,button:int)->bool ---
 read the state of `button` from `controller` (true while held down).