Command line tool

To facilitate development, testing, and validation of Asset Link, an interactive command-line interface al-ctl is provided. This tool enables users to interact with Asset Link through various commands. For instance, discovery can be manually triggered or stopped, and the results (i.e., discovered devices or assets) can be retrieved and stored in a file. These results can then be validated against the underlying data model.

The command line tool provides a possibility for user to test the Asset Link created using al-ctl even without having an associated gateway. The discovered assets can be retrieved in a file using various commands and the same can be validated against the underlying data model.

Command Line Tool for Local Debugging

As mentioned above, the Asset Link can be interactively triggered using a command line tool. Build it locally or install it by running:

# build
go build cmd/al-ctl/al-ctl.go
# install
go install github.com/industrial-asset-hub/asset-link-sdk/v4/cmd/al-ctl@main

By running the al-ctl with the --help argument will give you a description of the available commands and the options.

# To explore the details of all the available commands and subcommands which can be performed with the command line tool
$ al-ctl --help
# Use `al-ctl [command] --help` for details of a command

Below are the detailed description of some important commands:

Command: ‘assets’

# To explore the details of commands and subcommands related to asset discovery
$ al-ctl assets --help
$ al-ctl assets discover --help
$ al-ctl assets convert --help
$ al-ctl assets properties --help
$ al-ctl assets getsupportedproperties --help

Examples of these commands are described below:

# To run discovery on the Asset Link
$ al-ctl assets discover -e localhost:8081 [-d <discovery-config>] [-o <output-file>]

# Example: al-ctl assets discover -e localhost:8081 -d misc/discovery.json

Defining Filters and Options in Discovery Configuration:

The <discovery-config> file follows the structure shown below:
```
{
    "filters": [],
    "options": []
}
```
An example of such a discovery configuration is the Example discovery-config file used by the reference asset link.
- Note: The example provided may not be valid for all asset‑links. Supported filters and options vary depending on the capabilities of each asset‑link.
To identify the filters and options supported by a specific asset‑link, use the following command:
```
$ al-ctl info -e localhost:8081
```
After determining the supported filters and options for the target asset‑link, populate the filters and options sections accordingly.

# To convert discovered asset payload to actual assets
$ al-ctl assets convert -e localhost:8081 -i <input-file> -o <output-file>

# Example: al-ctl assets convert -e localhost:8081 -i asset.json -o converted-asset.json

# To get device properties from the Asset Link
$ al-ctl assets properties -e localhost:8081 -p <property-request-file-path> [-o <output-file>]

# Example: al-ctl assets properties -e localhost:8081 -p misc/property_values_request.json -o properties-output.json

# To get supported device properties from the Asset Link
$ al-ctl assets getsupportedproperties -e localhost:8081 -p <property-request-file-path> [-o <output-file>]

# Example: al-ctl assets getsupportedproperties -e localhost:8081 -p misc/supported_properties_request.json -o supported-properties-output.json

# To convert a GetPropertyValues response payload to actual assets
$ al-ctl assets convert -e localhost:8081 -i <property-response-file> -o <output-file>

# Example: al-ctl assets convert -e localhost:8081 -i examples/GetPropertyValuesResponse.json -o converted-property-asset.json

Command: ‘test’

# To explore the details of commands and subcommands related to test Asset Link
$ al-ctl test --help
$ al-ctl test api --help
$ al-ctl test assets --help
$ al-ctl test properties --help
$ al-ctl test registration --help

Examples of these commands are described below:

# To run the api tests on Asset Link
$ al-ctl test api -e localhost:8081 --service-name discovery [-d <discovery-config>]
# The Asset Link must be running on the provided address, for example here: localhost:8081

For more information about <discovery-config>, see the Defining Filters and Options in Discovery Configuration section.

# To also validate the discovered assets against the schema use -v flag
$ al-ctl test api -l -e localhost:8081 --service-name discovery -v --base-schema-path <base-schema> --target-class Asset
# The Asset Link must be running on the provided address, for example here: localhost:8081

# Example: al-ctl test api -l -e localhost:8081 --service-name discovery -v --base-schema-path model/iah_base_v1.11.0.yaml --target-class Asset

# To also validate the cancellation of the discovery use -c flag
$ al-ctl test api -e localhost:8081 --service-name discovery [-d <discovery-config>] -c -n <timeout>
# Timeout is the delay until the discovery is cancelled automatically. Timeout value can be given as a float value.

# To test the GetPropertyValues grpc api
$ al-ctl test api -e localhost:8081 --service-name properties -p <property-request-file-path>
# The Asset Link must be running on the provided address, for example here: localhost:8081 and the Asset Link must implement GetPropertyValues API. Also provide the property request file path.

# Example: al-ctl test api -e localhost:8081 --service-name properties -p misc/property_values_request.json

# To also validate the discovered assets with properties against the schema use -v flag
$ al-ctl test api -l -e localhost:8081 --service-name properties  -p <property-request-file-path> -v --base-schema-path <base-schema> --target-class Asset
# The Asset Link must be running on the provided address, for example here: localhost:8081

# Example: al-ctl test api -l -e localhost:8081 --service-name properties -p misc/property_values_request.json -v --base-schema-path model/iah_base_v1.11.0.yaml --target-class Asset

# To test the GetSupportedProperties grpc api
$ al-ctl test api -e localhost:8081 --service-name supported-properties -p <supported-properties-request-file-path>
# The Asset Link must be running on the provided address, for example here: localhost:8081 and the Asset Link must implement GetSupportedProperties API.

# Example: al-ctl test api -e localhost:8081 --service-name supported-properties -p misc/supported_properties_request.json

# To validate the asset against the base-schema using linkml-validator where schema file should be yaml
$ al-ctl test assets --base-schema-path <base-schema> --asset-path <asset>
--target-class <target-class>

# Example: al-ctl test assets --base-schema-path model/iah_base_v1.11.0.yaml --asset-path Asset-001.ld.json --target-class Asset

# To validate the asset against the extended-schema using linkml-validator where schema file should be yaml
$ al-ctl test assets --base-schema-path <base-schema> --asset-path <asset>
--schema-path <extended-schema> --target-class <target-class>

# Example: al-ctl test assets --base-schema-path model/iah_base_v1.11.0.yaml --asset-path SatController-001.json --schema-path cdm_sat.yaml --target-class SatController

Note: LinkML is used to validate assets against the schema.

If LinkML is already installed and available in the testing environment, use the -l flag for validation.
Otherwise, the validation will be performed using Docker to run the linkml-validator.
The iah_base_v1.11.0.yaml file is used as the base schema for validation, which can be found in the model directory.
For backward compatibility, use older versions of the base schema when the Asset Link is implemented against an earlier base schema version; this also applies to extended-schema use cases for base schema versions up to v0.12.0.

# To validate the registration of asset-link created via asset-link-SDK
# grpc-registry should be running in order to execute below command
# asset-link-endpoint is a required field in order to run this test
$ al-ctl test registration -e <asset-link-endpoint> -r <grpc-endpoint> -f <registry-file-path>

#Example: al-ctl test registration -r grpc-server-registry:50051 -f misc/registry.json