Difference between revisions of "The Open Source Vending Group Project/Osvend"

From Nottinghack Wiki
Jump to navigation Jump to search
m
Line 6: Line 6:
  
 
{| class="wikitable"
 
{| class="wikitable"
−
!Direction!!Message
+
!From!!To!!Message
 
|-
 
|-
−
|WG > VMC||MACHINEID:<server version>
+
|WG||VMC||MACHINEID:<server version>
 
|-
 
|-
−
|VMC > WG||MACHINEID:<MAC address>:<controller version
+
|VMC||WG||MACHINEID:<MAC address>:<controller version>
 
|-
 
|-
−
|WG > VMC||STATUS
+
|WG||VMC||STATUS
 
|-
 
|-
−
|VMC > WG||STATUS:<hopper details>:<overall state>:<reason>
+
|VMC||WG||STATUS:<hopper details>:<overall state>:<reason>
 
|-
 
|-
−
|WG > VMC||STOCK:<hopper>
+
|WG||VMC||STOCK:<hopper>
 
|-
 
|-
−
|VMC > WG||STOCK:<hopper>:<status>
+
|VMC||WG||STOCK:<hopper>:<status>
 
|-
 
|-
−
|WG > VMC||VEND:<hopper>
+
|WG||VMC||VEND:<hopper>
 
|-
 
|-
−
|VMC > WG||VEND:<hopper>:ACK
+
|VMC||WG||VEND:<hopper>:ACK
 
|-
 
|-
−
|VMC > WG||VEND:<hopper>:<status>:<reason>
+
|VMC||WG||VEND:<hopper>:<status>:<reason>
 
|}
 
|}
 +
 +
== Commands ==
 +
 +
All command-response pairs are initiated by the web gateway, and only one has to happen.
 +
 +
Machine ID is required, and must happen at the beginning of a connection.  All other commands can be sent at any time after the Machine ID handshake.
 +
 +
=== Machine ID ===
 +
 +
When a vending machine connects to the websocket within the web gateway it advertises itself as speaking the '''osvend''' protocol.  The server initiates the machine ID command-response pair:
 +
 +
{| class="wikitable"
 +
!From!!To!!Message
 +
|-
 +
|WG||VMC||MACHINEID:<server version>
 +
|-
 +
|VMC||WG||MACHINEID:<MAC address>:<controller version>
 +
|}
 +
 +
Where:
 +
 +
* <server version> is the version of the server software
 +
* <MAC address> MAC address of controllers network interface.  Hex parts are seperated by -
 +
* <controller version> is the version of the controller software
 +
 +
Server and controller versions specify which version of this protocol the software support.
 +
 +
=== Status ===
 +
 +
To get details of attached hoppers, the web gateway sends the status command:
 +
 +
{| class="wikitable"
 +
!From!!To!!Message
 +
|-
 +
|WG||VMC||STATUS
 +
|-
 +
|VMC||WG||STATUS:<hopper details>:<overall state>:<reason>
 +
|}
 +
 +
Where:
 +
 +
* <hopper details> gives information of each attached hopper:
 +
** Format: [<address>-<state>-<got_stock>],[<address>-<state>-<got_stock>],...,[<address>-<state>-<got_stock>]
 +
** Where:
 +
*** <address> is the I2C address of the hopper (not including offset, see hopper controller spec)
 +
*** <state> is current state of hopper, either ''GOOD'' or ''FAULT''
 +
*** <got_stock> is ''NO'' for no stock, ''YES'' for >= 1 item or ''ERR'' for unkown
 +
* <overall state> is general state of the machine - ''GOOD'' or ''FAULT''
 +
* <reason> optional free-text reason that can be set is state = FAULT
 +
 +
=== Stock ===
 +
 +
The web gateway can query the stock of any one hopper:
 +
 +
{| class="wikitable"
 +
!From!!To!!Message
 +
|-
 +
|WG||VMC||STOCK:<hopper>
 +
|-
 +
|VMC||WG||STOCK:<hopper>:<status>
 +
|}
 +
 +
Where:
 +
 +
* <hopper> is the I2C address as given in the STATUS response
 +
* <status> ''YES'' is >= 1 item, ''NO'' - Empty, ''ERR'' - error performing check
 +
 +
=== Vend ===
 +
 +
Once a transaction is completed, the web gateway instructs the machine to vend the product
 +
 +
{| class="wikitable"
 +
!From!!To!!Message
 +
|-
 +
|WG||VMC||VEND:<hopper>
 +
|-
 +
|VMC||WG||VEND:<hopper>:ACK
 +
|-
 +
|VMC||WG||VEND:<hopper>:<status>:<reason>
 +
|}
 +
 +
Where:
 +
 +
* <hopper> is the I2C address as given in the STATUS response
 +
* <status> is ''SUCCESS'' or ''FAILURE''
 +
* <reason> optional free-text reason that can be set is state = FAULT
 +
 +
The vending machine ACKs the vend request immediately, the web gateway then waits a set period of time for the actual response.
 +
 +
=== Info ===
 +
 +
The only command the controller can send to the web gateway.  The server stores the message in a logfile for later perusal.
 +
 +
{| class="wikitable"
 +
!From!!To!!Message
 +
|-
 +
|VMC||WG||INFO:<debug message>
 +
|}
 +
 +
Where
 +
 +
* <debug message> - the message to be saved.

Revision as of 21:19, 27 August 2012

The Vending Machine Controller (VMC) communicates with the Web Gateway (WG) using the osvend protocol over a websocket. The VMC initiates the websocket when it boots, the WG sends the first message, requesting the MachineID (MAC address) of the VMC.

Commands are case-sensitive. This is version 1 of the protocol

A typical conversation would go like this, more details below:

From To Message
WG VMC MACHINEID:<server version>
VMC WG MACHINEID:<MAC address>:<controller version>
WG VMC STATUS
VMC WG STATUS:<hopper details>:<overall state>:<reason>
WG VMC STOCK:<hopper>
VMC WG STOCK:<hopper>:<status>
WG VMC VEND:<hopper>
VMC WG VEND:<hopper>:ACK
VMC WG VEND:<hopper>:<status>:<reason>

Commands

All command-response pairs are initiated by the web gateway, and only one has to happen.

Machine ID is required, and must happen at the beginning of a connection. All other commands can be sent at any time after the Machine ID handshake.

Machine ID

When a vending machine connects to the websocket within the web gateway it advertises itself as speaking the osvend protocol. The server initiates the machine ID command-response pair:

From To Message
WG VMC MACHINEID:<server version>
VMC WG MACHINEID:<MAC address>:<controller version>

Where:

  • <server version> is the version of the server software
  • <MAC address> MAC address of controllers network interface. Hex parts are seperated by -
  • <controller version> is the version of the controller software

Server and controller versions specify which version of this protocol the software support.

Status

To get details of attached hoppers, the web gateway sends the status command:

From To Message
WG VMC STATUS
VMC WG STATUS:<hopper details>:<overall state>:<reason>

Where:

  • <hopper details> gives information of each attached hopper:
    • Format: [<address>-<state>-<got_stock>],[<address>-<state>-<got_stock>],...,[<address>-<state>-<got_stock>]
    • Where:
      • <address> is the I2C address of the hopper (not including offset, see hopper controller spec)
      • <state> is current state of hopper, either GOOD or FAULT
      • <got_stock> is NO for no stock, YES for >= 1 item or ERR for unkown
  • <overall state> is general state of the machine - GOOD or FAULT
  • <reason> optional free-text reason that can be set is state = FAULT

Stock

The web gateway can query the stock of any one hopper:

From To Message
WG VMC STOCK:<hopper>
VMC WG STOCK:<hopper>:<status>

Where:

  • <hopper> is the I2C address as given in the STATUS response
  • <status> YES is >= 1 item, NO - Empty, ERR - error performing check

Vend

Once a transaction is completed, the web gateway instructs the machine to vend the product

From To Message
WG VMC VEND:<hopper>
VMC WG VEND:<hopper>:ACK
VMC WG VEND:<hopper>:<status>:<reason>

Where:

  • <hopper> is the I2C address as given in the STATUS response
  • <status> is SUCCESS or FAILURE
  • <reason> optional free-text reason that can be set is state = FAULT

The vending machine ACKs the vend request immediately, the web gateway then waits a set period of time for the actual response.

Info

The only command the controller can send to the web gateway. The server stores the message in a logfile for later perusal.

From To Message
VMC WG INFO:<debug message>

Where

  • <debug message> - the message to be saved.
Retrieved from "https://wiki.nottinghack.org.uk/index.php?title=The_Open_Source_Vending_Group_Project/Osvend&oldid=4575"