Doc amendment for uavcan.register.Access: mapping between registers and environment variables

[pavel-kirienko]

Introduce well-defined mapping between UAVCAN registers and environment variables. Given registers uavcan.node.id and motor.inductance_dq, one will be able to assign them values 42 and (0.14, 0.16) respectively by exporting environment variables UAVCAN__NODE__ID=42 and MOTOR__INDUCTANCE_DQ=0.14 0.16.

This proposal is motivated by the recent experience with early v1 deployments and my own work on the Yukon backend rewrite (which itself is a UAVCAN-based system). Also, there is a weakly related thread about the possible role of UAVCAN as an IPC transport: https://forum.uavcan.org/t/will-libcanard-or-libuavcan-becomes-a-kind-of-software-bus-for-ipc/1119

While this is a minor change, its implications are significant. As I attempted to illustrate in OpenCyphal/pycyphal#154, proper integration between node registers and the parameter passing services offered by the operating system (which in this case means environment variables) allows one to easily construct software nodes without having to hard-code any UAVCAN-related parameters. Currently, as can be seen in the old demo for PyUAVCAN, it is necessary to either hard-code protocol-related parameters such as node-ID or port-ID (which is non-compliant), or one has to resort to non-standard ad-hoc solutions to make them configurable. Together these factors make UAVCAN significantly less appealing outside of deeply-embedded applications than it could be. This change request provides a way to fix that.

Since the capability to map environment variables to registers can be seen critical for any non-baremetal use of UAVCAN, I would like to see it supported in other higher-level implementations beside PyUAVCAN; specifically, libuavcan (@thirtytwobits) and uavcan.rs (@davidlenfesty). The aforementioned change request to PyUAVCAN builds a case in favor of this point.

A typical embedded or baremetal application will also benefit from using a higher-level implementation than what we can offer now --- which is only Libcanard at the moment. Considering that the register API is a much more critical part of UAVCAN in v1 than it was in v0, such higher-level implementations should treat registers as the first-class feature that is automatically introduced into the user's application by the implementation library, along with its tight integration with all protocol functionality (such as automatic look-up of port-IDs from the registry at port initialization time). Again, the PyUAVCAN CR will focus on the practical aspects.

Besides that, I also want to extend the set of standard registers with two CAN-specific values: uavcan.can.bitrate (which is already present in some v0-based devices, this change makes it regulated), and uavcan.can.iface (for software nodes only).

There are some insignificant formatting changes in the doc; in particular, I added sections to improve readability.

[thirtytwobits]

I really hate encouraging environment variables as a primary mechanism. It's fine as a secondary but I'd rather we define a configuration file standard as the primary mechanism. Can we not just use the same mapping but encourage a file of KEY=VALUE\n as the way to specify each?

[pavel-kirienko]

Environment variables are not meant to be directly used by the human integrator/developer excepting some unusual circumstances that require low-level access. They are convenient because they are present virtually everywhere and are familiar to virtually everybody, so it is a solid foundation to build upon. What you are describing can be implemented on top of the environment variable conventions that we define here. For instance, the configuration file-like behavior can be obtained using shell scripts or the orchestrator that you are already familiar with.

# my-configuration-file
UAVCAN__NODE__ID=42
UAVCAN__UDP__IFACE=127.9.0.0
UAVCAN__SUB__TEMPERATURE_SETPOINT__ID=2345
UAVCAN__SUB__TEMPERATURE_MEASUREMENT__ID=2346
UAVCAN__PUB__HEATER_VOLTAGE__ID=2347
UAVCAN__SRV__LEAST_SQUARES__ID=123
UAVCAN__DIAGNOSTIC__SEVERITY=2

$ . my-configuration-file
$ ./run_this

[thirtytwobits]

environment variables are a pain in automation. They are only suitable as overrides provided for interactive environments.

[pavel-kirienko]

Can you elaborate why? Environment variables are trivial to rely on because they provide a reasonably complete solution whereas a configuration parameter file would be a much heavier addition to the standard. Automation solutions built on top of that will also have to concern themselves with creating and managing the configuration files which carries more logic and is more error-prone.

[thirtytwobits]

environment variables infer a shell environment. We are creating a dependency on the presence of a shell.

[pavel-kirienko]

Yes, this is by design:

This section applies only to software nodes executed in a high-level operating system that supports environment variables or an equivalent mechanism.

A deeply embedded system is unlikely to source its configuration from a shell or a generic configuration file, so it doesn't seem relevant for that use case.

[thirtytwobits]

I don't know what to say. I think it's a bad design choice. You can override my opinion if you disagree.

[pavel-kirienko]

But if shell dependency is intentional and user-friendliness is not relevant, what makes it bad?

[thirtytwobits]

1. It's an abuse of environment variables since you are basically treating it as a list. If anything it should be a delineated value within a single environment variable to be consistent with things like $PATH
2. Not all build automation tools support environment variables but they all support files.

[pavel-kirienko]

1. The objective is to assign registers selectively such that each register is treated as an independent entity. A node process that is unaware of register X would not read the corresponding environment variable, so unless I misunderstood what you mean we don't seem to be following a list-like semantics here.

2. This is meant to be a method of integration-time/runtime configuration management. What build tools are you referring to and why is this relevant?

[thirtytwobits]

If it's runtime then this is even more inappropriate.

1. For most embedded systems there is no shell.
2. If you were developing a GUI environment variables are not appropriate. I know on Windows this has been a pain in the past where some GUI needed environment variables and you had to go through arcane and painful steps to add these to the user environment before you launched the application.

[thirtytwobits]

If it's runtime then this is even more inappropriate.

1. For most embedded systems there is no shell.
2. If you were developing a GUI environment variables are not appropriate. I know on Windows this has been a pain in the past where some GUI needed environment variables and you had to go through arcane and painful steps to add these to the user environment before you launched the application.

[pavel-kirienko]

Deeply embedded systems and GUI software are not the applications that this feature is intended for. Instead, it is aimed at software nodes executed in a relatively high-level/POSIX-like OS (e.g., NuttX or GNU/Linux running on an embedded computer on the vehicle). The first kind (deep embedded) is likely to rely on very application-specific means of configuration and the latter can just request the user to enter the required parameters explicitly. This is to be understood as a way to instantiate node processes with specific configuration per-instance.

[thirtytwobits]

FIne. I don't know how many ways I can say I don't like the design but it's your call here.