# CTC协议
**Repository Path**: GMSA/CTC
## Basic Information
- **Project Name**: CTC协议
- **Description**: 游戏机与管理系统通用协议
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-06-20
- **Last Updated**: 2025-10-16
## Categories & Tags
**Categories**: game-dev
**Tags**: None
## README
## [CTC协议](https://gitee.com/GMSA/CTC "CTC协议")V0.3
游戏机与卡头通用通讯协议
* CTC的LOGO矢量图[下载](https://gitee.com/GMSA/CTC/blob/master/Imgs/CTClogo.ai)
* 游戏机控台上预留卡头安装位置的实例[下载](https://gitee.com/GMSA/CTC/blob/master/Imgs/setup.pdf)
## 1.愿景
* 高效,减少出票投币时间,增加游戏有效时间
* 安全,彻底规避游戏机被干扰导致客诉和损失
* 简洁,对接速度快,有各平台代码拿来即用
* 准确,数据必达不重复,有校验
* 快捷,统一卡头安装尺寸,预留安装位置
## 2.物理接口
卡头统一使用下图接口,使用XHB2.54-4P接口标准,依次针脚为GND,TX,RX,12V,其中TX,RX接游戏机的RX,TX线.
* 通讯使用RS232标准串口通讯.电平12V
* 通讯波特率:38400,起始位1位,数据位:8位,奇偶校验:无,停止位:1
* 12V供电由游戏机提供,电流至少保证500mA
* 游戏机出厂时带此线材,需带钩.防止线吊着松动.
* 卡头会在TX,RX线串100欧姆限流电阻防止过流.
* 卡头需要在12V,RX,TX上加TVS管防止静电.
* 接口颜色使用蓝色,用于区分其他接口
---
**接入CTC协议后,原游戏机连接的投币器和出票器将不再经过卡头,还是由原游戏机控制,通过卡头给的通道选择来确定从哪个方向出奖励数据.**
---
对接CTC协议后的连接方式
## 3.通用底座安装尺寸
游戏机控台使用此标准预留卡头安装位置.
注意不使用自攻螺丝,统一使用M4标准机丝螺丝,避免自攻螺丝安装不牢固或拆除一次没法安装第二次问题
卡头未插卡时的高度不高于50mm
## 4.通讯基础协议
| 数据 | 长度 | 意义 |
| :------- | :------- | :----------------------------------------------------------------------------- |
| 包头 | 2字节 | 固定0xABCD |
| P位 | 1字节 | 默认从0开始,用于1块主板多个P位,此场景游戏机主板根据此字段判断哪个卡头来的通讯,卡头无需理会此字段,由CTC HUB(协议接线器)来自动处理. |
| 命令标识 | 2字节 | 具体功能的标识00开头为为行业标准协指令,非行业标准的私有指令不要使用00开头 |
| 事务ID | 4字节 | 用于防止重发|
| 长度 | 1字节 | 数据字段的长,考虑单片机内存资源的消耗,最大数据长度限制242,最大整帧长度256 |
| 数据 | n字节,n=长度 | 功能携带的参数 |
| 校验 | 4字节 | CRC32国际标准算法,对以上所有数据进行计算(不包含校验字段),算法代码见本仓库源码 |
事务ID用于对通讯过程防重复处理,卡头和游戏机会有发送事务ID和接收事务ID,接收事务ID以0开始,发送事务ID以1开始.
游戏机和卡头各自进行保存,每次发送新的指令都把发送事务ID+1进行发送,接收端对比接收事务ID如果和收到的事务ID不相同代表有效,并将自己的接收事务ID等于此ID,如果相同代表已经处理过,回应结果但不处理业务员逻辑,心跳数据无需使用事务ID.如果事务ID超过4字节最大值可再次从1开始.
基础协议中的数字按低位在后处理
如2字节数字1000=0x03E8
如4字节数字999999=0x000F423F
CRC32算法会在本仓库源码区存放,可直接下载使用
## 5.通讯时序
数据通讯使用波特率:38400,原则上每帧至少间隔10ms.程序应能将接收数据放入缓冲器自行搜索针头,并进行数据流处理.
==通讯协议必须遵循以下时序,确保收到指令马上回应ACK应答(200ms以内),ACK内容为是否已接收,目的是防止回应过慢导致低效的重发处理浪费各自的资源.指令如未收到ACK应答,将在200ms后进行重发3次,如果3次都没有回应将由上层应用断是否继续重发(某些业务需要一直重发,有些业务可放弃发送),如25秒都没有应答可判断为断开了连接,可在设备显示断联标识. 如ACK回应已接收,发起方可停止重发.==
游戏机判断断联可依据没有收到任何信息超过25秒,因为空闲状态卡头会每10秒发一次心跳.
单帧数据如果在100ms内没有接收完整将被丢弃等待下次重发
如接收方响应ACK告诉发送方缓冲已满,发送方将等待400ms后再次尝试发送,如果尝试3次都没成功会将由上层应用断是否继续重发
如果接收方发现基础协议都有异常会放慢处理速度,延迟1000ms再处理接收的数据,防止浪费性能
### 5.1设备启动时
游戏机与卡头启动时,卡头发起握手,握手完成后如果是当天未抄表,会发起一次抄表,收集游戏机的码表数据,用于门店经营者方便管理.
完成后每10秒发起一次心跳,心跳将带上卡头是否可用状态,如卡头不在可用状态,请根据卡头提供的错误码在游戏机屏幕显示,方便门店经营者及时维护.游戏机回应的心跳内容也会带上游戏机是否可用,当游戏机故障并且不可用状态时,卡头将禁止门店玩家进行消费,并将故障通知门店机修人员进行及时维护.
握手时卡头和游戏机都会知道对方的协议版本,由卡头方来处理兼容问题,游戏机端只需要支持某一个指定版本的协议.
异常情况
* 握手未收到应答,将每隔10秒进行一次握手,直到握手成功
* 心跳连续2次都未响应,将重新进入握手尝试直到握手成功,再次进行心跳循环
### 5.2 刷卡消费时(投币)
门店玩家在卡头刷卡或线上发起消费时,管理系统先进行扣费,扣费成功后投币给游戏机,如果游戏机响应不接受投币,卡头将返还给顾客.==如3次未收到正确响应可在管理系统后台添加日志等待人工处理,并跳过此事务ID==
### 5.3 游戏机奖励通道选择
由于使用了本CTC协议之后,卡头将不再控制游戏机的投币器和出票器,但门店经营者的需求多样,所以需要卡头来告诉游戏机出奖的方式.
如彩票,卡头会告诉游戏机:
* 出票给出票器(出实体票)
* 出票到卡头(出电子票)
* 暂时不出票,等待卡头后续的指令(用于场地希望节省彩票,非会员也迫使他去办卡,插卡后才出票)
如果卡头曾经连上过后来故障或断联可报错由工作人员处理
暂时不出票的模式下,卡头会在屏幕上显示两个按钮,按钮1:扫码或刷卡存票,在扫码或刷卡后,卡头会让游戏机出票给卡头. 按钮2: 出实物票,按下这个按钮卡头会告诉游戏机出票到出票器
### 5.4 游戏有奖励给玩家(出票)
当奖励通道选择成出奖励(电子票)到卡头时,游戏机发起指令,卡头应答收到就算完成.如果没有收到响应需要进行重发,重发时事务ID不能变化,以免重复处理.==如果超过3次都未收到应答需要等待再次握手成功后继续发送.==
### 5.5 实体数据(实物币,实物票)上报
由于接了CTC协议后卡头不在接投币器和出票器,门店需要知道全面的数据就需要游戏机将实体投币数和实体出票数告知卡头,方便对账.
### 5.6 需要同步游戏单局币数时
有些游戏机需要频繁设置每局币数,为了让门店经营者高效操作,希望能通过卡头同步到游戏机,特别是礼品机.
### 5.7 氛围通知
### 5.8 需要设置游戏机运行参数时
CTC1.0暂时不支持,等待后续版本添加
## 6.指令详解
### 6.1 ACK(通用指令回应)
**指令标识:0x0001**
| 数据字段 | 长度 | 说明 |
| :----- | :-- | :---------------------------------------------------------------- |
| 收到的指令ID | 2字节 | 应答的命令标识 |
| 指令接收结果 | 1字节 | 0=接收成功.1=包头错误,2=校验错误,3=长度错误(数据不完整并10ms接收超时),4=不支持的指令,100=接收方缓冲器已满 |
回应ACK时应将发送的事务ID和命令标识原样传回,并将自身内存中的接收事务ID变成最新的事务ID,需要对发送过来的指令进行防止重复处理,特别是在敏感数据计数时.
### 6.2 握手(卡头到游戏机)
**指令标识:0x0002**
| 数据字段 | 长度 | 说明 |
| :----------- | :--- | :--------------------------------------------------------------------- |
| 产品ID | 4字节 | CTC官网分配的产品ID,用于查询是哪个厂家出的什么产品，ctc1.0没有平台进行产品登记，此产品ID为预留字段，在2.0之前都使用全零填充 |
| 设备ID | 16字节 | 每个设备自己保证全球唯一 |
| 支持的CTC协议最高版本 | 2字节 | 本设备支持的CTC协议最高版本 |
版本适配由卡头来实现,游戏机只需要支持某个版本,卡头需要根据游戏机的CTC版本进行适应
### 6.3 回应握手(游戏机到卡头)
**指令标识:0x0003**
| 数据字段 | 长度 | 说明 |
| :----------- | :--- | :--------------------------- |
| 产品ID | 4字节 | CTC官网分配的产品ID,用于查询是哪个厂家出的什么产品 |
| 设备ID | 16字节 | 每个设备自己保证全球唯一 |
| 支持的CTC协议最高版本 | 2字节 | 本设备支持的CTC协议最高版本 |
在CTC1.0时还不具备分配产品ID的平台，此ID使用全零填充，在2.0时会有平台进行登记产品和编号分配。
### 6.4 发起抄表(卡头到游戏机)
**指令标识:0x0004**
| 数据字段 | 长度 | 说明 |
| :----- | :---- | :----- |
| 无 | 0字节 | 无需参数 |
### 6.5 抄表数据(游戏机到卡头)
**指令标识:0x0005**
| 数据字段 | 长度 | 说明 |
| :--------------- | :---------- | -------------------------------------------------------------- |
| 码表类型1 | 1字节 | 见码表类型说明 |
| 码表数量1 | 4字节 | 上次清零后到现在的码表数量 |
| 码表类型2 | 1字节 | 同上 |
| 码表数量2 | 4字节 | 同上 |
| 码表类型3 | 1字节 | 同上 |
| 码表数量3 | 4字节 | 同上 |
| 码表类型4 | 1字节 | 同上 |
| 码表数量4 | 4字节 | 同上 |
| 码表类型5 | 1字节 | 同上 |
| 码表数量5 | 4字节 | 同上 |
| 码表类型6 | 1字节 | 同上 |
| 码表数量6 | 4字节 | 同上 |
| 码表类型7 | 1字节 | 同上 |
| 码表数量7 | 4字节 | 同上 |
| 码表类型8 | 1字节 | 同上 |
| 码表数量8 | 4字节 | 同上 |
| 码表类型9 | 1字节 | 同上 |
| 码表数量9 | 4字节 | 同上 |
| 码表类型10 | 1字节 | 同上 |
| 码表数量10 | 4字节 | 同上 |
码表类型有如下类型:
* 0=投币总数,1=电子币总数,2=实物币总数
* 10=出票总数,11=出电子票总数,12=出实物票总数
* 20=出蓝票总数,21=出电子蓝票总数,22=出实物蓝票总数
* 30=总出卡片数
* 100=出礼品1总数,101=出实物礼品2总数,102=出实物礼品2总数,103=出实物礼品4总数,104=出实物礼品5总数,...130=出实物礼品31总数
* 255=数据结束(无效后面不能再放有效数据)
此指令将10条码表一起传输,用于游戏机的总数与系统数量进行核对
有条件的游戏机可区分电子币和电子票,也可只给总数
### 6.6 心跳(卡头到游戏机)
**指令标识:0x0006**
| 数据字段 | 长度 | 说明 |
| :----- | :-- | :---------------------------------------------- |
| 卡头可用状态 | 1字节 | 0=正常可用,1=等待配网,2=连接门店服务异常,3=网络无法连接,4=正在联网|
当卡头状态不等于0时,卡头处于非正常工作状态,不可刷卡消费,游戏机可在屏幕某个区域显示卡头状态,方便门店机修排查问题.特别是对没有屏幕的卡头,非正常可用时,游戏机可按没接卡头的逻辑运行,或在游戏屏幕中提示门店需要配置网络等
### 6.7 回应心跳(游戏机到卡头)
**指令标识:0x0007**
| 数据字段 | 长度 | 说明 |
| :----- | :-- | :------------------------ |
| 是否允许消费 | 1字节 | 0=卡头可正常消费,1=卡头不可进行消费 |
| 游戏机故障码 | 2字节 | 0=无故障,非0代表有故障 |
当游戏机不允许消费时,如游戏无法进行,或者游戏机处于某种繁忙状态不接受投币时可将允许消费变成1,此时卡头将禁止顾客投币
游戏机故障码,管理系统收集到后会进行记录,并尝试通知门店机修进行维护,管理系统可定期收集故障数据进行图表展示.后期CTC官网也会给每个游戏机厂商提供故障查询入口,查询报故障的报表
### 6.8 投币(卡头到游戏机)
**指令标识:0x0008**
| 数据字段 | 长度 | 说明 |
| :----- | :--- | :------------------ |
| 投币数量 | 4字节 | 投币数量 |
| 会员ID | 16字节 | 同一张会员卡或同一个会员账户时ID相同 |
| 消费记录ID | 16字节 | 标识此笔交易的ID |
### 6.9 投币应答(游戏机到卡头)
**指令标识:0x0009**
| 数据字段 | 长度 | 说明 |
| :----- | :--- | :------------ |
| 投币结果 | 1字节 | 0=成功接收,1=拒绝接收 |
| 消费记录ID | 16字节 | 投币时传递的交易ID |
应答如果是拒绝接收,门店管理系统会退还此次投币的储值,如果投币超时,卡头应记录到管理系统方便门店的人排查
### 6.10 通道选择(卡头到游戏机)
**指令标识:0x000A**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :--------------- |
| 彩票通道 | 1字节 | 0=实物,1=电子,2=暂时不出 |
| 蓝票通道 | 1字节 | 0=实物,1=电子,2=暂时不出 |
如果卡头只收彩票,会将蓝票通道设置成0,同理只出蓝票会将彩票通道设置成0,特殊情况可能会设置成2=暂时不出,等待卡头后续的判断再出,当游戏机被设置成暂时不出时,游戏机有奖励只是累计到游戏机不传递给卡头.如果通道选择给的的参数是1时,游戏机如果有奖励未出应马上通过(6.11 游戏有奖励给玩家)传递给卡头,此场景应用于场地希望此会员离开马上将奖励存到账户
### 6.11 游戏有奖励给玩家(游戏机到卡头)
**指令标识:0x000B**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :---------------------- |
| 奖励类型 | 1字节 | 0=奖励彩票,1=奖励蓝票,10=游戏任务得分 |
| 奖励数量 | 4字节 | 奖励的数量 |
如有游戏玩一局有多个数据要奖励,分多次进行传输,不可全部拼接在一个数据帧里面
### 6.12 实体数据(实物币,实物票)上报
**指令标识:0x000C**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :------------------------------------------------------- |
| 实物类型 | 1字节 | 0=实物币,1=实物彩票,2=实体蓝票,3=实体卡片,
100=实物礼品1,101=实物礼品2...130=实物礼品31 |
| 奖励数量 | 4字节 | 上报数量 |
为避免门店管理系统处理数据负担过重,需要将实物上报数据进行10秒缓存,也就是10秒没有累加了才进行上报.礼品机数据要求实时上传,出彩票或蓝票数据如果满200要求马上上报.
### 6.13 查询每局币数(卡头到游戏机)
**指令标识:0x000D**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :- |
| 无 | 0字节 | |
卡头根据机器设置来判断是否需要查询,如彩票机是不需要查询的
### 6.14 应答每局币数(游戏机到卡头)
**指令标识:0x000E**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :------------------ |
| 每局币数 | 2字节 | 每局游戏需要的投币数(投币器的脉冲数) |
卡头根据机器设置来判断是否需要查询,如彩票机是不需要查询的
### 6.15 设置每局币数(卡头到游戏机)
**指令标识:0x000F**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :------------------ |
| 每局币数 | 2字节 | 每局游戏需要的投币数(投币器的脉冲数) |
### 6.16 游戏氛围事件(游戏机到卡头)
**指令标识:0x0010**
| 数据字段 | 长度 | 说明 |
| :--- | :-- | :------------ |
| 事件等级 | 2字节 | 0开始,数字越大氛围越强烈 |
| 将要奖励类型 | 1字节 | 0=奖励彩票,1=奖励蓝票,10=游戏任务得分,100=奖励实物 |
| 将要奖励数量 | 4字节 | 产生的奖励相关的数量 |
事件需要在触发时及时通讯,避免延迟造成体验损失,此奖励类型和数量,仅用于展示氛围,不会累加到会员账户,如需存到会员账户需要使用6.11指令进行
CTC1.0只支持事件等级用数字表示是在特定条件触发,CTC2.0将要求登记触发等级与对应事件名称,事件相关图片资源等,相关数量也会用于氛围的展示.
## 7 接入流程
* 将本仓库代码根据需要移植到板子程序并初步编译通过
* 通过CTC调试工具(电脑程序)实现CTC协议
* 通过CTC调试工具进行验收,验收通过可进行对外发行
## 8 代码的使用
* 单片机代码移植指南见[代码指南](https://gitee.com/GMSA/CTC/blob/master/Code/CTC_STM32/README.md)
* PC机架构代码移植指南见[代码指南](https://gitee.com/GMSA/CTC/blob/master/Code/CTC_C%23/README.md)
## 9 验收标准
调试与验收工具等完善后发布