The PLUM OUTTM

PLUM logo.pngUser's Guide

 

Payment Layer for Unattended Merchandising TM

 

Version 1.0

 

Image Coming Soon…

 

 

Upstate Networks Inc.

1001 Broad Street

Utica, New York 13501 USA

 

 

 

 

(800) 369-5797

info@upstatenetworks.com

www.upstatenetworks.com

 

 

 


Table of Contents

 

 

 

Introduction.. 2

Overview... 3

Hardware Installation   5

Hardware Specifics. 5

PLUM OUT TM    Option Selection   5

Cashless Device Address. 5

Self Test.. 6

SPECIFICATIONS. 7

MDB PINOUT.. 8

Technical Support   9

MDB Operation Notes  10

 


DESIGNED BY:

Rob Smith


 

Revision

Date

Description

Written By

Approved By

1

9/17

Initial Release

Rob Smith

 

 

 

 

 

 

 

 

 

 

 

 

 

Introduction

The latest version of the PLUM OUT™ User’s Guide, along with technical support and information about Upstate Networks, may be found online at http://www.upstatenetworks.com/.

Overview

The PLUM OUT TM  HAT is a device which works in conjunction with a Raspberry Pi with Raspbian OS to act as a cashless device when combined with any multi-drop bus (MDB) vending product. It is installed as a slave device for an already existing vending machine controller (VMC).

This document describes the Interface Protocol for the PLUM OUT hardware circuit. The PLUM OUT™ interfaces any MDB vending machine controller (VMC) to a Raspberry Pi via the 40 pin header(J1)

 

System Requirements

 

·         A Raspberry Pi 3 (Also compatible with Rpi 2)

 

·         Raspbian OS installed

 

·         A multi-drop bus (MDB) compatible vending machine

 

·         MDB Y Cable

 

Hardware Installation

Install the PLUM OUT TM HAT at on a Raspberry Pi 3 with a Raspbian OS. (Serial Port settings are 9600, 8, 1, none.)

 

Connect the male 6-pin Molex MDB connector to the 6-pin Molex connector labeled U6 on the PLUM OUT TM HAT. Connect the second male 6-pin Molex MDB connector to the vending machine controller VMC.  Apply power.  Check for the power LED labeled D1 (Green) indicating power is OK.

Hardware Specifics for PLUM OUT TM

plum out user image 1.jpg

Figure 1 - Connector, Switches, and LED locations

 

 

OFF

ON

1

10H

60H

2

Level 1

Level 2/3

3

ASCII

Binary

ALL

Normal

Self Test

Table 1 – DIP Switch Setting

 

LED DESIGNATION

INDICATION

D1

+5 VDC

D4

MDB ACTIVITY

D5

RASPBERRY PI ACTIVITY

D6

STATUS 1

D7

STATUS 2

Table 2 - LED Functions

PLUM OUT Option Selection

The four-position dip switch controls the selection of various configurable options these include the cashless device address, the cashless device level (1 or 2), ASCII or Binary transfer from the MDB to the Raspberry Pi and selftest.

Cashless Device Address

DIP Switch Position 1 controls the cashless device MDB address.  If the switch is off the PLUM OUT board will respond to 10hex, the primary cashless device address.  If the switch is on the PLUM OUT board will respond to 0x60, the secondary cashless device address.

 

Cashless Device Level

DIP Switch Position 2 controls the cashless device level selection.  If the switch is off the PLUM OUT board will identify itself as a level 1 cashless device  If the switch is on the PLUM OUT board will identify itself as a level 2 cashless device.

 

ASCII / Binary Data Transmission

DIP switch position 3 controls ASCII or binary data transmission.  If switch 3 is in the off position all data transferred from the MDB will be in HEX ASCII format.  All ASCII strings are terminated by a CR/LF sequence.  Binary data transmission, from the MDB to the Raspberry Pi, is selected by turning position 3 of the DIP switch to the on position.  When switch #3 is on, all data from the MDB will be sent to the Raspberry Pi in its original 8 bit binary form.  In order to define the length of the data string being sent to the Raspberry Pi, a length byte is added to the beginning of the string.  The length count is a count of the total number of bytes sent including the length byte.

DIP switch position 4 is set to its default position

Self Test

All DIP switches set to ON invokes self test after reset.


SPECIFICATIONS

Power requirements
24 to 35 Vdc
90 ma Typical
300 ma Maximum
Environmental
Operating Temp 32°F to 158°F
0°C to 70°C
Storage Temp -22°F to 165°F
-30°C to 74°C
Relative Humidity 5% to 95% Non-condensing
Physical Weight
< 1 lb
Physical Dimensions
Length 65 mm Width 56.5 mm Height 1 mm
Connector Info
MDB

Pin 1 +24Vdc Nominal
Pin 2 Ground
Pin 3 N/C
Pin 4 MDB Receive Data
Pin 5 MDB Transmit Data
Pin 6 Common

LED Designations (See Figure 1)

 

 

 

 

MDB PINOUT

 

 

 


pinouts

 

 

PLUM OUT Utility Installation

 

New Hardware Setup

Step1:

v  Update Raspbian Jessie to the latest version by opening a command prompt and typing the following:

 

Ø  sudo apt-get update

 

v  Wait for the update to complete then type the following:

 

Ø  sudo apt-get upgrade

 

v  The update may take over 5 minutes to complete.

 

Step 2:

v  Using a command prompt, type the following:

 

Ø  sudo nano /boot/cmdline.txt

 

v  Find the section of the string containing “console = serial0,115200” and delete it. Click ctrl+x and type y then press enter twice.

 

Step 3:

v  Using a command prompt, type the following:

 

Ø  sudo raspi-config

 

v  Locate advanced settings and select it. Then, click serial and select “enable”

PLUM OUT Utility Setup

Step 1:

v  Create a folder named “PLUM_Apps” in the /home/pi directory. (If folder already exists, skip this step)

Ø  Copy and paste the “PLUM_OUT” folder as well as the “PLUM_OUT_Utility” script file to the “PLUM_Apps” folder.

 

Step 2:

v  In the “PLUM Apps” folder, right click on the “PLUM_OUT_Utility” file and click properties.

Ø  Click the permissions tab and select Anyone under the Execute selection box then click Ok.

 

Step 3:

v  In the “PLUM_Apps” folder, double click on the “PLUM_OUT” folder.

Ø  Scroll down until you see the “PLUM_OUT_utility” icon.

§  Right click and select properties.

·         Click the permissions tab and select “Anyone” under the Execute selection box and click ok.

 

Step 4:

v  To open the PLUM Picker Utility, simply double click on the “PLUM_OUT_Utility” icon and click execute.


 

Technical Support

 

UNI offers technical support for PLUM OUTÔ primarily by e-mail and at http://www.upstatenetworks.com.

 

Please read this manual thoroughly before contacting UNI.

 

Technical support is available via e-mail 24-hours-a-day, 7-days-a-week at tech@upstatenetworks.com.

 

 

Priority support will be given to people who have followed the instructions in the Before Contacting Technical Support section below.

Before Contacting Technical Support

When contacting technical support with a question, please have the following information available or enclosed with your e-mail:

 

Your name, e-mail address, fax and telephone number.

 

PLUM OUTÔ serial number (Located on the packaging material).

 

A detailed description of the problem you are experiencing.

 

Computer software type (operating system name and version, brand and version of other network drivers, video driver settings, plus the name and version of any device drivers or other memory-resident programs).

Computer hardware type (type and make of CPU, RAM, hard disk type and size, video and network cards installed plus any other unusual cards)


MDB Operation Notes

 

EXAMPLE VEND SESSION #1*
(Valid Single Vend) All values HEX

VMC= Vending Machine Controller,  PLUM OUT= Raspberry Pi to MDB interfaceSoftware= front end software or PLC

VMC-10

(RESET) 10h

PLUM OUT-00

(ACK) 00h

Acknowledged

VMC-11 00

(SETUP CONFIGURATION DATA) 11 00:

To send the VMC's configuration data and obtain the cashless device's data

PLUM OUT-01 01 00 01 01 01 30 00

(PLUM OUT RESPONSE) 8 BYTES Z1-Z8

Z1: reader config data (indicates the payment media reader is responding to a SETUP) 01H
Z2: Reader Feature Level 
01H: The reader is not capable or will not perform the advanced features. The reader will not provide advanced information to the VMC
, but can do the advanced features internally. The reader has no revaluation capability. 
02H: The reader is capable and willing to perform the advanced features. The reader will provide advanced information to the VMC (if possible) and will not do the advanced features internally. 
03H: The reader is able to support level 02, but also supports some or all of the optional features listed in the EXPANSION ID command (i.e., file transfer, 32 bit credit, multi-currency/language features, negative vend, and/or data entry).
Z3-Z4: Country/Currency Code- packed BCD. The packed BCD country/currency code of the reader can be sent in two different forms depending on the value of the left most BCD digit. If the left most digit is a 0, the International Telephone Code is used to indicate the country that the reader is set-up for. For example, the USA code is 00 01H (Z3= 00 and Z4 = 01). If the leftt most digit is a 1, the latest version of the ISO 4217 numeric currency code is used. For example,the code for the US dollar is 18 40H (Z2= 18 and Z3 = 40). Use FFFFh if the country code is unknown. For level 3 cashless devices, it is mandatory to use the ISO 4217 numeric currency code (see Appendix A1)
Z5: Scale Factor. The multiplier used to scale all monetary values transferred between the VMC and the reader. 
Z6: Decimal Places. The number of decimal places used to communicate monetary values between the VMC and the payment media reader. All pricing information sent between the VMC and the payment media reader is scaled using the scale factor and decimal places. This corresponds to: ActualPrice=P(X)(10^ -Y) where P is the scaled value send in the price bytes, and X is the sale factor, and Y is the number of decimal places. 
Z7: Application Maximum Response Time - seconds. The maximum length of time a reader sill require to provide a response to any command from the VMC. The value reported here supercedes the payment reader's default NON-RESPONSE time defined in section 7.5 if the value reported here is greater. 
Z8: Miscellaneous Options - xxxxyyyy 
xxxx: Unused 
yyyy: Option bits 
b0=0: he payment media reader is not capable or restoring funds to the user's payment media or account. Do not request refunds. 
b0=1: The payment media reader is capable of restoring funds to the user's payment media or account. Refunds may be requested. 
b1=0: The payment media reader is NOT multivend capable. Terminate session after each vend. b1=1: The payment media reader is multivend capable. Multiple items may be purchased within a single session. 
b2=0: The payment media reader does NOT have a display 
b2=1: The payment media reader does have its own display. 
b3=0: The payment media reader does NOT support the VEND/CASH SALE subcommand. 
b3=1: The payment media reader does support the VEND/CASH SALE subcommand. 
b4-b7: Any future options must be covered by the EXPANSION COMMAND option bits.

VMC-11 01

(SETUP MAX/MIN PRICE) 11 01:

To send the maximum and minimum prices in the VMC. These prices must be sent as Level 01/02 16 bit credit
n established and any time there is a change in the minimum price. If the VMC does not know the minimum price, 00 00h should be sent.

PLUM OUT-01 FF FF 00 00

(PLUM OUT RESPONSE) 5 BYTES Y1-Y5

Y1: Max/Min prices. Indicates the VMC is sending the price range to the reader (01H)
Y2-Y3: Maximum Price- scaled. This information should be sent as soon as the VMC prices have been established and any time there is a change in the maxmum price. If the VMC does not know the maximum price, FF FFh should be sent.
Y4-Y5: Minimum Price-Scaled. This information should be sent as soon as the VMC prices have been sent

VMC-17 00

(EXPANSION REQUEST ID) 17 00:

To obtain additional cashless device information and options

PLUM OUT-00 55 4E 49 00 00 00 00
                   00 00 00 00 00 00 00 00 
                   00 50 43 32 4D 44 42 20
                   20 20 20 20 20 00 01

(PLUM OUT RESPONSE) 30 BYTES Y1-Y30

Y1: Request ID. The VMC is requesting payment media reader identification information. The information included above (y2-Y30) provides the payment media reader with VMC identification information. 00h
Y2-Y4: Manufacturer Code-ASCII. Identification code for the equipment supplier. Currently defined codes are listed in the EVA document entitled :The Data Transfer Standard EVA-DTS" document, the Audit Data Dictionary section, chapter 4, "Manufacturer Codes". 
Y4-Y16: Serial Number-ASCII. Factory assigned serial number.  Y17-Y28:Model Number-ASCII. Manufacture assigned model number. Y29-Y30:Software Version-packed BCD. Current software version
54 4E 49 00 00 00 00 00 00 00 00 00 00 00 00 01 50 43 32 4D 44 42 00 00 00 00 00 00 00 01
UNI0000000000001PLUM OUT00000001

VMC-14 01

(ENABLE) 14 01/(DISABLE) 14 00

PLUM OUT-00

(ACK) 00h

Acknowledged

VMC-12

(POLL) 12h

PLUM OUT-00

(ACK) 00h

Acknowledged

SOFTWARE-03

(BEGIN SESSION) 03

The Programmer will have to issue a BEGIN SESSION command (03h) which will be sent to the VMC on a poll.

VMC-12

(POLL) 12h

PLUM OUT-03

(POLL) 12h

This is the value that was passed from the RASPBERRY PI via the PLUM OUT indicating that the programmer wished to begin a session.

VMC-00

(ACK) 00h Acknowledged

The VMC will ACK the BEGIN SESSION command

VMC- 13 00 00 14 00 01

(VEND REQUEST) 13 00

The VMC issues a VEND REQUEST command (13 00 00 14 00 01h).  The first two bytes 13 00 are vend request.  The VMC is requesting vend approval from the payment media reader before dispensing the product.  The next two bytes 00 14h are scaled item price.  This scaled item price is set by bytes Z5 and Z6 in the reader response data for the MAX/MIN PRICES SETUP command.  And the last two bytes 00 01h are item selection number.

PLUM OUT-00

(ACK) 00h

Acknowledged. The vend request command will be ACKed

VMC-12

(POLL) 12h

VMC-12

(POLL) 12h

SOFTWARE-05

(VEND APPROVED) 05

passed on to the programmer to be approved with a VEND APPROVED command (05h) command

VMC-12

(POLL) 12h

PLUM OUT-05

(VEND APPROVED) 05

The vend approved command that was sent from the RASPBERRY PI is relayed to the VMC via the PLUM OUT

VMC-00

(ACK) 00h

Acknowledged

VMC-13 02

(VEND SUCCESS) 13 02

Once this command has been received a VEND SUCCESS command  (13 02h) will be issued by the VMC, and ACKed by the cashless device.

PLUM OUT-00

(ACK) 00h

Acknowledged

VMC-13 04

(SESSION COMPLETE) 13 04

Upon the receiving of an ACK, a SESSION COMPLETE command (13 04h) will be issued by the VMC and also ACKed by the cashless device.

PLUM OUT-00

(ACK) 00h

Acknowledged

VMC-12

(POLL) 12h

PLUM OUT-07

(END SESSION) 07

In order to end a vend session, and END SESSION command (07h) will have to be sent to the VMC on a poll by the end user.

*[1]. National Automatic Merchandising Association, February, 2011. Multi_Drop Bus/Internal Communication Protocol: Section 7 "Cashless Device(s) VMC/Peripheral Communication Specifications": 7.1-7.53.

 

INDEX

 

 


BEGIN SESSION, 13

Connector, 4, 7

ENABLE, 13

EXPANSION REQUEST, 12

Hardware, 3, 4

MAX/MIN PRICE, 12

MDB, 3, 5, 7, 10

Power, 7

Quick Start, 3

Receive, 7

System Requirements, 3

Technical Support, 9

VEND APPROVED, 14

VMC, 3, 5, 10, 12, 13, 14, 15