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)

7.18.4 PayoutByValue Method

The PayoutByValue Method triggers a payout.

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, it does not indicate, that the payout has been completed successful. Clients need to access the PayoutStatus Variable to get the information, if the payout gets successfully finished.

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

Signature

	PayoutByValue (
	  [in]   PriceDataType              PayoutValue,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.18.5 PayoutBySupportedAssetList Method

The PayoutBySupportedAssetList Method triggers a payout.

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, it does not indicate, that the payout has been completed successful. Clients need to access the PayoutStatus Variable to get the information, if the payout gets successfully finished.

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

Signature

	PayoutBySupportedAssetList (
	  [in]   0:UInt32[]             NumberOfAssetsBySupportedAssetList,
	  [out]  0:Int32                Status);

Method Result Codes (defined in Call Service)

7.18.6 ConsumeAvailableValue Method

The ConsumeAvailableValue Method consumes part of the available money provided in the CurrentAvailableValue 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.

If the Method returns successful, it does indicate, that the CurrentAvailableValue Variable has been decreased.

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

Signature

	ConsumeAvailableValue (
	  [in]   PriceDataType              ValueToConsume,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.19 PaymentBillDeviceType definition

7.19.1 Overview

The PaymentBillDeviceType provides information about a payment device taking bills or token. It is formally defined in Table 61.

7.19.2 ObjectType definition

The CurrentValueInEscrow Variable indicates the asset currently in the escrow by pointing to the index of the SupportedAssetList.

7.19.3 CancelPayout Method

The CancelPayout Method cancels the current payout.

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, it indicates, that the current payout has been cancelled and will not continue.

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

Signature

	CancelPayout (
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.19.4 HandleBillFromEscrow Method

The HandleBillFromEscrow Method defines what the payment device shall do with the bill or token currently stored in the escrow.

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, it does not indicate, that the bill or token was already processed completely from the escrow. Clients need to access the CurrentValueInEscrow Variable to get the information, if the bill or token has successfully been moved.

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

Signature

	HandleBillFromEscrow (
	  [in]   0:Boolean                  AcceptBill,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.20 PaymentCoinDeviceType definition

7.20.1 Overview

The PaymentCoinDeviceType provides information about a payment device taking coins or token. It is formally defined in Table 66.

7.20.2 ObjectType definition

This ObjectType does not define any additional InstanceDeclarations.

7.21 PaymentCashlessDeviceType definition

7.21.1 Overview

The PaymentCashlessDeviceType provides information about a cashless payment taking for example credit cards. It is formally defined in Table 67.

7.21.2 ObjectType definition

The UserId Variable indicates the UserId associated with the card or other identification used for the cashless payment device. If the UserId is null or an empty string, it implies that there is currently nothing associated to the cashless payment device and neither money can be taken nor recharged.

The MaxRecharge Variable indicates how much money can be recharged to the account of the current UserId. Null or an amount of 0 indicates that no recharge functionality is available.

The CurrentContentOnCard Variable indicates how much money can currently be used. This may be the amount on a rechargeable card, or a fixed value already pre-charged from a credit card. A null value indicates that the amount is unknown. When no UserId is available, the CurrentContentOnCard shall be null.

The ApproveStatus Variable indicates the status of the last call of the Approve Method (see 7.21.4). The DataType is defined in 8.26. The CancelApproval Method (see 7.21.5) may be called while the approval is still ongoing to cancel the approval and thereby effecting the ApproveStatus.

The optional RechargeStatus Variable indicates the status of the last call of the optional Recharge Method (see 7.21.6). The DataType is defined in 8.26.

The RefundLastStatus Variable indicates the status of the last call of the RefundLast Method (see 7.21.7). The DataType is defined in 8.26.

The IsEnabled Variable indicates if the cashless payment device is enabled ("true") or disabled ("false"). When the payment device is disabled, the Approve, Recharge and RefundLast Methods will fail. IsEnabled can be changed by calling the EnableOrDisable Method.

7.21.3 Relation to MDB / ICP state for cashless devices

MDB / ICP defines several states for cashless devices. How to receive this information from the PaymentCashlessDeviceType is described in the following.

7.21.4 Approve Method

The Approve Method is charging money from an account associated to the current UserId. It may also check if it is allowed to sell the selection to the user (e.g., based on age restrictions).

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, it does not indicate, that the approve has been completed successful. Clients need to access the ApproveStatus Variable to get the information, if the approve successfully finished.

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

Signature

	Approve (
	  [in]   PriceDataType            Value,
	  [in]   0:String                 UserId,
	  [in]   SelectionDataType        Selection,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.21.5 CancelApproval Method

The CancelApproval Method is cancelling the current approval triggered by calling the Approve Method.

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.

The Method shall return an Uncertain StatusCode and the Status -1 when the ApproveStatus is not in "Ongoing" while the Method gets executed.

If the Method returns successful, it does not indicate, that the cancelling has been completed successful. Clients need to access the ApproveStatus Variable to get the information, if the cancelling of the approval has successfully finished.

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

Signature

	CancelApproval (
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.21.6 Recharge Method

The Recharge Method is recharging money to an account associated to the current UserId.

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, it does not indicate, that the recharge has been completed successful. Clients need to access the RechargeStatus Variable to get the information, if the recharge successfully finished.

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

Signature

	Recharge (
	  [in]   PriceDataType              Value,
	  [in]   0:String                   UserId,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.21.7 RefundLast Method

The RefundLast Method refunding the last successful operation executed with Approve. This is needed, for example, when a delivery cannot be executed but was already charged.

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, it does not indicate, that the approve has been completed successful. Clients need to access the RefundLastStatus Variable to get the information, if the approve successfully finished.

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

Signature

	RefundLast (
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)

7.21.8 EnableOrDisable Method

The EnableOrDisable Method changing the state of the payment device either to be disabled or enabled.

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, it does not indicate, that the state change has been completed successful. Clients need to access the IsEnabled Variable to get the information, if the change successfully finished.

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

Signature

	EnableOrDisable (
	  [in]   0:Boolean                  Enable,
	  [out]  0:Int32                    Status);

Method Result Codes (defined in Call Service)