The Open Source Vending Group Project/Osvend

From Nottinghack Wiki
Jump to navigation Jump to search

The Vending Machine Controller (VMC) communicates with the Connection Layer (CL) using the osvend protocol over a websocket. The VMC initiates the websocket when it boots, the CL 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
CL VMC MACHINEID:<server version>
VMC CL MACHINEID:<MAC address>:<controller version>
CL VMC STATUS
VMC CL STATUS:<hopper details>:<overall state>:<reason>
CL VMC STOCK:<hopper>
VMC CL STOCK:<hopper>:<status>
CL VMC VEND:<hopper>
VMC CL VEND:<hopper>:ACK
VMC CL VEND:<hopper>:<status>:<reason>

Commands

All command-response pairs are initiated by the connection layer, 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 connection layer it advertises itself as speaking the osvend protocol. The server initiates the machine ID command-response pair:

From To Message
CL VMC MACHINEID:<server version>
VMC CL 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 connection layer sends the status command:

From To Message
CL VMC STATUS
VMC CL 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 connection layer can query the stock of any one hopper:

From To Message
CL VMC STOCK:<hopper>
VMC CL 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 connection layer instructs the machine to vend the product

From To Message
CL VMC VEND:<hopper>
VMC CL VEND:<hopper>:ACK
VMC CL 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 status = FAILURE

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 connection layer. The server stores the message in a logfile for later perusal.

From To Message
VMC CL 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=16515"