|
|
| (7 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| == Introduction ==
| | {{Migrating|https://smartpossdk.gitbook.io/cloudpossdk/cloudpos-sdk/mdb-communication-protocal}} |
| 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 ===
| |
| {| 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 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 ==
| |
| [[File:Mdb flow chart.png|frame|center|MDB transacrion flow]]
| |
| | |
| == Protocol command definition ==
| |
| === common mdb forwarding command ===
| |
| '''Description:''' <br>
| |
| | |
| This command for forwarding the raw MDB commands (Including the
| |
| MDB CHK), Note that the MDB mode bit has been removed
| |
| {| 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 ===
| |
| '''Description:''' <br>
| |
| 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"
| |
| |-
| |
| ! 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 ===
| |
| '''Description:''' <br>
| |
| App can end the payment session by issue a session cancel request command, pos is in master mode during the command.
| |
| {| 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/mdb/MDBForCoffeeDemo-src-code.zip Source code of terminal APP]
| |
| | |
| [http://ftp.wizarpos.com/advanceSDK/mdb/MDBForCoffeeDemo-sign-wrf.apk APK]
| |
| | |
| [http://ftp.wizarpos.com/advanceSDK/mdb/vmc_master_tool-python-code.zip Source code of PC program]
| |
| | |
| [http://ftp.wizarpos.com/advanceSDK/mdb/MDBForCoffeeDemousage 20220725.pdf MDBForCoffeeDemo usage]
| |
