Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Server capabilities update #33

Merged
merged 3 commits into from
Nov 28, 2024
Merged

Server capabilities update #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
63e24c6
Server capabilities update
UlfBj Nov 28, 2024
08ae9ed
Merge branch 'main' of https://github.com/UlfBj/vehicle-information-s…
UlfBj Nov 28, 2024
43b94a9
Merge branch 'COVESA:main' into main
UlfBj Nov 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 74 additions & 26 deletions spec/VISSv3.0_Core.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1833,8 +1833,7 @@ <h2>File Transfer</h2>
File transfer use cases, where a client either sends or receives a file from the vehicle server,
can e. g. be a client that wants to push a map to the vehicle, or a client that wants to receive a video recording clip from the vehicle.<br>
File resources reprsented in the VSS tree can either be read-only, represented by the sensor node type,
or read-write, represented by the actuator node type. In either case the node datatype MUST be "filedescriptor",
which is a struct datatype with the following fixed definition:
or read-write, represented by the actuator node type. In either case the node datatype MUST be a reference to a struct datatype with the following fixed definition:
<pre><code>
typedef FileDescriptor struct {
name string
Expand Down Expand Up @@ -1927,7 +1926,20 @@ <h2>File Transfer</h2>
the chunk size to zero, and the last message to non-zero, on which the server shall respond with status set to zero.<br>
A file upload session is terminated by the client by issuing a message with the message number set to 255 and the status set to non-zero.<br>
The node type for the file resource MUST be "actuator" for the download case and "sensor" for the upload case.
This node must have a fixed datatype, a struct with the members "name", "hash", and "size".
This node must have a fixed datatype, a struct with the members "name", "hash", and "size".<br>
Examples of tree nodes for file download and upload, respectively:
<pre><code>
DownloadFile:
type: actuator
datatype: Types.Resources.FileDescriptor
description: File that may be downloaded to the vehicle.

UploadFile:
type: sensor
datatype: Types.Resources.FileDescriptor
description: File stored at the vehicle that may be uploaded to a client.
</code></pre>
The Types.Resources.FileDescriptor definition in the Types tree must mirror the struct definition above.
</p>
<h3>Data channel realization</h3>
<p>
Expand All @@ -1941,7 +1953,6 @@ <h3>Data channel realization</h3>
</ul>
The recommended mechanism for MQTT is to assing a separate topic name to the data channel.
The recommended topic name is created by appending "/datachannel" to the topic name of the control channel.
Examples for Websockets and MQTT are found in the [[viss3-transport-examples]] specification.
</p>
<h3>Alternative based on well-known file transfer protocols</h3>
<p>
Expand Down Expand Up @@ -1985,7 +1996,7 @@ <h2>JSON Schema</h2>
<h2>Server Capabilities</h2>
<p>
A client that wants to connect to a server may be interested in what capabilities the server offers.
The server maintains a separate Server tree which the client can access for this purpose.
The server shall maintain a separate Server tree which the client can access for this purpose to find out about optional features.
However, for the client to access this information it must have information about at least one transport protocol that the server supports.
The VISS API should not make any assumptions on the communication network topology.
Therefore it should not mandate any transport protocol, instead it should assume that a client can obtain necessary information via out-of-band means
Expand All @@ -2011,23 +2022,27 @@ <h3>Server Tree Example</h3>
<pre><code>
<embed type="text/yaml" src="resources/server.txt" width="700" height="500">
</code></pre>
A feature that is supported in at least one configuration shall be registered on the Support branch.
The Config branch shall contain the information needed for a client to utilize the feature,
for all configurations that has the feature supported.
If a server e. g. supports file transfer upload and download then this shall be found at the Support branch,
and then on the Config branch it shall be registered for which transport protocol(s) it is supported, and e. g. which port number is then used.

<h3>Server Feature Naming</h3>
<p>
The feature names that are used in the Server tree should for the features described in this specification use the names listed below.

<h4>Support Naming</h4>
<table style="width:50%">
<tr>
<th>Protocol</th>
<th>Description</th>
</tr>
<tr>
<td><u>http</u></td>
<td>http</td>
<td>[[viss3-transport-examples]], Transport Protocol Examples:<a data-link-type="dfn" href="https://raw.githack.com/COVESA/vehicle-information-service-specification/main/spec/VISSv3.0_TransportExamples.html#https">HTTPS</a> chapter</td>
</tr>
<tr>
<td><u>ws</u></td>
<td>ws</td>
<td>[[viss3-transport-examples]], Transport Protocol Examples:<a data-link-type="dfn" href="https://raw.githack.com/COVESA/vehicle-information-service-specification/main/spec/VISSv3.0_TransportExamples.html#secure-websockets">Secure Websocket</a> chapter</td>
</tr>
<tr>
Expand All @@ -2040,32 +2055,17 @@ <h4>Support Naming</h4>
</tr>
</table><br>

<table style="width:60%">
<tr>
<th>Security</th>
<th>Description</th>
</tr>
<tr>
<td>accesscontrol</td>
<td><a href="#access-control-model"></a></td>
</tr>
<tr>
<td>consent</td>
<td><a href="#consent-support"></a></td>
</tr>
</table><br>

<table style="width:50%">
<tr>
<th>Filter</th>
<th>Description</th>
</tr>
<tr>
<td><u>timebased</u></td>
<td>timebased</td>
<td><a href="#timebased-filter-operation"></a></td>
</tr>
<tr>
<td><u>change</u></td>
<td>change</td>
<td><a href="#change-filter-operation"></a></td>
</tr>
<tr>
Expand All @@ -2090,7 +2090,55 @@ <h4>Support Naming</h4>
</tr>
</table><br>

<h4>Config Naming</h4>
<table style="width:50%">
<tr>
<th>File transfer</th>
<th>Description</th>
</tr>
<tr>
<td>download</td>
<td>File download to vehicle</td>
</tr>
<tr>
<td>upload</td>
<td>File upload to client</td>
</tr>
</table><br>

<table style="width:50%">
<tr>
<th>Data compression</th>
<th>Description</th>
</tr>
<tr>
<td>pathuid</td>
<td>Static UID path compresion</td>
</tr>
<tr>
<td>pathlocal</td>
<td>Request local path compression</td>
</tr>
<tr>
<td>timestamplocal</td>
<td>Response local timestamp compression</td>
</tr>
</table>

<table style="width:60%">
<tr>
<th>Security</th>
<th>Description</th>
</tr>
<tr>
<td>accesscontrol</td>
<td><a href="#access-control-model"></a></td>
</tr>
<tr>
<td>consent</td>
<td><a href="#consent-support"></a></td>
</tr>
</table><br>

<table style="width:50%">
<tr>
<th>Access Control Flow</th>
Expand Down
20 changes: 20 additions & 0 deletions spec/resources/server.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,21 @@ Server.Support.Filter:
datatype: string[]
description: List of supported filter features.

Server.Support.Encoding:
type: attribute
datatype: string[]
description: List of supported payload encoding features.

Server.Support.Filetransfer:
type: attribute
datatype: string[]
description: List of supported file transfer features.

Server.Support.DataCompression:
type: attribute
datatype: string[]
description: List of supported data compression features.

Server.Config:
type: branch
description: Top branch declaring the configuration of server supported features.
Expand Down Expand Up @@ -94,6 +109,11 @@ Server.Config.Protocol.Mqtt.Protobuf.Topic:
datatype: string
description: MQTT topic name for the protobuf encoded payload format.

Server.Config.Protocol.Mqtt.Protobuf.DataCompression:
type: attribute
datatype: string[]
description: List of supported data compression variants.

Server.Config.Protocol.Grpc:
type: branch
description: Top branch for the server supported gRPC protocol.
Expand Down