diff --git a/resources/DataTypes.vspec b/resources/DataTypes.vspec new file mode 100644 index 00000000..59f2d486 --- /dev/null +++ b/resources/DataTypes.vspec @@ -0,0 +1,38 @@ +# Copyright (c) 2016 Contributors to COVESA +# +# This program and the accompanying materials are made available under the +# terms of the Mozilla Public License 2.0 which is available at +# https://www.mozilla.org/en-US/MPL/2.0/ +# +# SPDX-License-Identifier: MPL-2.0 + +# +# Root Datatypes file +# + +Types: + type: branch + description: Root node for the Types tree. + +Types.Resources: + type: branch + description: Vehicle resource types branch + +Types.Resources.FileDescriptor: + type: struct + description: File descriptor struct definition. + +Types.Resources.FileDescriptor.Name: + type: property + datatype: string + description: File name incl file extension. + +Types.Resources.FileDescriptor.Hash: + type: property + datatype: string + description: Hash calculated on file. + +Types.Resources.FileDescriptor.Uid: + type: property + datatype: string + description: Uid to identify up/download session. diff --git a/resources/Makefile b/resources/Makefile new file mode 100644 index 00000000..6d490af9 --- /dev/null +++ b/resources/Makefile @@ -0,0 +1,95 @@ +# +# Makefile to generate specifications +# + +.PHONY: clean all mandatory_targets json franca yaml csv ddsidl tests binary protobuf ttl graphql ocf c overlays id jsonschema + +all: clean mandatory_targets optional_targets + +# All mandatory targets that shall be built and pass on each pull request for +# vehicle-signal-specification or vss-tools +mandatory_targets: clean json json-noexpand franca yaml binary csv graphql ddsidl id jsonschema apigear samm overlays + +# Additional targets that shall be built by travis, but where it is not mandatory +# that the builds shall pass. +# This is typically intended for less maintainted tools that are allowed to break +# from time to time +# Can be run from e.g. travis with "make -k optional_targets || true" to continue +# even if errors occur and not do not halt travis build if errors occur +optional_targets: clean protobuf ttl + +TOOLSDIR?=./vss-tools +VSS_VERSION ?= 0.0 +#COMMON_ARGS=-u ./spec/units.yaml --strict +COMMON_ARGS=-u ./spec/units.yaml +COMMON_VSPEC_ARG=-s ./spec/VehicleSignalSpecification.vspec +#COMMON_VSPEC_ARG=-s ./spec/ServerSignalSpecification.vspec +TYPETREE = none +ifeq ($(TYPETREE), none) + TYPETREE_ARG = +else + TYPETREE_ARG = -t ./spec/${TYPETREE} --types-output vss-datatypes.$@ +endif +NEWKEY = none +ifeq ($(NEWKEY), none) + NEWKEY_ARG = +else + NEWKEY_ARG = -e $(NEWKEY) +endif +json: + vspec export json ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.json + +json-noexpand: + vspec export json ${COMMON_ARGS} --no-expand ${COMMON_VSPEC_ARG} -o vss_noexpand.json + +jsonschema: + vspec export jsonschema ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.jsonschema + +franca: + vspec export franca --franca-vss-version $(VSS_VERSION) ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.fidl + +yaml: + vspec export yaml ${TYPETREE_ARG} ${COMMON_ARGS} ${COMMON_VSPEC_ARG} ${NEWKEY_ARG} -o vss.yaml +# vspec export yaml ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.yaml + +csv: + vspec export csv ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.csv + +ddsidl: + vspec export ddsidl ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.idl + +# Verifies that supported overlay combinations are syntactically correct. +overlays: + vspec export json ${COMMON_ARGS} -l overlays/profiles/motorbike.vspec ${COMMON_VSPEC_ARG} -o vss_motorbike.json + vspec export json ${COMMON_ARGS} -l overlays/extensions/dual_wiper_systems.vspec ${COMMON_VSPEC_ARG} -o vss_dualwiper.json + vspec export json ${COMMON_ARGS} -l overlays/extensions/OBD.vspec ${COMMON_VSPEC_ARG} -o vss_obd.json + +binary: +# vspec export binary ${COMMON_ARGS} ${COMMON_VSPEC_ARG} ${NEWKEY_ARG} -o vss.binary + vspec export binary ${TYPETREE_ARG} ${COMMON_ARGS} ${COMMON_VSPEC_ARG} ${NEWKEY_ARG} -o vss.binary + +protobuf: + vspec export protobuf ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.proto + +graphql: + vspec export graphql ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.graphql.ts + +apigear: + vspec export apigear ${COMMON_ARGS} ${COMMON_VSPEC_ARG} --output-dir apigear + cd apigear && tar -czvf ../vss_apigear.tar.gz * && cd .. + +samm: + vspec export samm ${COMMON_ARGS} ${COMMON_VSPEC_ARG} --target-folder samm + cd samm && tar -czvf ../vss_samm.tar.gz * && cd .. + +# vspec2ttl does not use common generator framework +ttl: + ${TOOLSDIR}/contrib/vspec2ttl/vspec2ttl.py -u ./spec/units.yaml ./spec/VehicleSignalSpecification.vspec vss.ttl + +id: + vspec export id ${COMMON_ARGS} ${COMMON_VSPEC_ARG} -o vss.vspec + +clean: + rm -f vss.* + rm -rf apigear + rm -rf samm diff --git a/scripts/copyBins.sh b/scripts/copyBins.sh deleted file mode 100755 index 8728e8a8..00000000 --- a/scripts/copyBins.sh +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash - -helpFunction() -{ - echo "" - echo "Usage: $0 -u user -s server -p path" - echo -e "\t-u Server username" - echo -e "\t-s Server URL" - echo -e "\t-p folder/path on the server (/home/user/folder/)" - exit 1 # Exit script after printing help -} - -while getopts "u:s:p:" opt -do - case "$opt" in - u ) username="$OPTARG" ;; - s ) server="$OPTARG" ;; - p ) path="$OPTARG" ;; - ? ) helpFunction ;; # Print helpFunction in case parameter is non-existent - esac -done - -# Print helpFunction in case parameters are empty -if [ -z "$username" ] || [ -z "$server" ] || [ -z "$path" ] -then - echo "Some or all of the parameters are empty"; - helpFunction -fi - -cmd="rsync -avzhe ssh" -echo $(pwd) -$cmd puppi.sh $username@$server:$path -cd .. #move to project root -dir=$(pwd) -echo $dir -cd server/server-core && go build -o servercore -$cmd servercore vss_rel_2.0.0-alpha+006.cnative $username@$server:$path -cd $dir - -cd server/servicemgr && go build -o servicemgr -$cmd servicemgr $username@$server:$path -cd $dir - -cd server/wsmgr && go build -o wsmgr -$cmd wsmgr $username@$server:$path -cd $dir - -cd server/httpmgr && go build -o httpmgr -$cmd httpmgr $username@$server:$path -cd $dir - -cd client/client-1.0/Go && go build -o agtserver -$cmd agtserver $username@$server:$path -cd $dir - -cd server/atserver && go build -o atserver -$cmd atserver $username@$server:$path -cd $dir - diff --git a/scripts/httpmanager.sh b/scripts/httpmanager.sh deleted file mode 100755 index 461c0bbb..00000000 --- a/scripts/httpmanager.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash -e -cd server/httpmgr -./http_mgr -cd .. -cd .. diff --git a/scripts/puppi.sh b/scripts/puppi.sh deleted file mode 100755 index 15b18242..00000000 --- a/scripts/puppi.sh +++ /dev/null @@ -1,40 +0,0 @@ -#!/bin/bash - -usage() { - echo "usage: $0 startme|stopme" >&2 -} - -startme() { - stopme #stoping zombie screens before starting new ones - echo "starting ..." - screen -dmS servercore ./servercore - sleep 5s - screen -dmS servicemgr ./servicemgr - screen -dmS wsmgr ./wsmgr - screen -dmS httpmgr ./httpmgr - screen -dmS agtserver ./agtserver - screen -dmS atserver ./atserver -} - -stopme() { - screen -X -S atserver quit - screen -X -S agtserver quit - screen -X -S httpmgr quit - screen -X -S wsmgr quit - screen -X -S servicemgr quit - screen -X -S servercore quit -} - -if [ $# -ne 1 ] - then - usage $0 - exit 1 -fi - -case "$1" in - startme) startme ;; - stopme) stopme ;; - *) usage - exit 1 - ;; -esac diff --git a/scripts/servercore.sh b/scripts/servercore.sh deleted file mode 100755 index 5ffec89b..00000000 --- a/scripts/servercore.sh +++ /dev/null @@ -1,6 +0,0 @@ -#!/bin/bash -cd server/server-core -./server-core -cd .. -cd .. -echo server core script executed. diff --git a/scripts/servicemanager.sh b/scripts/servicemanager.sh deleted file mode 100755 index 2d076881..00000000 --- a/scripts/servicemanager.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash -e -cd server/servicemgr -./service_mgr -cd .. -cd .. diff --git a/scripts/wsmanager.sh b/scripts/wsmanager.sh deleted file mode 100755 index e1c92b05..00000000 --- a/scripts/wsmanager.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/bin/bash -e -cd server/wsmgr -./ws_mgr -cd .. -cd .. diff --git a/tutorial/content/server/Access-control-servers/_index.md b/tutorial/content/server/Access-control-servers/_index.md index 7835684c..1778692c 100644 --- a/tutorial/content/server/Access-control-servers/_index.md +++ b/tutorial/content/server/Access-control-servers/_index.md @@ -1,5 +1,5 @@ --- -title: "VISSv2 Access Control Servers" +title: "VISSR Access Control Servers" --- The [VISSv2 access control model](https://raw.githack.com/covesa/vehicle-information-service-specification/main/spec/VISSv2_Core.html#access-control-model) specifies two authorization servers: diff --git a/tutorial/content/server/_index.md b/tutorial/content/server/_index.md index 12e5c2fe..dee25a13 100644 --- a/tutorial/content/server/_index.md +++ b/tutorial/content/server/_index.md @@ -2,7 +2,7 @@ title: "VISSR Server" --- -The VISSv2 server is the Sw component that implements the interface that is exposed to the clients, and that must conform to the COVESA VISSv2 specification. +The VISSR server is the Sw component that implements the interface that is exposed to the clients, and that must conform to the COVESA VISSv2 specification. ## Build the server Please check the chapter [VISSv2 Build System](/vissr/build-system) for general Golang information. @@ -17,75 +17,7 @@ $ go build The server has a copy of the VSS tree that it uses to verify that client requsts are valid - that there is a node in the tree that corresponds to the path in a request, if a node requires an access control token and consent permission, etc. The tree parser that is used expects the tree to have the 'binary format' that the binary exporter of the VSS-Tools generates from the vspec files. - -### Using the VSS project to generate the binary file -This requires that the [VSS](https://github.com/COVESA/vehicle_signal_specification) repo is cloned and configured, for th latter see instructions on the repo. -To generate the binary file the make file in the root directory of the repo is used, -which requires that a Python virtual environment is configured before it is used for the first time. -This is done by entering the VSS root directory, then issuing a command to configure the environment, -and then activating it, installing the vss-tools, and deactivate it. -``` -$ cd vehicle_signal_specification -$ python3 -m venv ~/.venv -$ source ~/.venv/bin/activate -(.venv)$ pip install --pre vss-tools -(.venv)$ deactivate -``` -The above is only needed to be done once. -It might be necessary to install both python and pip if that is not already installed on the computer, see instructions in the repo documentation. - -To then generate the VSS tree binary file the environment is activated, the make file is called to generate the binary file, -and then the environment can be deactivated. -``` -$ source ~/.venv/bin/activate -(.venv)$ make binary -(.venv)$ deactivate -``` -This generates a file with a name like 'vss.binary', -which then needs to be possibly renamed to a more descriptive name and then copied to the vissr/server/vissv2server/forest directory. -It must also be added to the viss.him file in the same directory for the server to include it at startup. - -### Using the CVIS project to generate the binary file -Another alternative for generating the binary file is to use the HIM configurator tool in the -[Commercial Vehicle Information Specifications](https://github.com/COVESA/commercial-vehicle-information-specifications) repo. -The CVIS project is aiming at creating signal trees tailored to the needs of other vehicle types than the passenger cars that the VSS tree is focusing on. -Development is ongoing for the vehicle types Truck, Trailer, and Bus, but the project is open for development initiatives for other vehicle types. -Following the patterns and rules described on the repo it is reasonably straight forward to create your own tree on your local computer. - -The generation of a binary tree from the vspec files is here done by using the HIM configurator tool. -It uses the VSS-tools exporters for the final step of generating the files, -providing extended tree configuration options, see the [CVIS](https://covesa.github.io/commercial-vehicle-information-specifications/) documentation. -There it is also described how the same Python virtual environment as is used in the VSS alternative is configured (if not already done so in a VSS context) -and activated before using the HIM configurator. -ust as in the oher alternative the binary file needs to be copied to the vissr/server/vissv2server/forest directory, -and the viss.him file edited to include it. - -### Tagging the tree for access control and consent management -If you want to configure the tree to include access control, access control tags as described in the -[VISSv2 - Access Control Selection chapter](https://raw.githack.com/covesa/vehicle-information-service-specification/main/spec/VISSv2_Core.html#access-control-selection) needs to be added to appropriate tree nodes. -This can either be done by editing vspec files directly (example below), or using the [VSS-Tools](https://github.com/covesa/vss-tools) overlay mechanism. - -Adding read-write access control and consent to the entire VSS tree can be done by modifying the root node in the spec/VehicleSignalSpecification.vspec file as shown below. -If consent should not be included then the commented line should be used instead. -``` -Vehicle: - type: branch - validate: read-write+consent -# validate: read-write - description: High-level vehicle data. -``` -The above validate statement is inherited by all of the descendants of the node. -It can be applied to any node in the tree to allow for some nodes to not be access controlled while others will be access controlled. -Changing read-write to write-only leads to that the server will allow reading of the data without a token, -but requiring a valid token for write requests to the data. - -If the HIM configurator in the CVIS project is used to generate the binary tree that has been tagged as described a binary tree with the tagging data will be generated. -In the case that it is the alternative using the VSS support that is used then it is necessary to also manually edit the make file to add '-e validate' -in the calls to the exporters. This should be added just before the output file name in the command, c. f. how it is added in the -[overlay example](https://covesa.github.io/vehicle_signal_specification/rule_set/overlay/index.html). - -The AT server uses the purposelist.json file to validate that a client request to access controlled data is permitted by the access token included in the request. -It therefore necessary to ensure that this file contains purpose(s) that includes the data that is access controlled tagged in the tree. +More information about tree configuration [here](/vissr/server/binary-tree-config/). ## Command line configuration Starting the server with the command line option -h will show the screen below. diff --git a/tutorial/content/server/binary-tree-config/_index.md b/tutorial/content/server/binary-tree-config/_index.md new file mode 100644 index 00000000..a2c7b5a9 --- /dev/null +++ b/tutorial/content/server/binary-tree-config/_index.md @@ -0,0 +1,109 @@ +--- +title: "VISSR binary tree configuration" +--- + +## Using the VSS project to generate the binary file +This requires that the [VSS](https://github.com/COVESA/vehicle_signal_specification) repo is cloned and configured, for th latter see instructions on the repo. +To generate the binary file the make file in the root directory of the repo is used, +which requires that a Python virtual environment is configured before it is used for the first time. +This is done by entering the VSS root directory, then issuing a command to configure the environment, +and then activating it, installing the vss-tools, and deactivate it. +``` +$ cd vehicle_signal_specification +$ python3 -m venv ~/.venv +$ source ~/.venv/bin/activate +(.venv)$ pip install --pre vss-tools +(.venv)$ deactivate +``` +The above is only needed to be done once. +It might be necessary to install both python and pip if that is not already installed on the computer, see instructions in the repo documentation. +If the exporter complains when used to make the binary file also after following the instructions above, then adding the command +``` +(.venv)$ pip install -e . +``` +may fix it. If problems prevail it is probably necessary to create an issue at the VSS repo. + +To then generate the VSS tree binary file the environment is activated, the make file is called to generate the binary file, +and then the environment can be deactivated. +``` +$ source ~/.venv/bin/activate +(.venv)$ make binary +(.venv)$ deactivate +``` +This generates a file with a name like 'vss.binary', +which then needs to be possibly renamed to a more descriptive name and then copied to the vissr/server/vissv2server/forest directory. +It must also be added to the viss.him file in the same directory for the server to include it at startup. + +## Using the CVIS project to generate the binary file +Another alternative for generating the binary file is to use the HIM configurator tool in the +[Commercial Vehicle Information Specifications](https://github.com/COVESA/commercial-vehicle-information-specifications) repo. +The CVIS project is aiming at creating signal trees tailored to the needs of other vehicle types than the passenger cars that the VSS tree is focusing on. +Development is ongoing for the vehicle types Truck, Trailer, and Bus, but the project is open for development initiatives for other vehicle types. +Following the patterns and rules described on the repo it is reasonably straight forward to create your own tree on your local computer. + +The generation of a binary tree from the vspec files is here done by using the HIM configurator tool. +It uses the VSS-tools exporters for the final step of generating the files, +providing extended tree configuration options, see the [CVIS](https://covesa.github.io/commercial-vehicle-information-specifications/) documentation. +There it is also described how the same Python virtual environment as is used in the VSS alternative is configured (if not already done so in a VSS context) +and activated before using the HIM configurator. +ust as in the oher alternative the binary file needs to be copied to the vissr/server/vissv2server/forest directory, +and the viss.him file edited to include it. + +## Tagging the tree for access control and consent management +If you want to configure the tree to include access control, access control tags as described in the +[VISSv2 - Access Control Selection chapter](https://raw.githack.com/covesa/vehicle-information-service-specification/main/spec/VISSv2_Core.html#access-control-selection) needs to be added to appropriate tree nodes. +This can either be done by editing vspec files directly (example below), or using the [VSS-Tools](https://github.com/covesa/vss-tools) overlay mechanism. + +Adding read-write access control and consent to the entire VSS tree can be done by modifying the root node in the spec/VehicleSignalSpecification.vspec file as shown below. +If consent should not be included then the commented line should be used instead. +``` +Vehicle: + type: branch + validate: read-write+consent +# validate: read-write + description: High-level vehicle data. +``` +The above validate statement is inherited by all of the descendants of the node. +It can be applied to any node in the tree to allow for some nodes to not be access controlled while others will be access controlled. +Changing read-write to write-only leads to that the server will allow reading of the data without a token, +but requiring a valid token for write requests to the data. + +If the HIM configurator in the CVIS project is used to generate the binary tree that has been tagged as described a binary tree with the tagging data will be generated. +In the case that it is the alternative using the VSS support that is used then it is necessary to also manually edit the make file to add '-e validate' +in the calls to the exporters. This should be added just before the output file name in the command, c. f. how it is added in the +[overlay example](https://covesa.github.io/vehicle_signal_specification/rule_set/overlay/index.html). + +The AT server uses the purposelist.json file to validate that a client request to access controlled data is permitted by the access token included in the request. +It therefore necessary to ensure that this file contains purpose(s) that includes the data that is access controlled tagged in the tree. + +## Using a modified make file +The make file in the [VSS](https://github.com/COVESA/vehicle_signal_specification) repo does not provide +CLI support for inserting validate tags or using struct datatypes that refer to a separate Type definition tree, +which leads to that the make file must be manually edited. +To avoid having to enter into such daring endeavours a modified make file can be found in the resource directory. +If this file replaces the existing VSS make file then it can be used as explained below when using the VSS as decribed above. +The CVIS project is currently not updated to use this file. + +## Inserting 'validate' tags +Adding the CLI parameter NEWKEY=validate will instruct the binary exporter that it shall accept any lines with this keyword in the vspec files. +Before running the command below these lines must be manually edited into the desired nodes. +``` +(.venv)$ make binary NEWKEY=validate +``` + +## Using the struct datatype +The [VSS rule set](https://covesa.github.io/vehicle_signal_specification/rule_set/data_entry/data_types_struct/index.html#general-idea-and-basic-semantics) +defines that struct datatypes shall be defined in a separate type definition tree that the 'datatype' key references, see example below. +``` +DownloadFile: + type: actuator + datatype: Types.Resources.FileDescriptor +# default: {"name":"downloadfile.txt", "hash":"20e87e71b6948d6e6dd11d776e9be79c374751bb", "uid":"1d878212") + description: File to be used by the vehicle. Default contains internal filesystem path. +``` +The type tree for the example above is found in the resources directory. +If the type tree is stored in the root directory of the VSS tree, then the make file can be called with the command +below to generate binary representations of both trees. +``` +(.venv)$ make binary TYPETREE=DataTypes.vspec +```