[DS-015] Formalize the port naming convention and restore the origina…

…l unabbreviated namespace names (#98)

* Rename abbreviated "rotat" and "trans" back into the full unabbreviated form.

This change is enabled by OpenCyphal/specification#101 as we are
no longer constrained by the 50-character data type name length limit.
This change does not affect wire compatibility.

* Revert 0be09fd by restoring the original long names as explained in the previous commit

* Implement https://forum.uavcan.org/t/automatic-configuration-of-port-identifiers/840/7\?u\=pavel.kirienko

.vscode/spellright.dict

@@ -405,3 +405,4 @@ pitot
 CAS
 OOP
 alignee
+UML

reg/drone/README.md

@@ -6,8 +6,8 @@ If you have any questions, feel free to bring them to the [UAVCAN Forum](https:/
 
 This namespace contains the following nested namespaces:
 
-- `phy` -- abstract physical processes and states in the system.
-- `srv` -- narrowly specialized types for common device classes.
+- `physics` -- abstract physical processes and states in the system.
+- `service` -- narrowly specialized types for common device classes.
 
 ## Service-oriented architecture
 
@@ -45,7 +45,7 @@ which is necessitated by the increasing complexity of modern intravehicular soft
 
 ## Typical applications
 
-The definitions in the `srv` namespace contain descriptions of some common use cases
+The definitions in the `service` namespace contain descriptions of some common use cases
 that can be addressed with this standard.
 Adopters are expected to mix and match various components to create new network services that were not originally
 envisioned by the authors of this standard.
@@ -57,13 +57,13 @@ For example, a COTS (commercial off-the-shelf) electric drive may realistically
 
 - Naturally, the ESC service.
 - The servo service for generality.
-- Acoustic feedback by subscribing to `reg.drone.phy.acoustics.Note`.
-- Visual feedback via the LED by subscribing to `reg.drone.phy.optics.HighColor`.
+- Acoustic feedback by subscribing to `reg.drone.physics.acoustics.Note`.
+- Visual feedback via the LED by subscribing to `reg.drone.physics.optics.HighColor`.
 
 Another service that is interested in tracking the state of, say, a propeller drive
 (say, for thrust estimation) would not need to concern itself with the ESC service at all.
 Instead, it would simply subscribe to the generalized subject of type
-`reg.drone.phy.dynamics.rotat.PlanarTs` published by the unit that drives the propeller
+`reg.drone.physics.dynamics.rotation.PlanarTs` published by the unit that drives the propeller
 and extract its business-level information from that while being unaware of the specifics of the drive
 (the propeller drive may be changed from an electric motor to a turboprop engine without affecting the
 thrust estimation service).
@@ -93,6 +93,8 @@ UAVCAN implementation libraries are optimized for handling multi-frame transfers
 
 ## Conventions
 
+### Network service design conventions
+
 - All physical quantities except error variance should be represented as `float32` by default.
   Error variance and covariance matrices should use `float16` by default.
 
@@ -104,4 +106,76 @@ UAVCAN implementation libraries are optimized for handling multi-frame transfers
   The timestamp field, if present, should be the first one;
   error (co)variance information should follow the data field(s) it relates to.
 
-- Publishers of measurements or estimates should apply low-pass filtering to avoid frequency aliasing.
+### Port naming conventions
+
+In UAVCAN, the name of a port (i.e., subject or RPC-service) defines the names of related registers
+as described in the documentation for the standard RPC-service `uavcan.register.Access`.
+For instance, a node that publishes to the subject named `measurement` would have registers named
+`uavcan.pub.measurement.id` and `uavcan.pub.measurement.type` (among others).
+
+> N.B.: Contrary to other protocols, in UAVCAN, the name of a port is a node-local property that does not affect
+  network exchanges over that port.
+  This means that nodes can publish/subscribe to a port even if they name it differently
+  as long as they are configured to use the same numerical port-ID.
+  The details are given in the UAVCAN Specification.
+
+Network service specifications given here under the `service` namespace provide the recommended names for
+every defined port.
+For example, the smart battery network service specification defines subjects named `status` and `parameters`.
+
+Using the suggested names in practical implementations directly is not always possible because nodes that
+implement different network services (or multiple instances of the same service) would see naming conflicts
+(e.g., many services define a subject named `status`).
+Hence, implementations are advised to use the recommended port names with a prefix such that ports that
+relate to the same instance of a network service share the same prefix.
+
+Imagine a node that implements two smart battery services (primary and secondary)
+and a servo service (suppose we call it the main drive);
+then it might have the following registers (among others):
+
+    uavcan.pub.battery.primary.source.id
+    uavcan.pub.battery.primary.status.id
+    uavcan.pub.battery.primary.parameters.id
+    uavcan.pub.battery.secondary.source.id
+    uavcan.pub.battery.secondary.status.id
+    uavcan.pub.battery.secondary.parameters.id
+    uavcan.sub.main_drive.setpoint.id
+    uavcan.sub.main_drive.readiness.id
+    uavcan.pub.main_drive.feedback.id
+    uavcan.pub.main_drive.status.id
+    uavcan.pub.main_drive.power.id
+    uavcan.pub.main_drive.dynamics.id
+
+By virtue of sharing common prefixes, the registers clearly define three network services:
+
+- `battery.primary`
+- `battery.secondary`
+- `main_drive`
+
+The convention can be described in UML notation as follows:
+
+    +-----------------------------------+
+    |   Network service specification   |   E.g., the smart battery network service
+    +-----------------------------------+   defined under reg.drone.service.battery
+                    △ 0..*
+                    ┆
+                    ┆ implements
+                    ┆
+    +-----------------------------------+   Example group "battery.main":
+    |        Prefixed port group        |   - battery.main.source
+    +-----------------------------------+   - battery.main.status
+                    │                       - battery.main.parameters
+                    │ has
+                    │
+                    ♢ 1..*
+    +-----------------------------------+
+    |             Port                  |
+    |     (subject or RPC-service)      |
+    +-----------------------------------+
+
+Following this convention is highly recommended as it aids one's understanding of the node's functional capabilities
+and may enable some systems to implement automatic assignment of port identifiers.
+
+### Behavioral conventions
+
+Publishers of measurements or estimates should apply low-pass filtering to avoid frequency aliasing.

reg/drone/phy/dynamics/rotat/Planar.0.1.uavcan → reg/drone/physics/dynamics/rotation/Planar.0.1.uavcan

@@ -1,5 +1,5 @@
 # Positive torque is co-directed with positive position/velocity/acceleration.
 # Provided states may allow the consumer to deduce certain hidden states such as the moment of inertia.
-reg.drone.phy.kinematics.rotat.Planar.0.1 kinematics
+reg.drone.physics.kinematics.rotation.Planar.0.1 kinematics
 uavcan.si.unit.torque.Scalar.1.0 torque  # NaN if unknown
 @sealed

reg/drone/phy/dynamics/trans/Linear.0.1.uavcan → reg/drone/physics/dynamics/translation/Linear.0.1.uavcan

@@ -1,5 +1,5 @@
 # Positive force is co-directed with positive position/velocity/acceleration.
 # Provided kinetic states may allow the consumer to deduce certain hidden states such as the mass of the load.
-reg.drone.phy.kinematics.trans.Linear.0.1 kinematics
+reg.drone.physics.kinematics.translation.Linear.0.1 kinematics
 uavcan.si.unit.force.Scalar.1.0 force  # NaN if unknown
 @sealed

reg/drone/srv/actuator/common/Feedback.0.1.uavcan → reg/drone/service/actuator/common/Feedback.0.1.uavcan

@@ -4,7 +4,7 @@
 # be lower than the defined limit.
 # The priority of this message should be the same as that of the corresponding setpoint message.
 
-reg.drone.srv.common.Heartbeat.0.1 heartbeat
+reg.drone.service.common.Heartbeat.0.1 heartbeat
 # If ENGAGED, the actuator provides service according to its nominal performance characteristics.
 # Otherwise, no availability guarantees are provided.
 # Notice that the feedback type is a structural subtype of the heartbeat type, so one can subscribe to a

reg/drone/srv/actuator/esc/_.0.1.uavcan → reg/drone/service/actuator/esc/_.0.1.uavcan

@@ -17,20 +17,21 @@
 #   - Individual subjects, whose subject-ID is offset from the setpoint subject-ID `S` as a function of
 #     group member index `i` as specified below.
 #
-#                                                   SUBJECT     TYPE                                        SUBJECT-ID
+#                                                   SUBJECT
+#                                                   NAME        SUBJECT TYPE                                SUBJECT-ID
 #  +----------------+
-#  |   Controller   |---------+------------+----... setpoint    reg.drone.srv.actuator.common.sp.*          S
-#  |                |-------+-)----------+-)----... readiness   reg.drone.srv.common.Readiness              S+1
+#  |   Controller   |---------+------------+----... setpoint    reg.drone.service.actuator.common.sp.*      S
+#  |                |-------+-)----------+-)----... readiness   reg.drone.service.common.Readiness          S+1
 #  +----------------+       | |          | |
 #   ^ ^ ^ ^  ^ ^ ^ ^        v v          v v
 #   | | | |  | | | |   +---------+  +---------+
 #   | | | |  | | | |   |Drive i=0|  |Drive i=1| ...
 #   | | | |  | | | |   +---------+  +---------+
 #   | | | |  | | | |     | | | |      | | | |
-#   | | | |  | | | +-----+ | | |      | | | |       feedback    reg.drone.srv.actuator.common.Feedback      S+(i+1)*5+1
-#   | | | |  | | +---------+ | |      | | | |       status      reg.drone.srv.actuator.common.Status        S+(i+1)*5+2
-#   | | | |  | +-------------+ |      | | | |       power       reg.drone.phy.electricity.PowerTs           S+(i+1)*5+3
-#   | | | |  +-----------------+      | | | |       dynamics    reg.drone.phy.dynamics.rotat.PlanarTs       S+(i+1)*5+4
+#   | | | |  | | | +-----+ | | |      | | | |       feedback    reg.drone.service.actuator.common.Feedback   S+(i+1)*5+1
+#   | | | |  | | +---------+ | |      | | | |       status      reg.drone.service.actuator.common.Status     S+(i+1)*5+2
+#   | | | |  | +-------------+ |      | | | |       power       reg.drone.physics.electricity.PowerTs        S+(i+1)*5+3
+#   | | | |  +-----------------+      | | | |       dynamics    reg.drone.physics.dynamics.rotation.PlanarTs S+(i+1)*5+4
 #   | | | |                           | | | |
 #   | | | +---------------------------+ | | |
 #   | | +-------------------------------+ | |
@@ -66,7 +67,7 @@
 # to enforce unless the drive is ENGAGED because it may require delivering power to the load.
 #
 # The setpoint message types that can be used to command a group of drives are defined in
-# reg.drone.srv.actuator.common.sp; please read the documentation related to that namespace for further information.
+# reg.drone.service.actuator.common.sp; please read the documentation related to that namespace for further information.
 # Servo setpoint message types may also be supported on an implementation-specific basis for enhanced interoperability.
 # If the group is controlled using different setpoint subjects concurrently, the behavior is implementation-defined.
 #

reg/drone/srv/actuator/servo/_.0.1.uavcan → reg/drone/service/actuator/servo/_.0.1.uavcan

@@ -2,8 +2,8 @@
 #
 # The type of load (translational or rotational) dictates which type is used for commanding the setpoint and reporting
 # the status:
-#   - reg.drone.phy.dynamics.rotat.Planar[Ts]
-#   - reg.drone.phy.dynamics.trans.Linear[Ts]
+#   - reg.drone.physics.dynamics.rotation.Planar[Ts]
+#   - reg.drone.physics.dynamics.translation.Linear[Ts]
 # For generality, either or both of these types are referred to as "timestamped dynamics" or "non-timestamped dynamics".
 #
 # The default readiness state is STANDBY. While in this state, the servo is not allowed to apply force to the load,
@@ -13,17 +13,17 @@
 # The subjects defined by this service are shown on the following canvas. Implementers are encouraged to add
 # custom subjects with additional data. Notice that the physics subjects are timestamped.
 #
-#                    SUBJECT                            TYPE                                            RATE
+#                    SUBJECT NAME                       SUBJECT TYPE                                    RATE
 #
 #   +------------+   setpoint       +------------+      (non-timestamped dynamics) (see below)          R
 #   |            |----------------->|            |
-#   |            |   readiness      |            |      reg.drone.srv.common.Readiness                  any
+#   |            |   readiness      |            |      reg.drone.service.common.Readiness              any
 #   |            |----------------->|            |
-#   |            |   feedback       |            |      reg.drone.srv.actuator.common.Feedback          R
+#   |            |   feedback       |            |      reg.drone.service.actuator.common.Feedback      R
 #   |            |<-----------------|            |
-#   | Controller |   status         |   Servo    |      reg.drone.srv.actuator.common.Status            any
+#   | Controller |   status         |   Servo    |      reg.drone.service.actuator.common.Status        any
 #   |            |<-----------------|            |
-#   |            |   power          |            |      reg.drone.phy.electricity.PowerTs               R
+#   |            |   power          |            |      reg.drone.physics.electricity.PowerTs           R
 #   |            |<-----------------|            |
 #   |            |   dynamics       |            |      (timestamped dynamics)                          R
 #   |            |<-----------------|            |
@@ -59,24 +59,25 @@
 # Some applications may require synchronous independent control of multiple servos in a group, similar to ESC.
 # To address this, a compliant servo should support another operating mode where the controlled quantity
 # (position, velocity, force, etc.) is selected statically along with the motion profile (using the register API),
-# and the servo subscribes to the setpoint subject of type "reg.drone.srv.actuator.common.sp.*".
+# and the servo subscribes to the setpoint subject of type "reg.drone.service.actuator.common.sp.*".
 # Having its index in the group configured statically, the servo fetches the setpoint from the appropriate
 # index in the setpoint array.
 # The resulting topology closely resembles that of the ESC service:
 #
-#                                                   SUBJECT     TYPE
+#                                                   SUBJECT
+#                                                   NAME        SUBJECT TYPE
 #  +----------------+
-#  |   Controller   |---------+------------+----... setpoint    reg.drone.srv.actuator.common.sp.*
-#  |                |-------+-)----------+-)----... readiness   reg.drone.srv.common.Readiness
+#  |   Controller   |---------+------------+----... setpoint    reg.drone.service.actuator.common.sp.*
+#  |                |-------+-)----------+-)----... readiness   reg.drone.service.common.Readiness
 #  +----------------+       | |          | |
 #   ^ ^ ^ ^  ^ ^ ^ ^        v v          v v
 #   | | | |  | | | |   +---------+  +---------+
 #   | | | |  | | | |   |Servo i=0|  |Servo i=1| ...
 #   | | | |  | | | |   +---------+  +---------+
 #   | | | |  | | | |     | | | |      | | | |
-#   | | | |  | | | +-----+ | | |      | | | |       feedback    reg.drone.srv.actuator.common.Feedback
-#   | | | |  | | +---------+ | |      | | | |       status      reg.drone.srv.actuator.common.Status
-#   | | | |  | +-------------+ |      | | | |       power       reg.drone.phy.electricity.PowerTs
+#   | | | |  | | | +-----+ | | |      | | | |       feedback    reg.drone.service.actuator.common.Feedback
+#   | | | |  | | +---------+ | |      | | | |       status      reg.drone.service.actuator.common.Status
+#   | | | |  | +-------------+ |      | | | |       power       reg.drone.physics.electricity.PowerTs
 #   | | | |  +-----------------+      | | | |       dynamics    (timestamped dynamics)
 #   | | | |                           | | | |
 #   | | | +---------------------------+ | | |
@@ -92,7 +93,7 @@
 #
 # The following subjects shall be published immediately after a new setpoint is applied even if the servo is STANDBY:
 #
-#   SUBJECT             RECOMMENDED PRIORITY
+#   SUBJECT NAME        RECOMMENDED PRIORITY
 #   ---------------------------------------------
 #   feedback            same as the setpoint
 #   power               second to the setpoint

reg/drone/srv/air_data_computer/_.0.1.uavcan → reg/drone/service/air_data_computer/_.0.1.uavcan

@@ -20,11 +20,11 @@
 # which should not be lower than the specified limit. The measurements should be low-pass filtered
 # to avoid frequency aliasing effects.
 #
-#   PUBLISHED SUBJECT       TYPE                                                NOTE
-#   calibrated airspeed     reg.drone.phy.kinematics.trans.Velocity1VarTs
-#   true airspeed           reg.drone.phy.kinematics.trans.Velocity1VarTs       optional
-#   pressure altitude data  reg.drone.phy.kinematics.trans.LinearVarTs          assume ISA; NED frame (+down, -up)
-#   static air data         reg.drone.phy.thermodynamics.PressureTempVarTs      pressure and OAT
+#   PUBLISHED SUBJECT NAME  SUBJECT TYPE                                            NOTE
+#   calibrated_airspeed     reg.drone.physics.kinematics.translation.Velocity1VarTs
+#   true_airspeed           reg.drone.physics.kinematics.translation.Velocity1VarTs optional
+#   pressure_altitude       reg.drone.physics.kinematics.translation.LinearVarTs    assume ISA; NED frame (+down, -up)
+#   static_air_data         reg.drone.physics.thermodynamics.PressureTempVarTs      pressure and OAT
 #
 # Observe that there is no subject for indicated airspeed. This is because per the principles of service-oriented
 # design, the air data computer is responsible for applying the necessary transformations on its data to render it
@@ -34,16 +34,16 @@
 # In addition to the above, an ENGAGED service should publish the following service subjects at an
 # implementation-defined rate:
 #
-#   PUBLISHED SUBJECT       TYPE
-#   heartbeat               reg.drone.srv.common.Heartbeat
-#   sensor status           reg.drone.srv.sensor.Status
+#   PUBLISHED SUBJECT NAME      SUBJECT TYPE
+#   heartbeat                   reg.drone.service.common.Heartbeat
+#   sensor_status               reg.drone.service.sensor.Status
 #
 # Despite being a non-interactive service, it is recommended to subscribe to the readiness command subject.
 # This recommendation may be omitted if the service does not support readiness state selection, in which case it should
 # always report itself as being ENGAGED.
 #
-#   SUBSCRIBED SUBJECT      TYPE
-#   readiness control       reg.drone.srv.common.Readiness
+#   SUBSCRIBED SUBJECT NAME     SUBJECT TYPE
+#   readiness                   reg.drone.service.common.Readiness
 
 float32 MAX_PUBLICATION_PERIOD = 0.1  # [second]
 

reg/drone/srv/battery/Status.0.1.uavcan → reg/drone/service/battery/Status.0.1.uavcan

@@ -1,6 +1,6 @@
 # This low-rate battery status should be published at least once per second.
 
-reg.drone.srv.common.Heartbeat.0.1 heartbeat
+reg.drone.service.common.Heartbeat.0.1 heartbeat
 # Note that the health code generally should not reflect the battery charge unless the service provider knows
 # that the availability of energy in the battery is critical for the safe operation of the vehicle, which is usually
 # not the case. For example, if the vehicle is equipped with several batteries that are discharged in series, one

reg/drone/srv/battery/_.0.1.uavcan → reg/drone/service/battery/_.0.1.uavcan

@@ -1,14 +1,14 @@
 # This is the smart battery monitoring service. A smart battery is required to publish the following subjects:
 #
 #   SUBJECT                 TYPE                                            TYP. RATE [Hz]
-#   energy source state     reg.drone.phy.electricity.SourceTs              1...100
-#   battery status          reg.drone.srv.battery.Status                    ~1
-#   battery parameters      reg.drone.srv.battery.Parameters                ~0.2
+#   energy_source           reg.drone.physics.electricity.SourceTs          1...100
+#   battery_status          reg.drone.service.battery.Status                ~1
+#   battery_parameters      reg.drone.service.battery.Parameters            ~0.2
 #
 # Observe that only the first subject can be used for estimating the endurance of the power source. The other subjects
 # are designed for monitoring, diagnostics, and maintenance.
 #
-# Optionally, the battery service can subscribe to a readiness control subject (see reg.drone.srv.common.Readiness),
+# Optionally, the battery service can subscribe to a readiness control subject (see reg.drone.service.common.Readiness),
 # which enables the following two optional capabilities:
 #
 #   - SLEEP mode: when the readiness subject commands the sleep state, the battery management system may enter a