|
|
| Line 1: |
Line 1: |
| == Introduction ==
| | {{Migrating|https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal}} |
| 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===
| |
| {| class="wikitable"
| |
| |-
| |
| | 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).<br>
| |
| 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:
| |
| # VMC sends MDB request to Q3v.
| |
| # Q3v receives the data, removes the 9th MDB mode bit, and sends the serial packet to the application.
| |
| # The application processes the data, handles the MDB request, and sends the MDB response to Q3v.
| |
| # Q3v forwards the response to the MDB master.
| |
| # MDB master handles the MDB slave response.
| |
| | |
| '''Example: RESET'''
| |
| # ''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===
| |
| * 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 ==
| |
| [[File:Mdb flow chart.png|frame|center|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:'''<br>
| |
| {| class="wikitable"
| |
| |-
| |
| ! Mode !! Data
| |
| |-
| |
| | Request 00H || VMC Request Command
| |
| (Reset,Setup,Reader,Expansion,Vend)
| |
| |}
| |
| '''Response Packet:'''<br>
| |
| {| class="wikitable"
| |
| |-
| |
| ! Mode!! Data
| |
| |-
| |
| | Response 01H || Peripheral Response
| |
| |}
| |
| '''Example:''' <br>
| |
| Q3v -> app 09 04 00 10 10 E0 0D <br>
| |
| | |
| 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:'''<br>
| |
| {| class="wikitable"
| |
| |-
| |
| ! Mode !! Data
| |
| |-
| |
| | Request 00H || Begin Session (03H) + Funds Available + MDB Checksum
| |
| |}
| |
| '''Response Packet:'''<br>
| |
| {| class="wikitable"
| |
| |-
| |
| ! Mode!! Data
| |
| |-
| |
| | Response 01H || ACK 00H
| |
| |}
| |
| '''Example:''' <br>
| |
| Q3v <- app 09 06 00 03 00 64 67 32 0d <br>
| |
| | |
| 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:'''<br>
| |
| {| class="wikitable" | |
| |-
| |
| ! Mode !! Data
| |
| |-
| |
| | Request 00H || Cancel Session Req(04H) + Funds Available + Checksum
| |
| |}
| |
| '''Response Packet:'''<br>
| |
| {| class="wikitable" | |
| |-
| |
| ! Mode!! Data
| |
| |-
| |
| | Response 01H || ACK 00H
| |
| |}
| |
| == Demo ==
| |
| [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/vmc_master_tool-python-code.zip Source Code for PC Program]
| |
| | |
| [http://ftp.wizarpos.com/advanceSDK/MDBForCoffeeDemousage20220725.pdf MDBForCoffeeDemo Usage]
| |
