The Open Source Vending Group Project/Osvend: Difference between revisions

From Nottinghack Wiki
Jump to navigation Jump to search
← Older edit
No edit summary
 
(4 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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.
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
Commands are '''case-sensitive'''.  This is version 1 of the protocol
Line 8: Line 8:
!From!!To!!Message
!From!!To!!Message
|-
|-
|WG||VMC||MACHINEID:<server version>
|CL||VMC||MACHINEID:<server version>
|-
|-
|VMC||WG||MACHINEID:<MAC address>:<controller version>
|VMC||CL||MACHINEID:<MAC address>:<controller version>
|-
|-
|WG||VMC||STATUS
|CL||VMC||STATUS
|-
|-
|VMC||WG||STATUS:<hopper details>:<overall state>:<reason>
|VMC||CL||STATUS:<hopper details>:<overall state>:<reason>
|-
|-
|WG||VMC||STOCK:<hopper>
|CL||VMC||STOCK:<hopper>
|-
|-
|VMC||WG||STOCK:<hopper>:<status>
|VMC||CL||STOCK:<hopper>:<status>
|-
|-
|WG||VMC||VEND:<hopper>
|CL||VMC||VEND:<hopper>
|-
|-
|VMC||WG||VEND:<hopper>:ACK
|VMC||CL||VEND:<hopper>:ACK
|-
|-
|VMC||WG||VEND:<hopper>:<status>:<reason>
|VMC||CL||VEND:<hopper>:<status>:<reason>
|}
|}


== Commands ==
== Commands ==


All command-response pairs are initiated by the web gateway, and only one has to happen.
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 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.
Line 35: Line 35:
=== Machine ID ===
=== 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:
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:


{| class="wikitable"
{| class="wikitable"
!From!!To!!Message
!From!!To!!Message
|-
|-
|WG||VMC||MACHINEID:<server version>
|CL||VMC||MACHINEID:<server version>
|-
|-
|VMC||WG||MACHINEID:<MAC address>:<controller version>
|VMC||CL||MACHINEID:<MAC address>:<controller version>
|}
|}


Line 55: Line 55:
=== Status ===
=== Status ===


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


{| class="wikitable"
{| class="wikitable"
!From!!To!!Message
!From!!To!!Message
|-
|-
|WG||VMC||STATUS
|CL||VMC||STATUS
|-
|-
|VMC||WG||STATUS:<hopper details>:<overall state>:<reason>
|VMC||CL||STATUS:<hopper details>:<overall state>:<reason>
|}
|}


Line 78: Line 78:
=== Stock ===
=== Stock ===


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


{| class="wikitable"
{| class="wikitable"
!From!!To!!Message
!From!!To!!Message
|-
|-
|WG||VMC||STOCK:<hopper>
|CL||VMC||STOCK:<hopper>
|-
|-
|VMC||WG||STOCK:<hopper>:<status>
|VMC||CL||STOCK:<hopper>:<status>
|}
|}


Line 95: Line 95:
=== Vend ===
=== Vend ===


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


{| class="wikitable"
{| class="wikitable"
!From!!To!!Message
!From!!To!!Message
|-
|-
|WG||VMC||VEND:<hopper>
|CL||VMC||VEND:<hopper>
|-
|-
|VMC||WG||VEND:<hopper>:ACK
|VMC||CL||VEND:<hopper>:ACK
|-
|-
|VMC||WG||VEND:<hopper>:<status>:<reason>
|VMC||CL||VEND:<hopper>:<status>:<reason>
|}
|}


Line 111: Line 111:
* <hopper> is the I2C address as given in the STATUS response
* <hopper> is the I2C address as given in the STATUS response
* <status> is ''SUCCESS'' or ''FAILURE''
* <status> is ''SUCCESS'' or ''FAILURE''
* <reason> optional free-text reason that can be set is state = FAULT
* <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.
The vending machine ACKs the vend request immediately, the web gateway then waits a set period of time for the actual response.
Line 117: Line 117:
=== Info ===
=== Info ===


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


{| class="wikitable"
{| class="wikitable"
!From!!To!!Message
!From!!To!!Message
|-
|-
|VMC||WG||INFO:<debug message>
|VMC||CL||INFO:<debug message>
|}
|}


Line 128: Line 128:


* <debug message> - the message to be saved.
* <debug message> - the message to be saved.
[[Category:Projects]]

Latest revision as of 11:59, 5 February 2019

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"