traits/vending.proto

Table of Contents

• traits/vending.proto

  • Consumable

  • Consumable.IdsEntry

  • Consumable.MoreEntry

  • Consumable.Portion

  • Consumable.Quantity

  • Consumable.Stock

  • DispenseRequest

  • GetStockRequest

  • ListConsumablesRequest

  • ListConsumablesResponse

  • ListInventoryRequest

  • ListInventoryResponse

  • PullConsumablesRequest

  • PullConsumablesResponse

  • PullConsumablesResponse.Change

  • PullInventoryRequest

  • PullInventoryResponse

  • PullInventoryResponse.Change

  • PullStockRequest

  • PullStockResponse

  • PullStockResponse.Change

  • StopDispenseRequest

  • UpdateStockRequest

  • Consumable.Unit

  • VendingApi

  • VendingInfo

• Scalar Value Types

Top

traits/vending.proto

Consumable

Consumable describes some item that can be dispensed from a vending device. Noticeable variations, so far as someone might want to choose between two consumables, should be modelled as separate consumable instances. For example red or green apples, large or regular drinks.

Field	Type	Label	Description
name	string		A name that can be used to uniquely refer to this consumable in the device.
available_portions	Consumable.Portion	repeated	The available portions that this consumable can be dispensed in.
default_portion	Consumable.Quantity		The portion that will be dispensed if not specified as part of the request.
title	string		An official title for this item.
display_name	string		A recognisable display name for this item.
picture	smartcore.types.Image		A picture of the item.
url	string		A url that resolves to more information on this item.
ids	Consumable.IdsEntry	repeated	IDs holds external consumable ids. For example this might hold an id representing an Amazon Dash button product code. The map key should uniquely represent the domain for the id, for example "amazon.com/dash", the use of uris is not required, values should be the id of this consumable in that domain, for example "sma81r6t1c5o3r58e1-3r8u16l1es".
more	Consumable.MoreEntry	repeated	Additional properties associated with the consumable. Typically displayed to a user to help them to distinguish between similar consumables.

Consumable.IdsEntry

Field	Type	Label	Description
key	string
value	string

Consumable.MoreEntry

Field	Type	Label	Description
key	string
value	string

Consumable.Portion

Portion describes a possible consumption for this consumable. Portions are potential units to be dispensed, a device might support dispensing individual cups of water, in which case it would use {unit:CUP, bounds:[1,1]}. Alternatively a device might dispense sweets in chunks of 50g, and would describe this using {unit:KILOGRAM, step:0.05}. If the device had a safety feature to limit the sweets dispensed at one time it might also specify bounds:[0.05, 5].

Field	Type	Label	Description
unit	Consumable.Unit		The unit the portion is measured in.
bounds	smartcore.types.FloatBounds		Upper and lower bounds for the portion quantity.
step	float		The minimal increment for the portion quantity.

Consumable.Quantity

Quantity combines an amount and a unit.

Field	Type	Label	Description
amount	float
unit	Consumable.Unit

Consumable.Stock

Stock describes how much of a consumable is available.

Field	Type	Label	Description
consumable	string		The name of a consumable supported by this device.
remaining	Consumable.Quantity		How many/much of the consumable is remaining. Optional. If the consumable is currently dispensing, this should report how much is remaining after dispensing finishes.
used	Consumable.Quantity		How many/much of the consumable has been used since the counter was last reset. Optional. Devices may reset the counter when the stock is filled, or may count for longer. If the consumable is currently dispensing, this should report how much will be used after dispensing finishes.
last_dispensed	Consumable.Quantity		How many/much of the consumable was most recently dispensed. If the consumable is currently dispensing, this should report the quantity it dispensed prior to the current session. Optional.
dispensing	bool		True if the consumable is currently being dispensed.

DispenseRequest

Field	Type	Label	Description
name	string		Name of the device to invoke the action on
consumable	string		The name of the consumable to dispense the stock for.
quantity	Consumable.Quantity		The quantity of the consumable to dispense.
update_mask	google.protobuf.FieldMask		Fields to update relative to the quantity property.

GetStockRequest

Field	Type	Label	Description
name	string		Name of the device to update the state for
consumable	string		The name of the consumable to get the stock for.
read_mask	google.protobuf.FieldMask		Fields to read relative to the Consumable.Stock type.

ListConsumablesRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Consumable type
page_size	int32		The maximum number of items to return. The service may return fewer than this value. If unspecified, at most 50 items will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.
page_token	string		A page token, received from a previous ListConsumablesRequest call. Provide this to retrieve the subsequent page.

todo: enable filtering Filter allows for customisation of the items returned by this request. See https://google.aip.dev/160 for details. Individual devices should document if and how filter is supported by that device. string filter = 5; |

ListConsumablesResponse

Field	Type	Label	Description
consumables	Consumable	repeated
next_page_token	string		A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
total_size	int32		If non-zero this is the total number of consumables. This may be an estimate.

ListInventoryRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Consumable.Stock type
page_size	int32		The maximum number of items to return. The service may return fewer than this value. If unspecified, at most 50 items will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.
page_token	string		A page token, received from a previous ListInventoryRequest call. Provide this to retrieve the subsequent page.

ListInventoryResponse

Field	Type	Label	Description
inventory	Consumable.Stock	repeated	The stock requested.
next_page_token	string		A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
total_size	int32		If non-zero this is the total number of stocked consumables. This may be an estimate.

PullConsumablesRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Consumable type
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

todo: enable filtering Filter allows for customisation of the items returned by this request. See https://google.aip.dev/160 for details. Individual devices should document if and how filter is supported by that device. string filter = 4; |

PullConsumablesResponse

Field	Type	Label	Description
changes	PullConsumablesResponse.Change	repeated	The list of changes which have occurred

PullConsumablesResponse.Change

Field	Type	Label	Description
name	string		The name of the device that emitted this change
type	smartcore.types.ChangeType		The type of change (e.g. ADD, UPDATE, etc...)
new_value	Consumable		The new value to use for ADD
old_value	Consumable		The old value to use for UPDATE
change_time	google.protobuf.Timestamp		When the change occurred

PullInventoryRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Consumable.Stock type
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

todo: enable filtering Filter allows for customisation of the items returned by this request. See https://google.aip.dev/160 for details. Individual devices should document if and how filter is supported by that device. string filter = 4; |

PullInventoryResponse

Field	Type	Label	Description
changes	PullInventoryResponse.Change	repeated	The list of changes which have occurred

PullInventoryResponse.Change

Field	Type	Label	Description
name	string		The name of the device that emitted this change
type	smartcore.types.ChangeType		The type of change (e.g. ADD, UPDATE, etc...)
new_value	Consumable.Stock		The new value to use for ADD
old_value	Consumable.Stock		The old value to use for UPDATE
change_time	google.protobuf.Timestamp		When the change occurred

PullStockRequest

Field	Type	Label	Description
name	string		Name of the device to fetch the state for
consumable	string		The name of the consumable to get the stock for.
read_mask	google.protobuf.FieldMask		Fields to fetch relative to the Consumable.Stock type
updates_only	bool		When true the device will only send changes to the resource value. The default behaviour is to send the current value immediately followed by any updates as they happen.

PullStockResponse

Field	Type	Label	Description
changes	PullStockResponse.Change	repeated	Changes that have occurred since the last event

PullStockResponse.Change

A change to the state

Field	Type	Label	Description
name	string		name for the device that issued the change
change_time	google.protobuf.Timestamp		when the change occurred
stock	Consumable.Stock		the new state for the device

StopDispenseRequest

Field	Type	Label	Description
name	string		Name of the device to invoke the action on
consumable	string		The consumable that should stop dispensing.

UpdateStockRequest

Field	Type	Label	Description
name	string		Name of the device to update the state for
stock	Consumable.Stock		New quantities for the consumable stock.
update_mask	google.protobuf.FieldMask		Fields to update relative to the Consumable.Stock type.
relative	bool		If true, stock adjustments are relative to their current values.

Consumable.Unit

Unit defines different consumable units.

Name	Number	Description
UNIT_UNSPECIFIED	0
NO_UNIT	1	There is no unit for this quantity, typically a count.
METER	2	The quantity is a length, in meters.
LITER	3	The quantity is a volume, in liters
CUBIC_METER	4	The quantity is a volume, in cubic meters.
CUP	5	The quantity is a portion, sized to fill a cup.
KILOGRAM	6	The quantity is a mass, in kilograms.

VendingApi

VendingApi describes devices that hold a stock and can dispense their consumables on command. Applies to devices like vending machines, water taps, coffee machines, and pet food dispensers.

The VendingApi encodes two different resources, the consumables and the stock. Consumables represent information about the products that are available from this device. Stock is a measure of how many/much of a consumables is currently available. When referring to the stock of all consumables, this trait uses the term inventory.

Quantities, both available and dispensed, can be either discrete items like apples, or continuous like water. Some consumables are both discrete and continuous, you can have 0.3L or 1 cup of water.

fixme: Need to make a decision on whether Consumables belongs as a resource here or in VendingInfo

Method Name	Request Type	Response Type	Description
ListConsumables	ListConsumablesRequest	ListConsumablesResponse	List the consumables available from this device. This has no information on stock, only descriptive information about the physical item.
PullConsumables	PullConsumablesRequest	PullConsumablesResponse stream	Subscribe to change in consumables available from this device.
GetStock	GetStockRequest	Consumable.Stock	Get the current stock levels for a consumable. If the consumable is unknown will return NotFound. If the consumable is out of stock, returns a Stock with a zero remaining quantity.
UpdateStock	UpdateStockRequest	Consumable.Stock	Update the quantity of a consumable in the device.

This is unlikely to actually create physical consumables out of thin air, but is useful if the device doesn't have internal sensors monitoring the physical quantity of its consumables. For example to let a cookie dispenser know that it was refilled with 100 new tasty cookies. | | PullStock | PullStockRequest | PullStockResponse stream | Subscribe to changes in the stock levels for a consumable. | | ListInventory | ListInventoryRequest | ListInventoryResponse | List the stock for each consumable in the device. The device should return zero-quantity stock for consumables that are out-of-stock. | | PullInventory | PullInventoryRequest | PullInventoryResponse stream | Subscribe to changes in consumable stock. | | Dispense | DispenseRequest | Consumable.Stock | Trigger the dispensing of some quantity of consumables. Devices should return only stock items that are mentioned in the request. | | StopDispense | StopDispenseRequest | Consumable.Stock | Stop the dispensing of the mentioned consumables. Devices should return only stock items that are mentioned in the request. |

VendingInfo

todo: implement VendingInfo

Method Name	Request Type	Response Type	Description

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)