MDB Communication Protocal: Difference between revisions

From wizarPOS
No edit summary
No edit summary
Line 106: Line 106:
|}
|}
== Demo ==
== Demo ==
[http://ftp.wizarpos.com/advanceSDK/MDBTest.zip Source code of terminal APP]
[http://ftp.wizarpos.com/advanceSDK/MDBTest.zip Source Code for Terminal App]


[http://ftp.wizarpos.com/advanceSDK/MDBTest_zlh_signed.apk APK]
[http://ftp.wizarpos.com/advanceSDK/MDBTest_zlh_signed.apk APK]


[http://ftp.wizarpos.com/advanceSDK/vmc_master_tool-python-code.zip Source code of PC program]
[http://ftp.wizarpos.com/advanceSDK/vmc_master_tool-python-code.zip Source Code for PC Program]


[http://ftp.wizarpos.com/advanceSDK/MDBForCoffeeDemousage20220725.pdf MDBForCoffeeDemo usage]
[http://ftp.wizarpos.com/advanceSDK/MDBForCoffeeDemousage20220725.pdf MDBForCoffeeDemo Usage]

Revision as of 07:06, 18 December 2023

Introduction

This document outlines the communication protocol between an Android application and MDB Vending machines via the Q3v hardware. The Q3v acts as a bridge, forwarding MDB requests from the vending machine to the Android application as serial data. The communication is bi-directional, allowing the application to request configuration commands, such as "get firmware version." A mode byte indicates the direction of communication.

Serial Protocol Packet Definition

Serial Port Parameters

  • Baud rate: 115200
  • Data format: 8 bits, 1 stop bit, no parity

Packet Format

Start code Length mode Data Checksum End code
  • Start code size 1 byte, always be 0x09
  • Length size: 1byte, the number bytes of mode, data, and checksum.
  • Mode size: 1, 0x00 means a master request packet, 0x01 means a slave response packet, other value is prohibited.
  • Data size: n bytes. The data could be raw MDB commands, such as SETUP, VEND(please refer the <Multi-Drop Bus Protocol V4.3>for detials).

Or the MIB control commands, such as GET VERSION, SET PARAMETER.

  • Checksum size: 1byte, using LRC algorithm, input data were "mode, data"


Specifics

MDB Forwarding Mechanism

The Q3v forwards all MDB cashless device commands except the POLL command. The request and response procedure involves several steps:

  1. VMC sends MDB request to Q3v.
  2. Q3v receives the data, removes the 9th MDB mode bit, and sends the serial packet to the application.
  3. The application processes the data, handles the MDB request, and sends the MDB response to Q3v.
  4. Q3v forwards the response to the MDB master.
  5. MDB master handles the MDB slave response.

Example: RESET

  1. VMC -> q3v: 0x110 0x10
  2. q3v -> app: 0x09 0x04 0x00 0x10 0x10 0xE0 0x0D
  3. app -> q3v: 0x09 0x04 0x01 0x00 0x00 0xFF 0x0D
  4. q3v -> VMC: 0x00 0x100
  5. VMC -> q3v: 0x00

Application Notes

  • Focus on steps 2 and 3 in the MDB Forwarding Mechanism.
  • The application handles all cashless commands except POLL.
  • The cashless reader initiates a begin session command to notify the VMC when ready for a transaction.
  • MDB raw data includes its checksum byte, distinct from the serial frame checksum.


A Typical MDB Transaction Flow

MDB transacrion flow

Protocol Command Definition

Common MDB Forwarding Command

This command forwards raw MDB commands (including MDB CHK), with the MDB mode bit removed.

Request Packet:

Mode Data
Request 00H VMC Request Command

(Reset,Setup,Reader,Expansion,Vend)

Response Packet:

Mode Data
Response 01H Peripheral Response

Example:
q3v -> app 09 04 00 10 10 E0 0D

q3v <- app 09 04 01 00 00 FF 0D.

Begin Session Command

When the application is ready for a transaction, it issues a begin session command to inform the VMC master. This marks the beginning of a transaction. Balance amount is 2 bytes; if balance does not exist, fill with 0xFF. This command follows MDB spec definition but is initiated by the app.

Request Packet:

Mode Data
Request 00H Begin Session (03H) + Funds Available + MDB Checksum

Response Packet:

Mode Data
Response 01H ACK 00H

Example:
q3v <- app 09 06 00 03 00 64 67 32 0d

q3v -> app 09 03 01 00 ff 0d

Session Cancel Request(0x04)

The application can end a payment session by issuing a session cancel request command. The POS acts as the master during this command.

Request Packet:

Mode Data
Request 00H Cancel Session Req(04H) + Funds Available + Checksum

Response Packet:

Mode Data
Response 01H ACK 00H

Demo

Source Code for Terminal App

APK

Source Code for PC Program

MDBForCoffeeDemo Usage