-
-
Notifications
You must be signed in to change notification settings - Fork 95
/
384.Access.1.0.dsdl
247 lines (237 loc) · 14 KB
/
384.Access.1.0.dsdl
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
# 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.
#
# ---------------------------------------------------------------------------------------------------------------------
Name.1.0 name
# The name of the accessed register. Shall not be empty.
# Use the List service to obtain the list of registers on the node.
Value.1.0 value
# Value to be written. Empty if no write is required.
@sealed
---
uavcan.time.SynchronizedTimestamp.1.0 timestamp
# The moment of time when the register was read (not written).
# Zero if the server does not support timestamping.
bool mutable
# Mutable means that the register can be written using this service.
# Immutable registers cannot be written, but that doesn't imply that their values are constant (unchanging).
bool persistent
# Persistence means that the register retains its value permanently across power cycles or any other changes
# in the state of the server, until it is explicitly overwritten (either via Cyphal, any other interface,
# or by the device itself).
#
# The server is recommended to manage persistence automatically by committing changed register values to a
# non-volatile storage automatically as necessary. If automatic persistence management is not implemented, it
# can be controlled manually via the standard service uavcan.node.ExecuteCommand. The same service can be used
# to return the configuration to a factory-default state. Please refer to its definition for more information.
#
# Consider the following examples:
# - Configuration parameters are usually both mutable and persistent.
# - Diagnostic values are usually immutable and non-persisient.
# - Registers that trigger an activity when written are typically mutable but non-persisient.
# - Registers that contain factory-programmed values such as calibration coefficients that can't
# be changed are typically immutable but persistent.
void6
Value.1.0 value
# The value of the register when it was read (beware of race conditions).
# Registers never change their type and dimensionality while the node is running.
# Empty value means that the register does not exist (in this case the flags should be cleared/ignored).
# By comparing the returned value against the write request the caller can determine whether the register
# was written successfully, unless write was not requested.
# An empty value shall never be returned for an existing register.
@sealed