1 Scope

This document defines OPC UA interfaces for components of Unattended Retail & Coffee Solutions. By using those standardized interfaces, vendors and system integrators can easily combine components from different suppliers to assemble their Unattended Retail & Coffee Solutions.

This specification is marketed under the name EVA SmartLink. The name has been deliberately chosen to reflect the core ambition of the initiative: to create a smart, secure and future-proof link between all components of Unattended Retail, Vending & Coffee Solutions. "Smart" refers to the intelligent, modular architecture enabled by OPC UA; "Link" highlights interoperability, openness and the seamless connection between machine engines, user interfaces, payment systems, pricing services and audit functionalities.

The EVA SmartLink branding provides the industry with a clear, recognisable identity for this open standard, facilitating communication, market adoption and implementation across Europe and beyond. While the technical foundation remains OPC UA, the name EVA SmartLink emphasises its specific application to the unattended retail and vending ecosystem and underlines its role as an industry-driven, vendor-neutral framework designed to foster innovation, flexibility and fair competition. The logo of EVA SmartLink is shown in Figure 1.

OPC Foundation

OPC is the interoperability standard for the secure and reliable exchange of data and information in the industrial automation space and in other industries. It is platform independent and ensures the seamless flow of information among devices from multiple vendors. The OPC Foundation is responsible for the development and maintenance of this standard.

OPC UA is a platform independent service-oriented architecture that integrates all the functionality of the individual OPC Classic specifications into one extensible framework. This multi-layered approach accomplishes the original design specification goals of:

Platform independence: from an embedded microcontroller to cloud-based infrastructure

Secure: encryption, authentication, authorisation, and auditing

Extensible: ability to add new features including transports without affecting existing applications

Comprehensive information modelling capabilities: for defining any model from simple to complex

EVA

The European Vending & Coffee Service Association (EVA) is a not-for-profit organisation established and situated in Brussels since 1994. It represents the interests of the European coffee service and vending industry vis-à-vis the European Institutions and other relevant authorities or bodies. Its membership is composed of national associations and individual companies across Europe. The EVA represents all segments of the coffee service, water dispenser and vending industry: machine and component manufacturers, suppliers of commodities (coffee, ingredients, snacks, cold drinks, cups etc.), and operators.

2 Normative references

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments and errata) applies.

OPC 10000-1, OPC Unified Architecture - Part 1: Overview and Concepts

http://www.opcfoundation.org/documents/10000-1/

OPC 10000-2, OPC Unified Architecture - Part 2: Security Model

http://www.opcfoundation.org/documents/10000-2/

OPC 10000-3, OPC Unified Architecture - Part 3: Address Space Model

http://www.opcfoundation.org/documents/10000-3/

OPC 10000-4, OPC Unified Architecture - Part 4: Services

http://www.opcfoundation.org/documents/10000-4/

OPC 10000-5, OPC Unified Architecture - Part 5: Information Model

http://www.opcfoundation.org/documents/10000-5/

OPC 10000-6, OPC Unified Architecture - Part 6: Mappings

http://www.opcfoundation.org/documents/10000-6/

OPC 10000-7, OPC Unified Architecture - Part 7: Profiles

http://www.opcfoundation.org/documents/10000-7/

OPC 10000-12, OPC Unified Architecture - Part 12: Discovery and Global Services

http://www.opcfoundation.org/documents/10000-12/

OPC 10000-100, OPC Unified Architecture - Part 100: Devices

http://www.opcfoundation.org/documents/10000-100/

EVA DTS, Data Transfer Standard EVA DTS 6.2.2

MDB / ICP: Multi-Drop Bus / Internal Communication Protocol, Version 4.3

https://www.namanow.org/wp-content/uploads/Multi-Drop-Bus-and-Internal-Communication-Protocol.pdf

IEEE 802.3: IEEE Standard for Ethernet

https://standards.ieee.org/ieee/802.3/10422/

3 Terms, abbreviated terms and conventions

3.1 Overview

It is assumed that basic concepts of OPC UA information modelling and Unattended Retail & Coffee Solutions are understood in this document. This document will use these concepts to describe the Unattended Retail & Coffee Solutions Information Model. For the purposes of this document, the terms and definitions given in OPC 10000-1, OPC 10000-3, OPC 10000-4, OPC 10000-5, OPC 10000-7, OPC 10000-100 as well as the following apply.

Note that OPC UA terms and terms defined in this document are italicized in the document.

3.2 OPC UA for Unattended Retail & Coffee Solutions terms

3.2.1 Vending Machine

Unattended Retail & Coffee Solution

3.2.2 Option

any user-selectable parameter which can change product delivery

3.3 Abbreviated terms

3.4 Conventions used in this document

3.4.1 Conventions for Node descriptions

3.4.1.1 Node definitions

Node definitions are specified using tables (see Table 2).

Attributes are defined by providing the Attribute name and a value, or a description of the value.

References are defined by providing the ReferenceType name, the BrowseName of the TargetNode and its NodeClass.

• If the TargetNode is a component of the Node being defined in the table the Attributes of the composed Node are defined in the same row of the table.

• The DataType is only specified for Variables; "[<number>]" indicates a single-dimensional array, for multi-dimensional arrays the expression is repeated for each dimension (e.g. [2][3] for a two-dimensional array). For all arrays the ArrayDimensions is set as identified by <number> values. If no <number> is set, the corresponding dimension is set to 0, indicating an unknown size. If no number is provided at all the ArrayDimensions can be omitted. If no brackets are provided, it identifies a scalar DataType and the ValueRank is set to the corresponding value (see OPC 10000-3). In addition, ArrayDimensions is set to null or is omitted. If it can be Any or ScalarOrOneDimension, the value is put into "{<value>}", so either "{Any}" or "{ScalarOrOneDimension}" and the ValueRank is set to the corresponding value (see OPC 10000-3) and the ArrayDimensions is set to null or is omitted. Examples are given in Table 1.

• The TypeDefinition is specified for Objects and Variables.

• The TypeDefinition column specifies a symbolic name for a NodeId, i.e., the specified Node points with a HasTypeDefinition Reference to the corresponding Node.

• The ModellingRule of the referenced component is provided by specifying the symbolic name of the rule in the ModellingRule column. In the AddressSpace, the Node shall use a HasModellingRule Reference to point to the corresponding ModellingRule Object.

If the NodeId of a DataType is provided, the symbolic name of the Node representing the DataType shall be used.

Note that if a symbolic name of a different namespace is used, it is prefixed by the NamespaceIndex (see 3.4.2.2).

Nodes of all other NodeClasses cannot be defined in the same table; therefore, only the used ReferenceType, their NodeClass and their BrowseName are specified. A reference to another part of this document points to their definition. Table 2 illustrates the table. If no components are provided, the DataType, TypeDefinition and Other columns may be omitted and only a Comment column is introduced to point to the Node definition.

Each Type Node or well-known Instance Node defined shall have one or more ConformanceUnits defined in 0 that require the Node to be in the AddressSpace.

The relations between Nodes and ConformanceUnits are defined at the end of the tables defining Nodes, one row per ConformanceUnit. The ConformanceUnits are reflected in the Category element for the Node definition in the UANodeSet (see OPC 10000-6).

The list of ConformanceUnits in the UANodeSet allows Servers to optimize resource consumption by using a list of supported ConformanceUnits to select a subset of the Nodes in an Information Model.

When a Node is selected in this way, all dependencies implied by the References are also selected.

Dependencies exist if the Node is the source of HasTypeDefinition, HasInterface, HasAddIn or any HierarchicalReference. Dependencies also exist if the Node is the target of a HasSubtype Reference. For Variables and VariableTypes, the value of the DataType Attribute is a dependency. For DataType Nodes, any DataTypes referenced in the DataTypeDefinition Attribute are also dependencies.

For additional details see OPC 10000-5.

Components of Nodes can be complex that is containing components by themselves. The TypeDefinition, NodeClass and DataType can be derived from the type definitions, and the symbolic name can be created as defined in 3.4.3.1. Therefore, those containing components are not explicitly specified; they are implicitly specified by the type definitions.

The Other column defines additional characteristics of the Node. Examples of characteristics that can appear in this column are show in Table 3.

If multiple characteristics are defined, they are separated by commas. The name or the short name may be used.

3.4.1.2 Additional References

To provide information about additional References, the format as shown in Table 4 is used.

References can be to any other Node.

3.4.1.3 Additional sub-components

To provide information about sub-components, the format as shown in Table 5 is used.

3.4.1.4 Additional Attribute values

The type definition table provides columns to specify the values for required Node Attributes for InstanceDeclarations. To provide information about additional Attributes, the format as shown in Table 6 is used.

There can be multiple columns to define more than one Attribute.

3.4.2 NodeIds and BrowseNames

3.4.2.1 NodeIds

The NodeIds of all Nodes described in this standard are only symbolic names. Annex A defines the actual NodeIds.

The symbolic name of each Node defined in this document is its BrowseName, or, when it is part of another Node, the BrowseName of the other Node, a ".", and the BrowseName of itself. In this case "part of" means that the whole has a HasProperty or HasComponent Reference to its part. Since all Nodes not being part of another Node have a unique name in this document, the symbolic name is unique.

The NamespaceUri for all NodeIds defined in this document is defined in Annex A. The NamespaceIndex for this NamespaceUri is vendor-specific and depends on the position of the NamespaceUri in the server namespace table.

Note that this document not only defines concrete Nodes, but also requires that some Nodes shall be generated, for example one for each Session running on the Server. The NodeIds of those Nodes are Server-specific, including the namespace. But the NamespaceIndex of those Nodes cannot be the NamespaceIndex used for the Nodes defined in this document, because they are not defined by this document but generated by the Server.

3.4.2.2 BrowseNames

The text part of the BrowseNames for all Nodes defined in this document is specified in the tables defining the Nodes. The NamespaceUri for all BrowseNames defined in this document is defined in 10.2.

For InstanceDeclarations of NodeClass Object and Variable that are placeholders (OptionalPlaceholder and MandatoryPlaceholder ModellingRule), the BrowseName and the DisplayName are enclosed in angle brackets (<>) as recommended in OPC 10000-3.

If a BrowseName is not defined by this document, a namespace index prefix is added to the BrowseName (e.g., prefix '0' leading to '0:EngineeringUnits' or prefix '2' leading to '2:DeviceRevision'). This is typically necessary if a Property of another specification is overwritten or used in the OPC UA types defined in this document. Table 144 provides a list of namespaces and their indexes as used in this document.

3.4.3 Common Attributes

3.4.3.1 General

The Attributes of Nodes, their DataTypes and descriptions are defined in OPC 10000-3. Attributes not marked as optional are mandatory and shall be provided by a Server. The following tables define if the Attribute value is defined by this document or if it is server-specific.

For all Nodes specified in this document, the Attributes named in Table 7 shall be set as specified in the table.

3.4.3.2 Objects

For all Objects specified in this document, the Attributes named in Table 8 shall be set as specified in the Table 8. The definitions for the Attributes can be found in OPC 10000-3.

3.4.3.3 Variables

For all Variables specified in this document, the Attributes named in Table 9 shall be set as specified in the table. The definitions for the Attributes can be found in OPC 10000-3.

3.4.3.4 VariableTypes

For all VariableTypes specified in this document, the Attributes named in Table 10 shall be set as specified in the table. The definitions for the Attributes can be found in OPC 10000-3.

3.4.3.5 Methods

For all Methods specified in this document, the Attributes named in Table 11 shall be set as specified in the table. The definitions for the Attributes can be found in OPC 10000-3.

3.4.4 Structures

OPC 10000-3 differentiates between different kinds of Structures. The following conventions explain, how these Structures shall be defined.

The first kind are Structures without optional fields where none of the fields allows subtype (except fields with abstract DataTypes). Its definition is in Table 12.

The second kind are Structures with optional fields where none of the fields allows subtypes (except fields with abstract DataTypes). Its definition is in Table 13.

Structures with fields that are optional have an "Optional" column. Fields that are optional have True set, otherwise False.

The third kind are Structures without optional fields where one or more of the fields allow subtypes. Its definition is in Table 14.

Structures with fields that allow subtypes have an "Allow Subtypes" column. Fields that allow subtypes have True set, otherwise False. Fields with abstract DataTypes can always be subtyped.

4 General information to Unattended Retail & Coffee Solutions and OPC UA

4.1 Introduction to Unattended Retail & Coffee Solutions

4.1.1 Overview

The vending industry in key markets globally represents over 14 million machines and an annual estimated revenue of €80 billion.

Despite efforts to create and adopt common standards and protocols, the industry is fragmented and certain markets are more likely use particular vending machine interfaces, for historic and traditional reasons. This fragmentation leads to barriers and costs for machine and peripheral manufacturers, vending operators, as well as leading to integration problems within the machine. As the industry becomes more and more connected and in order to meet increased demand from consumers, the current situation can be considered no longer viable and hence a new specification is deemed to make the industry fit for the future.

4.1.2 Unattended Retail & Coffee Solutions

4.1.2.1 Vending Machine

A Vending Machine (see Figure 2 for examples) is an operational machine located either at a client site or in a public location designed specifically for the sale and dispensing of food, drinks, and other goods and services. The EVA does not include cigarette or gaming machines within this definition.

10,000 operating companies manage the vending machines across Europe, while the industry overall employs more than 85,000 people directly, bringing manufacturing jobs and contributing to the EU's industrial strategy.

Note that we use the term Vending Machine as synonym for Unattended Retail & Coffee Solutions (see 3.2.1) in later sections for better readability.

4.1.2.2 Office Coffee Service (OCS)

While 64% of the vending industry is made up of hot drinks/coffee machines, OCS is a specific part of this segment and involves a hot drink table-top operation in the office environment, maintained and supplied with ingredients by the operator. OCS machines (for examples see Figure 3), however, are filled by the company where the machines are located, and these systems do not usually have coin/payment systems as a 'free' and quality coffee provision in the office is more and more seen as a necessity for workers and a service provided by companies for their employees.

4.1.2.3 Unattended Retail (Micromarkets & Smart Fridges)

Micromarkets are small, unattended convenience stores in workplaces. A new and growing trend in Europe, with more than 10,000 in operation as of 2023 and typically include the following elements:

Products are on open shelves, or chiller cabinets or fridges so consumers can select them as they would in a store

Selected products are scanned by the consumer either at a central unattended till, or using a smartphone app

Payment is taken either at the central till (usually cashless), or through a smartphone app

Usually includes at least one hot beverage machine

May include a microwave to heat purchased food

May include an area with tables and seating

The EVA estimates the total number of Smart Fridges across Europe to be between 2,500 and 3,500, with more machine operators operating Smart Fridges than Micromarkets in Europe.

In Figure 4, an example of a Micromarket and a Smart Fridge is given.

4.2 Introduction to OPC Unified Architecture

4.2.1 What is OPC UA?

OPC UA is an open and royalty free set of standards designed as a universal communication protocol. While there are numerous communication solutions available, OPC UA has key advantages:

A state of art security model (see OPC 10000-2).

A fault tolerant communication protocol.

An information modelling framework that allows application developers to represent their data in a way that makes sense to them.

OPC UA has a broad scope which delivers for economies of scale for application developers. This means that a larger number of high-quality applications at a reasonable cost are available. When combined with semantic models such as Unattended Retail & Coffee Solutions, OPC UA makes it easier for end users to access data via generic commercial applications.

The OPC UA model is scalable from small devices to ERP systems. OPC UA Servers process information locally and then provide that data in a consistent format to any application requesting data - ERP, MES, PMS, Maintenance Systems, HMI, Smartphone, or a standard Browser, for examples. For a more complete overview see OPC 10000-1.

4.2.2 Basics of OPC UA

As an open standard, OPC UA is based on standard internet technologies, like TCP/IP, HTTP, Web Sockets.

As an extensible standard, OPC UA provides a set of Services (see OPC 10000-4) and a basic information model framework. This framework provides an easy manner for creating and exposing vendor defined information in a standard way. More importantly all OPC UA Clients are expected to be able to discover and use vendor-defined information. This means OPC UA users can benefit from the economies of scale that come with generic visualisation and historian applications. This specification is an example of an OPC UA Information Model designed to meet the needs of developers and users.

OPC UA Clients can be any consumer of data from another device on the network to browser based thin clients and ERP systems. The full scope of OPC UA applications is shown in Figure 5.

OPC UA provides a robust and reliable communication infrastructure having mechanisms for handling lost messages, failover, heartbeat, etc. With its binary encoded data, it offers a high-performing data exchange solution. Security is built into OPC UA as security requirements become more and more important especially since environments are connected to the office network or the internet and attackers are starting to focus on automation systems.

4.2.3 Information modelling in OPC UA

4.2.3.1 Concepts

OPC UA provides a framework that can be used to represent complex information as Objects in an AddressSpace which can be accessed with standard services. These Objects consist of Nodes connected by References. Different classes of Nodes convey different semantics. For example, a Variable Node represents a value that can be read or written. The Variable Node has an associated DataType that can define the actual value, such as a string, float, structure etc. It can also describe the Variable value as a variant. A Method Node represents a function that can be called. Every Node has a number of Attributes including a unique identifier called a NodeId and non-localized name called as BrowseName. An Object representing a 'Reservation' is shown in Figure 6.

Object and Variable Nodes represent instances and they always reference a TypeDefinition (ObjectType or VariableType) Node which describes their semantics and structure. Figure 7 illustrates the relationship between an instance and its TypeDefinition.

The type Nodes are templates that define all of the children that can be present in an instance of the type. In the example in Figure 8 the PersonType ObjectType defines two children: First Name and Last Name. All instances of PersonType are expected to have the same children with the same BrowseNames. Within a type the BrowseNames uniquely identify the children. This means Client applications can be designed to search for children based on the BrowseNames from the type instead of NodeIds. This eliminates the need for manual reconfiguration of systems if a Client uses types that multiple Servers implement.

OPC UA also supports the concept of sub-typing. This allows a modeller to take an existing type and extend it. There are rules regarding sub-typing defined in OPC 10000-3, but in general they allow the extension of a given type or the restriction of a DataType. For example, the modeller may decide that the existing ObjectType in some cases needs an additional Variable. The modeller can create a subtype of the ObjectType and add the Variable. A Client that is expecting the parent type can treat the new type as if it was of the parent type. Regarding DataTypes, subtypes can only restrict. If a Variable is defined to have a numeric value, a subtype could restrict it to a float.

References allow Nodes to be connected in ways that describe their relationships. All References have a ReferenceType that specifies the semantics of the relationship. References can be hierarchical or non-hierarchical. Hierarchical references are used to create the structure of Objects and Variables. Non-hierarchical are used to create arbitrary associations. Applications can define their own ReferenceType by creating subtypes of an existing ReferenceType. Subtypes inherit the semantics of the parent but may add additional restrictions. Figure 8 depicts several References, connecting different Objects.

The figures above use a notation that was developed for the OPC UA specification. The notation is summarized in Figure 9. UML representations can also be used; however, the OPC UA notation is less ambiguous because there is a direct mapping from the elements in the figures to Nodes in the AddressSpace of an OPC UA Server.

A complete description of the different types of Nodes and References can be found in OPC 10000-3 and the base structure is described in OPC 10000-5.

The OPC UA specification defines a very wide range of functionality in its basic information model. It is not required that all Clients or Servers support all functionality in the OPC UA specifications. OPC UA includes the concept of Profiles, which segment the functionality into testable certifiable units. This allows the definition of functional subsets (that are expected to be implemented) within a companion specification. The Profiles do not restrict functionality, but generate requirements for a minimum set of functionalities (see OPC 10000-7).

4.2.3.2 Namespaces

OPC UA allows information from many different sources to be combined into a single coherent AddressSpace. Namespaces are used to make this possible by eliminating naming and id conflicts between information from different sources. Each namespace in OPC UA has a globally unique string called a NamespaceUri which identifies a naming authority and a locally unique integer called a NamespaceIndex, which is an index into the Server's table of NamespaceUris. The NamespaceIndex is unique only within the context of a Session between an OPC UA Client and an OPC UA Server- the NamespaceIndex can change between Sessions and still identify the same item even though the NamespaceUri's location in the table has changed. The Services defined for OPC UA use the NamespaceIndex to specify the Namespace for qualified values.

There are two types of structured values in OPC UA that are qualified with NamespaceIndexes: NodeIds and QualifiedNames. NodeIds are locally unique (and sometimes globally unique) identifiers for Nodes. The same globally unique NodeId can be used as the identifier in a node in many Servers - the node's instance data may vary but its semantic meaning is the same regardless of the Server it appears in. This means Clients can have built-in knowledge of what the data means in these Nodes. OPC UA Information Models generally define globally unique NodeIds for the TypeDefinitions defined by the Information Model.

QualifiedNames are non-localized names qualified with a Namespace. They are used for the BrowseNames of Nodes and allow the same names to be used by different information models without conflict. TypeDefinitions are not allowed to have children with duplicate BrowseNames; however, instances do not have that restriction.

4.2.3.3 Companion Specifications

An OPC UA companion specification for an industry specific vertical market describes an Information Model by defining ObjectTypes, VariableTypes, DataTypes and ReferenceTypes that represent the concepts used in the vertical market, and potentially also well-defined Objects as entry points into the AddressSpace.

5 Use cases

5.1 Manufacturers of unattended retail components

The unattended retail device which is used to sell a product/service to the user is the combination of the experiences of many different actors, and sometimes also from people coming from outside the unattended retail area.

As in many other areas, the knowledge required to create any device grows over time.

The basic idea of the specification is to be able better insulate the knowledge of each actor providing also simple way to interconnect the components needed.

And the boundaries are basically already the way the manufacturers of vending machines are internally dividing their knowledge: people making good coffee, or reliably delivering pre-packaged product, or making effective method of payments, or finally managing the machine data to best operate the business.

This is not done to make strong separation between company business, but to enable knowledge in each area to be able to grow in independent way; this is why the first people which will take advantage of the specification are the manufacturers.

5.2 Hotel breakfast

Many hotel, B&B, have machine used in morning to prepare and serve hot and cold beverages.

These machines many times do not have payment systems, and selections are free, being paid as an hotel service.

The machines are normally table top, and many of them have a graphical user interface. The user interface is used mainly to select the product to prepare. The machines are typically not connected.

Making these machines modular will enable large ( and small ) hotel chain to handle the use interface independently for the details of the internal operation of the delivery process.

Even if payment is not typically added, the modular approach enables to easily add different payment devices of needed, including the hotel contactless key used by the customer to enter the room. If the machine is also connected, the standardization of the exchanged data ( Audit ) will enable to automatic calculation of customer recipes, if the delivered product must be paid, for example, when product is taken after the morning breakfast time window.

5.3 Closed location vending machines

Many offices have local vending machines, to sell hot, cold beverages, and pre-packaged items: the machine are operated by the office manager, which handles machine filling, product selection.

If the office manager is also the employer, many times, the sold product can be directly accounted to the employee's payroll, or can be part of the company benefit plan.

The machine is bought based on type of product to sell, and the employer can use the machine graphical UI possibly as a company notice board.

Having the machines built by easy integrated component from different sources will enable more freedom in the selection and composition of the final device: the notice-board application must be able to be used on devices providing delivering different product.

Standardized way to connect to the machines, and a known format for the provided data make easy the integration with the company back-end.

5.4 Externally managed location vending machines

Many offices have local vending machines, to sell hot, cold beverages, and pre-packaged items: the machines are operated by an external operating company, which handles machine filling and product selection.

These companies will manage different sets of locations, and have a great variety of product to handle.

Managing a location means also to get information about the device status and operational conditions. The standard audit used today is very limited and mainly provides accounting information. A larger set of data, and a standardized way to get these data make managing widely different device simpler.

Local payment devices are basic elements for these operations: in the past days cash was the only option.

Today cash is important, but a large variety of different other payment types are available. Anything which is not cash is "cashless" but under this definition there is a large variety of different technologies:

standard credit cards,

closed system payment cards,

hotel may require integration in the general customer accounting,

employer can require integration in company payroll,

loyalty cards,

points, and many other.

5.5 Better customer engagement

Any unattended retail finally has as customer interacting with a device able to provide the service or product the customer asks.

These devices can use a graphic display which is normally used only for the selection.

An operator of an unattended retail device is never in physical contact with his customer, but the device display can provide a window: a blackboard for different other type of information, with the final intent the user can come again; but, when the user is in front of the vending device, there is good probability he will buy.

To management of the "user interface" has to be as must as possible independent for the operating details of the product delivery process, and this is the purpose of the standardized interfaces.

The technologies and knowledge used by the user interface designed are evolving and changing very fast. There is need to separate this development from the standard user interface normally embedded in the standard unattended retail devices.

5.6 New machine types

This application will use of a well-known and widely used framework, with an existing large number of devices following the same general environment.

This will enable to buy and integrate components from the market, making the development of new machine types or solving a customer specific requirement faster and more reliably.

Prototyping can be also faster, using standard parts from the market to make a sample before designing the final device.

6 Unattended Retail & Coffee Solutions Information Model overview

6.1 Overview

An Unattended Retail & Coffee Solution (for better readability we use the term Vending Machine in the following text) is built out of various components. This specification focuses on components that may be provided by different vendors and therefore require standardized exchange of information between those components. A component may be used by various Vending Machines and does not necessarily need to be physically connected to a Vending Machine, like for example a user interface (UI) that runs on a smart device of a customer like a smart phone or tablet.

In addition to the interactions of the components of a Vending Machine, this specification also defines information exchange to monitor Vending Machines by applications that cannot be considered to be part of the Vending Machine.

Requirements on the power supply of components of a Vending Machine are described in Annex C, and requirements on the network infrastructure of components of a Vending Machine in Annex D.

6.2 Components of a Vending Machine

6.2.1 Machine engine

The machine engine is the device able to create or deliver or collect a given product. It interacts with the UI, the payment service, and the audit collect. It interacts with the customer by physically providing the product to the customer. It provides information to monitor the Vending Machine. A Vending Machine according to this specification needs to support at least one machine engine, but may have several machine engines as components. A machine engine cannot be assigned to more than one Vending Machine, i.e., it can only be used by one payment service.

The machine engine provides its interface by implementing an instance of the MachineEngineType (shown in Figure 10, defined in 7.1). The machine engine does not require OPC UA Client functionality to access other components of the Vending Machine.

The MachineEngineType provides the identification of the machine engine in the Identification Object, defined in OPC 10000-100. The configuration of the machine engine is provided by the Configuration Object of BaseConfigurationType defined in 7.3. The configuration may be writable via the OPC UA interface to change the configuration of the machine engine. The machine engine provides the configuration for the UI in the Capabilities Object of MachineEngineCapabilitiesType defined in 7.5. The configuration is accessed by the UI and parts may be writable to change the configuration of the UI. The Delivery Object of MachineEngineDeliveryType defined in 7.6 provides functionality to request a delivery (by the payment service) as well as expose the status of the delivery (displayed by the UI). The Status Object of MachineEngineStatusType defined in 7.7 provides the overall status of the machine engine, to be displayed in the UI and consumed by the payment service. The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the machine engine. The machine engine generates Events of VendingBaseAuditEventType to provide audit data.

6.2.2 Payment service

The payment service is responsible to approve product delivery, for example by receiving coins or charging a credit card or any other needed condition for the delivery of a product, like age. It is also responsible of all money movements between the different payment devices, like using cash to revalue a card system, handling change or overpay. It interacts with the UI, the machine engine, the audit collect and the price service. It may interact with the customer, for example by physically collecting coins or bills or scanning a credit card. It provides information to monitor the Vending Machine. A Vending Machine according to this specification supports exactly one payment service.

The payment service provides its interface by implementing an instance of the PaymentServiceType (shown in Figure 11, defined in 7.8). The payment service requires OPC UA Client functionality to access the machine engine(s) and the primary price service of the Vending Machine.

The PaymentServiceType provides the identification of the payment service in the Identification Object, defined in OPC 10000-100. The configuration of the payment service is provided by the Configuration Object of BaseConfigurationType defined in 7.3. The configuration may be writable via the OPC UA interface to change the configuration of the payment service. The Delivery Object of PaymentServiceDeliveryType defined in 7.9 provides functionality to request a delivery (by the UI) as well as expose the status of the payment of the delivery (displayed by the UI). The PriceInformation Object of PriceInformationType defined in 7.11 provides price information for deliverables of products of machine engines manged by the payment service. The PaymentModes Object of PaymentModesType defined in 7.13 provides information about the different payment systems supported by the payment service and their status, having on Object of PaymentModeType defined in 7.14 per payment system. The Status Object provides the overall status of the payment service defined in 7.22. The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the payment service. The payment service generates Events of VendingAuditEventType to provide audit data.

The payment service receives price information from the primary price service of the Vending Machine using the PriceInformation Object of the price service. It is up to the implementation of the payment service whether the requests of the UI about price information is always forwarded to the price service, or cached in the payment service.

The payment service will need to interface to any other device which can affect the delivery, and these devices are payment devices. Payment service will provide the UI with enough information from the payment devices to define the payment, but the detailed implementation of the process is internal to payment service. It is also possible (and for sure will happen in the transition phase before OPC UA compliant payment devices will be available, the payment service will handle internally legacy coin, bills, cashless devices using proprietary protocols. When this happens, payment service has to act relative to audit collect to provide, in a way which is in line with this specification, all the required information.

But, with OPC UA compliant payment devices, the payment service is responsible only for the delivery approval but not for the effective handling of other payment device related data, like audit and configuration. There is a specific configuration Property (IsEmulated) used to expose if the payment service is internally handling the payment device, or if an OPC UA enabled payment device is available, enabling direct access to payment device configuration and audit events.

The IsEmulated Property enable easy switch for the need, today, to handle MDB (and other legacy protocols) before fully switch to OPC UA compliant devices.

The payment service may supervise the audit collect for operation and reject new requests when the audit collect is not operating correctly using the IsCollectingAudit Variable of the AuditCollectType.

6.2.3 Standalone Payment Devices

As stated in 6.2.2, a payment device may be managed in a proprietary manner by the payment service. A standalone payment device is a payment device, that has a standardized OPC UA Server. It is responsible to receive money, either via a physical asset (coin, bill, or token), as a payment cash device, or cashless as a payment cashless device. It provides the information about the received money and mechanisms to payout money. It interacts with the payment service and the audit collect. A Vending Machine according to this specification may have zero to many standalone payment devices.

As there are different types of payment devices, the type hierarchy is shown in Figure 12.

The standalone payment device provides its interface by implementing an instance of a subtype of the StandalonePaymentDeviceType (shown in Figure 12, defined in 7.17), which is an abstract subtype of the PaymentDeviceType used in the payment service. The standalone payment device does not require OPC UA Client functionality.

The PaymentDeviceType provides the identification of the payment device in the Identification Object, defined in OPC 10000-100. The configuration of the standalone payment device is provided by the Configuration Object of BaseConfigurationType defined in 7.3. The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the standalone payment device. The payment device generates Events of VendingAuditEventType to provide audit data.

The abstract PaymentCashDeviceType defined in 7.18 defines common functionality for cash-based payment devices like the supported assets and the capability to payout cash. The concrete PaymentCoinDeviceType defined 7.19 represents standalone payment devices handing coins and / or token, with no additional functionality. The concrete PaymentBillDeviceType defined in 7.20 represents standalone payment devices handling bills and / or token, and provides additional functionality like cancelling the payout. The concrete PaymentCashlessDeviceType defined in 7.21 represents standalone payment devices handling cashless money, and provide the corresponding functionality.

6.2.4 UI

The UI (user interface) is the interface between the customer and the system. The UI is only related to the final customer interaction. Technical user interfaces for configuration or maintenance of the machine are not part of this component and not addressed by this specification. A Vending Machine according to this specification needs to have at least one UI, but may have several UIs.

The UI provides its interface by implementing an instance of the UIType (shown in Figure 13, defined in 7.23). The UI requires OPC UA Client functionality to access the payment service and the machine engine(s) of the Vending Machine. The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the UI. The UI generates Events of VendingBaseAuditEventType to provide audit data.

The UI receives the configuration of the Vending Machine by accessing the Machine Engine capabilities specific to a machine engine from the machine engine(s) of the Vending Machine by accessing the Capabilities Object of MachineEngineCapabilitiesType defined in 7.5. This includes the available selections and possible Options per selection. The availability of the selections is provided by the Status Object of MachineEngineStatusType defined in 7.7. The Delivery Object of MachineEngineDeliveryType defined in 7.6 expose the status of a delivery.

The UI receives price information for the selections as well as payment options provided by the payment service of the Vending Machine by accessing the PriceInformation Object of PriceInformationType defined in 7.11. A deliver request is triggered on the Delivery Object of PaymentServiceDeliveryType defined in 7.9.

6.2.5 Price service

The price service calculates the price of a selection of products and considers all discounts. Discounts may be gained on various vendor-specific options, like time of the day, expiry date of the product, availability of product, customer and discount programs, etc. A Vending Machine according to this specification needs to have access to exactly one price service. This price service may internally use other price services (see Annex B).

The price service provides its interface by implementing an instance of the PriceServiceType (shown in Figure 14, defined in 7.24). The price service does not require OPC UA Client functionality to access other components of the Vending Machine.

The PriceServiceType provides the identification of the payment service in the Identification Object, defined in OPC 10000-100. The configuration of the payment service is provided by the Configuration Object of BaseConfigurationType defined in 7.3. The configuration may be writable via the OPC UA interface to change the configuration of the payment service. The PriceInformation Object of PriceInformationType defined in 7.11 provides price information for deliverables of products potentially provided by various Vending Machines. The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the payment service.

6.2.6 Audit collect

The audit collect collects audit data from all components providing audit Events and makes them available for external access. A Vending Machine according to this specification supports exactly one audit collect, and in addition optionally one tax audit (see 6.2.7).

The audit collect provides its interface by implementing an instance of the AuditCollectType (shown in Figure 15, defined in 7.25). The optional Components Object of BaseComponentsType defined in 7.4 can provide information about subcomponents of the audit collect. The audit collect requires OPC UA Client functionality to access audit information of the payment service, the standalone payment devices, the UI(s) and the machine engine(s) of the Vending Machine.

6.2.7 Tax audit

A special case of the audit collect is the TAX audit, which is selecting all tax relevant information of the audit information. This component is implemented according to the tax regulations of the area the Vending Machine is operating, and receives and processes all tax relevant information.

It provides and uses the same interfaces as the audit collect (see 6.2.6), but filters the audit Events to those relevant for the tax regulations. Depending on the tax regulations, different audit Events may be relevant.

In the following sections, the tax audit is included when an audit collect component is referenced.

6.3 Interactions between components

6.3.1 General Considerations on handling method processing

In OPC UA, each service call is executed asynchronously between Client and Server. This is also true for calling an OPC UA Method from a Client. However, a Method call is expected to return a result rather fast (milliseconds or seconds, when provided to a UI it should be milliseconds up to small fractions of a second), not after minutes. Therefore, in cases where the actual execution like creating a product may take longer, the Method is returning a result immediately, before the execution has been done, and the status of the execution is provided by some Variables. This is applied in various places in this specification.

In order to not lose any data, Clients should subscribe to the status Variables to get notified about all changes of the status.

6.3.2 Requesting and Delivering Products

6.3.2.1 Overview

In the following sections, the interactions for providing the main functionality of a Vending Machine, the requesting and delivering of products, is described.

In Figure 16, an overview of the needed components and the interfaces used is given. The interface names reflect the Object names of the corresponding ObjectTypes. To emphasise, that the UI is accessing the status of the Delivery Object of the machine engine, but not calling the Deliver Method, the DeliveryStatus interface was introduced. Same applies for StopDelivery, referencing to the StopDelivery Method of the Delivery Object of the machine engine.

A Vending Machine contains one main price service, which internally may use additional price services (see Annex B).

6.3.2.2 TransactionId

A TransactionId (UInt64) is used to uniquely identify a deliver request. It is generated by the payment service and distributed to other components of the Vending Machine. The uniqueness can only be guaranteed for a certain amount of time in order to identify different deliver requests at the same time, which must be unique at least for the whole time the transaction is active. A reasonable strategy to assign the TransactionId is increasing the number every time by one and roll over to 0 at the maximum of UInt64. However, the strategy of assigning a TransactionId is vendor-specific and other components shall not make assumptions about this.

The TransactionId will not protect against false delivery request; there is protection given using the OPC UA security mechanisms, i.e., only specific Clients can communicate and request deliveries.

6.3.2.3 BasketId

A Vending Machine may support the delivery of many products at once. This can be handled in two ways.

Either by defining selections that consists of various products (e.g., a menu). In that case, it is handled like any other delivery, potentially using different outputs to deliver more than one product.

Or it may support a basket, where the user can select several products into one basket and according to the content the user may get a discount. In that case, a BasketId (UInt64) is used to uniquely identify the basket. It is generated by the payment service and distributed to other components of the Vending Machine. The same assumptions for uniqueness apply as for the TransactionId. In order to support a BasketId, the Delivery Object of the payment service needs to be of type PaymentServiceBasketDeliveryType.

Not all payment services may support basket functionality.

6.3.2.4 Startup of UI

When the UI gets started, it needs to connect to the machine engine(s) it is interested in. Depending on the UI this may be based on user interactions selecting the interesting machine engine(s).

The UI needs to read the information of the Capabilities Object of the machine engine. It may cache the information and just check the SelectionListVersion, if the configuration has changed. The UI needs to subscribe to changes of the status of the machine engine (see 6.3.2.5) to display information like a certain product is not available.

Given the SelectionId and AvailableOptionIds provided by Capabilities are only machine specific and used primarily to provide the needed info for the Deliver method, the UI need to map using separate tables (not part of this specification, typically generated by the back-end software and called plan-o-grams) the SelectionId and AvailableOptionIds to the correct graphic resources in the UI itself.

The UI needs to access the price information of the payment service by accessing the PriceInformation Object of the payment service, and potentially the PaymentModes Object to get information about the available payment modes and their status.

The price for a product is taken by combining the selection parameters (SelectionId, and Options which are machine specific) and the MachineEngineProductInstanceUri to identify the machine engine and the plan-o-gram which defines the final product to be delivered. Typically, this is done in the UI by loading the plan-o-gram into the UI.

If the price service is located on the same hardware of a vending machine, for the vending machine itself the SelectionId and Options have a defined and unique value being connected with the vending machine where they are implemented. Still, given price services can be chained, if chaining is implemented the price search can still be extended.

Any allergens, nutrition values and similar information associated with a product are not provided by mechanisms of this specification, but are typically provided by the plan-o-gram loaded into the UI.

6.3.2.5 Update UI with status of machine engine

While connected to a machine engine, the UI needs to check the status of the machine engine, by subscribing to the corresponding Variables of the Status Object of the machine engine.

In addition, it needs to subscribe to the DeliveryRequests and DeliveryProgress Variables of the Delivery Object of the machine engine. This may be done when connecting to the machine engine and is required once the UI has started a deliver request via the payment service using the DeliverRequest Method of the Delivery Object of the payment service.

6.3.2.6 Update UI with status of payment service

In order to display the price for products the UI needs to get the price information of the products. This is done calling the corresponding Methods of the PriceInformation Object of the payment service. The price may depend on the UserId and PaymentMode, therefore the UI needs to call the Methods each time, this is changing. In addition, the UI should subscribe to Events of the PriceChangeEventType to get the information, when the price information was changed and the Methods need to be called, again.

When the UI has requested a delivery, it needs to subscribe to the TransactionProgress Variable of the Delivery Object to get updates on the progress of the payment.

In case a basket is requested, it needs to subscribe to the overall basket status in the BasketProgress Variable.

In case the user is filling a basket, the UI needs to call the GetPriceForBasket Method of the PriceInformation Object each time the content of the basket is changing (adding or removing items) to get the price for the current basket.

The UI may use the Status Variable of the Status Object to display the overall status of the Vending Machine.

6.3.2.7 Requesting a delivery by the UI

UI calls payment service (DeliverRequest Method)

When a user selects a product to be delivered, the UI calls the DeliverRequest Method of the Delivery Object of the payment service. This includes the last price information recovered by the last PriceInformation Object, the PaymentMode selected, and a generic UserId (the meaning of the variable is custom specific, the effect is to possibly change the price). The payment service generates a TransactionId and returns this to UI.

The payment service may already do some of the following steps before returning the DeliverRequest Method call and potentially return a failure status instead of the TransactionId. This is up to the implementation of the payment service. However, it needs to be considered that the Method call should return rather fast (as fast as possible, not waiting till the end of the delivery, maybe milliseconds), not after minutes (see also 6.3.1).

Payment service checks correct price (internal or via price service)

The payment service checks the correctness of the price provided by the UI. Since the payment service needs to maintain the current price for the UI anyhow, it can check its local data. Alternatively, the payment service may access the primary price service again to validate the price. When the price is not correct, the payment service does not continue the deliver request and provides the corresponding status of the TransactionId in its TransactionProgress Variable.

Payment service collects payment (internal functionality)

The payment service collects the payment from the user. How this is done, is up to the nature of the payment service. It may be collecting coins or bills, charging a credit card, etc. Once successfully collected, the payment service changes the status of the TransactionId in its TransactionProgress Variable. If the payment process gets somehow aborted (implementation specific), the payment service does not continue the deliver request and provides the corresponding status of the TransactionId in its TransactionProgress Variable. The UI may handle this transparent to the user and do another deliver request with a different payment mode.

Payment service triggers delivery in machine engine (Deliver Method)

Once the payment is collected, the payment service triggers the delivery at the machine engine by calling the Deliver Method of the Delivery Object of the machine engine. It provides the TransactionId so that the machine engine can provide the TransactionId in its DeliveryRequests and DeliveryProgress Variables.

Delivery by machine engine (internal functionality)

The machine engine potentially creates the product to be delivered (e.g., coffee) and delivers it to the user. How this is done is vendor-specific. Via the DeliveryProgress Variable it informs the UI and the payment service about the status of the delivery.

Once the delivery was successfully done, the payment service informs the UI about closure of the payment via its TransactionProgress Variable.

When the delivery is aborted, for example due to an error in the machine engine, the machine engine informs both UI and payment service via the DeliveryProgress Variable. In this case, the payment service triggers (if possible) a refund of the payment to the user. How this is done, is specific to the payment service. The payment service informs the UI about this using its TransactionProgress Variable.

In both cases, the successful delivery or the abortion, the payment service and the machine engine will clean up their status Variables and remove the information about the TransactionId. The duration before doing this is vendor-specific.

6.3.2.8 Requesting a delivery stop by the UI

When a delivery has been requested by the UI as described in 6.3.2.7 in step 1, the delivery may be cancelled by the CancelDeliverRequest Method.

When the CancelDeliverRequest Method is called before the payment is collected by the payment service (step 3 in 6.3.2.7), the Method call should be successful. In that case, the payment service does not continue the deliver request and provides the corresponding status of the TransactionId in its TransactionProgress Variable.

When the CancelDeliverRequest Method is called while or after the payment gets collected by the payment service (step 3 in 6.3.2.7), but before requesting the deliver in the machine engine, and the payment service is able to refund the payment, the Method call should be successful. In that case, the payment service triggers a refund, does not continue the deliver request and provides the corresponding status of the TransactionId in its TransactionProgress Variable.

When the CancelDeliverRequest Method is called after the payment service has called the Deliver Method of the machine engine (step 4 in 6.3.2.7), the Method call should fail and no cancellation is possible anymore.

6.3.2.9 Requesting a basket delivery by the UI

In order to support this functionality, the Delivery Object of the payment service needs to be of type PaymentServiceBasketDeliveryType.

UI calls payment service (DeliverBasketRequest Method)

When a user selects the products to be delivered, the UI calls the DeliverBasketRequest Method of the Delivery Object of the payment service. This includes the price information as displayed to the user. The payment service generates a TransactionId per item of the basket and a BasketId and returns this to UI.

The payment service may already do some of the following steps before returning the DeliverBasketRequest Method call and potentially return a failure status instead of the TransactionId. This is up to the implementation of the payment service. However, it needs to be considered that the Method call should return rather fast (milliseconds or seconds), not after minutes.

Payment service checks correct price (internal or via price service)

The payment service checks the correctness of the price provided by the UI. Since the payment service needs to maintain the current price for the UI anyhow, it can check its local data. Alternatively, the payment service may access the primary price service again to validate the price. When the price is not correct, the payment service does not continue the deliver request and provides the corresponding status of the BasketId in its BasketProgress Variable and in addition per item the TransactionIds in its TransactionProgress Variable.

Payment service collects payment (internal functionality)

The payment service collects the payment from the user. How this is done, is up to the nature of the payment service. It may be collecting coins or bills, charging a credit card, etc. Once successfully collected, the payment service changes the status of the TransactionIds in its TransactionProgress Variable and the overall status of the BasketId in its BasketProgress Variable. If the payment of the whole basket is handled at once, that requires that the TransactionProgress of all TransactionIds of the basket shall change at the same time. If the payment process gets somehow aborted (implementation specific), the payment service does not continue the deliver request and provides the corresponding status of the TransactionIds in its TransactionProgress Variable and the overall status of the BasketId in its BasketProgress Variable. The UI may handle this transparent to the user and do another basket deliver request with a different payment mode.

Payment service triggers delivery in machine engine (Deliver Method)

Once the payment is collected, the payment service triggers the delivery per item of the basket at the corresponding machine engines by calling the Deliver Method of the Delivery Object of the machine engine per item. It provides a TransactionId per item of the basket, so that the machine engine can provide the TransactionId for each item in its DeliveryRequests and DeliveryProgress Variables. Whether the payment service calls the Deliver Method for all items in parallel or serializes by some internal logic the requests, is an implementation detail of the payment service.

Delivery by machine engine per item of the basket (internal functionality)

The machine engine potentially creates the product to be delivered (e.g., coffee) and delivers it to the user. How this is done is vendor-specific. Via the DeliveryProgress Variable it informs the UI and the payment service about the status of the delivery.

Once the delivery of all items was successfully done, the payment service informs the UI about closure of the payment via its TransactionProgress Variable.

When the delivery is aborted, for example due to an error in the machine engine, the machine engine informs both UI and payment service via the DeliveryProgress Variable. In this case, the payment service triggers a refund of the payment to the user. How this is done, is specific to the payment service. The payment service informs the UI about this using its TransactionProgress Variable. In addition, it updates the overall status of the basket in the BasketProgress Variable.

In both cases, the successful delivery or the abortion, the payment service and the machine engine will clean up their status Variables and remove the information about the TransactionId. The duration before doing this is vendor-specific.

Clean up of the basket information (internal functionality)

Once the delivery of all items of the basket has been finalized (either successful or not), the payment service updates the BasketProgress Variable. The payment service will clean up this Variable and remove the information about the BasketId. The duration before doing this is vendor-specific.

6.3.2.10 Requesting a basket delivery stop by the UI

When a basket delivery has been requested by the UI as described in 6.3.2.9 in step 1, the delivery may be cancelled by the CancelDeliverBasketRequest Method.

When the CancelDeliverBasketRequest Method is called before the payment is collected by the payment service (step 3 in 6.3.2.9), the Method call should be successful. In that case, the payment service does not continue the deliver request and provides the corresponding status of the TransactionIds in its TransactionProgress Variable and the overall status of the BasketId in its BasketProgress Variable.

When the CancelDeliverBasketRequest Method is called while or after the payment gets collected by the payment service (step 3 in 6.3.2.9), but before requesting any deliver in any machine engine, and the payment service is able to refund the payment, the Method call should be successful. In that case, the payment service triggers a refund, does not continue the deliver request and provides the corresponding status of the TransactionIds in its TransactionProgress Variable and the overall status of the BasketId in its BasketProgress Variable.

When the CancelDeliverBasketRequest Method is called after the payment service has called the Deliver Method of any machine engine (step 4 in 6.3.2.9) for any of the TransactionIds of the basket, the Method call should fail and no cancellation is possible anymore.

6.3.3 Handling Payment Devices

6.3.3.1 Overview

A Vending Machine may have several payment devices responsible to handle money, either received from a customer or provided to the customer. Those devices may be handled in a proprietary way by the payment service, or accessed using a standardized OPC UA information model defined in this specification. The type hierarchy for those devices is introduced in 6.2.3. The following clauses describe the interactions between the payment services and the different types of payment devices.

6.3.3.2 Coin devices

The payment service reads the configuration of the payment device like the SupportedAssetList and the SlotConfigurationList. It may monitor the SupportedAssetListVersion to get notified, when the configuration has changed. It should monitor the Status of the payment device and take appropriate actions if it changes. The AssetConfigurationList defines how to handle specific coins or tokens and can be changed by the payment service using the ChangeAssetConfigurationList Method.

By configuring the AssetConfigurationList to reject all supported assets, the payment service can effectively disable a payment device.

By monitoring the CurrentAvailableValue the payment service knows how much money is currently in the payment device that a customer has already added to the payment device and can be used for a delivery. By calling the ConsumeAvailableValue Method, the payment service can actually consume part of the CurrentAvailableValue.

By monitoring the CurrentSlotContentList the payment service knows the available money currently in the payment device for payout. By monitoring the PayoutStatus the payment service knows about the status of any payout, that can be triggered by the PayoutByValue and PayoutBySupportedAssetList Methods.

A payout does not change the CurrentAvailableValue. If the payment service wants to trigger a logic, that a payout does decrease the CurrentAvailableValue, it needs to call the ConsumeAvailableValue Method in addition to the Method for the payout.

6.3.3.3 Bill devices

The payment devices supporting bills have some additional functionality to that the payment devices for coins support. They allow to cancel a running payout with the CancelPayout Method and provide information about the current bill or token in the escrow. With the HandleBillFromEscrow Method, the payment service can control what the payment device is supposed to do with the current bill in the escrow.

6.3.3.4 Cashless devices

The payment service supervises information from the cashless payment devices, like the UserId, MaxRecharge and CurrentContentOnCard Variables.

The payment service may charge money with the Approve Method. The ApproveStatus Variable provides the result, as the approval may take time. While the approval process is ongoing, the payment service may try to cancel it by calling the CancelApproval Method.

The payment service may add money to the card with the Recharge Method. The RechargeStatus Variable provides the result, as the recharging may take time.

The payment service may refund the last approved charging with the RefundLast Method. The RefundLastStatus Variable provides the result, as the refunding may take time.

The payment service may enable or disable the payment device with the EnableOrDisable Method. The IsEnabled Variable provides the result, as the operation may take time.

6.3.4 Audit

Audit information is provided by OPC UA Events. The VendingBaseAuditEventType defined in 7.26 and its subtypes are used for all audit information. The general audit collect is supposed to subscribe to all Events of VendingBaseAuditEventType from all UIs, all machine engines, the payment service and all payment devices having their own OPC UA Server of the Vending Machine. The optional, specialized tax audit component would only subscribe to Events relevant for the tax regulations.

An audit collect may need identification information of the components its accesses, and as special case for the payment service also the identification of the payment devices. This is provided by the IdentificationType.

For some payment devices, it is required to access configuration information in order to interpret the audit information. Potentially, also the current content of those payment devices needs to be accessed, which in principle could be calculated out of the Events if the initial content is known. This information is provided by Objects of PaymentDeviceType.

As a Vending Machine may be configured not to work when no audit is collected, the audit collect provides a IsCollectingAudit Variable which may be supervised by the payment service, which may reject new requests while the audit is not collected.

In Figure 17, an overview of the needed components and the interfaces used is given.

An OPC UA Server may represent several components of a Vending Machine, and as a special case, for the payment service, the payment devices. All those components individually generate Events of VendingBaseAuditEventType, in order to relate the Events to the corresponding component. The audit collect should subscribe to the 0:Server Object and filter for Events of VendingBaseAuditEventType to receive all audit information of the individual components of an OPC UA Server. In Figure 18, an example is given of an OPC UA Server AddressSpace, providing a machine engine and a payment service with two payment devices. X:MyMachineEngine, X:MyPaymentService, X:MyCoins and X:MyBills are all of TypeDefinitions generating Events of VendingBaseAuditEventType. At the bottom of Figure 18 some examples of Events are sketched, showing how the SourceNode and SourceName of the Events are identifying the source of the Events.

6.3.5 Initial Connection, reconnecting, and ConfigurationChangedEvents

Components like audit collect may want to keep track of information of components of a Vending Machine, and potentially subcomponents. Therefore, when initially connecting to an OPC UA Server representing one or several components of a Vending Machine, those components need to browse and read the required information. For example, audit collect does need some information, to interpret the audit information. Therefore, it may need to browse the PaymentDevices and PaymentModes of the payment service. In order to keep track of changes of the configuration of components of a Vending Machine, the audit collect should subscribe to ConfigurationChangedEvents, and in case it receives such an Event re-browse and reread the information of that component. Although the configuration of a Vending Machine is typically quite static, it may be that at restart some devices like a bill validator take a much longer time to restart, and therefore get added to the configuration while the Vending Machine is already running.

When a component like audit collect is reconnecting to an OPC UA Server representing one or several components of a Vending Machine, there are two scenarios:

The connection could be re-established without loss of data. That means, the subscription is still running and the data indicate no loss of data. In that case, the component does not need to do any specific actions.

The connection could not be re-established or some losses of data have been indicated. In that case, the component needs to reread the information from the OPC UA Server.

6.3.6 Configuration

The configuration of components of a Vending Machine is vendor-specific and not defined in this specification. This specification does define an entry point where vendors are supposed to manage their configuration options, an Object called Configuration of the BaseConfigurationType defined in 7.3.

In Figure 19 an overview of the needed components and the interfaces used is given. The Configuration Client component is vendor-specific and not further described in this specification.

7 OPC UA ObjectTypes

7.1 MachineEngineType definition

7.1.1 Overview

The MachineEngineType provides the interface to access the machine engine. It is used by other components like the UI, the payment service and the audit collect. A more detailed overview is given in 6.2.1. It is formally defined in Table 15.

7.1.2 ObjectType definition

The 2:Identification Object provides Properties describing the identification of the machine engine (see 7.2 for details).

The Configuration Object provides the configuration information of the machine engine (see 7.3 for details).

The Capabilities Object provides configuration information for the UI (see 7.5 for details).

The Delivery Object provides functionality to request a delivery (by the payment service) as well as expose the status of the delivery (displayed by the UI) (see 7.6 for details).

The Status Object provides the overall status of the machine engine, to be displayed in the UI and consumed by the payment service (see 7.7 for details).

The optional Components Object is the entry point to information about subcomponents of the machine engine (see 7.4 for details).

The GeneratesEvent Reference to the VendingBaseAuditEventType indicates that instances will generate Events of that EventType (see 7.26 for details).

The GeneratesEvent Reference to the ConfigurationChangedEventType indicates that an instance may generate Events of that EventType (see 7.29). Such an Event shall be generated when Objects gets added or removed from the Components Object, or when the values of Variables of the Configuration or Capabilities change. Multiple changes may be reported by a single Event.

7.2 IdentificationType definition

7.2.1 Overview

The IdentificationType provides identification information of components of a Vending Machine. It is formally defined in Table 16.

7.2.2 ObjectType definition

The ObjectType implements the Interface 2:IVendorNameplateType. The Properties of the 2:IVendorNameplateType Interface shall be used as defined in OPC 10000-100.

The 2:Manufacturer Property shall use the three-character manufacturer identification as defined in Annex B of EVA DTS, if the company is represented in that annex. The LocaleId shall be left empty.

The 2:ProductInstanceUri Property identifies the component globally unique, as defined in OPC 10000-100. The maximum length is 255 characters, as defined in OPC 10000-100. It is recommended to use the 2:ManufacturerUri followed by the 2:Model followed by the 2:SerialNumber, for example "https://example.com/Model_ABC/SN12345678".

If the component is delivered with a specific hardware, the 2:HardwareRevision Property shall be provided. If the component is only provided as software, it may be omitted.

7.3 BaseConfigurationType definition

7.3.1 Overview

The BaseConfigurationType provides configuration information of components of a Vending Machine. It is formally defined in Table 17.

7.3.2 ObjectType definition

The optional 0:LocalTime Property provides information about the current difference between the local time and the UTC time of the component. If the OPC UA Server is in the same local time (which typically is the case), the 0:LocalTime Property of the Server Object of the OPC UA Server may be referenced.

The optional DefaultCurrency Property provides the default currency the component uses when sending/receiving values of PriceDataType without a specified currency. When the default currency is provided, any usage of PriceDataType is setting the Currency field to NULL, if the DefaultCurrency is used. Any change of the DefaultCurrency requires a restart of the OPC UA Server. If an OPC UA Server provides several components with a DefaultCurrency (e.g., payment service and payment devices), the DefaultCurrency shall be identical for all those components.

Vendors may add additional configuration information to this Object. Vendors may define subtypes of this ObjectType in their implementations.

The configuration may be writable via the OPC UA interface to change the configuration of the Vending Machine component.

7.4 BaseComponentsType definition

7.4.1 Overview

The BaseComponentsType provides an entry point for subcomponents of components of a Vending Machine. It is formally defined in Table 18.

7.4.2 ObjectType definition

The <Component> Object of optional placeholder is a representative for subcomponents that may be added to the Object. This specification does not define any requirements on how to represent a subcomponent.

Vendors may define subtypes of this ObjectType in their implementations.

7.5 MachineEngineCapabilitiesType definition

7.5.1 Overview

The MachineEngineCapabilitiesType provides configuration information for the UI. It is formally defined in Table 19.

7.5.2 ObjectType definition

The Options Variable provides the available options of the machine engine. For each possible selection in the SelectionList, it is defined what options are allowed to be used. The DataType is defined in 8.1. Each OptionId in the array shall be unique.

The SelectionList Variable provides the available selections of the machine engine. The DataType is defined in 8.2. Each entry of AvailableOptionIds shall be unique and shall also be an OptionId in the Options Variable.

The SelectionListVersion provides the current version of the SelectionList. Clients may cache the SelectionList and only access it after reconnect, if the SelectionListVersion has changed. Therefore, each change in the SelectionList shall change the SelectionListVersion. The same SelectionListVersion shall only be used if the new SelectionList is identical to the content of the previous SelectionList using the same SelectionListVersion. As the Options are used from the SelectionList, this also applies to the Options. If the Options are changing, the SelectionListVersion shall change as well.

The OutputIds provide a list of outputs for products the machine engine supports. It shall have at least one entry.

7.6 MachineEngineDeliveryType definition

7.6.1 Overview

The MachineEngineDeliveryType provides functionality to request a delivery (by the payment service) as well as exposes the status of the delivery (displayed by the UI). It is formally defined in Table 20.

7.6.2 ObjectType definition

The DeliveryRequests Variable is an array that contains all delivery requests that have recently been added to the machine engine. It shall contain all delivery requests that are currently executing or are queued for execution. It is up to the implementation when the finished delivery requests get removed from the array. The simplest implementation just manages one entry and disallows a new delivery request while there is already one in execution. The DataType is defined in 8.3.

The DeliveryProgress Variable is an array that contains the progress information of delivery requests that are currently in execution or have recently been executed. It shall have one entry for each delivery request entry in the DeliveryRequests Variable. The DataType is defined in 8.5. It is up to the implementation how often to update the ProgressInPercent of a delivery progress entry. When the Status is changing, the entry of a delivery progress shall change.

7.6.3 Deliver Method

The Deliver Method puts a delivery request into the machine engine. When successfully executed, the delivery request shall be added to the DeliveryRequests Variable, and, considering the internal logic of the machine engine with respect to the order of the delivery requests, being executed. The status of the execution shall be reflected in the DeliveryProgress Variable.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and no entries are added to the DeliveryRequests and DeliveryProgress Variables.

The signature of this Method is specified below. Table 21 and Table 22 specify the Arguments and AddressSpace representation, respectively.

Signature

	Deliver (
	  [in]  0:String                      SelectionId,
	  [in]  OptionSelectionDataType[]     Options,
	  [in]  0:UInt64                      TransactionId,
	  [out] 0:Int32                       Status);

Method Result Codes (defined in Call Service)

7.6.4 StopDelivery Method

The StopDelivery Method stops the physical delivery of a TransactionId, that has already been started. When executed, the delivery is still counted to be successfully delivered. The StopDelivery may be called by the UI, when for example a cup is overflowing with a coffee delivery.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed and the delivery was not stopped.

The signature of this Method is specified below. Table 23 and Table 24 specify the Arguments and AddressSpace representation, respectively.

Signature

	StopDelivery (
	  [in]  0:UInt64                      TransactionId,
	  [out] 0:Int32                       Status);

Method Result Codes (defined in Call Service)

7.7 MachineEngineStatusType definition

7.7.1 Overview

The MachineEngineStatusType provides status information of the machine engine. It is formally defined in Table 25.

7.7.2 ObjectType definition

The WorkingStatus Variable provides the information about the main status of the machine engine. The DataType is defined in 8.10.

The OutputStatus Variable indicates the status of each output from the machine engine. It shall have one entry per entry of the OutputIds of Capabilities with the same OutputId. The DataType is defined in 8.7.

The SelectionIdStatus Variable is an array and indicates for each selection the status. The UI should use this information to indicate if a selection is currently not available. For each entry in the SelectionList of the Capabilities Object there shall be an entry in the SelectionIdStatus. There shall not be entries in the SelectionIdStatus, that are not also in the SelectionList. The DataType is defined in 8.11.

The OptionIdStatus Variable is an array and indicates for each Option the status. The UI should use this information to indicate if an Option of a selection is currently not available. For each entry in the Options of the Capabilities Object there shall be an entry in the OptionIdStatus. There shall not be entries in the OptionIdStatus, that are not also in the Options. The DataType is defined in 8.11.

The <SensorData> Variable is an optional placeholder indicating that vendors may add additional sensor data to the Status Object. In this case, the AnalogUnitType should be used in order to provide meta data like the EngineeringUnits.

The MainHotTemperature is an optional Variable that should be used in Vending Machines where there is one main hot temperature, like the hot water temperature of a coffee machine.

The MainColdTemperature is an optional Variable that should be used in Vending Machines where there is one main cold temperature, like the cold air temperature in a snack or beverage machine.

The ActiveEVADTSStatusCodes Variable is an array of active status codes according to Annex C of EVA DTS.

7.8 PaymentServiceType definition

7.8.1 Overview

The PaymentServiceType provides the interface to access the payment service. It is used by other components like the UI and the audit collect. A more detailed overview is given in 6.2.2. It is formally defined in Table 26.

7.8.2 ObjectType definition

The 2:Identification Object provides Properties describing the identification of the payment service (see 7.2 for details).

The Delivery Object provides the functionality to trigger a delivery by the UI (see 7.9 for details). In order to support a BasketId (see 6.3.2.3), the Delivery Object needs to be of type PaymentServiceBasketDeliveryType (see 7.10 for details).

The Configuration Object provides the configuration information of the payment service (see 7.3 for details).

The PriceInformation Object provides the prices for the selections of the machine engines, managed by the payment service (see 7.11 for details).

The optional PaymentModes Object contains one Object of PaymentModeType per payment mode supported by the payment service. It shall reference at least one Object of PaymentModeType (see 7.13 for details).

The optional PaymentDevices Object contains one Object of PaymentDeviceType per payment device provided by the payment service. It shall reference at least one Object of PaymentDeviceType (see 7.15 for details). Several payment devices may support the same payment mode. For example, there may be the payment mode "Cash" and the payment devices "Coin" and "Bill".

The PaymentModes and PaymentDevices Objects are optional and should be included only if the vending machine charges a price for any of the offered products; otherwise, they should be omitted.

The Status Object provides the status of the payment service and thereby of the overall Vending Machine (see 7.22 for details).

The optional Components Object is the entry point to information about subcomponents of the payment service (see 7.4 for details).

The GeneratesEvent Reference to the VendingAuditEventType indicates that instances will generate Events of that EventType (see 7.27 for details).

The GeneratesEvent Reference to the ConfigurationChangedEventType indicates that an instance may generate Events of that EventType (see 7.29). Such an Event shall be generated when Objects gets added or removed from the Components, PaymentModes or PaymentDevices Objects, or when the values of Variables of the Configuration change. Multiple changes may be reported by a single Event.

Note: Changes of Variables of the PaymentModes like AvailableCredit or the PaymentDevices do not trigger the creation of a ConfigurationChangedEvent. Clients interested in changes of those Variables need to subscribe to them.

7.9 PaymentServiceDeliveryType definition

7.9.1 Overview

The PaymentServiceDeliveryType provides the functionality to trigger a delivery by the UI. It is formally defined in Table 27.

7.9.2 ObjectType definition

The TransactionProgress Variable is an array that contains the progress information of the payment of the delivery requests that are currently in execution or have recently been executed. The DataType is defined in 8.15. When the Status is changing, the entry of a delivery progress shall change. It is up to the implementation when the finished delivery requests get removed from the array. The simplest implementation just manages one entry and disallows a new delivery request while there is already one in execution and will keep the value there till a new delivery is started.

7.9.3 DeliverRequest Method

The DeliverRequest Method puts a deliver request into the payment service. The payment service checks the correct price, collects the payment and puts the deliver request into the corresponding machine engine (see 6.3.2.7 for details).

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and no deliver request was added to the corresponding machine engine.

The signature of this Method is specified below. Table 28 and Table 29 specify the Arguments and AddressSpace representation, respectively.

If no UserId or PaymentMode is provided, the payment service assumes appropriate values. If the user choses a different UserId or PaymentMode when initiating the payment, that effects the price, the transaction may fail. The entry of the transaction in the TransactionProgress Variable indicates the used UserId and PaymentMode. The UI may use this information to get the price for those, displays it to the user and if the user accepts, automatically triggers a new DeliverRequest.

Signature

	DeliverRequest (
	  [in]  0:String                   UserId,
	  [in]  0:String                   PaymentMode,
	  [in]  SelectionDataType          Selection,
	  [in]  PriceDataType              Price,
	  [out] 0:UInt64                   TransactionId,
	  [out] 0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.9.4 CancelDeliverRequest Method

The CancelDeliverRequest Method requests to cancel a deliver request. The payment service checks if the deliver request can still be cancelled, and if yes, cancels the request, otherwise returns a corresponding Status argument.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and the TransactionId was not cancelled.

The signature of this Method is specified below. Table 28 and Table 29 specify the Arguments and AddressSpace representation, respectively.

Note: If a TransactionId is used inside a basket (see 7.10), it cannot be cancelled individually. A call of the Method with such a TransactionId should return a -2 Status.

Note: Once a TransactionId has been forwarded to the MachineEngine it is expected that it cannot be cancelled anymore and should return a -2 Status.

Signature

	CancelDeliverRequest (
	  [in] 0:UInt64                    TransactionId,
	  [out] 0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.10 PaymentServiceBasketDeliveryType definition

7.10.1 Overview

The PaymentServiceBasketDeliveryType provides the functionality to trigger the delivery of a basket by the UI. It is formally defined in Table 32.

7.10.2 ObjectType definition

The BasketProgress Variable is an array that contains the progress information of the payment of the basket delivery requests that are currently in execution or have recently been executed. The DataType is defined in 8.17. When the Status is changing, the entry of a delivery progress shall change. It is up to the implementation when the finished basket delivery requests get removed from the array. The simplest implementation just manages one entry and disallows a new basket delivery request while there is already one in execution.

Note that in addition to the BasketProgress the TransactionProgress provides the status of the individual entries of the basket.

7.10.3 DeliverBasketRequest Method

The DeliverBasketRequest Method receives a set of deliver requests and puts them into one or several machine engines, after checking the correct price and collecting the (see 6.3.2.9 for details).

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and no basket was created.

The signature of this Method is specified below. Table 33 and Table 34 specify the Arguments and AddressSpace representation, respectively.

If no UserId or PaymentMode is provided, the payment service assumes appropriate values. If the user choses a different UserId or PaymentMode when initiating the payment, that effects the price, the basket delivery may fail. The status of the basket indicates the used UserId and PaymentMode. The UI may use this information to get the price for those, displays it to the user and if the user accepts, automatically triggers a new DeliverRequest.

Signature

	DeliverBasketRequest (
	  [in]  0:String                   UserId,
	  [in]  0:String                   PaymentMode,
	  [in]  SelectionDataType[]        BasketContent,
	  [in]  PriceDataType              Price,
	  [out] 0:UInt64[]                 TransactionIds,
	  [out] 0:UInt64                   BasketId,
	  [out] 0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.10.4 CancelDeliverBasketRequest Method

The CancelDeliverBasketRequest Method requests to cancel all deliver requests of a basket. The payment service checks if the basket can still be cancelled, and if yes, cancels all the requests of the basket, otherwise returns a corresponding Status argument.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and the BasketId was not cancelled.

The signature of this Method is specified below. Table 28 and Table 29 specify the Arguments and AddressSpace representation, respectively.

Signature

	CancelDeliverBasketRequest (
	  [in] 0:UInt64                    BasketId,
	  [out] 0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.11 PriceInformationType definition

7.11.1 Overview

The PriceInformationType provides information on selections with specific Options and baskets. It is provided by the payment service and the price service. It is formally defined in Table 37.

7.11.2 ObjectType definition

Instances of the PriceInformationType will generate Events of PriceChangeEventType, when the prices provided with one of the Methods may have changed, for example based on the time, different base prices, etc. Clients currently using the price information (e.g., for display) should subscribe for these Events and call the Methods again, after receiving the Event.

7.11.3 GetPriceForSelections Method

The GetPriceForSelections Method asks for the current price of all selections of a machine engine of the Vending Machine. It takes indications (UserId, PaymentMode) as input that influence the price. The output contains the price information including price information per Option.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and the returned PriceInformationList shall not be interpreted.

The signature of this Method is specified below. Table 38 and Table 39 specify the Arguments and AddressSpace representation, respectively.

Signature

	GetPriceForSelections (
	  [in]   0:String                   UserId,
	  [in]   0:String                   PaymentMode,
	  [in]   0:UriString                MachineEngineProductInstanceUri,
	  [in]   0:SemanticVersionString    SelectionListVersion,
	  [out]  SelectionPriceDataType[]   PriceInformationList,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.11.4 GetPriceForOneSelection Method

The GetPriceForOneSelection Method asks for the current price of one selection of the Vending Machine. It takes indications as input that influence the price. The output contains the price information.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and the returned PriceInformation shall not be interpreted.

The signature of this Method is specified below. Table 40 and Table 41 specify the Arguments and AddressSpace representation, respectively.

Signature

	GetPriceForOneSelection (
	  [in]   0:String                   UserId,
	  [in]   0:String                   PaymentMode,
	  [in]   SelectionDataType          Selection,
	  [out]  PriceAndContextDataType    PriceInformation,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.11.5 GetPriceForBasket Method

The GetPriceForBasket Method asks for the current price of a basket of selections of the Vending Machine. It takes indications as input that influence the price. The output contains the price information.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed, and the returned OverallPriceInformation and PriceInformationList shall not be interpreted.

The signature of this Method is specified below. Table 42 and Table 43 specify the Arguments and AddressSpace representation, respectively.

Signature

	GetPriceForBasket (
	  [in]   0:String                   UserId,
	  [in]   0:String                   PaymentMode,
	  [in]   SelectionDataType[]        BasketContent,
	  [out]  PriceDataType              OverallPriceInformation,
	  [out]  PriceAndContextDataType[]  PriceInformationList,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.12 PriceChangeEventType definition

7.12.1 Overview

The PriceChangeEventType describes Events that are fired to indicate a change in prices. It is formally defined in Table 44.

7.12.2 ObjectType definition

The Properties of the 0:BaseEventType shall be used according to their definitions. This specification does not define any further restrictions on the usage.

The MachineEngineProductInstanceUri contains the machine engine, for which the prices have changed. Clients should use this to filter only for those price change events they are interested in.

7.13 PaymentModesType definition

7.13.1 Overview

The PaymentModesType provides all payment modes of a payment service. It is formally defined in Table 45.

7.13.2 ObjectType definition

The <PaymentMode> Object indicates that Objects of PaymentModesType shall have one or more Objects of PaymentModeType, each representing one payment mode (see 7.14 for details).

7.14 PaymentModeType definition

7.14.1 Overview

The PaymentModeType provides information on selections with specific Options and baskets. It is provided by the payment service and the price service. It is formally defined in Table 46.

7.14.2 ObjectType definition

The Status represents the current status of the payment system supporting the payment mode (see 8.21 for details).

The PaymentModeId represents a unique identification of the payment mode, that is used in the DeliverRequest Method of the Delivery Object. It is recommended, that this string is also used for the text part of the DisplayName Attribute of the Object for the default locale. The PaymentMode "NoCheck" has a special meaning and shall not be used as PaymentModeId. The recommended PaymentModeId values are: "Cash" and "Cashless".

The optional CurrentlyUsedUserId provides information about the UserId currently used in the payment mode (e.g., when a customer card is used).

The optional AvailableCredit Variable contains the currently managed amount (e.g., coins already added to the machine, pre-charged credit card, etc.).

7.14.3 EscrowRefund Method

The optional EscrowRefund Method is provided when the payment mode contains an escrow area (e.g., a special area to keep coins). When called, the escrow gets returned.

The signature of this Method is specified below. Table 47 and Table 48 specify the Arguments and AddressSpace representation, respectively.

Signature

	EscrowRefund ();

Method Result Codes (defined in Call Service)

7.15 PaymentDevicesType definition

7.15.1 Overview

The PaymentDevicesType provides all payment devices of a payment service. It is formally defined in Table 49.

7.15.2 ObjectType definition

The <PaymentDevice> Object indicates that Objects of PaymentDevicesType shall have one or more Objects of PaymentDeviceType, each representing one payment device (see 7.16 for details).

7.16 PaymentDeviceType definition

7.16.1 Overview

The PaymentDeviceType provides information about a payment device. It is formally defined in Table 50.

7.16.2 ObjectType definition

The 2:Identification Object provides Properties describing the identification of the payment device (see 7.2 for details).

The string-part of the DisplayName of Objects of this ObjectType shall be the 2:ProductInstanceUri defined in the 2:Identification Object. This simplifies identifying in the Events of the VendingAuditEventType which payment device has generated the Event, as the 0:SourceName of the Event is the string-part of the DisplayName.

The mandatory Property IsEmulated indicates if the Object is just an emulation. When set to "true", it indicates that the Object of PaymentDeviceType is just an emulation representing the payment device, and the payment device itself provides an OPC UA Server with an instance of PaymentDeviceType. In that case, no Events of VendingAuditEventType are generated, and consumers of those Events need to subscribe to the OPC UA Server of the payment device for those Events. This is used in a payment service providing information about the payment device, but the payment device has its own OPC UA Server. When set to "false", it indicates that this Object is not emulated and generates Events of VendingAuditEventType. This is used in a payment service where the payment device does not have an OPC UA Server and in the payment device if the payment device has an OPC UA Server. In 6.2.2 more descriptive text is given.

The mandatory Status represents the current status of the payment device (see 8.21 for details). A payment device taking physical assets of value (e.g., coins, bills, and tokens) provides the information about the physical assets it supports in the SupportedAssetList Property. The list shall be in ascending order by the Amount, not considering the Currency. If no physical assets of value are taken, the optional SupportedAssetList shall not be provided. For coin changers the SupportedAssetList is the list of accepted coins and tokens, as for bill validators is the list of bills and tokens handled.

Note: Tokens are managed the same way as cash, but the Currency of the PriceDataType shall use 000 as NumericCode and 0 as Exponent.

The SupportedAssetListVersion provides the current version of the SupportedAssetList. Clients may cache the SupportedAssetList and only access it after reconnect, if the SupportedAssetListVersion has changed. Therefore, each change in the SupportedAssetList shall change the SupportedAssetListVersion. The same SupportedAssetListVersion shall only be used if the SupportedAssetList is identical to the content of the previous SupportedAssetList using the same SupportedAssetListVersion.

A payment device taking physical assets of value (e.g., coins, bills, and tokens) may have two places where to store those assets.

The cashbox (coins) or stacker (bills) stores the assets and will be emptied by the technician. Typically, the amount of value in the cashbox or stacker is not known. A VendingAuditEvent (see 7.27) gets generated when a new value is added to the cashbox or stacker. Therefore, no information on the amount of value in the cashbox or stacker is provided by the PaymentDeviceType.

The tube (for coins) or recycler (for bills) buffers the assets, so that they can be returned as change, payback or when the user cancels the order or requests a refund. Those buffers have different slots to store different types of coins, bills, or tokens. The information about the general setup of those slots is provided in the SlotConfigurationList. Each entry of the list of SlotConfigurationDataType (see 8.20) consists of two indexes, the first one identifying the slot and the second the asset going to the slot as an index into the SupportedAssetList. Several entries of the SupportedAssetList may be assigned to the same slot index. In this case, the Amount and Currency shall be identical. Several slot indexes may have the same entries of the SupportedAssetList assigned to them. The slot indexes shall start with 0 and increase without interruptions (0, 1, 2, 3, …). As special index -1 is used in the SlotConfigurationList to indicate that the referenced entry of the SupportedAssetList is directly moved into the cashbox / stacker. The SlotConfigurationList shall have at least one entry for each entry of the SupportedAssetList.

In the following, an example is given.

SupportedAssetList = { (10, € cent), (50, € cent), (50, € cent), (100, € cent), (100, € cent) }

SlotConfigurationList = {(-1,4), (0,0), (1,0), (2,1), (2,2), (3,3), (4,3) }

In the example, the machine accepts coins of 10, 50, and 100 € cent. It distinguishes between two different types of 50 and 100 € cent coins.

The buffer contains 5 slots, the first two (index 0 and 1) taking 10 € cent coins, another one (index 2) taking all 50 € cent coins, and two more taking 100 € cent coins of one type, whereas the second one never goes into the buffer but always directly into the cashbox (index -1, first entry in the SlotConfigurationList).

An Object emulating a payment device (IsEmulated = "true") should not provide the SupportedAssetList, SupportedAssetListVersion, and SlotConfigurationList.

An Object not emulating a payment device (IsEmulated = "false") and taking physical assets of value (e.g., coins, bills, and tokens) shall provide the SupportedAssetList, the SupportedAssetListVersion and the SlotConfigurationList.

Remark: The SupportedAssetList and SlotConfigurationList are needed to interpret Events of VendingAuditEventType having a SlotIndex.

The GeneratesEvent Reference to the VendingAuditEventType indicates that instances may generate Events of that EventType (see 7.27 for details).

7.17 StandalonePaymentDeviceType definition

7.17.1 Overview

The abstract StandalonePaymentDeviceType provides information about a payment device having its own OPC UA Server. It is formally defined in Table 51.

7.17.2 ObjectType definition

The Configuration Object provides the configuration information of the payment device (see 7.3 for details). It may provide the default currency used in the payment device.

The optional Components Object is the entry point to information about subcomponents of the payment device (see 7.4 for details).

The GeneratesEvent Reference to the ConfigurationChangedEventType indicates that an instance may generate Events of that EventType (see 7.29). Such an Event shall be generated when Objects gets added or removed from the Components Object, or when the values of Variables of the Configuration change. Multiple changes may be reported by a single Event.

7.18 PaymentCashDeviceType definition

7.18.1 Overview

The abstract PaymentCashDeviceType provides information about a payment device taking cash. It is formally defined in Table 52.

7.18.2 ObjectType definition

The inherited Variables SupportedAssetList, SupportedAssetListVersion, and SlotConfigurationList become mandatory in the PaymentCashDeviceType.

In case of the buffer (see 7.16.2), most payment devices maintain the information about the current amount stored in the buffer. If the payment device supports this information, it shall be provided in the CurrentSlotContentList Property. This list contains for each index representing a slot the number of physical assets currently in the slot. The list shall have the same size as the maximum slot index of the SlotConfigurationList.

In the following, an example is given, extending the example of 7.16.2.

SupportedAssetList = { (10, € cent), (50, € cent), (50, € cent), (100, € cent), (100, € cent) }

SlotConfigurationList = { (-1,4), (0,0), (1,0), (2,1), (2,2), (3,3), (4,3) }

CurrentSlotContentList = { 10, 3, 15, 7, 0 }

An explanation of SupportedAssetList and SlotConfigurationList can be found in 7.16.2.

The CurrentSlotContentList indicates, that there are 10+3 10 € cent coins, 15 50 € cent coins, and 7 100€ cent coins in the buffer.

The CurrentSlotContentList Variable value is the best approximation for the slot content, and may not be the exact number of assets in each slot, the behaviour can be manufacturer depended.

The mandatory AssetConfigurationList Variable is an array of AssetConfigurationEnum. The DataType is defined in 8.24. It shall have the same length as the SupportedAssetList. Each entry of the array defines what the payment device shall do with an asset as defined in the corresponding entry of the SupportedAssetList when inserted into the payment device. The AssetConfigurationList can be changed by the ChangeAssetConfigurationList Method defined in 7.18.3.

The optional PayoutStatus Variable indicates the status of a payout, requested via the PayoutByValue (see 7.18.4) or PayoutBySupportedAssetList (see 7.18.5) Method call. The DataType is defined in 8.25. The CurrentSlotContentList Variable needs to be updated when a payout occurs. If a payout was not successful, checking the CurrentSlotContentList indicates what assets have been paid out. The CurrentSlotContentList Variable can also be monitored to identify in case of a successful payout, what assets have been paid out.

The mandatory CurrentAvailableValue Variable indicates the amount of money currently available in the payment cash device for deliveries. When a user inserts an asset (e.g., a coin) that is accepted by the payment cash device, the CurrentAvailableValue increases. Typically, the CurrentAvailableValue is initialized to 0 when the payment cash device starts. When the ConsumeAvailableValue Method is called (see 7.18.6), the CurrentAvailableValue decreases according to the input parameters of the Method. Any payout operation (PayoutByValue or PayoutBySupportedAssetList Methods) does not affect the CurrentAvailableValue.

7.18.3 ChangeAssetConfigurationList Method

The ChangeAssetConfigurationList Method changes the configuration of the payment device reflected in the AssetConfigurationList.

If the execution of the Method cannot be done due to some application logic, the Method should return an Uncertain StatusCode and provide details of the failure in the Status output Argument. When the Method returns an Uncertain StatusCode, the Method is considered to be failed.

If the Method returns successful, the AssetConfigurationList shall reflect the new configuration.

The signature of this Method is specified below. Table 53 and Table 54 specify the Arguments and AddressSpace representation, respectively.

Signature

	ChangeAssetConfigurationList (
	  [in]   AssetConfigurationEnum[]   NewAssetConfigurationList,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)