Struct canadensis_data_types::uavcan::register::access_1_0::AccessRequest

pub struct AccessRequest {
    pub name: Name,
    pub value: Value,
}

uavcan.register.Access.1.0

Size ranges from 2 to 515 bytes

Registers are strongly-typed named values used to store the configuration parameters of a node. This service is used to write and read a register.

READ/WRITE BEHAVIORS

The write operation is performed first, unless skipped by sending an empty value in the request. The server may attempt to convert the type of the supplied value to the correct type if there is a type mismatch (e.g. uint8 may be converted to uint16); however, servers are not required to perform implicit type conversion, and the rules of such conversion are not explicitly specified, so this behavior should not be relied upon.

On the next step the register will be read regardless of the outcome of the write operation. As such, if the write operation could not be performed (e.g. due to a type mismatch or any other issue), the register will retain its old value. By evaluating the response the caller can determine whether the register was written successfully.

The write-read sequence is not guaranteed to be atomic, meaning that external influences may cause the register to change its value between the write and the subsequent read operation. The caller is responsible for handling that case properly.

The timestamp provided in the response corresponds to the time when the register was read. The timestamp may be empty if the server does not support timestamping or its clock is not (yet) synchronized with the network.

If only read is desired, but not write, the caller shall provide a value of type ‘empty’. That will signal the server that the write operation shall be skipped, and it will proceed to read the register immediately.

If the requested register does not exist, the write operation will have no effect and the returned value will be empty. Existing registers should not return ‘empty’ when read since that would make them indistinguishable from nonexistent registers.

REGISTER DEFINITION REQUIREMENTS

Registers shall never change their type or flags as long as the server is running. Meaning that:

• Mutability and persistence flags cannot change their states.
• Read operations shall always return values of the same type and same dimensionality. The dimensionality requirement does not apply to inherently variable-length values such as strings and unstructured chunks.

Register name should contain only:

• Lowercase ASCII alphanumeric characters (a-z, 0-9)
• Full stop (.)
• Low line (underscore) (_) With the following limitations/recommendations:
• The name shall not begin with a decimal digit (0-9).
• The name shall neither begin nor end with a full stop.
• A low line shall not be followed by a non-alphanumeric character.
• The name should contain at least one full stop character. Other patterns and ASCII characters are reserved for special function registers (introduced below).

ENVIRONMENT VARIABLES

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

When a software node is launched, it is usually necessary to provide some of its configuration information early, particularly that which is related to Cyphal networking, before the node is started. Environment variables offer a convenient way of addressing this. Software nodes that support the register interface should evaluate the available environment variables during initialization and update their registers (whether they are stored in a persistent storage or in memory) accoringly. This should be completed before the first register read access.

A register name is mapped to an environment variable name as follows:

• the name is upper-cased;
• full stop characters are replaced with double low line characters. For example: ‘motor.inductance_dq’ is mapped to ‘MOTOR__INDUCTANCE_DQ’.

Register values are represented in environment variables as follows:

• string: utf-8 or platform-specific
• unstructured: as-is
• bit, integer*, natural*, real*: space-separated decimals

If an environment variable matches the name of an existing register but its value cannot be converted to the register’s type, an error should be raised.

If an environment variable does not match the name of any register, it may be ignored. However, if the implementation can reliably deduce the type and purpose of the register, it may create one automatically. This provision is to support applications where the register schema may be altered by configuration.

SPECIAL FUNCTION REGISTERS

The following optional special function register names are defined:

• suffix ‘<’ is used to define an immutable persistent value that contains the maximum value of the respective register.
• suffix ‘>’ is like above, used to define the minimum value of the respective register.
• suffix ‘=’ is like above, used to define the default value of the respective register.
• prefix ‘*’ is reserved for raw memory access (to be defined later). Examples:
• register name “system.parameter”
• maximum value is contained in the register named “system.parameter<” (optional)
• minimum value is contained in the register named “system.parameter>” (optional)
• default value is contained in the register named “system.parameter=” (optional)

The type and dimensionality of the special function registers containing the minimum, maximum, and the default value of a register shall be the same as those of the register they relate to.

If a written value exceeds the minimum/maximum specified by the respective special function registers, the server may either adjust the value automatically, or to retain the old value, depending on which behavior suits the objectives of the application better. The values of registers containing non-scalar numerical entities should be compared elementwise.

STANDARD REGISTERS

The following table specifies the register name patterns that are reserved by the specification for common functions. These conventions are not mandatory to follow, but implementers are recommended to adhere because they enable enhanced introspection capabilities and simplify device configuration and diagnostics.

REGISTER NAME PATTERN TYPE FLAGS RECOMMENDED DEFAULT

uavcan.node.id natural16[1] mutable, persistent 65535 (unset/PnP)

Contains the node-ID of the local node. Values above the maximum valid node-ID for the current transport indicate that the node-ID is not set; if plug-and-play is supported, it will be used by the node to obtain an automatic node-ID. Invalid values other than 65535 should be avoided for consistency.

---

uavcan.node.description string mutable, persistent (empty)

User/integrator-defined, human-readable description of this specific node. This is intended for use by a system integrator and should not be set by the manufacturer of a component. For example: on a quad-rotor drone this might read “motor 2” for one of the ESC nodes.

---

uavcan.pub.PORT_NAME.id natural16[1] mutable, persistent 65535 (unset, invalid) uavcan.sub.PORT_NAME.id ditto ditto ditto uavcan.cln.PORT_NAME.id ditto ditto ditto uavcan.srv.PORT_NAME.id ditto ditto ditto

Publication/subscription/client/server port-ID, respectively. These registers are configured by the system integrator or an autoconfiguration authority when the node is first connected to a network.

The “PORT_NAME” defines the human-friendly name of the port, which is related to the corresponding function or a network service supported by the node. The name shall match the following POSIX ERE expression:

[a-zA-Z_][a-zA-Z0-9_.]*

The names are defined by the vendor of the node. The user/integrator is expected to understand their meaning and relation to the functional capabilities of the node by reading the technical documentation provided by the vendor.

A port whose port-ID register is unset (invalid value) remains inactive (unused); the corresponding function may be disabled. For example, a register named “uavcan.pub.measurement.id” defines the subject-ID of a measurement published by this node; if the register contains an invalid value (above the maximum valid subject-ID), said measurement is not published.

The same name is used in other similar registers defined below. Network introspection and autoconfiguration tools will expect to find a register of this form for every configurable port supported by the node.

---

uavcan.pub.PORT_NAME.type string immutable, persistent N/A uavcan.sub.PORT_NAME.type ditto ditto ditto uavcan.cln.PORT_NAME.type ditto ditto ditto uavcan.srv.PORT_NAME.type ditto ditto ditto

Publication/subscription/client/server full data type name and dot-separated version numbers, respectively. These registers are set by the vendor once and typically they are to remain unchanged (hence “immutable”). The “PORT_NAME” defines the human-friendly name of the port as specified above. For example, a register named “uavcan.pub.measurement.type” may contain “uavcan.si.sample.angle.Quaternion.1.0”.

---

uavcan.diagnostic.*

Prefix reserved for future use.

---

uavcan.can.bitrate natural32[2] implementation-defined implementation-defined uavcan.can.iface string mutable, persistent implementation-defined

These registers are only relevant for nodes that support Cyphal/CAN.

uavcan.can.bitrate defines the CAN bus bit rate: the first value is the arbitration bit rate, the second is the data phase bit rate. Nodes that support only Classic CAN should ignore the second value. Nodes that support CAN FD should initialize in the Classic CAN mode (MTU 8 bytes, BRS flag not set) if the values are equal. If CAN bitrate is not configurable or is always auto-detected, this register may be omitted or made immutable; otherwise it should be mutable and persistent.

uavcan.can.iface is only relevant for software nodes or nodes that are capable of using different CAN interfaces. The value is a space-separated list of CAN interface names to use. The name format is implementation-defined (for example, “can0”).

---

uavcan.udp.*

Prefix reserved for future use.

———————————————————————————————————————#

uavcan.serial.*

Prefix reserved for future use.

---

Fields

name: Name

The name of the accessed register. Shall not be empty. Use the List service to obtain the list of registers on the node.

uavcan.register.Name.1.0

Always aligned, size ranges from 8 to 2048 bits

value: Value

Value to be written. Empty if no write is required.

uavcan.register.Value.1.0

Always aligned, size ranges from 8 to 2072 bits

Trait Implementations

impl DataType for AccessRequest

const EXTENT_BYTES: Option<u32> = None

This type is sealed.

impl Deserialize for AccessRequest

fn deserialize(cursor: &mut ReadCursor<'_>) -> Result<Self, DeserializeError>where Self: Sized,

Deserializes a value and returns it

fn deserialize_from_bytes(bytes: &[u8]) -> Result<Self, DeserializeError>where Self: Sized,

A convenience function that creates a cursor around the provided bytes and calls deserialize

impl Serialize for AccessRequest

fn size_bits(&self) -> usize

Returns the size of the encoded form of this value, in bits

fn serialize(&self, cursor: &mut WriteCursor<'_>)

Serializes this value into a buffer

fn serialize_to_bytes(&self, bytes: &mut [u8])

A convenience function that creates a cursor around the provided bytes and calls serialize

impl Request for AccessRequest