MDB Communication Protocal

Introduction

This doc defines a serial communication protocol between the application running on Q3v and MDB Vending machine. 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 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 will forward all the MDB cashless device commands,except the the POLL command,the request and response procedure can be described in following steps:

VMC Send 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.
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
q3v get the step 3 data, unwrap to mdb response data, add mdb mode bit,forwarding to mdb master.
mdb master handle the mdb slave response

Taking the RESET for example

VMC -> q3v: 0x110 0x10
q3v -> app: 0x09 0x04 0x00 0x10 0x10 0xE0 0x0D
app -> q3v: 0x09 0x04 0x01 0x00 0x00 0xFF 0x0D
q3v -> VMC: 0x00 0x100
VMC -> q3v: 0x00

Application notes

App need to focus on step 2,3 list above
It's application's own task to tackle all cashless command except the POLL
When the cashless reader is ready for transaction, it lunch a begin session command,to notify the VMC
mdb raw data including its checksum byte(try to make different with the serial frame checksum )

A typical MDB transacrion flow

MDB transacrion flow

Protocol command definition

common mdb forwarding command

Description:

This command for forwarding the raw MDB commands (Including the MDB CHK), Note that the MDB mode bit has been 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

Description:
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

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

Description:
App can end the payment session by issue a session cancel request command, pos is in master mode during the 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