INTUS-Junior with mini-magnetic antenna.
GSMVend Technical Manual
GSMVend is a software module for M-Commerce solutions running on INTUS-Junior. It is designed to communicate with vending machines to implement 'Pay with your Handy' application. GSMVend offers the following primary features:
|
Figure 1 INTUS-Junior with mini-magnetic antenna. |
Contents:
How the three parties cooperate
INTUS-Junior connects to the provider's GSM network
Configuration for your requirements
How to obtain a valid licence number for GSMVend
A typical interconnection inside a vending machine
The components to upgrade a vending machine
How to change parameter settings
Configuration parameter description
Information furnished herein by BonusData AG is believed to be accurate and reliable. However, no responsibility is assumed for it's usage. Also the information contained herein is subject to change without any notice.
INTUS-Junior is a BonusData AG brand for a mobile payment and telemetry application. This application consists of a Falcom A2D-3 GSM modem hardware and the GSMVend software application. The operating system was originally issued by AMD (Advanced Micro Devices, Inc.) and adapted by Falcom GmbH for the A2D-3 and finally extended with additional functionality by BonusData AG. GSMVend is especially designed for this purpose and operates as M-Commerce payment and telemetry system.
Three parties are involved on the implementation of a mobile payment solution:
The consumer who wants an easy and comfortable way to buy products.
The vending machine operator who wants to sell his products.
The phone network provider who wants to sell communication services to consumer.
Cooperation between consumer, phone network provider and vending machine:
 |
Figure 2 Communication overview. |
A typical vend cycle:
1. The consumer dials the phone number shown on the vending machine.
2. The phone network provider checks authorization and vend credit.
3. The vending machine display shows the message 'Please choose your product'.
4. The customer makes a selection or the credit will timeout after 20 seconds.
5. The vending machine returns a vend acknowledge to the phone network provider.
6. The purchased item will be charged to the consumer's phone invoice.
How the three parties cooperate
A consumer is probably most used to make a simple phone call. So the phone number assigned by the phone network provider is shown on the vending machine. If the customer dials this number (1), the provider will have quite a lot of information. The dialers phone number, the vending machine phone number, because that is the dialed number. So the consumer can be identified and if accepted, give credit to the vending machine (2). The vending machine will show the message 'Please choose your product' and wait for the user's selection (3). If the consumer does not make a selection within the timeout of approximate. 20 seconds the vend cycle is aborted. If the consumer makes a selection (4), the product is dispensed and a acknowledge message send to the provider (5). If the sold item is acknowledged, the provider will charge it to the consumers phone invoice.
This is a simplified description of a vend cycle. In reality there are many details to be considered.
BonusData AG concentrates all efforts to the front end implementation, to offer a simple interface to the GSM network provider. Many different solutions are possible depending on the requirements of the GSM network providers. This example just shows one of them.
INTUS-Junior connects to the provider's GSM network
To communicate between a phone network provider and a vending machine (2)(5) requires a GSM device inside the vending machine. Today, there are very sophisticated devices available on the marked. INTUS-Junior is one of them. It can communicate by Voice, SMS, USSD and also TCP/IP and Fax if required. GSMVend is a software application to communicate between the phone network provider and a vending machine. Today following communication types are implemented: Voice, SMS and USSD.
1) Provider to GSMVend by voice call.
2) Provider to GSMVend by SMS.
3) Provider to GSMVend by USSD message.
4) GSMVend to Provider by voice call.
5) GSMVend to Provider by SMS.
6) GSMVend to Provider by USSD message.
The solution with USSD messages is implemented by Sicap AG and not covered by this manual.
Provider to GSMVend by a voice call
The phone network provider call's GSMVend by a simple voice call. GSMVend will not respond to it, but check the caller's phone number (CALLNUMBER) and if it matched give credit to the vending machine for some time. The timeout can by set (TIMEOUT) as requested. The eight last significant digits of the caller's phone number are used as identification number.
The phone network provider is sending a SMS to GSMVend with following contents:
I:<Identification Number> Mandatory and in the range of 0..4294967295 (32 Bits).
S:<Security code> Mandatory and calculated from the <Identification Number>. (Not implemented with version 1.03)
C:<Credit> Optional and in the range of 0..65535 of the smallest currency units.
T:<Timeout> Optional and in the range of 0..65535 seconds.
M:<Message> Optional and in the range of the vending machine display.
Note: Optional parameter will be replaced by default values or parameter settings. (See Parameters below)
| I:123456 S:572106 C:1000 T:20 |
Sample SMS send to GSMVend to start a transaction.
GSMVend to provider by a voice call
Configured with Bit #4 of parameter (OPTIONS).
GSMVend will call an voice phone number (OKAYNUMBER) after a successful vend. So the provider is able to update the database. Optional, GSMVend will also call an voice phone number (FAILNUMBER) after a failed vend, but not after a timeout.
Configured with Bit #5 of parameter (OPTIONS).
GSMVend will send a SMS to (SMSNUMBER) after a successful vend. So the provider is able to update the database. Optional, GSMVend will also send a SMS to (SMSNUMBER) after failed vend, but not after a timeout.
The SMS contains following items:
I:<Identification number> This is the number previous received from the provider for this transaction.
A:<Article number> Actually the selection number of the vending machine for this transaction.
P:<Price> The price in cents of the article sold in this transaction.
X:<Sales tax code> The sales tax code of the article in this transaction.
F:<Field strength> The actual average GSM field strength just before this transaction.
V:<Version> The current version of GSMVend.
| I:123456 A:4 P:250 X:0 F:23 V:1.03 |
Note: Of course, you may simulate the voice calls and SMS messages with your handy to do some tests.
Configuration for your requirements
Before a INTUS-Junior module can be mounted inside a vending machine, it should be configured for your requirements. There is a minimum parameter setting for the correct operation of INTUS-Junior. The other parameters depend on your requirements.
List of the minimum parameter settings:
AUTO="LG0" GSM="9600,D2,1234,0" LICENCE="012345678901234" |
If one of this parameter is missing INTUS-Junior will not work!
How to obtain a valid licence number for GSMVend
Registered customer of BonusData AG can obtain a licence number by filling in a licence registration form at http://www.bonusdata.net/register. Important, the IMEI number must be supplied to the form. The IMEI number can be found at the back of INTUS-Junior. After the registration form is submitted, the licence number is automatically send by e-mail. The Licence number is not free, it will be charged afterwards according the previous signed sales contract. A lost licence number can be re-registered without any charge.
A typical interconnection inside a vending machine
The schematic below shows a typical interconnection inside a modern vending machine. The vending machine controller must support the MDB protocol. Currently there are two connection between the vending machine controller and INTUS-Junior. One is used to communicate with the vending machine with the MDB protocol. The other is used to readout the audit data over the DDCMP or DEX/UCS protocol.
 |
Figure 3 Vending machine interconnection. |
Disconnect the vending machine from any power supply.
Fit the mounting clamp of INTUS-Junior inside the vending machine.
Insert the SIM-Card at the back of INTUS-Junior. Make sure that the card is correct oriented.
Put the mini-magnetic antenna somewhere inside the vending machine. Usually in the front door behind the plastic cover. It will not work if surrounded by metal. In such a case use a planar type of antenna and stick it on top of the vending machine case. Connect it with INTUS-Junior. Note: The antenna cable should not bend around sharp corners or around the door angle.
Connect the MDB interface cable between the vending machine controller and INTUS-Junior leaving a free connector for a optional change giver.
If requested, connect the optional audit data cable (EVA-DTS) between INTUS-Junior and the vending machine controller.
Information about normal operation is available by LED indicators. There are two LED near the MDB connector, see picture below.
 |
Figure 4 LED Indicators of INTUS Junior: Indicator A: Yellow GSM network LED Indicator B: Green Power LED
|
The LED indication states:
After reset both LED's are on for about 3 seconds.
The green power LED (B) goes off and the GSM yellow network LED (A) is flashing until logon to the GSM network.
The yellow LED (A) goes steady after successful network logon.
An other two red LED's are on the MDB interface cable with converter. One for each direction. At normal operation, both LED's should be flashing, one on the poll of the master and the other at the response of GSMVend.
After connected to the GSM network, the GSMVend software version and field strength are displayed on the vending machine display for approximate 5 seconds:
GSM Ready. 1.03 / 23 |
Note: The display must be enabled by parameter OPTIONS Bit #2.
The components to upgrade a vending machine
The following items are necessary to upgrade a vending machine for M-Commerce and telemetric:
| Part number: | Description: |
| FA-1002 | INTUS-Junior an intelligent GSM-Modem 900/1800 MHz with integrated micro controller. |
| BD-0001 | Software GSMVend for INTUS-Junior (M-Commerce) including download and configuration. |
| BD-2004 | Interface cable RJ-45/RS-232 <-> MDB-Slave with integrated converter (MDB). |
| BD-2001 | Interface cable DB15-M/RS-232 <-> Audio-Jack 6.3 mm with integrated converter (EVA-DTS). |
| WY-1000 | Mini Magnet Antenna 900/1800 MHz. |
All this items are also available as complete package. Part number: BD-5000-S.
If connected to a vending machine with a MDB-Slave interface cable INTUS-Junior will get the power supply from the vending machine thorough the MDB connection.
It is recommended to assemble a power supply for service purposes. A standard plugable power supply with 15 or 24 VDC will do very well. Connect to INTUS Junior as the schematics show below.
 |
Figure 5 Power supply cable. |
A switch for the power supply is very comfortable. If you use both hands to connect and type a @ it can be very stressfully.
How to change parameter settings
To change any parameter setting, a terminal and a download cable (Part # BD-2008) is required. Within this document we use Hyper Terminal shipped as accessory with Microsoft Windows. Usually found on the task bar at at Start/Accessories/Communications.
HyperTerminal mist be configured for one of the serial ports with 38400 Baud and hardware handshake.
Step 1:
 |
Figure 6 Setup of Hyper Terminal for a serial port COM1: |
Step 2:
 |
Figure 7 Setup for 38400, 8, None, 1, Hardware. Important: Set flow control to 'Hardware'. |
With this steps, the Hyper Terminal is correct configured. Now disconnect and the connect to get the new settings active.
Enter to integrated debugger DBG186 of GSMVend
Connect INTUS-Junior with the download cable to a serial port of your PC. Start and setup Hyper Terminal as described above. Connect INTUS-Junior to the power supply (See: Power supply for INTUS-Junior above) and enter a @ character within 3 seconds after connected. If you miss it, disconnect and repeat the procedure. The screen of Hyper Terminal should show like below.
Figure 8 - Integrated debugger DBG186 prompt.
After connection to the debugger is established, enter a ? to display the help screen.
Figure 9 - Debugger DBG186 help screen with command summary.
The command K is used to display and change GSMVend parameters. The K command has on own help screen use K? to display it.
Figure 10 - Command K help screen.
Finally enter the K command to display all current available parameters.
Figure 11 - List of current available parameters.
How to set the individual parameters is described below.
Configuration parameter description
All the configuration parameter are stored in a EEPROM. If a parameter is not found, a predefined default parameter will be used.
| Default: | No default. |
| Usage: | Licence of BonusData AG to legal use of GSMVend on INTUS-Junior. |
| Values: | Exact 15 numeric digits. |
| Example: | k LICENCE "012345678901234" A correct licence number will enable GSMVend for normal operation. |
| Default: | 9600,D2,<PIN> (9600 Baud, Dualband, PIN-Code.) |
| Usage: | Used to initialize the GSM engine. This parameter is absolutely necessary for a correct operation of INTUS-Junior. Just the PIN-Code can be changed. |
| Values: | Baudrate: 9600, Device: D2, <PIN> up to 6 digits. |
| Example: | k GSM "9600,D2,4444" With this setting the pin to access the SIM card is 4444. Note: The PIN is requested only, if the SIM card is configured to request the PIN-Code. |
Parameter: MONITOR (Attention: Special hardware is required to use the monitor)
| Default: | 0 |
| Usage: | Enable monitor options at start up. Not used for normal operation. |
| Values: | Bit #0: Enable monitor debug output. Bit #1: Enable redirect of monitor console to GSM engine. Bit #2: Enable MDB state machine trace output. Bit #3: Enable application state machine trace output. Bit #4: Enable vending state machine trace output. Bit #5..31 Not used. |
| Example: | k MONITOR 0 With this setting are all monitor options disabled. Note: The monitor uses the serial port COM4 as console. COM4 is not available on standard INTUS-Junior devices. Therefore special assembled devices must be used. |
| Default: | 0 |
| Usage: | Enable of software options. |
| Values: | Bit #0: Not used. Bit #1: Not used. Bit #2: Enable messages on the vending machine display. Bit #3: Not used. Bit #4: Respond to host with a voice call. (Only one of Bit #4, #5 #6 may be set at the same time) Bit #5: Respond to host with a SMS message. (Only one of Bit #4, #5 #6 may be set at the same time) Bit #6: Respond to host with a USSD message. (Only one of Bit #4, #5 #6 may be set at the same time) Bit #7..31 Not used. |
| Example: | k OPTIONS 36 With this setting Bit #2 and Bit #5 are enabled. Note: (2^2)+2^5)=36 |
| Default: | 0 |
| Usage: | Select the audit data transfer protocol to readout the connected vending machine. |
| Values: | 0 = DDCMP protocol. 1 = DEX/UCS protocol. |
| Example: | k AUDITTYPE 1 Select the DEX/UCS audit data transfer protocol. |
Parameter: MACHINE
| Default: | 0 |
| Usage: | Select the type of connected vending machine. (Not implemented with version 1.03) |
| Values: | 0 = No vending machine connected. 1 = Vending machine with MDB protocol connected. |
| Example: | k MACHINE 1 Select the MDB protocol. |
| Default: | No default |
| Usage: | Set the phone number to enable a vend if a call is received. |
| Values: | +<Country code><Area code><Phone number> |
| Example: | k CALLNUMBER "+41791234567" Note: This is the phone number of the host (caller). |
| Default: | No default |
| Usage: | Set the phone number where to send the response SMS after a vend. (See OPTIONS Bit #5) |
| Values: | +<Country code><Area code><Phone number> |
| Example: | k CALLNUMBER "+41791234567" Note: This is the SMS destination phone number. |
| Default: | USER01 |
| Usage: | The user name to login for remote device support and configuration. |
| Values: | <username> |
| Example: | k USER01 "Support" Note: The user name is not case sensitive. |
| Default: | PASS01 |
| Usage: | The password to login for remote device support and configuration. |
| Values: | <password> |
| Example: | k PASS01 "password" Note: The password is case sensitive. |
| Default: | USER02 |
| Usage: | The user name to login for remote audit data download. |
| Values: | <username> |
| Example: | k USER02 "Download" Note: The user name is not case sensitive. |
| Default: | PASS02 |
| Usage: | The password to login for remote audit data download. |
| Values: | <password> |
| Example: | k PASS02 "password" Note: The password is case sensitive. |
Parameter: DIALTIMEOUT
| Default: | 5 Seconds |
| Usage: | The dialup timeout until failed. |
| Values: | 5...120 Seconds. |
| Example: | k DIALTIMEOUT 10 Set the dial timeout to 10 seconds. |
| Default: | No default |
| Usage: | Set the phone number to call after a successful vend. (See OPTIONS Bit #4) |
| Values: | +<Country code><Area code><Phone number> |
| Example: | k OKAYNUMBER "+41791234567" |
| Default: | No default |
| Usage: | Set the phone number to call after a failed vend. (See OPTIONS Bit #4) |
| Values: | +<Country code><Area code><Phone number> |
| Example: | k FAILNUMBER "+41791234567" |
| Default: | 1000 |
| Usage: | Credit send to the vending machine to allow a vend. |
| Values: | 1...65535 smallest currency units. |
| Example: | k CREDIT 500 Set the credit to 500 cents. Note: This value will enable the possible selections with a price of less or equal to 500 cents. |
| Default: | 20 Seconds |
| Usage: | Timeout for a selection after the vending machine got the credit. |
| Values: | 10...120 Seconds. |
| Example: | k TIMEOUT 30 Set the selection timeout to 30 seconds. |
| Default: | No default. |
| Usage: | First line of Text to display on the vending machine display when a selection can be made. |
| Values: | Text, up to 16 characters. |
| Example: | k LABEL10 "Please choose" Display this text in the upper line of the vending machine display. |
| Default: | No default. |
| Usage: | Second line of Text to display on the vending machine display when a selection can be made. |
| Values: | Text, up to 16 characters. |
| Example: | k LABEL11 "your product.." Display this text in the lower line of the vending machine display. |
07.03.2002 First release for version 1.01
02.08.2002 English modified release for version 1.03
AMD is a trademark of Advanced Micro Devices Inc. USA.
Falcom is a trademark of Falcom GmbH, Germany.
INTUS-Junior is a trademark of BonusData AG, Switzerland.
[Home] - Copyright (C) 1999-2003 by BonusData AG, webmaster@bonusdata.net. Last update: 16.09.2003