Overview of the manifest.yaml URCap descriptor

The following section is intended to give an overview of the different options available for the manifest.yaml that is required when creating a URCap. The manifest resides in the top level of the URCapX file and contains two primary parts:

• Metadata: ID and an optional common description of all contributed artifacts

• Artifacts: The actual artifacts to be contributes

[Required] metadata

The metadata section of the manifest contains information that identifies the URCap, including:

Metadata structure description

metadata:
  vendorID: Unique identifier for the vendor that developed the URCap application
  vendorName: The full vendor name
  urcapID: A unique identifier for the URCap developed by the vendor
  urcapName: The full URCap name
  version: Version of the URCap
  description: A brief description of the URCap functionality
  copyright: The copyright information for the URCap
  licenseType: The type of license for the URCap
  license: License information
  contactInfo: Contact information for the vendor/company that developed the URCap

See example here URCap contribution manifest

Properties:

• [Required] id: Unique identifier for the vendor that developed the URCap application

• [Required] vendorName: The full vendor name

• [Required] urcapID: A unique identifier for the URCap developed by the vendor

• [Required] urcapName: The full URCap name

• [Required] version: Version of the URCap. Should be of format <major>.<minor>.<patch>.<buildNo>. Where build number is optional

• [Optional] description: A brief description of the URCap functionality

• [Optional] copyright: The copyright information for the URCap

• [Optional] licenseType: The type of license for the URCap

• [Optional] license: License information

• [Optional] contactInfo: Contact information for the vendor/company that developed the URCap

Note

The properties vendorID and urcapID in combination uniquely defines an ID for the URCap. They must only contain letters, digits and hyphens. see Creating a container backend Contribution for an example of how the URCap ID is used when communicating with a container contribution.

[Required] artifacts

After describing the metadata of the URCap, the following section is about the actual artifacts that the URCap is bringing.

Artifacts structure

metadata:
  ...
artifacts:
  container:
    ...
  webArchives:
    ...

The two types of artifacts that the URCap can bring with it are containers and webArchives. The following sections will showcase the different artifacts, and describe some of the required and optional properties and where appropriate refer to guides with more in-depth descriptions.

• [Optional] Containers

  Properties for containers

  metadata:
    ...
  artifacts:
    container:
      id: Name of the container artifact
      image: Container image name
      startup: Decide if the container should start automatically or not
      exposePorts: An array of container network ports to be exposed
      environment: An array of environment variables to be available inside the container
      mounts: An array of volume mounts to be mounted inside the container
      devices: An array of devices to be mounted inside the container
      networks: An array of networks to be available inside the container
      ingress: An array if ingress configurations
      services: An array of controller interfaces this container wants to communicate with
  

  Properties:

  • [Required] id: The name to identify the artifact. See note below

  • [Required] image: Name of the docker image

  • [Optional] exposePorts: Enables communication between a network port on the container and a network port on the host. The exposed network ports are defined as follows:

    exposePorts:
      [Required] id: Uniqe name of this exposed network port
      [Required] containerPort: This is the network port number on the container
      [Optional] hostPort: This is the network port number on the host used to map the "containerPort" to this "hostPort"
        Port range is [1 - 61000]
      [Optional] protocol: Values can be "udp" or "tcp". Default value is "tcp"
      [Optional] externallyAvailable: Values can be "true" or "false". Default value is "false" 
        Indicates whether the host network port is available on the physical network
    

  • [Optional] environment: Environment variables are defined as follows:

      environment:
        [Required] name: The container environment variable name. Convention is to use capital letters with underscore delimiters
        [Required] value: The container environment variable value. Any configuration information required at runtime by URCap container
    

  • [Optional] mounts: See Data storage for a description on how to use the different types of mounts

  • [Optional] devices: List of physical USB device types / classes that should be accessible from the container. Device types are defined as follows:

      devices:
        [Required] type: Type of device the container should get access to
    

    • Valid device types are:

      • ttyTool: Built in robot tool connector

      • serial: USB to serial device

      • video, USB to video device

      • network: USB to ethernet device

    See Serial Device - Hot plug For a description on how devices can be accessed in the container using a hot plug mechanism.

  • [Optional] networks: Enables additional networks in the container. The networks are defined as follows:

    networks:
      [Required] id: Interface name inside container
      [Optional] type: network type
      [Optional] description: The purpose of this network
    

    • Valid network types are:

      • eth: Ethernet interface

      • macvlan: See Networking - Macvlan

      • vlan: vlan interface

  • [Optional] ingress: Ingress path routing configurations. Specifies how to communicate with servers in containers. Ingress is defined as follows:

    ingress:
      [Required] id: Logical name of the ingress rule
      [Required] containerPort: The network port number to be used by the server in the container
      [Optional] protocol: Values can be "http" or "websocket". Default value is "http"
      [Optional] proxyUrl: The full URL can be forwarded to a simpler URL to be used inside the container. 
       Default is that no forwarding is done
      [Optional] devUrl: Forward requests to this URL instead of serving them from the container. 
       Used for debugging and realtime development of URCaps
    

    See URCap contribution manifest for an ingress example.

    Note

    The series of ID’s: vendor, urcap, container and ingress is used to form the URL where the container can be contacted. The actual URL to use from the frontend is defined as: <vendorID>/<urcapID>/<container-id>/<ingress-id>. See Creating a container backend Contribution for an example of how the complete URL is formed.

  • [Optional] services: Services e.g. controller interfaces this container will access

    services:
      - [Required] service: The Services the container want to access
    

    See Communicating with the robot controller for a list of valid services and how to work with them.

• [Optional] Web archives

  metadata:
    ...
  artifacts:
    webArchive:
      id: Unique ID for this web archive
      folder: Name of the folder containing the web archive
      devUrl: Forward requests to this URL instead of serving them from the robot
  

  properties:

  • [Required] id: The unique name of the web archive

  • [Required] folder: The name of the web archive folder

  • [Optional] devurl: A URL indicating where the development web artifacts is located. Used for debugging and realtime development of URCaps. See How to enable live development of frontend contributions for a description on how to utilize this feature

  See URCap contribution manifest for an example of how to use a web archive. See also examples of how to develop a web archive in Creating a Frontend Contribution