Version: Upcoming 🤫🚧

ADR 104 – Video Streaming

Purpose

This Architecture Decision Record (ADR) provides normative guidance for the use case "Autonomous Operation as a Service (AOaaS)". As "Autonomous Operation as a Service" provides different scenarios, the ADRs are separated.

This ADR provides guidance about Video Streaming.

Autonomous Operation as a Service aims at keeping machine downtime minimal by accelerating the process to solve a faulty situation using knowledge of prior events as well as human ingenuity. One of the main "fault-to-solution" paths within AOaaS involves a Machine Operator diagnosing faulty situations remotely while only using machine data and video information.

To access the available video content (either as dashcam-style video segments or as live streams) some guidelines were established, which are documented here. Please note, that this document assumes to only handle the credential and endpoint information; accessing the actual video data itself is not part of this document.

Roles

Machine Owner acts as Data Provider
Machine (Remote) Operator acts as Data Consumer

API Structure

Data Provider

The Data Provider MUST expose the endpoints according to the following Architecture Decision Records (ADRs):

Architecture Decision Record (ADR)	Version	Link
ADR 002 – Cross-Company Authorization and Discovery Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr002-authorization-discovery
ADR 003 – Authentication for Dataspaces Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr003-authentication
ADR 008 – Asset Administration Shell Profile for Factory-X Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr008-aas-profile
ADR 009 – Discovery of AAS Services via DSP Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr009-aas-rest-dsp

Data Consumer

The Data Consumer MUST expose the endpoints according to the following Architecture Decision Records (ADRs):

Architecture Decision Record (ADR)	Version	Link
ADR 002 – Cross-Company Authorization and Discovery Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr002-authorization-discovery
ADR 003 – Authentication for Dataspaces Version 0.2.0	0.2.0	https://factory-x-contributions.github.io/architecture-decisions/docs/hercules_network_adr/adr003-authentication

Note: The Consumer is not required to provide any assets

Data Models

The following submodels are used (the Short Name will be used in further chapters):

Short Name	Full Name	Version	Reference	Status
Asset Interfaces Description	Asset Interfaces Description	1.0	IDTA Submodel Template	Required
Bills of Material	Hierarchical Structures enabling Bills of Material	1.1	IDTA Submodel Template	Optional

How to Provide Data

To provide information and credentials about available video data the Asset Interfaces Description Submodel MUST be used. This Submodel MUST be part of an Asset Administration Shell (AAS) of a streaming device (like a camera). This AAS itself MUST be referable by using the globalAssetId of the streaming device.

A Data Provider MUST provide the Asset Interfaces Description Submodel in at least one of two ways:

Providing its AAS directly using the globalAssetId
Providing its AAS using a self-managed Entity as part of a Bills of Material Submodel of another AAS, also referable using the globalAssetId

Note: This step is optional if the dspEndpoint and all relevant metadata are already known - in which case a negotiation can begin right away.

Asset Interfaces Description Submodel

The Asset Interfaces Description Submodel MUST contain an Interface with:

Actions for LiveStream and Videos within InteractionMetadata according to the PropertyDefinition:
- LiveStream (Action):
  - The REST API endpoint that returns a URL (e.g., WebRTC) for the camera's live video stream.
- Videos (Action):
  - The REST API endpoint that returns URLs for recorded videos of a specific event ID.

Application specific dsp_sc in securityDefinitions within EndpointMetadata:

scheme: Defines the security mechanism that used during access; Set to: dsp.
id: ID of the Dataset in the Data Providers catalog that contains the Submodel.
dspEndpoint: Points to a DSP Catalog endpoint containing the relevant Dataset.

Note: dsp_sc is defined as follows:

dsp_no_sec.json — Security Definition

{
  "idShort": "dsp_sc",
  "qualifiers": [
    {
      "kind": "ConceptQualifier",
      "type": "Cardinality",
      "valueType": "xs:string",
      "value": "ZeroToOne"
    }
  ],
  "value": [
    {
      "idShort": "scheme",
      "semanticId": {
        "type": "ExternalReference",
        "keys": [
          {
            "type": "GlobalReference",
            "value": "https://www.w3.org/2019/wot/security#SecurityScheme"
          }
        ]
      },
      "qualifiers": [
        {
          "kind": "ConceptQualifier",
          "type": "Cardinality",
          "valueType": "xs:string",
          "value": "One"
        }
      ],
      "valueType": "xs:string",
      "value": "dsp",
      "modelType": "Property"
    },
    {
      "idShort": "id",
      "description": [
        {
          "language": "en",
          "text": "id represents the id of that Dataset in the Data Providers catalog that contains the Submodel."
        }
      ],
      "qualifiers": [
        {
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://admin-shell.io/SubmodelTemplates/Cardinality/1/0"
              }
            ]
          },
          "kind": "TemplateQualifier",
          "type": "SMT/Cardinality",
          "valueType": "xs:string",
          "value": "One"
        }
      ],
      "valueType": "xs:string",
      "modelType": "Property"
    },
    {
      "idShort": "dspEndpoint",
      "description": [
        {
          "language": "en",
          "text": "dspEndpoint represents the endpoint of the Data Provider's DSP endpoint where the catalog containing the relevant Dataset is located."
        }
      ],
      "qualifiers": [
        {
          "semanticId": {
            "type": "ExternalReference",
            "keys": [
              {
                "type": "GlobalReference",
                "value": "https://admin-shell.io/SubmodelTemplates/Cardinality/1/0"
              }
            ]
          },
          "kind": "TemplateQualifier",
          "type": "SMT/Cardinality",
          "valueType": "xs:string",
          "value": "One"
        }
      ],
      "valueType": "xs:string",
      "modelType": "Property"
    }
  ],
  "modelType": "SubmodelElementCollection"
}

Download dsp_no_sec.json

Reference to dsp_sc within the security of EndpointMetadata.

Authentication and Authorization

Apart from mechanism already described within the linked ADRs, no additional Authentication or Authorization mechanism is specified.

Alternatives evaluated

Only credentials are shared within Factory-X dataspace to access stream relevant data through a cloud service. As an alternative, streams may be integrated directly into the Factory-X EDC. Access to streams can be provided by sharing the credentials similar to how it is done in ADR012.

Purpose​

Roles​

API Structure​

Data Provider​

Data Consumer​

Data Models​

How to Provide Data​

Asset Interfaces Description Submodel​

Authentication and Authorization​

Alternatives evaluated​