| 版本号 Version |
修改标识 Modify Logo |
修改原因/内容 Modification reason/content |
修改人 Modified by |
审核人 Reviewer |
修改时间 Modification time |
|---|---|---|---|---|---|
| v1.0 | 新建/Create | 创建原始文档 Create original file |
李保志 Li Baozhi |
王显泽 Wang Xianze |
2026-09-10 10:00 |
10H)10H).12H) 由 MDB-RS232 透传器完成,App 只收推送帧。12H) is performed by the MDB-RS232 pass-through device, and the App only receives pushed frames.| 时机 Timing |
指令 Command |
编码 Code |
意义 Meaning |
|---|---|---|---|
串口连通后 initialize()After serial port connection initialize() |
RESET | 10 |
复位刷卡器;成功以推送 10 00(Just Reset)判定Reset the card reader; success is determined by pushed 10 00 (Just Reset). |
| Just Reset 之后 After Just Reset |
SETUP | 11 00 … |
读 Reader Config(缩放系数、小数位等),用于 fenToScaledRead Reader Config (scaling factor, decimal places, etc.), used for fenToScaled. |
| Setup 之后 After Setup |
MAX/MIN PRICE | 11 01 FF FF 00 00 |
放开价格范围 Release price range. |
| 同上 Same as above |
READ ID | 17 00 … |
外设标识(应答 10 09…)Peripheral identification (response 10 09…). |
| 同上 Same as above |
ENABLE(Expansion) | 17 04 00 00 00 20 |
启用刷卡器能力 Enable card reader capabilities. |
| Init 末尾 / 每次 SessionComplete 后 At end of Init / after each SessionComplete |
START SESSION(Reader Enable) | 14 01 |
进入可发起 Vend 的会话就绪(设备态 → READY)Enter session ready state for initiating Vend (device state → READY). |
用户选刷卡支付 startPaymentUser selects card payment startPayment |
VEND REQUEST | 13 00 PP PP II II |
发起扣款;设备态 → ENABLED;引擎 WaitingPayment;60s 超时Initiate deduction; device state → ENABLED; engine WaitingPayment; 60s timeout. |
| 用户取消 / 超时 / 会话取消等 User cancel / timeout / session cancel, etc. |
VEND CANCEL | 13 01 |
撤销进行中的 Vend(10 06 刷卡拒绝时不发)Cancel ongoing Vend (not sent when 10 06 card denied). |
出货成功 finishTransaction(true)Dispense success finishTransaction(true) |
VEND SUCCESS | 13 02 II II |
确认出货,正式结算扣款 Confirm dispensing and formally settle deduction. |
出货失败 finishTransaction(false)Dispense failure finishTransaction(false) |
VEND FAILURE | 13 03 |
通知失败/冲正 Notify failure/reversal. |
| 取消、拒绝收尾、成功/失败结算后 After cancel, denial cleanup, success/failure settlement |
SESSION COMPLETE | 13 04 |
结束本会话(期望应答 10 07),随后再发 14 01 开下一轮End this session (expected response 10 07), then send 14 01 again to start next round. |
辅助逻辑:ensureReadyForVend() —— 非 READY 时先 sessionComplete()(脏会话),仍不行则全量 initialize()。
Auxiliary logic: ensureReadyForVend() — when not READY, first call sessionComplete() (dirty session); if still not working, perform full initialize().
| 帧 Frame |
事件 Event |
时机 Timing |
引擎行为 Engine Behavior |
|---|---|---|---|
10 00 |
Just Reset | Reset 应答或自发复位 Reset response or spontaneous reset |
Init 等待完成;支付中则按失败处理并可能重 init Init waits for completion; during payment, handle as failure and possibly re-init. |
10 04 |
Session Cancel | 设备请求取消 Device requests cancel |
onCashlessDenied → VendCancel + SessionComplete |
10 05 [HH LL] |
Vend Approved | 刷卡批准 Card approved |
→ Paying → Paid(UI 继续下单/出货)→ Paying → Paid (UI continues ordering/dispensing). |
10 06 |
Vend Denied | 刷卡拒绝 Card denied |
SessionComplete 跳过 VendCancel → FailedSessionComplete skips VendCancel → Failed. |
FF |
Offline | 链路/设备离线 Link/device offline |
设备 OFFLINE;支付中按失败收尾Device OFFLINE; if paying, finalize as failure. |
未接线的 POLL 码(03 BEGIN SESSION 等)见 [.cursor/rules/mdb-development.mdc](.cursor/rules/mdb-development.mdc);本项目用 VMC 主动 14 01 + 13 00 替代标准 Begin Session 被动路径。
Unconnected POLL codes (03 BEGIN SESSION, etc.) are described in [.cursor/rules/mdb-development.mdc](.cursor/rules/mdb-development.mdc); this project uses VMC active 14 01 + 13 00 instead of the standard Begin Session passive path.
内容即下方指令表 + 流程图。本次只梳理 硬币 + 纸币(CASH)。
Content includes the command tables and flowcharts below. This section only covers coin + bill (CASH).
| 指令类 Command Class |
报文 Message |
下发时机 Timing |
意义 Meaning |
|---|---|---|---|
CoinSetupCommand |
09 |
initialize() 第 1 步Step 1 of initialize() |
Setup:读缩放系数、小数位、面额映射(typeKey 50~55)Setup: read scaling factor, decimal places, denomination mapping (typeKey 50~55). |
CoinStatusCommand |
0A |
Setup 成功后 After Setup succeeds |
Tube Status:查钱管库存/状态 Tube Status: query tube inventory/status. |
CoinEnableCommand |
0F 01 00 00 00 01 |
Status 成功后 After Status succeeds |
Expansion Enable:打开扩展能力(含找零相关) Expansion Enable: enable extended capabilities (including change-related). |
CoinStartCommand |
0C FF FF FF FF |
startPayment(CASH) 且硬币 READY/ENABLEDstartPayment(CASH) and coin READY/ENABLED |
Coin Type:使能全部币种与钱管,开始收币 Coin Type: enable all coin types and tubes, start accepting coins. |
| (推送)CoinAccepted (Push) CoinAccepted |
08 aa bb(aa=01yyxxxx) |
用户投币后设备上报 Device reports after user inserts coin |
入账:CashBox/Tube 才累加;Rejected/Unused 不计 Credit: only CashBox/Tube accumulate; Rejected/Unused are not counted. |
CoinCloseCommand |
0C 00 00 00 00 |
足额 / pausePayment / cancelPaymentFull amount / pausePayment / cancelPayment |
Coin Type 全 0:关闭收币 Coin Type all 0: stop accepting coins. |
CoinChangeCommand |
0F 02 XX |
executeChange / dispenseMoney |
Expansion Payout:分批找零,每次 ≤200 单位,间隔 3.5s Expansion Payout: batch change dispensing, each batch ≤200 units, interval 3.5s. |
CoinChangeConfirmCommand |
0F 04 |
找零批次发完后(延时 500ms) After change batches are sent (delay 500ms) |
Payout Poll:查已退出枚数 Payout Poll: query number of dispensed coins. |
CoinChangeConfirmAgainCommand |
0F 03 |
Confirm 之后 After Confirm |
二次确认找零完成状态 Secondary confirmation of change completion status. |
状态机:UNKNOWN → INITIALIZING → READY → ENABLED ↔ DISABLED(失败 → ERROR)。
State machine: UNKNOWN → INITIALIZING → READY → ENABLED ↔ DISABLED (failure → ERROR).
| 指令类 Command Class |
报文 Message |
下发时机 Timing |
意义 Meaning |
|---|---|---|---|
BillSetupCommand |
31 |
initialize() 第 1 步Step 1 of initialize() |
Setup:读缩放、小数位、面额映射(typeKey 80~)Setup: read scaling, decimal places, denomination mapping (typeKey 80~). |
BillChangeEnableCommand |
37 01 00 00 00 02 |
Setup 成功后 After Setup succeeds |
Expansion:使能找零/回收相关能力 Expansion: enable change/recycling related capabilities. |
BillChangeUnitCommand |
37 03 |
ChangeEnable 之后 After ChangeEnable |
查询单币找零面额编号 → changeUnitCodeQuery single-bill change denomination number → changeUnitCode. |
BillStartCommand |
34 FF FF 00 00 |
startPayment(CASH) 且纸币 READY/ENABLEDstartPayment(CASH) and bill READY/ENABLED |
Bill Type:使能全部纸币类型;00 00 表示不走 escrow 使能掩码,开始收钞Bill Type: enable all bill types; 00 00 means not using escrow enable mask, start accepting bills. |
| (推送)BillAccepted (Push) BillAccepted |
30 xx(bit7=1) |
用户投钞后设备上报 Device reports after user inserts bill |
仅 Stacked / ToRecycler 入账;Escrow/Returned 等不计Only Stacked / ToRecycler are credited; Escrow/Returned etc. are not counted. |
BillCloseCommand |
34 00 00 00 00 |
足额 / pause / cancel Full amount / pause / cancel |
Bill Type 全 0:关闭收钞 Bill Type all 0: stop accepting bills. |
BillChangeExecuteCommand |
37 07 HH LL |
executeChange / dispenseMoney 硬币找零后仍有剩余After coin change, if remainder still exists in executeChange / dispenseMoney |
Expansion Change:按缩放金额执行纸币找零 Expansion Change: execute bill change according to scaled amount. |
本实现没有单独下发 Escrow Accept/Return(35);入账依赖设备已堆叠/进回收器的推送。
This implementation does not separately send Escrow Accept/Return (35); crediting depends on device pushes indicating stacked/into recycler.
找零策略(dispenseMoney):先硬币后纸币;仍退不完 → ManualRequired。
Change strategy (dispenseMoney): coins first, then bills; if still incomplete → ManualRequired.
取消路径:cancelPayment → 双侧 stopCollect → dispenseMoney(已收总额) 原路退回。
Cancel path: cancelPayment → both sides stopCollect → dispenseMoney(total accepted) refund along original path.
| 功能项 Function |
发送指令(HEX) Send Command (HEX) |
接收原始字节(HEX) Received Raw Bytes (HEX) |
ASCII解析消息 ASCII Parsed Message |
备注 Remarks |
|---|---|---|---|---|
| 初始化配置 level 2/3 Initialization config Level 2/3 |
110002000002110003000000 |
31302030312030332031382034302030312030322035412030420D0A |
100103184001025A0B |
刷卡器初始化,配置 MDB Level2/Level3 协议版本, 设备返回版本及基础能力报文 Card reader initialization, configure MDB Level2/Level3 protocol version; device returns version and basic capability message. |
| 配置最大最小值 Configure max/min values |
1101FFFF0000 |
3030200D0A |
00 |
配置刷卡器交易金额上下限, 返回 00 代表配置成功 Configure card reader transaction amount upper/lower limits; return 00 indicates successful configuration. |
| 读取 ID Read ID |
17004E4543303030303030303030303030202020534F4C4953544120200011 |
31302030392035302034312035382034362034362034362034362034362034362034362034362034362034362034362034362034362034362034392034442033332033302030302030302030302030302030302030302030302030302030302030302030302030302030302030302030302030302030302030302030322030302030302030302030302032300D0A |
1009504158464646464646464646464646494D33300000000000000000000000000200000020 |
读取刷卡器设备序列号/厂商ID, 用于设备身份识别 Read card reader device serial number/vendor ID, used for device identity identification. |
| 使能模式 Enable mode |
170400000020 |
3030200D0A |
00 |
刷卡器模块使能,启用刷卡交易能力, 返回 00 表示执行成功 Card reader module enable, enable card transaction capability; return 00 indicates successful execution. |
| 开启交易 Start transaction |
1401 |
3030200D0A |
00 |
启动一次刷卡交易会话, 设备进入等待刷卡状态 Start a card transaction session; device enters waiting-for-card state. |
| 发起刷卡支付金额 Initiate card payment amount |
130006D60001 |
3030200D0A |
00 |
配置本次刷卡交易的目标扣款金额 Configure target deduction amount for this card transaction. |
| 收到支付金额上报 Receive payment amount report |
- | 31302030352030362044360D0A |
100506D6 |
设备主动上报:用户已刷卡, 成功读取支付金额数据 Device actively reports: user has swiped card, successfully read payment amount data. |
| 取消交易 Cancel transaction |
1301 |
3030200D0A31302030360D0A |
001006 |
主机下发交易取消指令, 设备应答成功并上报交易取消事件 Host sends transaction cancel command; device responds successfully and reports transaction cancel event. |
| 扣款成功 Deduction success |
13020001 |
3030200D0A |
00 |
主机下发指令,告知刷卡器云端/后台扣款成功 Host sends command to inform card reader that cloud/backend deduction succeeded. |
| 扣款失败 Deduction failure |
1303 |
3030200D0A |
00 |
主机下发指令,告知刷卡器扣款失败, 可提示用户重新支付 Host sends command to inform card reader that deduction failed; user can be prompted to pay again. |
| 结束交易 End transaction |
1304 |
31302030370D0A |
1007 |
主机关闭本次交易会话, 设备返回交易结束应答事件 Host closes this transaction session; device returns transaction end response event. |
| 重置 Reset |
10 |
3030200D0A31302030300D0A |
001000 |
下发设备复位指令, 刷卡器完成重置并返回复位成功事件 Send device reset command; card reader completes reset and returns reset success event. |
| PAX 刷卡器待机断开 PAX card reader standby disconnect |
- | 31302030300D0A |
1000 |
设备主动上报待机断开事件, 刷卡器进入待机休眠状态 Device actively reports standby disconnect event; card reader enters standby sleep state. |
| 功能项 Function |
发送指令(HEX) Send Command (HEX) |
接收原始字节(HEX) Received Raw Bytes (HEX) |
ASCII解析消息 ASCII Parsed Message |
备注 Remarks |
|---|---|---|---|---|
| 初始化配置 Initialization config |
31 |
3032203139203738203030203634203032203031203243204646204646204646203035203041203134203332203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203738200D0A |
021978006402012CFFFFFF050A14320000000000000000000078 |
纸币器初始化,返回设备支持面额、比例系数、小数位移参数 1. 常规参数:比例系数HEX=0064(十进制100),小数位移=2,支持面额:1.00、5.00、10.00、20.00、50.00、100.00 2. 拓展示例:比例系数HEX=03E8(十进制1000),小数位移=0,支持面额:1000.00、5000.00、10000.00、20000.00、50000.00、100000.00 3. 投入20000纸币,设备上报报文:30B329 Bill acceptor initialization, returns supported denominations, scaling factor, decimal shift parameters. 1. Regular parameters: scaling factor HEX=0064 (decimal 100), decimal shift=2, supported denominations: 1.00, 5.00, 10.00, 20.00, 50.00, 100.00. 2. Extended example: scaling factor HEX=03E8 (decimal 1000), decimal shift=0, supported denominations: 1000.00, 5000.00, 10000.00, 20000.00, 50000.00, 100000.00. 3. Insert 20000 bill, device reports message: 30B329. |
| 开启收钱 Start accepting money |
34FFFF0000 |
3030200D0A33302030330D0A |
003003 |
开启纸币接收功能,允许用户投入纸币;3003为设备状态事件上报 Enable bill acceptance function, allow user to insert bills; 3003 is device status event report. |
| 关闭收钱 Stop accepting money |
3400000000 |
3030200D0A33302032322030390D0A |
00302209 |
关闭纸币接收功能,停止识别纸币;附带设备状态事件上报 Disable bill acceptance function, stop recognizing bills; includes device status event report. |
| 找零钱箱余额查询 Change cash box balance query |
3705 |
3030203030203030203030203030203030203030203030203030203030203031203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203031200D0A |
000000000000000001000000000000000000000000000000000000000000000000000001 |
查询纸币找零器各面额纸币剩余库存数量及余额状态 Query remaining inventory quantity and balance status of each denomination in bill change dispenser. |
| 使能支持纸币找零器 Enable bill change dispenser support |
370100000002 |
3030200D0A |
00 |
启用纸币找零硬件功能,设备支持纸币找零输出,返回00成功 Enable bill change hardware function; device supports bill change output; return 00 success. |
| 读取找零器单币值 Read change dispenser single bill value |
3703 |
3030203038203038200D0A3030203034203034200D0A |
000808000404 |
读取纸币找零器预设的单张找零面额配置参数 Read preset single-bill change denomination configuration parameters of bill change dispenser. |
| 发起单币值找零 Initiate single bill value change |
3707000A |
3030200D0A |
00 |
下发单张纸币找零指令,设备执行吐钞动作,返回00表示执行成功 Send single-bill change command; device executes bill dispensing action; return 00 indicates successful execution. |
| 功能项 Function |
发送指令(HEX) Send Command (HEX) |
接收原始字节(HEX) Received Raw Bytes (HEX) |
ASCII解析消息 ASCII Parsed Message |
备注 Remarks |
|---|---|---|---|---|
| 初始化配置 Initialization config |
09 |
3033203131203730203634203030203030203046203031203032203035203041203030203030203030203030203030203030203030203030203030203030203030203030203030203030203039200D0A |
0311706400000F0102050A0000000000000000000000000000000009 |
投币器初始化,返回硬币面额、比例系数、小数位移参数 1. 大金额模式:系数0x64(100)、位移0,面额:100/200/500/1000元 2. 小金额模式:系数0x01(1)、位移2,面额:0.05/0.10/0.20/0.50/1.00/2.00元 3. 投入0.1元硬币,设备上报报文:085101 Coin acceptor initialization, returns coin denominations, scaling factor, decimal shift parameters. 1. Large amount mode: factor 0x64 (100), shift 0, denominations: 100/200/500/1000 yuan. 2. Small amount mode: factor 0x01 (1), shift 2, denominations: 0.05/0.10/0.20/0.50/1.00/2.00 yuan. 3. Insert 0.1 yuan coin, device reports message: 085101. |
| 钱箱余额查询 Cash box balance query |
0A |
3030203030203030203031203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203030203031200D0A |
000000010000000000000000000000000000000000000001 |
查询投币器钱箱余额及各面值硬币剩余库存数量 Query coin acceptor cash box balance and remaining inventory quantity of each coin denomination. |
| 使能模式 Enable mode |
0F0100000001 |
3030200D0A |
00 |
投币器功能使能,开启投币检测与识别能力,返回00成功 Coin acceptor function enable, start coin insertion detection and recognition capability; return 00 success. |
| 开启收钱 Start accepting money |
0CFFFFFFFF |
3030200D0A |
00 |
开启硬币接收功能,允许用户投入硬币 Enable coin acceptance function, allow user to insert coins. |
| 关闭收钱 Stop accepting money |
0C00000000 |
3030200D0A |
00 |
关闭硬币接收功能,停止识别用户投币 Disable coin acceptance function, stop recognizing user coin insertion. |
| 投币找零 Coin change dispensing |
0F02 + 找零金额(元)0F02 + change amount (yuan) |
- | - | 找零指令格式:0F02后拼接换算后的金额存储值 换算公式:存储值 = (实际金额 × 10^小数位移) ÷ 比例系数 Change command format: 0F02 followed by converted amount storage value.Conversion formula: stored value = (actual amount × 10^decimal shift) ÷ scaling factor. |
| 查询找零数量 Query change quantity |
0F04 |
3041203041200D0A |
0A0A |
查询找零器各面值硬币的剩余可找零数量 Query remaining dispensable quantity of each coin denomination in change dispenser. |
| 再次查询钱箱余额/找零数量 Query cash box balance/change quantity again |
0F03 |
3030203031203030203030203030203030203030203030203030203030203030203030203030203031200D0A |
000100000000000000000000000000000001 |
二次复核投币找零器余额及各面额硬币库存数量,用于数据校验 Secondary verification of coin change dispenser balance and coin inventory quantity of each denomination, used for data verification. |