云打印接入协议1.2

云打印接入协议主要描述了云打印场景下设备设备与云打印应用如何通过数据交互实现设备信息上报、打印任务下发执行等云打印关键业务。

云打印设备接入指南

连接平台接入介绍

设备接入平台有详细介绍，请仔细阅读得力E+开放文档中心.

特别注意

• 设备接入协议详细介绍请查看设备标准接入，需要申请产品型号以及产品密钥，接入平台鉴权使用.
• 设备配网详情介绍请查看APP设备标准交互协议。设备常用配网方式是wifi配网，查看设备http配网。

平台指令接入介绍

平台是设备与应用的通讯桥梁，设备与应用所有交互通讯通过平台中转完成，下面表格只介绍跟云打印相关的指令，更多平台指令介绍详情请阅读平台标准指令集）。

应用指令接入介绍

设备信息同步

设备信息上报

设备主动上报设备当前信息，以便云打印应用掌握设备最新信息，包含：网络信息、固件版本、墨盒信息、设备故障状态信息等。

以下情况设备都应主动使用本指令向应用上报设备最新信息：

• 重新接入平台
• 设备信息发生变化（网络信息、墨量信息、固件版本、设备状态（故障，繁忙，就绪）等）
• 设备绑定新应用
• 应用主动查询（收到应用指令-设备信息查询）

请求示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086,
    "action": 300,
    "data": {
        "cmd": "printer_push_report_info",
        "payload": {
            "printer_name": "Deli P2500DW-3a2f",
            "work_status": "error",
            "firmware_version": "HD_2.00.014",
            "error_code": "4611",
            "error_msg": "设备故障，重启/联系客服",
            "error_time": "1503025335",
            "mac_address": "EC:F0:0E:84:36:FE",
            "ssid": "DELI",
            "network_mode": "WLAN",
            "printer_ip": "172.193.12.11",
            "total_page_count": "10",
            "total_paper_count": "7",
            "error_paper_count": "0",
            "inkboxs": [{
                "inkbox_sn": "123123",
                "inkbox_status": "0",
                "inkbox_type":"K",
                "inkbox_status_des": "正常",
                "inkbox_colors": [{
                    "color": "black",
                    "toner_total_count":"10000",
                    "toner_remain_count":"9000",
                    "toner_remain": "90"
                }]
            }]
        }
    }
}

其中cmd固定为printer_push_report_info表示设备信息上报，请求payload各参数说明如下：

inkbox墨盒/硒鼓对象参数说明如下

一个墨盒/硒鼓表示一个单独更换的整体，常见的墨盒/硒鼓类型有4种

• 黑白彩色一体墨盒/硒鼓，数量1个，类型为："CMYK"。
• 黑白+彩色墨盒/硒鼓，数量2个墨盒，类型分别为：“K”、"CMY"。
• 四单色墨盒/硒鼓，数量4个墨盒，类型分别为：“K”、"C"、"M"、"Y"。
• 黑白单色墨盒/硒鼓，数量1个，类型为："K"

inkbox_color颜料对象参数说明如下

响应示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "printer_push_report_info"
    }
}

设备信息查询

应用可通过本指令主动向设备设备获取设备最新信息，设备收到查询请求后，通过应用指令-设备信息上报指令上报最新的设备信息。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "server_push_report_info"
    }
}

其中cmd固定为server_push_report_info表示设备信息查询，无payload信息。

响应示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678", 
    "to": "511542236802977792", 
    "time": 1555307488,
    "action": 300,
    "data": {
        "cmd": "server_push_report_info"
    }
}

云打印

功能流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、选择文件打印
app->app: 2、打印报文转换
app->device: 3、发送[打印任务通知]指令
device->app: 4、发送[打印任务执行]指令
app--device: 5、返回执行任务详情
Note left of device: 如果设备繁忙或者故障不能执行任务
device--app: 返回任务打印结果：排队等待中
device--device: 6、开始打印
device->app: 7、返回任务进度：打印中
device--device: 8、打印完成一页
device->app: 9、返回任务进度：打印中，已打印页数

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回任务状态：打印暂停
Note left of device: 解决故障，恢复打印
device--app: 返回任务状态：打印中

Note left of device: 如果打印取消
device--app: 返回任务打印结果：打印取消

Note left of device: 如果打印失败
device--app: 返回任务打印结果：打印失败

device--device: 10、打印完成。
device->app: 11、返回任务打印结果：打印完成

app->user: 12、给用户返回打印结果

流程说明：

• 打印取消：用户可以在设备上取消打印，也可以通过app发送应用指令-取消打印任务来取消打印

打印任务通知

当设备有新的打印任务时，云打印应用服务会通过本指令向设备下发任务通知。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_task_add",
        "payload": {
            "task_type": "print"
        }
    }
}

其中cmd固定为server_push_task_add表示打印任务通知，请求payload各参数说明如下：

响应示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "action": 300,
    "time": 1584079078,
    "data": {
        "cmd": "server_push_task_add",
    }
}

响应无payload信息。

注意

• 同一个业务上下文的请求和响应，请确保使用相同的mid。
• 如果设备此时处于可打印状态（在线、空闲、非故障），除了发送响应信息之后，还需要发送指令打印任务执行指令执行打印任务。

打印任务执行

当设备可通过此指令，获取当前设备可执行任务信息，下载打印报文打印。

以下情况执行此指令：

• 1、当设备收到应用指令-打印任务通知，并且设备处于可打印状态（在线、空闲、非故障）。
• 2、当设备重新连接平台后且设备已被绑定应用时。
• 3、当设备由故障变为空闲时，防止故障过程中漏掉任务没有执行。
• 4、打印设备执行完任务后（打印、扫描、固件升级等），防止在设备执行任务过程中，有新任务通知没有执行。

请求示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086,
    "action": 300,
    "data": {
        "cmd": "printer_push_task_execute"
    }
}

其中cmd固定为printer_push_task_execute表示打印任务执行，请求无payload信息：

响应示例：

云打印应用服务收到该请求后，会将当前设备任务信息发给设备，如果有执行的任务，该任务的状态被锁定为准备打印。响应结果如下：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "server_push_task_execute",
        "payload": {
            "task_status": "1",
            "task_id": "P4429f8e8d3b1443bbc6ca04619883884",
            "task_type": "print",
            "task_info": {
                "download_url": "https://domain/123"
            }
        }
    }
}

响应payload参数说明如下：

• task_type为print时，打印任务task_info信息格式如下：

{
    "download_url": "https://domain/123"
}

目前仅支持打印任务类型，其他任务类型暂不支持。

打印任务进度上报

设备开始执行打印任务之后，可通过本指令向云打印应用实时上报打印任务的执行状态。

请求示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "action": 300,
    "time": 1584091154,
    "data": {
        "cmd": "printer_push_print_progress",
        "payload": {
            "task_id": "Pf642ad1468eb4482998e61001b0b560d",
            "print_status": "printing",
            "error_code": "",
            "error_msg": "",
            "error_cause": "",
            "printed_page_count": "0",
            "printed_paper_count": "0"
        }
    }
}

其中cmd固定为printer_push_print_progress表示打印任务进度上报，请求payload各参数说明如下：

设备扫描状态print_status的具体说明如下：

1. 准备打印任务时，设备繁忙或者设备故障导致无法不能打印，返回print_status为queue，error_code、error_msg 见异常情况说明；
2. 设备开始打印时，返回print_status为printing；
3. 打印过程中，每打印完一页时，返回print_status为printing，printed_page_count为已打印页数，printed_paper_count为已打印纸张数；
4. 打印过程中，设备出现用户解决后可恢复打印的故障，返回print_status为pause，printed_page_count为已打印页数，printed_paper_count为已打印纸张数,error_code、error_msg 见异常情况说明；
5. 打印任务全部完成时，返回print_status为finish，printed_page_count为已打印页数，printed_paper_count为已打印纸张数；
6. 打印任务出现失败终止时，返回print_status为fail，printed_page_count为已打印页数，printed_paper_count为已打印纸张数,error_code、error_msg 见异常情况说明；
7. 打印任务中，取消打印或者收到指令-取消打印任务时，返回print_status为cancel，printed_page_count为已打印页数，printed_paper_count为已打印纸张数；

注意：

• 排队等待表示打印机结束本次操作，等设备恢复就绪状态后需要再次发送打印任务执行指令来执行任务。

异常情况说明 如下:

1. 如果收到云打印指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务排队等候。
2. 如果收到云打印指令设备故障无法执行任务时，设备故障描述，任务排队等候。
3. 如果设备打印过程中下载报文失败导致任务结束时，下载报文失败，任务失败。
4. 如果设备打印过程中设备故障，需要用户解决可恢复继续打印时，设备故障描述，任务暂停。
5. 如果设备打印过程中设备故障，不能恢复继续打印时，设备故障描述，任务失败。
6. 如果设备打印过程中报文格式不支持导致任务结束时，报文格式错误，任务失败。
7. 如果其他异常导致任务失败时，其他异常描述，任务失败。

异常错误码请详见错误码说明

注意，应用获取打印任务结果的唯一来源是通过设备结果上报，必须保证每一个任务的执行结果必须上报成功

由于设备执行任务后，可能会因为断网、断电、网络信号弱等各种原因导致任务结果无法上报服务器，使用户无法得到任务的真实状态。 建议：

• 当收到执行打印任务时，将任务的信息缓存起来，实时更新打印进度。
• 当打印完成时，需要上报打印结果，每次上报如果失败，重试3次。
• 如果上报3次都失败，则间隔一段时间上报（建议5s），直到打印任务结果上报成功为止。
• 如果设备断网，或者重启导致上报失败，每次联网成功后，发现还有缓存的任务信息没有上报，则继续上报任务打印结果。
• 只有打印任务结果上报成功后，才删除缓存的任务信息。

响应示例：

无

取消打印任务

当打印过程中，用户想取消打印，可通过应用发送本指令取消正在打印的任务。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584103546,
    "action": 301,
    "data": {
        "cmd": "server_push_task_cancel",
        "payload": {
            "task_id": "Pf642ad1468eb4482998e61001b0b560d"
        }
    }
}

其中cmd固定为server_push_task_cancel表示打印任务取消，请求payload各参数说明如下：

注意 设备收到请求后，如果任务未执行完毕，则应执行取消操作，并通过打印任务进度上报上报任务状态，如果任务已完成，则忽略该请求即可。

响应示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "cmd": "server_push_task_cancel"
    }
}

响应无payload信息

云扫描

功能流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 云存储服务 as css

user->app: 1、使用云扫描
app->device: 2、发送[云扫描]指令
device--device: 3、扫描确认
device->app: 4、上报扫描就绪

device--device: 5、扫描开始
device->app: 6、上报扫描中
device--device: 7、扫描结束
device->css: 8、扫描图片上传
css--device: 9、返回图片访问URL
device->app: 10、上报单页扫描完成

Note left of device:如果是平板扫描
device--app: 上报扫描完成

Note right of device:如果是自动进纸器扫描
device--device: 11、多页扫描，重复5～10

Note left of device:如果用户取消扫描
device--app: 上报扫描已取消，扫描结束

Note left of device:如果扫描失败
device--app: 上报扫描失败，扫描结束

device--device: 12、扫描完成
device->app: 13、上报扫描完成

app->user: 14、给用户返回扫描结果

流程说明：

• 流程3-扫描确认：是否可以扫描、扫描参数是否支持、进纸器是否有纸
• 流程10-单页扫描完成：如果是平板扫描，扫描只有一页，可以直接上报扫描完成并返回扫描图片信息。
• 云扫描取消：用户在设备上取消扫描或者发送指令-取消云扫描来取消扫描

执行云扫描

应用可通过以下指令向设备设备发起云扫描操作，设备将扫描得到的图片上传到云存储后，将图片信息返回给应用保存，完成云扫描功能。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_cloud_scan",
        "payload": {
            "task_id": "123",
            "scan_source": "Flat",
            "paper_size": "A4",
            "dpi": 600,
            "image_type" : "jpg",
            "color": "rgb"
        }
    }
}

其中cmd固定为server_push_cloud_scan表示执行云扫描请求，请求payload各参数说明如下：

注意： 纸张尺寸、扫描dpi、图片类型，颜色支持需要提前确认，避免不支持导致新问题。

响应示例：

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_cloud_scan", 
        "payload": {
            "task_id": "123",
            "cloud_scan_status": "page_done",
            "error_code": "",
            "error_msg": "",
            "error_cause": "",
            "image_info":{
                "image_url": "https://xxxx",
                "image_type": "jpg",
                "image_index": "1"
            }
        }
    }
}

响应payload各参数说明如下：

image_info各参数说明如下：

设备扫描状态cloud_scan_status的具体说明如下：

1. 设备在接收到扫描指令，扫描就绪时，返回cloud_scan_status为start；
2. 设备每次扫描开始时，返回cloud_scan_status为scanning；
3. 设备扫描一张完成时，先上传图片到云存储服务获取图片网络地址，返回cloud_scan_status为page_done（如果是平板扫描 则返回finish），image_info为扫描图片信息；
4. 设备使用进纸器扫描1张或者多张图片完成后，进纸器无纸则代表全部完成，返回cloud_scan_status为finish；
5. 设备扫描过程中出现失败导致任务终止时，返回cloud_scan_status为fail，error_code、error_msg 见异常情况说明；
6. 当设备扫描过程中，用户在设备上取消扫描或者收到指令-取消云扫描指令时，设备取消扫描，返回cloud_scan_status为cancel；

异常情况说明 如下:

1. 如果收到云扫描指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务失败。
2. 如果收到云扫描指令设备故障无法执行任务时，设备故障描述，任务失败。
3. 如果收到云扫描指令请求参数不正确无法执行任务时，请求参数错误（通用业务异常），任务失败。
4. 如果设备扫描过程中设备故障无法继续扫描时，设备故障描述，任务失败。
5. 如果设备扫描过程中设备本地存储空间不足导致图片保存失败时，设备存储空间不足，任务失败。
6. 如果设备扫描过程中文件云存储失败时，文件云存储失败，任务失败。
7. 如果其他异常导致任务失败时，其他异常描述，任务失败。

异常错误码请详见错误码说明

取消云扫描

当用户想取消扫描时，可通过应用发送取消云扫描指令，取消此次扫描操作。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_cloud_scan_cancel",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_cloud_scan_cancel表示云扫描取消指令，请求payload各参数说明如下：

注意：当设备此时正在扫描中则取消本次扫描并上报结果，没有扫描则忽略此指令

响应示例：

无

证件扫描

功能流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 云存储服务 as css

user->app: 1、使用证件扫描
app->device: 2、发送[证件扫描]指令
device--device: 3、扫描确认 
device->app: 4、上报证件扫描就绪

device--device: 5、扫描开始
device->app: 6、上报扫描中
device--device: 7、扫描结束
device->css: 8、扫描图片上传
css--device: 9、返回图片访问URL
device->app: 10、上报单页扫描完成

device--device: 11、等待用户确认是否继续扫描
Note left of device:如果用户取消扫描
device--app: 上报扫描取消，扫描结束

Note right of device:如果用户选择继续扫描
device--device: 12、继续扫描，重复5～11


Note left of device:如果扫描失败
device--app: 上报扫描失败，扫描结束

device--device: 13、扫描完成
device->app: 14、上报扫描完成

app->user: 15、给用户返回证件扫描结果

流程说明：

• 流程3-扫描确认：是否可以扫描、扫描参数是否支持
• 流程11-等待用户确认是否继续扫描：等待用户更换证件正反面，继续扫描，用户也可以选择完成或者取消扫描，
• 流程11-等待用户确认是否继续扫描：当等待用户确认60s超时，可认为扫描完成。
• 流程12-继续扫描：用户在设备上选择继续扫描或者发送指令-继续证件扫描来继续扫描
• 扫描取消：用户在设备上取消扫描或者发送指令-取消证件扫描来取消扫描
• 扫描完成：当等待用户确认是否继续扫描60s超时、用户在设备上选择完成扫描或者发送指令-完成证件扫描来完成扫描

执行证件扫描

应用可通过证件指令向设备设备发起证件扫描操作，设备将多次扫描到的图像合并在一张图片上，并将得到的图片上传到云存储后，最后将图片信息返回给应用保存，完成证件扫描功能。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan",
        "payload": {
            "task_id":"123",
            "paper_size": "A4",
            "dpi": 600,
            "image_type" : "jpg",
            "color": "rgb"
        }
    }
}

其中cmd固定为server_push_credential_scan表示执行证件扫描请求， 请求payload各参数说明如下：

注意： 纸张尺寸、扫描dpi、图片类型，颜色支持需要提前确认，避免不支持导致新问题。

响应示例：

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678", 
    "to": "511542236802977792", 
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_credential_scan", 
        "payload": {
            "task_id":"123",
            "credential_scan_status": "page_done",
            "error_code": "",
            "error_msg": "",
            "error_cause": "",
            "image_info":{
                "image_url": "https://xxxx",
                "image_type": "jpg",
                "image_index": "1"
            }
        }
    }
}

响应payload各参数说明如下:

image_info各参数说明如下:

设备扫描状态credential_scan_status的具体说明如下：

1. 设备在接收到扫描指令，开始扫描时，返回credential_scan_status为start；
2. 设备每次扫描开始时，返回credential_scan_status为scanning；
3. 设备扫描一张完成时，先上传图片到云存储服务获取图片网络地址，然后返回credential_scan_status为page_done（如果是平板扫描 则返回finish），image_info为扫描图片信息；
4. 当设备等待状态，用户在设备上继续扫描或者收到继续证件扫描指令时，继续扫描，扫描开始时，返回credential_scan_status为scanning；
5. 设备扫描过程中出现失败导致任务终止时，返回cloud_scan_status为fail，error_code、error_msg 见异常情况说明；
6. 当设备等待状态，用户在设备完成扫描 或者 等待用户继续扫描超过60s 或者 收到完成证件扫描指令时，设备结束扫描，返回credential_scan_status为finish；
7. 如果设备扫描过程中，用户在设备上取消扫描或者收到取消证件扫描指令时，设备取消扫描，返回credential_scan_status为cancel；

异常情况说明 如下:

1. 如果收到证件扫描指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务失败。
2. 如果收到证件扫描指令设备故障无法执行任务时，设备故障描述，任务失败。
3. 如果收到证件扫描指令请求参数不正确无法执行任务时，请求参数错误（通用业务异常），任务失败。
4. 如果设备扫描过程中设备故障无法继续扫描时，设备故障描述，任务失败。
5. 如果设备扫描过程中本地存储空间不足导致图片保存失败时，设备存储空间不足，任务失败。
6. 如果设备扫描过程中文件云存储失败时，文件云存储失败，任务失败。
7. 如果设备扫描过程中其他异常，导致任务结束时，任务失败。

异常错误码请详见错误码说明

取消证件扫描

当用户不想扫描时，可通过应用发送取消云扫描指令，取消此次扫描操作。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan_cancel",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_cancel表示证件扫描取消指令，请求payload各参数说明如下：

注意：当设备此时正在证件扫描中则取消本次扫描并上报结果，没有扫描则忽略此指令。

响应示例：

无

继续证件扫描

当用户扫描完一次证件想继续添加扫描，在设备上放好证件后，可以在app上操作继续扫描，发送继续证件扫描指令，设备执行继续扫描。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301, 
    "data": {
        "cmd": "server_push_credential_scan_continue",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_continue表示继续证件扫描指令，请求payload各参数说明如下：

当设备收到此指令时，如果设备处于证件等待中，则继续证件扫描。

响应示例：

无

完成证件扫描

当用户扫描完一次证件想结束扫描，可以在app上操作完成，发送完成证件扫描指令，设备收到指令后结束扫描并返回扫描完成。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_credential_scan_finish",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_credential_scan_finish表示完成证件扫描指令，请求payload各参数说明如下：

注意：当设备此时正在证件扫描则完成本次扫描并上报结果，没有证件扫描则忽略此指令。

响应示例：

无

固件升级

固件升级有两种方式：自动升级、手机升级，详情请仔细阅读平台指令-103

注意：由于设备固件升级失败风险较大，要求用户必须知晓风险并确认才能升级，因此建议手动固件升级，下面详细介绍手动固件升级流程。

手动固件升级

手动固件升级流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device
participant 平台 as platform


user->app: 1、手动发起设备升级
app->device: 2、发送[206指令]通知设备升级
device->platform: 3、发送[103指令]获取固件信息
platform--device: 4、返回设备最新固件版本
Note right of device: 可提前获取固件信息
device->platform: 5、108指令上报升级状态：准备就绪
platform->app: 6、固件升级准备就绪
app->user: 7、准备就绪，确认是否升级

device--device: 8、等待用户确认是否升级

Note right of device:如果等待超时或者用户取消升级
device--platform: 108指令上报升级状态：升级取消


Note right of device:如果用户确认升级
device--device: 9、确认升级后，下载固件 
device->platform: 10、108指令上报下载进度

device--device: 11、安装固件
device->platform: 12、108指令上报安装进度

device--device: 13、设备重启
device->platform: 14、重启后，101指令上报升级后固件版本

platform->app: 15、固件已升级到新版本，升级完成
app-->user: 16、升级结果

流程说明：

• 流程3～4：获取升级固件信息，为节省时间，也可以提前完成，设备有新固件时，102指令会返回新固件版本，提前通过103指令获取。
• 流程8：等待用户确认升级，用户需要在设备上确认升级或者取消，如果等待超过60s,则表示升级取消，取消原因是等待确认超时。
• 流程9-下载固件：如果设备存储空间足够，当获取了升级固件信息后，也可以提前下载固件，用户确认升级后可直接返回固件下载成功，节约用户升级等待时间。
  下载后的固件，如果没有升级成功，也可以继续保存。
• 流程11-安装固件：安装固件之前，需要检验下载固件的完整性以及正确性。

云打印的108指令要求如下：

请求示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "system",
    "time": 1555307375,
    "action": 108,
    "data": {
        "version":"1.1.0",
        "step": 0,
        "status": 0,
        "progress": 80,
        "error": ""
    }
}

指令参数描述如下：

step 说明如下：

1. 准备阶段：设备空闲可升级->获取升级固件信息->等待用户确认是否升级
2. 下载固件阶段：下载固件开始-下载固件完成-校验固件格式是否正确
3. 安装固件阶段：安装固件开始-安装固件完成
4. 完成阶段：安装固件需要重启后才能生效，重装固件后重启会丢失上下文，因此不需要上报此阶段的进度以及结果 ，当设备升级完成且重启后需要将当前固件版本上报给应用。上报指令：平台指令101、设备信息上报。

注意：

• 下载固件阶段，上报当前下载进度，如果之前已经下载完上报下载进度100%。设备存储空间足够时，建议提前下载固件。

各流程 返回参数说明如下:

1. 设备在接收到平台指令-206，返回step为0，status为0；
2. 设备查询平台指令-103获取到需要升级的版本信息后，设备准备固件升级就绪等待用户确认升级，返回step为0，status为1；
3. 设备如果固件准备就绪后等待用户确认超过60s,则等待用户确认超时自动取消,返回step为0，status为3,error详见异常情况说明;
4. 设备收到用户确认升级操作后，进入下载固件阶段，返回step为1，status为0，progress为当前进度；
5. 设备下载过程中，进度定时更新并返回step为1，status为1，progress为当前进度；
6. 设备下载完成后，校验固件成功开始安装后，返回step为2，status为0，progress为0；
7. 设备安装固件成功后，返回step为2，status为1，progress为100；
8. 设备升级过程中，任何阶段出现异常导致升级失败，返回step为当前阶段，status为2,error详见异常情况说明；
9. 设备升级过程中，用户操作取消升级，返回step为当前阶段，status为3；

异常情况说明 如下:

1. 如果收到固件升级指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务失败。
2. 如果收到固件升级指令设备故障无法执行任务时，设备故障描述，任务失败。
3. 如果固件准备就绪后等待用户确认超时时，等待用户确认超时，任务失败。
4. 如果固件下载失败时，固件下载失败，任务失败。
5. 如果设备存储空间不足导致固件保存失败时，设备存储空间不足，任务失败。
6. 如果固件下载后发现固件格式错误时，固件格式错误，任务失败。
7. 如果其他异常导致任务失败时，其他异常描述，任务失败。

异常错误码请详见错误码说明

云清洁

在用户使用过程中，会出现缺失某一种色彩、文字深浅不一、图片上有明显的线条等打印问题，云清洁功能可以一定程度解决这些问题，改善打印的画质。

云清洁流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、云清洁
app->device: 2、发送[执行云清洁]指令
device->device: 3、任务是否执行确认
device->app: 4、返回清洁中
device->device: 5、清洁打印

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回清洁暂停

Note left of device: 解决故障，恢复打印
device--app: 返回清洁中

Note left of device: 如果取消清洁
device--app: 返回清洁取消，任务结束

Note left of device: 如果清洁失败
device--app: 返回清洁失败，任务结束

device->app: 6、清洁成功
app->user: 7、返回清洁结果

流程说明：

• 任务是否执行确认：设备是否空闲、是否故障，请求参数是否正确。
• 清洁打印暂停：设备在打印过程中出现出现部分可恢复的故障导致打印暂停，具体故障由设备产品确定（可包含：缺纸、纸张放置不正确等）。
• 暂停后恢复打印：解决暂停故障后，设备可以恢复继续打印。
• 清洁打印失败：设备在处理清洁任务过程中，无法执行任务或者由于故障导致清洁失败，则返回清洁失败。
• 清洁打印取消：如果清洁过程中当用户取消清洁或者收到取消云清洁指令，则返回清洁取消，任务结束。

执行云清洁

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_cloud_clean",
        "payload": {
            "task_id": "123",
            "clean_mode": "normal"
        }
    }
}

其中cmd固定为server_push_cloud_clean表示执行云清洁请求，请求payload各参数描述如下。

响应示例：

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_cloud_clean", 
        "payload": {
            "task_id": "123",
            "clean_status": "cleaning",
            "error_code": "",
            "error_msg": "",
            "error_cause": ""

        }
    }
}

各参数说明如下：

清洁状态clean_status的具体说明如下：

1. 开始清洁时，返回clean_status为cleaning；
2. 设备在清洁打印过程中出现部分原因会导致打印暂停，返回clean_status为pause，暂停原因见异常情况说明；
3. 当清洁打印因故暂停，在解决故障恢复打印后，返回clean_status为cleaning；
4. 清洁打印失败终止时，返回clean_status为fail，失败原因见异常情况说明；
5. 当用户取消清洁或者收到取消云清洁指令后，返回clean_status为cancel；
6. 当清洁完成后，返回clean_status为finish；

异常情况说明 如下:

1. 如果收到云清洁指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务失败。
2. 如果收到云清洁指令设备故障无法执行任务时，设备故障描述，任务失败。
3. 如果收到云清洁指令请求参数不正确无法执行任务时，请求参数错误（通用业务异常），任务失败。
4. 如果设备清洁打印过程中设备故障，需要用户解决可恢复继续清洁打印时，设备故障描述，任务暂停。
5. 如果设备清洁打印过程中设备故障，不能恢复继续清洁打印时，设备故障描述，任务失败。
6. 如果其他异常导致任务失败时，其他异常描述，任务失败。

异常错误码请详见错误码说明

取消云清洁

当用户想取消设备云清洁时，可发送本指令，取消此次清洁操作。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_cloud_clean_cancel"
    }
}

其中cmd固定为server_push_cloud_clean_cancel表示取消云清洁指令，当设备处于云清洁打印中，取消清洁，并上报结果已取消，如果清洁已完成或者没有清洁任务则忽略。 无请求payload：

响应示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "cmd": "server_push_cloud_clean_cancel"
    }
}

无响应payload

打印校准

在用户使用过程中，必定会出现文字、图像重影，线条不直歪斜等打印问题，校准可以改善打印的画质。

功能流程图：

participant 用户 as user
participant 应用 as app
participant 设备 as device

user->app: 1、打印校准
app->device: 2、发送[校准打印]指令
device->device: 3、任务是否执行确认
device->app: 4、返回打印中
device->device: 5、打印完一页校准画像
device->app: 6、返回打印中（更新打印页数）

Note left of device: 如果设备出现故障打印被暂停
device--app: 返回校准打印暂停
Note left of device: 解决故障，恢复打印
device--app: 返回校准打印中

Note left of device: 如果取消打印
device--app: 返回校准打印取消，任务结束

Note left of device: 如果打印失败
device--app: 返回校准打印失败，任务结束

device->device: 7、打印完成
device->app: 8、返回校准打印完成

app->user: 9、提示用户打印完成，请根据结果完成设置
user-app: 10、设置校准参数
app->device: 11、发送[校准设置]指令
device->device: 12、校准参数设置
device->app: 13、校准设置结果
app->user: 14、校准设置结果

流程说明：

• 任务是否执行确认：设备是否空闲、是否故障，请求参数是否正确。
• 校准打印暂停：设备在打印过程中出现出现部分可恢复的故障导致打印暂停，具体故障由设备产品确定（可包含：缺纸、纸张放置不正确等）。
• 暂停后恢复打印：解决暂停故障后，设备可以恢复继续打印。
• 校准打印失败：设备在处理校准打印任务过程中，无法执行任务或者由于故障导致校准失败，则返回校准打印失败。
• 校准打印取消：如果清洁过程中当用户取消校准打印或者收到取消校准打印指令，则返回校准打印取消。

执行校准打印

应用可通过以下指令向设备设备发起打印校准操作，设备收到此指令后，进入打印校准流程。

请求示例：

{
    "mid": "123456",
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1584091074,
    "action": 301,
    "data": {
        "cmd": "server_push_alignment_print",
        "payload": {
            "task_id": "123"
        }
    }
}

其中cmd固定为server_push_alignment_print表示执行校准打印请求，payload各参数说明如下：

响应示例：

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_alignment_print", 
        "payload": {
            "task_id": "123",
            "print_status": "printing",
            "total_page_count":"2",
            "printed_page_count":"0",
            "error_code": "",
            "error_msg": "",
            "error_cause": ""
        }
    }
}

各参数说明如下：

校准打印状态print_status的具体说明如下：

1. 开始打印时，返回print_status为printing；
2. 设备在打印过程中出现部分原因会导致打印暂停，返回print_status为pause，暂停原因见异常情况说明；
3. 当校准打印因故暂停，在解决故障恢复打印后，返回print_status为printing；
4. 打印任务出现失败时，返回print_status为fail，error_code、error_msg见异常情况说明；
5. 当用户取消校准打印或者收到取消校准打印指令后，返回print_status为cancel；
6. 当打印完成后，返回print_status为finish；

异常情况说明 如下:

1. 如果收到校准打印指令设备正忙（执行其他任务）无法执行任务时，设备忙（通用业务异常），任务失败。
2. 如果收到校准打印指令设备故障无法执行任务时，设备故障描述，任务失败。
3. 如果收到校准打印指令请求参数不正确无法执行任务时，校准打印业务不支持（通用业务异常），任务失败。
4. 如果设备校准打印过程中设备故障，需要用户解决可恢复继续打印时，设备故障描述，任务暂停。
5. 如果设备校准打印过程中设备故障，不能恢复继续打印时，设备故障描述，任务失败。
6. 如果其他异常导致任务失败时，其他异常描述，任务失败。

异常错误码请详见错误码说明

取消校准打印

当用户想取消校准打印时，可发送本指令，取消此次校准打印操作。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_alignment_print_cancel"
    }
}

其中cmd固定为server_push_alignment_print_cancel表示取消校准打印指令，当设备处于校准打印中，取消打印，并上报结果已取消，如果校准打印已完成或者没有执行则忽略。 无请求payload：

响应示例：

{
    "mid": "123456",
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1584103546,
    "action": 300,
    "data": {
        "cmd": "server_push_alignment_print_cancel"
    }
}

无响应payload

校准设置

当用户打印完校准页，用户可根据参数进行设定。

请求示例：

{
    "mid": "123456", 
    "from": "511542236802977792",
    "to": "M2500ADNW_12345678",
    "time": 1502867086, 
    "action": 301, 
    "data": {
        "cmd": "server_push_alignment_set",
        "payload": {
            "task_id": "123",
            "set_properties":[{
                "key": "key1",
                "value": "value1"
            }] 
        }
    }
}

其中cmd固定为server_push_alignment_set表示校准设置指令，用户可以通过打印结果对比设置参考对设备进行设置。设置成功后，设备根据设置参数，对设备进行校准。 payload各参数说明如下：

响应示例：

{
    "mid": "123456", 
    "from": "M2500ADNW_12345678",
    "to": "511542236802977792",
    "time": 1502867086, 
    "action": 300, 
    "data": {
        "cmd": "server_push_alignment_set", 
        "payload": {
            "task_id": "123",
            "set_status": "success",
            "error_code": "",
            "error_msg": "",
            "error_cause": ""
        }
    }
}

payload各参数说明如下：

注意：

• 设备可能由于版本原因，部分属性设置不支持，所有不支持的属性通过fail_properties返回

错误码说明

本章节主要定义导致设备功能不可用以及业务执行暂停或者异常结束的错误码定义，错误码主要包含设备故障错误码以及业务异常错误码。

设备故障错误码

设备故障错误码是指设备硬件本身发生故障，会导致部分功能不可使用的故障错误信息,由于不同设备厂商，不同设备型号的故障类型有很多不同，设备故障错误码有厂商自行定义。

例如：进纸托盘处无纸、纸张放置不正确、墨盒仓门已打开、进纸托盘处发生卡纸等。

如果设备发生故障时:

1. 需要上报设备故障状态以及设备故障错误码给应用，上报指令：设备信息上报。
2. 如果此时设备正在执行业务任务且导致任务暂停或者任务异常结束，还需要上报任务执行状态以及错误信息给应用 (请参考业务异常错误码)。

设备故障码要求：

• 设备故障错误码为4～5位的整数，便于区分业务异常和设备故障。
• 设备故障错误描述将直接提示给用户，请产品做好文字描述。

业务异常错误码

业务异常错误码主要是指设备执行业务任务过程中，出现导致任务暂停或者异常结束的业务异常错误信息（非设备硬件本身的故障）。

例如：设备忙（执行A任务不能执行B任务）、请求参数异常（业务请求参数不合法或者不支持）等。

如果设备执行业务任务过程中出现业务异常导致任务暂停或者任务异常结束，需要上报任务执行状态以及业务错误码信息,上报指令根据业务类型选择，例如：云打印-打印任务进度上报、云扫描-执行云打印扫描 等。

异常定义：

• 错误码（error_code）是指：错误的唯一标识，方便后期统计、查询、解决错误。
• 错误描述（error_msg）是指：业务处理过程中出现了异常，提示给用户当前发生了什么。给用户的提示，提示需要产品定义
• 错误原因（error_cause）是指：错误发生的具体原因，方便研发定位解决问题。