MDB Communication Protocal: Difference between revisions

From wizarPOS
No edit summary
Line 1: Line 1:
== Introduction ==
== Introduction ==
This doc defines a serial communication protocol between the application running on Q3v and MDB Vending machine.
This document outlines a serial communication protocol between the application running on Q3v and MDB Vending machines. The Q3v low-level hardware forwards MDB requests from the vending machine to the Android application as serial data. When the application processes all request serial data, the Q3v POS can be regarded as an MDB cashless slave device. Additionally, the application can request configuration commands, such as "get firmware version," making the protocol bi-directional. A mode byte indicates the direction of communication.
Overall,the q3v low level hardware will forwarding the mdb request from the vendg machine,and forward to the Android application as serial data,
When the app tackle all the request serial data, the q3v pos could be regarded as a MDB cashless slave device.
And also,the application could request some config command, e.g. "get firmware version",Therefore the protocol is 2-way-direction,
and there is a mode byte indicates the direction.


== Serial Protocol Packet Definition ==
== Serial Protocol Packet Definition ==
=== Serial Port parameters ===
=== Serial Port Parameters ===
* Baud rate 115200
* Baud rate 115200
* 8bit, 1 stop bit, and no parity
* 8bit, 1 stop bit, and no parity
=== Packet format ===
=== Packet Format===
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 24: Line 20:


== Specifics ==
== Specifics ==
=== MDB Forwarding mechanism ===
=== MDB Forwarding Mechanism ===
The q3v will forward all the MDB cashless device commands,except the the POLL command,the request and response procedure can be described in following steps:
The Q3v forwards all MDB cashless device commands except the POLL command. The request and response procedure can be described in the following steps:
# VMC Send MDB request to q3v
# VMC sends MDB request to Q3v.
# q3v receive the step 1 data,get rid the 9th mdb mode bit,fill into serial packet '''data''' part,sending the serial packet to application.
# Q3v receives the data, removes the 9th MDB mode bit, fills it into the serial packet data part, and sends the serial packet to the application.
# The application will listen to to the serial port all the time,after receiving step 2 serial data,unwrap it to mdb request data,handle it, and wrap its mdb response into serial packet, sending to q3v
# The application listens to the serial port, receives step 2 data, unwraps it to MDB request data, handles it, wraps its MDB response into a serial packet, and sends it to Q3v.
# q3v get the step 3 data, unwrap to mdb response data, add mdb mode bit,forwarding to mdb master.
# Q3v receives step 3 data, unwraps it to MDB response data, adds the MDB mode bit, and forwards it to the MDB master.
# mdb master handle the mdb slave response
# MDB master handles the MDB slave response.


Taking the '''RESET''' for example
Taking the '''RESET''' for example
Line 38: Line 34:
# ''q3v -> VMC: 0x00 0x100''
# ''q3v -> VMC: 0x00 0x100''
# ''VMC -> q3v: 0x00''
# ''VMC -> q3v: 0x00''
=== Application notes ===
=== Application Notes===
* App need to focus on step 2,3 list above
* Focus on steps 2 and 3 listed above.
* It's application's own task to tackle all cashless command except the POLL
* The application is responsible for handling all cashless commands except the POLL command.
* When the cashless reader is ready for transaction, it lunch a '''begin session''' command,to notify the VMC
* When the cashless reader is ready for a transaction, it initiates a begin session command to notify the VMC.
* mdb raw data including its checksum byte(try to make different with the serial frame checksum )
* MDB raw data includes its checksum byte (distinct from the serial frame checksum).




== A typical MDB transacrion flow ==
== A Typical MDB Transaction Flow ==
[[File:Mdb flow chart.png|frame|center|MDB transacrion flow]]
[[File:Mdb flow chart.png|frame|center|MDB transacrion flow]]


== Protocol command definition ==
== Protocol Command Definition ==
=== common mdb forwarding command ===
=== Common MDB Forwarding Command ===
'''Description:''' <br>
Common MDB Forwarding Command Description: This command forwards raw MDB commands (including MDB CHK), with the MDB mode bit removed.
 
This command for forwarding the raw MDB commands (Including the
MDB CHK), Note that the MDB mode bit has been removed
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 72: Line 65:


q3v <- app 09 04 01 00 00 FF 0D.
q3v <- app 09 04 01 00 00 FF 0D.
=== Begin session command  ===
=== Begin Session Command  ===
'''Description:''' <br>
Begin Session Command Description: 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.
When app ready for transaction, it will issue a begin session command, to inform the VMC master.  
it is the beginning of one transaction.
Balance amount: 2 Bytes, if balance does not exist, it should be filled with 0xFF.
This command still obeys the MDB spec definition, however it is request by app
{| class="wikitable"
{| class="wikitable"
|-
|-
Line 95: Line 84:


q3v -> app 09 03 01 00 ff 0d
q3v -> app 09 03 01 00 ff 0d
=== session cancel request -0x04  ===
=== Session Cancel Request(0x04) ===
'''Description:''' <br>
Session Cancel Request (0x04) Description: The application can end a payment session by issuing a session cancel request command. The POS acts as the master during this command.
App can end the payment session by issue a session cancel request command, pos is in master mode during the command.
{| class="wikitable"
{| class="wikitable"
|-
|-

Revision as of 03:40, 18 December 2023

Introduction

This document outlines a serial communication protocol between the application running on Q3v and MDB Vending machines. The Q3v low-level hardware forwards MDB requests from the vending machine to the Android application as serial data. When the application processes all request serial data, the Q3v POS can be regarded as an MDB cashless slave device. Additionally, the application can request configuration commands, such as "get firmware version," making the protocol bi-directional. A mode byte indicates the direction of communication.

Serial Protocol Packet Definition

Serial Port Parameters

  • Baud rate 115200
  • 8bit, 1 stop bit, and 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 can be described in the following steps:

  1. VMC sends MDB request to Q3v.
  2. Q3v receives the data, removes the 9th MDB mode bit, fills it into the serial packet data part, and sends the serial packet to the application.
  3. The application listens to the serial port, receives step 2 data, unwraps it to MDB request data, handles it, wraps its MDB response into a serial packet, and sends it to Q3v.
  4. Q3v receives step 3 data, unwraps it to MDB response data, adds the MDB mode bit, and forwards it to the MDB master.
  5. MDB master handles the MDB slave response.

Taking the RESET for example

  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 listed above.
  • The application is responsible for handling all cashless commands except the POLL command.
  • When the cashless reader is ready for a transaction, it initiates a begin session command to notify the VMC.
  • 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

Common MDB Forwarding Command Description: This command forwards raw MDB commands (including MDB CHK), with the MDB mode bit removed.

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

Begin Session Command Description: 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.

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)

Session Cancel Request (0x04) Description: The application can end a payment session by issuing a session cancel request command. The POS acts as the master during this command.

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

Response packet

Mode Data
Response 01H ACK 00H

Demo

Source code of terminal APP

APK

Source code of PC program

MDBForCoffeeDemo usage

Retrieved from "http://sdkwiki.wizarpos.com/index.php?title=MDB_Communication_Protocal&oldid=3373"