云打印机对接说明

7 数据采集接口说明

7.1 基本描述

商米数字店铺开放平台与SaaS合作方的数据交互可以是双向实时。一方面SaaS合作方可以将数据通过openAPI传入数字店铺,也可以对商米的IoT设备进行远程控制。

除此之外,商米数字店铺开放平台也可以通过消息推送中心,将系统中的消息实时反馈给SaaS合作方。根据合作平台需求订阅实时消息推送,商米数字店铺开放平台会将消息和事件推送给SaaS合作方。

7.2 接口规范

7.2.1 协议说明

对接的接口目前只开放HTTPS方式推送消息,所有的消息一律采用POST方式。

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考2.2 签名规则

7.2.2 签名规则

参考《鉴权认证》文档。

7.2.3 公共参数

参数名必填类型说明
app_idstring唯一标识接入身份,联系商米数字店铺提供
randomstring随机字符串,由数字和字母组成,长度范围为6-10位
timestampint当前的unix timestamp,精度到秒级,10位数字
signstring签名信息,详见2.2

7.3 店铺设计规范

参考《商户店铺》文档。

7.4 SaaS合作方提供HTTP回调地址

SaaS合作方添加监听事件时,需要提供相应的HTTP回调地址,并提供需要监听的设备以及事件。当商米数字开放平台收到该设备的该事件时,会调用该HTTP接口。

7.4.1 回调HTTP鉴权方式

对于该回调HTTP回调的鉴权方式,遵照商米数字店铺开放平台的鉴权方式。 请参考《鉴权认证》文档。

7.4.2 回调HTTP接口参数

回调HTTP需要带以下接口参数:

参数名称是否必须类型说明
sunmi_shop_nostring 商米数字店铺平台门店唯一编号
shop_idstring 店铺在SaaS软件体系下的唯一标识
eventint触发消息的类型
payloadstring消息的具体格式(根据消息不同会有不同的json)

消息的具体格式请参考相关业务的《事件及消息示例》文档。

7.4.3 消息重传

如果回调消息发送失败,会触发重传机制。一共会触发4次重传,时间间隔分别为15秒, 30 秒, 1分钟和2分钟。

7.5 消息监听接口

7.5.1 接口描述

消息监听接口用来管理需要监听的事件和相应的回调HTTP地址。

7.5.2 接口列表

接口名称接口描述
/hook/add增加消息监听的HTTP回调地址
/hook/delete取消消息监听的HTTP回调地址

7.5.3 接口详情

7.5.3.1 增加消息监听

接口描述:通过本接口调用,用户可以增加消息监听的HTTP回调地址。

请求链接:/hook/add

接口版本: v2.0

接口参数

参数名称是否必须类型说明
sunmi_shop_no string 商米数字店铺平台门店唯一编号(v2.0之后为必填项)
shop_idstring店铺在SaaS软件体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
http_callbackstringHTTPS回调地址链接
event_listarray[int]需要监听的事件的列表

返回值: 

{
    "code": 0,   /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {}
}

7.5.3.2 取消消息监听

接口描述:通过本接口调用,用户可以取消消息监听的HTTP回调地址。

请求链接:/hook/delete

接口版本: v2.0

接口参数

参数名称是否必须类型说明
sunmi_shop_no string商米数字店铺平台门店唯一编号(v2.0之后为必填项)
shop_idstring店铺在SaaS软件体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可)
event_listarray[int]需要取消监听的事件的列表

返回值: 

{
    "code": 0,   /* 其他错误参考错误列表 */
    "msg": "succeed",
    "data": {}
}

7.6 CP事件及消息示例

7.6.1 事件列表

event取值说明
6001未经处理的文字小票上传消息
6002未经处理的图片小票上传消息
6003经过处理的小票消息

7.6.2 事件消息示例

7.6.2.1 未经处理的文字小票上传消息(event=6001)

{
  "id": 123,     // 系统生成的小票ID
  "sn": "sn",    // 打印设备SN
  "text": "abc"  // 文字小票内容
}

7.6.2.2 未经处理的图片小票上传消息 (event=6002)

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn", // 打印设备SN
  "base64_image": "avc"  // 图片小票的base64 encoded string
}

7.6.2.3 经过处理的小票消息 (event=6003)

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn",  // 打印设备SN
  "order_id": "a123456", // 小票上的订单ID (原tradeNo字段)
  "order_time": "2020-01-01", // 小票生成时间 (原tradeTime字段)
  "order_received_amount": 10.11  // 小票金额 (原tradePayAmount字段)
  "sales_detail_list": [{   //明细列表
    "amount": 10,          // 商品单价
    "item":   "商品",      // 商品名字
    "quantity": 1          // 商品数量
  },
  ...
  ]
}

Cloud Printer Product R&D Instruction

5.Develop API for communication (method 2: Cloud to Cloud)

Important declare:

Through cloud to cloud method, the data on partner cloud will be pushed to SUNMI cloud, and then pushed to the printer by SUNMI cloud. SUNMI will adopt a secure method to protect the data privacy of partners. If you want to better protect your data privacy, method 1 (device to cloud) is recommended, because data will be obtained from partner cloud directly.

Parameter specification:

  1. Each request contains common parameters and private parameters. Please refer to the following corresponding specification for details.
  2. Parameters will be passed in a form of key-value, and “application/x-www-form-urlencoded” will be added on the request header.
  3. Only private parameters and return results are listed for the following interfaces. For other information, please see the specification on common request parameters.
  4. The returned results are all json format data.

Specification on common request parameters (the parameters must be passed in all requests):

Request parameterTypeSpecification
signstringSignature. Refer to the content below for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI. It can be obtained when subscribing for SUNMI cloud printer channel service
msnstringDevice SN
timestampstringUnix timestamp (second)

Specification on common return parameters:

Return parameterTypeSpecification
codeintReturn code. Please see common error code list
dataindefinitePlease refer to private return parameter data for data type and content. If there is an error, null will be returned
msgstringInformation which indicates the result. If there is an error, an error description will be returned

Specification on generating a common request parameter:

Signature algorithm: MD5

Example on how a signature is generated (It supposes that the required parameters are as below):
app_id:sm5b9b4daef3463 
msn:NT1234DF23456 
timestamp:1589277365 
shop_id:1

Step 1: place the parameters per their orders in ASCII in a form of “key=value”: stringA=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365″

Step2: supposing the app_key, the key part “dd3ac24736589ae17d333e362859bf4c” to join a character string, is: stringB=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365dd3ac24736589ae17d333e362859bf4c”

Step 3: encrypt stringB with MD5 to generate the final signature sign (sign=MD5(stringB), that is sign=”946720303FEFF4516626A4431D2753CA”

Among the steps above, the private parameters app_id and app_Key will be provided by SUNMI. Note: a sign must be a 32-character string in upper case which is encrypted by MD5

Specification on common error codes:

Error codeSpecification
10000The interface is called successfully
20000Unavailable service
20001Failed to authorize
40001Required parameter is missing
40002Invalid parameter

The table above is a specification on global common error codes, and follow-up information will be added to the table. In addition to the common error codes, please refer to specific business error codes in content related to specific business interfaces.

URL address of the interface for pushing:

Request URL address: https://openapi.sunmi.com/

1)Interface for binding a printer

Interface name:

  • /v1/printer/printerAdd

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Shop_id is the only condition for grouping devices under the merchant account and is used when querying the status list of devices in the store. Please pass “” if this function is not needed, and null will be returned for the store device status list result set.

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60004Bind failed
60007Binding exception
60008The device has been bound already. Please check whether you have bound the device in SUNMI Assistant, if so, please unbind the device in SUNMI Assistant before binding it to this channel
60012 shop_id to long. MAX 32 character.

2)Interface for unbinding a printer

Interface name:

  • /v1/printer/printerUnBind

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterValueSpecification
shop_idstringThe partner’s shop ID

shop_id must be passed, otherwise the printer cannot be unbound from the shop

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60005Unbind failed

3)Query the status of devices which has been bound to the shop

Interface name:

  • /v1/machine/queryBindMachine

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Example on return result (success)

{
    "code": "10000",
    "data": [
        {
            "is_online": "1",//1 device online, 0 device offline
            "msn": "N302D94D40068"//Device SN
        }
    ],
    "msg": ""
}

Specification on return parameter (success):

ParameterTypeSpecification
dataObjectmsn: device SN; is online: whether the device is online. 1 – online; 2 – offline

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60006Invalid shop ID

4)Push voice messages

Interface name:

  • /v1/printer/pushVoice

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
call_contentstringThe character string which is need to voice playback. You can only choose one between call_content with call_url. Please pass “” if there is no data
call_urlstringThe address of the voice file to be downloaded and played by the device. You can only choose one between call_content with call_url. Please pass “” if there is no data. The available formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
expTimestampintUnix timestamp which indicates when the voice message will expire. Default to 300 seconds delay of current time
cycleintVoice playback times: 0 – do not remind again; 1 – play once; 3 – play 3 times; 999 – loop
delayintThe time interval (second) between voice messages, and the default is 2s

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

5)Push order details

Interface name:

  • /v1/printer/pushContent

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
pushIdstringPush unique ID. Different ID of each print order means different print content
voiceCntintVoice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
voicestringThe character string which is need to voice playback. You can only choose one between call_content with call_url. Please pass “” if there is no data
voiceUrlstringThe address of the voice file to be downloaded and played by the device. You can only choose one between call_content with call_url. Please pass “” if there is no data. The available formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
orderCntintThe number of orders to be printed (1 by default)
orderTypeintThe type of order printed: 1. New order; 2. Cancelled order; 3. Order reminder; 4. Refund; 5. Others
orderDatastringThe order content to be printed. UTF8 encoding is adopted for all text contents. ESC/POS command set can be directly used in the contents to control printing, also for layout and format

Example on content conversion:

//PHP code example:  

$str = chr(27).chr(33).chr(48)."Supermarket".chr(27).chr(33).chr(0).chr(0x0A);  //chr(27).chr(33).chr(48)are font effect (double height and width) in ESC/POS command;chr(27).chr(33).chr(0)are the standard font size in ESC/POS command; 0A is carriage return
$str = $str."Table:01       Employee ID:01".chr(0x0A);
$str = $str."Time:12:45:28".chr(0x0A);
$str = $str."Order No:00554789713585".chr(0x0A);
$str = $str."Item     Price*Num       Amount".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."Item1  7.00*1      7.00".chr(0x0A);
$str = $str."Item2        8.00*1      8.00".chr(0x0A);
$str = $str."Item3        2.50*1      2.50".chr(0x0A);
$str = $str."Item4     10.00*1     10.00".chr(0x0A);
$str = $str."Item5     10.00*1     10.00".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."Total items:5          Total RMB: 27.00".chr(0x0A);
$str = $str.chr(0x0A);
$str = $str.chr(27).chr(33).chr(16)."      Wish you a good day".chr(27).chr(33).chr(0).chr(0x0A);//The font shown is in double height and width; 0A is carriage return

$orderData = bin2hex(strToUtf8($str));  //$orderData is:1b2130e58d97e59bbde8b685e5b8821b21000ae58fb0e58fb73a303120202020202020e5b7a5e58fb73a30310ae697b6e997b43a31323a34353a32380ae58d95e58fb73a30303535343738393731333538350ae59586e59381e5908de7a7b020202020202020202020202020e58d95e4bbb72ae695b0e9878f202020202020e98791e9a29d0a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae799bee4ba8be588a9e7b2bee8a385e7b396e69e9c2020202020202020372e30302a312020202020202020372e30300ae697bae697bae99baae9a5bc2020202020202020202020202020382e30302a312020202020202020382e30300ae58fafe58fa3e58fafe4b9902020202020202020202020202020322e35302a312020202020202020322e35300ae5969ce4b98be69c97e69e9ce586bb202020202020202020202031302e30302a312020202020202031302e30300ae5b7a7e5858be58a9be9a5bce5b9b2202020202020202020202031302e30302a312020202020202031302e30300a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae680bbe4bbb6e695b02020342e303020202020202020202020e680bbe8aea1524d4220202020202032372e30300a0a1b2110202020202020e8b0a2e8b0a2e683a0e9a1bee6aca2e8bf8ee4b88be6aca1e58589e4b8b41b21000a

//The method can judge whether the character string content is UTF8 encoding. if so, it will be returned directly. Otherwise the character string will be turned into UTF8 encoding
function strToUtf8($str){
    $encode = mb_detect_encoding($str, array("ASCII",'UTF-8',"GB2312","GBK",'BIG5'));
    if($encode == 'UTF-8'){
        return $str;
    }else{
        return mb_convert_encoding($str, 'UTF-8', $encode);
    }
}

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example of return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60009The unique ID which is pushed cannot be empty
60010The unique ID already exists
60011Failed to push

6)Clear the print queue

Interface name:

  • /v1/printer/clearPrintList

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
N/A

Example on return result (success):

{
    "code": "10000",
    "data":{
       "count":2
    },
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
dataObjectThe order count which has been clear will be returned. If no order need to be cleared, null will be returned

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

7)Query the status of printing order

Interface name:

  • /v1/printer/getPrintStatus

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
pushIdstringThe order ID which is need to be queried.To avoid server pressure, do not call this interface frequently.The recommended interval for querying the same ID is more than 1 minute.

Example on return result (success):

//Order printing completed
{
    "code": "10000",
    "data": {
        "msn"    : "NT210XXXXXXXX", 
        "isPrint": "1", //1-printing completed, 0-printing not completed,-1-printing abnormal
        "unixTime": "1577425708" //the Time of printing completed
    },
    "msg" : ""
}
//Order printing not completed
{
    "code": "10000",
    "data": {
        "status": "0", //1-printing completed,0-printing not completed,-1-printing abnormal
        "unixTime":  null //the Unix Time of printing completed
    },
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
dataObjectIf no order which can to be queried, null will be returned.Return print information if query successful:
“status”1-printing completed,0-printing not completed,-1-printing abnormal.
“unixTime”The Unix time will be returned if print successful”、Null will returned if print not successful

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

Cloud Printer Product R&D Instruction

6.Printer common ESC/POS command set

  • LF Print and line feed
ContentSpecification
[Format]ASCII:LF
Hex:0A
Decimal:10
[Description]· Print the data in the buffer and line feed under the standard mode
[Note]· This command places the current position at the beginning in the line
  • ESC ! n select print mode
ContentSpecification
[Format]ASCII:ESC ! n
Hex:1B 21 n
Decimal:27 33 n
[Range]0≤n≤255
[Description]Set the print mode of characters according to the value of n
n=0font in standard size
n=16font in double height
n=32font in double width
n=48font in double height and double width
[注释]· All characters are bottom aligned
· Valid for both English letters, numbers and Chinese characters
[默认值]n=0
  • ESC a n select alignment
ContentSpecification
[Format]ASCII:ESC a n
Hex:1B 61 n
Decimal:27 97 n
[Range]0≤n≤2 or 48≤n≤50
[Description]A line of data is aligned per the value of n:
0,48 Left alignment
1,49 Center
2,50 Right alignment
[Note]· In standard mode, this command is only effective at the beginning in a line
· This command sets the alignment rule at the print area
[Default]n=0
  • ESC p m t1 t2 open a cash drawer with drive pulse
ContentSpecification
[Format]ASCII:ESC p m t1 t2
Hex:1B 70 m t1 t2
Decimal:27 112 m t1 t2
[Rane]m = 0, 1, 48, 49
0 ≤ t1 ≤ 255
0 ≤ t2 ≤ 255
[Description]· m=0, 48 Cash box socket pin 2;m=1, 49 Cash box socket pin 5
· t1 specifies the drive pulse start time[ t1 × 2 ms].
· t2 specifies the drive pulse end time[ t2 × 2 ms].
[注释]· t1 must be smaller than t2 to make the end time larger than the start time < td="" style="box-sizing: border-box;">
  • GS V m Cutting paper
ContentSpecification
[Format]ASCII:GS V m
Hex:1D 56 m
Decimal:29 86 m
[Range]m=1, 49
[Description]· Select a mode to cut paper
[Note]· The modes to cut paper vary per the paper cutter types
· This command is only effective when it is processed at the beginning in a line
· The paper won’t be cut out completely
  • GS H n select where to print barcode characters
ContentSpecification
[Format]ASCII:GS H n
Hex:1D 48 n
Decimal:29 72 n
[Range]0≤n≤3 or 48≤n≤51
[Description]Select where to print barcode characters when printing a barcode
n specifies the position to print barcode characters:
0,48 do not print
1,49 above the barcode
2,50 below the barcode
3,51 above and below the barcode
[Default]n = 0
  • GS h n select the height of a barcode
ContentSpecification
[Format]ASCII:GS h n
Hex:1D 68 n
Decimal:29 104 n
[Range]1≤n≤255
[Description]· Set the vertical height of a barcode per n (the number of dots vertically placed. 0.125mm/dot)
[Default]n= 162
  • GS w n set the width of a barcode
ContentSpecification
[Format]ASCII:GS w n
Hex:1D 77 n
Decimal:29 119 n
[Range]1≤n≤6
[Description]· Set the horizontal width of a barcode
[Default]n=3
  • GS k m n d1…dn print barcode
ContentSpecification
[Format]ASCII:GS k m n d1…dk
Hex:1D 6B m n d1…dk
Decima:29 107 m n d1…dk
[Range]65≤ m ≤89(the length of d1…dn depends on the barcode system used)
[Description]· Select a barcode system and print
[Note]· n indicates the number of barcode data, and printer processes the n-byte data following as barcode data
· If n exceeds the specified range, the printer will stop processing this command and process the following data as normal data
· The command will be invalid if the barcode data d exceeds the specified range
· If the width of the barcode exceeds the width of a print area, it will be invalid
· No matter how high the line is set by the ESC2 or ESC3 command, the paper distance is the same as the bar code height
· This command is only effective when there is no data in the buffer, otherwise the command will be neglected
· After printing the barcode, set the print position at the beginning in a line

The selected barcode systems for m are:

mBarcode systemData lengthNumber of charactersCharacterRange
65UPC-AFixed11≤n≤120~948≤d≤57
66UPC-EFixed6≤n≤70~948≤d≤57
67JAN13(EAN13)Fixed12≤n≤130~948≤d≤57
68JAN8(EAN8)Fixed7≤n≤80~948≤d≤57
69CODE39Variable1≤n≤640~9, A~Z, SP, $,
%, *, +, -, ., /
48≤d≤57, 65≤d≤90, 32,
36, 37, 43, 45, 46, 47
70Code 2 of 5 InterleavedVariable2≤n≤64
(even number)
0~948≤d≤57
71CODABARVariable1≤n0~9, A~D, a~d,
$, +, -, ., /, :
48≤d≤57, 65≤d≤68, 97≤d≤100,
36, 43, 45, 46, 47, 58,
65≤d1≤68, 97≤d1≤100,
65≤dk≤68, 97≤dk≤100
72CODE93Variable1≤n≤64
73CODE128Variable2≤n≤64
81Code 2 of 5 MatrixVariable1≤n≤640~948≤d≤57
82Code 2 of 5 IndustrialVariable1≤n≤640~948≤d≤57
83Code 2 of 5 IATAVariable1≤n≤640~948≤d≤57
84Code 2 of 5 DatalogicVariable1≤n≤640~948≤d≤57
85CODE11Variable1≤n≤640~9, –48≤d≤57,45
86CODE39 xtendedVariable1≤n≤64
87GS1 DataBarFixedn=130~948≤d≤57
88GS1 DataBar ExpandedVariable
89MSI PlesseyVariable1≤n≤640~948≤d≤57
  • GS v 0 m xL xH yL yH d1….dk Print raster bit image
ContentSpecification
[Format]ASCII:GS v 0 m xL xH yL yH d1…dk
Hex:1D 76 30 m xL xH yL yH d1…dk
Decimal:29 118 48 m xL xH yL yH d1…dk
[Range]0 ≤ m ≤ 3, 48 ≤ m ≤ 51
0 ≤ xL ≤ 255
0 ≤ xH ≤ 255 ; The 1≤(xL+xH×256)≤128
0 ≤ yL ≤ 255
0 ≤ yH ≤ 8 ; The 1≤(xL+xH×256)≤4095
0 ≤ d ≤ 255
k = (xL+xH×256) × (yL+yH×256);(k≠0)
[Description]• m,Selects Raster bit-image mode
• xL, xH,select the number of data bits (xL+xH´256) in the horizontal direction for the bit image
• yL, yH,select the number of data bits (yL+yH´256) in the vertical direction for the bit image.
[Note]• In standard mode, this command is effective only when there is no data in the print buffer. 
• This command has no effect in all print modes (character size, emphasized, double-strike, upside-down, underline, white/black reverse printing, etc.) for raster bit image. 
• Data outside the printing area is read in and discarded on a dot-by-dot basis. 
• The ESC a (Select justification) setting is also effective on raster bit images.
• When this command is received during macro definition, the printer ends macro definition, and begins performing this command. The definition of this command should be cleared.

The value of m selects the mode, as follows:

mModeVertical Dot Density (DPI)Horizontal Dot Density (DPI)
0, 48Normal203.2dpi203.2dpi
1, 49Double-width203.2dpi101.6dpi
2, 50Double-height101.6dpi203.2dpi
3, 51Quadruple101.6dpi101.6dpi

Print raster bit image demo:

• Assume that there is an bit image with 32 pixels width and 32 pixels height to be printed in quadruple, then the printed image is 64×64.
We have m=3, xL=4, xH=0, yL=32, yH=0. Please refer to picture for the arrangement of dk.

• The instruction data should be:
GS v 0 3D 4D 0D 32D 0D FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH FFH 00H FFH 00H 00H FFH 00H FFH LF LF LF LF
• Coverted into hexadecimal:
1D76300304002000FF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FFFF00FF0000FF00FF0A0A0A0A

Cloud Printer Product R&D Instruction

7.Other FAQs to know

a) How the design logic ensures that the printer can receive orders?

A: SUNMI cloud printer has the following process to ensure:

  1. Printers access to SUNMI cloud MQTT server, which adopts a cluster architecture and is maintained by SUNMI QA team. Years of experience in accessing millions SUNMI business devices, ensuring the triggering and pushing of order messages.
  2. After receiving orders, the printer will initiate HTTP order list request and the orders will be limited within 5 to avoid missing any order during peak time.
  3. After receiving the order list, the printer will request order content per the sequence on the list one by one. The next order will be printed only after the last one has been printed.
  4. After printing, the printer will report the printing result to the server timely. Orders not reported as printed can be requested and printed again.
  5. If the printer is out of paper during printing, the order will be printed thoroughly again after paper loading to avoid any miss in content.
  6. If there is an outage during printing, the printer will automatically get unprinted order from the server to print after power on.
  7. If there is a network disconnection during printing, only orders which are thoroughly obtained by the printer can be printed.
  8. If the order printed is not complete due to problems including paper jam during printing, you can press the button on the printer to reprint the last order conveniently.
  9. If the printer cannot obtain new orders after repeated requests due to a network connection problem, the first order will also be obtained and printed when the printer receives the second new order list.
  10. The printer can automatically connect to/switch to a higher speed network, which only will take about 20s.
  11. The cloud indicator light can indicate whether the server is connected and whether the network of the printer is disconnected.
  12. Users can test the network by pressing a button on the printer and get a test report to check the network connection if necessary.
  13. If the network cannot be fixed for the time being, users can receive orders through phones and send orders to the printer via Bluetooth to complete order printing.

b) Will the order be lost if the printer is out of paper during printing?

A: Please reload a till roll if the printer is out of paper during printing, and the unfinished order will be printed again automatically and completely.

c) How to deal with incomplete order printing due to paper jam during printing?

A: You can double click thebutton on the printer to reprint the last order.

d) How to configure WIFI for the printer?

A: Network can be configured via Bluetooth for SUNMI cloud printers, which avoid problems caused by the cross-network configuration due to the different WIFI routers the user’s phone and the printer connected to. SUNMI provides developers with 3 SDKs for network configuration (one for Android, one for IOS and one for WeChat mini program). Developers can call Bluetooth for communication conveniently with the 3 SDKs without any complicated development on reconnection mechanism caused by communication errors.

e) How to deal with the lost order caused by the no good WiFi network in the shop?

A: A network state can be affected by lots of factors; thus, no ultimate solution can be adopted to solve the problem. As a result, a WIFI+GPRS version printer is recommended for it can switch to a stronger network automatically. Normally the printer connects to WIFI for communication, but it will switch to GPRS if the WIFI currently used is unstable and switch back when the WIFI is back to the normal state. Orders can be received normally through this mechanism. Receiving orders via GPRS is slower than via WIFI for the speed is limited, but as a backup, GPRS also ensures no miss in order receiving.

f) How to print an order that can be received on the phone but abnormal network on the printer?

A: SUNMI cloud printer conducts transaction printing in cloud, USB and Bluetooth mode. You can also print the data you received from a POS device or a phone through USB or BT. Therefore, you can send the order you received on your phone to the printer via Bluetooth to print.

g) How can I troubleshoot a network error?

A: A network state can be affected by lots of factors; thus, no ultimate solution can be adopted to solve the problem. You can double click thebutton to test your network and get a test report, and you can analyze the FAIL item on the report to locate the problem and feed it back to tech support to solve your problem.

ItemSpecificationSolution
Current NetworkThe currently used network (WIFI or GPRS) for communication.Please ignore this error if you have not configured WIFI. If the printer consistently uses GPRS, there might be something wrong with WIFI. Please check whether you have correctly configured WIFI or whether the router is working normally.
Link=>SSID:The SSID of the WIFI router currently connected to and the connection. PASS – connected. FAIL – disconnected.No SSID indicates that WIFI has not been configured for the printer. Please configure WIFI in this case. Please check whether the WIFI router with this SSID is working normally, or reconfigure WIFI for the printer.
Link=>GPRSThe current connection state to GPRS. PASS – connected. FAIL – disconnected.It might be caused by a weak GPRS signal. Please move your printer away from metals or walls and try again. Additionally, connecting to a GPRS takes a comparatively long time, and it might fail for the printer has not connected to an AP after booting. Please wait few minutes and try again in this case.
Check=>DHCP ConflictCheck whether there are more than one DHCP in the network (more than one DHCP or no DHCP will lead to network connection error). PASS – one DHCP. Warn – more than one DHCP. FAIL – no DHCP.Only when the Link item is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the item Link=>SSID has not become FAIL, please make sure it is PASS.
Warn indicates that there is a DHCP conflict caused by private WIFI routers. Please check if there are more than one router have turned on DHCP mode, if so, please keep only one of them which can connect to internet and turn off other DHCPs.
FAIL indicates there is no server which has configured DHCP and the printer cannot get the IP address. Please check whether the DHCP server in the network is working normally.
Check=>IP ConflictCheck whether there is more than one IP with the same IP address in the network for it will lead to network communication error. PASS – there is no IP with the same IP address. FAIL – there is more than one IP with the same IP address.Only when the Link item is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the item Link=>SSID has not become FAIL, please make sure it is PASS first.
An IP address conflict occurs if there are more than one DHCP or you have manually set IP address for your device. Please turn off needless DHCPs or find the device with the problem IP and change the IP address into the address distributed by DHCP.
Ping=>GWCheck the link between the device and gateway to decide whether the intranet connection is normal. The return value, which is a delay value, can be used to tell whether the network speed reaches the standard. FAIL – the gateway is blocked.Only when the Check item is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the item Check=>DHCP Conflict is FAIL, please make sure it is PASS first.
If the Ping value is too high or this item is FAIL, please check the WIFI router is working normally or check the AP signal.
Ping=>DNSCheck the link between the device and public network root DNS to decide whether a connection to extranet has been established. The return value, which is a delay value can be used to tell whether the network speed reaches the standard. FAIL – the gateway is blocked.Only when the Ping=>GW item is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the Link=>GPRS, Ping=>GW are FAIL, please make sure they are PASS first.
DNS root server is the major node in the internet. We can tell whether the device has been connected to the internet according to the value of Ping. Please check whether the WIFI router is working normally or the AP signal is too weak if the value of Ping is too high or this item is FAIL.
Ping=>MQTT ServerCheck the link between MQTT server and the device to decide whether it has been connected to a business server. The return value, which is a delay value can be used to tell whether the network speed reaches the standard.Only when the Ping=>GW, Ping=>DNS are PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the Link=>GPRS, Ping=>GW are FAIL, please make sure they are PASS first.
MQTT is a server to push orders, and the value of Ping can be used to decide whether the link of this server is normal. Please consult the customer service of the manufacturer for troubleshooting if the value of Ping is too high or this item is FAIL.
Ping=>HTTP ServerCheck the link between the device and HTTP server to decide whether it has been connected to a business server. The return value, which is a delay value can be used to tell whether the network speed reaches the standard. FAIL – the gateway is blocked.Only when the Ping=>GW, Ping=>DNS are PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the Link=>GPRS, Ping=>GW are FAIL, please make sure they are PASS first.
HTTP is a server for order content, and the value of Ping can be used to decide whether the link of this server is normal. Please consult the customer service of the manufacturer for troubleshooting if the value of Ping is too high or this item is FAIL.
MQTT=>Check ConfigThe printer mainly communicates via MQTT, so it automatically checks whether the server information is correct and whether order message from cloud can be received. PASS – correct information. FAIL – wrong information.Only when the item Ping=>HTTP is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the Ping=>HTTPServer is FAIL, please make sure it is PASS first.
If the information accesses to MQTT server goes wrong, please consult the customer service of the manufacturer for troubleshooting.
MQTT=>ConnectThe printer mainly communicates via MQTT. It checks whether MQTT is connected and whether order message from cloud can be received. PASS – connected. FAIL – disconnected.Only when the item MQTT=>MQTT config is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the MQTT=>Check Config is FAIL, please make sure it is PASS first.
If there is something go wrong in accessing to MQTT, please consult the customer service of the manufacturer for troubleshooting.
MQTT=>R&WThe printer mainly communicates via MQTT. It checks whether the communication data of MQTT is normal and whether order message from cloud can be received. PASS – normal communication. FAIL – disconnected communication.Only when the item MQTT=>MQTT Link is PASS, FAIL in this item can be used for troubleshooting, otherwise please ignore the following analysis. If the MQTT=>MQTT Link is FAIL, please make sure it is PASS first.
If the information accessing to MQTT server goes wrong, please consult the customer service of the manufacturer for troubleshooting.

h) How to get the self-test page of the printer?

A: if need complete printer hardware information, please press the buttonand then the buttonand release them simultaneously to print the self-test page.

i) What caused the gibberish printed on the receipt?

A: SUNMI cloud printer can print characters of global font library and adopts UTF8 encoding, so all characters transmitted must be transferred into UTF8 to be printed. Adopting UTF8 encoding realizes printing multiple languages on one receipt to meet the needs of some merchants.

j) Can I change the content of voice message?

A: SUNMI cloud printer adopts TTS voice synthesis technology, which can transfer your text into voice message for broadcast regardless what the content is. Thus, you can customize your voice message according your needs on dishes, contact numbers, notes, etc. However, please avoid using polyphonic characters if you want to make sure it can broadcast the voice message with your desired pronunciation.

k) How to change WIFI setting?

A: After WIFI pairing, please reconfigure network if you want to change WIFI node. There is no need to deauthorize and rebind.

l) Can the printers receive orders simultaneously from a takeaway delivery platform?

A: the rule on how many devices can receive orders from a platform is determined by the platform instead of the printer. Ele.me allows more than one printer to access to the same account and receive orders simultaneously, but Meituan allows only one printer to access to one account. If the authorization has been bound to other platforms, the original one will be deauthorized forcedly.

m) Does GPRS version come with SIM card? If so, how much traffic can I use per month?

A: The SUNMI cloud printer is equipped with an inbuilt eSIM and does not need to use an extra SIM card. It can connect to 2G network without any traffic limit.

n) I have bound the device via SUNMI Assistant APP, can I unbind it?

A: Yes. Please click the small dots on the up right corner in SUNMI Assistant APP to find the option “delete device”. After deleting the device, you can rebind the device with another phone. A bound device cannot be rebound to another account.

o) What should I do if it prompts “failed to connect to the Bluetooth of the device” when binding the printer?

A: When binding a cloud printer, communication is conducted via Bluetooth. The prompt usually because the App (Android version) does not have the permission to access the location. Please go to Setting – App – SUNMI Assistant – Permission – Location to turn on the permission.

p) What are the functions of indicator lights?

A: A cloud printer has three indicator lights. The green one indicates the power, which will be on when the printer is plugged to a power supply; the blue one indicates the network, which will be on when the printer has been connected to a server, and it will be off if the network is disconnected; the red one indicates errors including out of paper, overheat and other problems, and it will be off when all problems have been solved.

Cloud Printer Product R&D Instruction

4.Develop API for communication (method 1: Device to Cloud)

Important declare:

For better protection of partners’ data privacy, also SUNMI cloud printer can realize the complete order printing functions. It is need what our partners work hard together with SUNMI to achieve. The document as below define the interfaces (which are divided into two parts) to realize the communication of cloud printers. One API which is provided by SUNMI is order to bind devices and push messages. Another API which is provided by partners is open to the printer for completing printing function.

Parameter specification:

  1. Each request contains common parameters and private parameters. For details, please see corresponding specifications below.
  2. Parameters will be passed in a form of key-value, and “application/x-www-form-urlencoded” will be added to the request header.
  3. Only private parameters and return results are listed in the following interfaces. For other information, please see the specifications of common request parameters.
  4. The data format of return results is json.

Specification on common request parameters (the parameters that must be passed for all requests):

Request parameterTypeSpecification
signstringSignature. Please refer to the following signature how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI. It can be obtained when subscribing for SUNMI cloud printer channel service
msnstringDevice SN
timestampstringUnix timestamp (second)

Specification on returning common parameters:

Return parameterTypeSpecification
codeintReturn code. Please see common error code list.
dataallPlease refer to private return parameter data for data type and content. If there is an error, null will be returned.
msgstringInformation which indicates the result. If there is an error, the error description will be returned.

Specification on generating a common request parameter:

Signature algorithm: MD5

Example on how a signature is generated (It supposes that the required parameters are as below):
app_id:sm5b9b4daef3463 
msn:NT1234DF23456 
timestamp:1589277365 
shop_id:1

Step 1: place the parameters per their orders in ASCII in a form of “key=value”: stringA=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365″

Step2: supposing the app_key, the key part “dd3ac24736589ae17d333e362859bf4c” to join a character string, is: stringB=”app_id=sm5b9b4daef3463&msn=NT1234DF23456&shop_id=1&timestamp=1589277365dd3ac24736589ae17d333e362859bf4c”

Step 3: encrypt stringB with MD5 to generate the final signature sign (sign=MD5(stringB), that is sign=”946720303FEFF4516626A4431D2753CA”

Among the steps above, the private parameters app_id and app_Key will be provided by SUNMI. Note: a sign must be a 32-character string in upper case which is encrypted by MD5

Specification on common error codes:

Error codeSpecification
10000The interface is called successfully
20000Unavailable service
20001Failed to authorize
40001Required parameter is missing
40002Invalid parameter

The table above is a specification on global common error codes, and follow-up information will be added to the table. In addition to the common error codes, please refer to specific business error codes in content related to specific business interfaces.

4.1 SUNMI cloud API

Due to protect partner data privacy, SUNMI cloud does not directly obtain the print data, but adopts the message passing method, and the printer directly connects to the partner cloud to pull the required data for printing. The following interfaces are provided by SUNMI to realize device binding, order notification, voice transmission and other functions.

Request URL address: https://openapi.sunmi.com/

Document of developing API demo(PHP): https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter-Request_PHP_DEMO.rar

1)Interface for binding a printer

Interface name:

  • /v1/printer/printerAdd

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Shop_id is the only condition for grouping devices under the merchant account and is used when querying the status list of devices in the store. You can pass “” if this function is not needed, and null will be returned for the store device status list result set.

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameters (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60004Bind failed
60007Bind exception
60008The device has been bound already. Please check whether you have bound the device in SUNMI Assistant, if so, please unbind the device in SUNMI Assistant before binding it to this channel
60012shop_id to long. MAX 32 character.

2)Interface for unbinding a printer

Interface name:

  • /v1/printer/printerUnBind

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Shop_id must be passed, otherwise the printer cannot be unbound from the shop

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
  "code": "10000",
  "data": {
     "subCode": "60001",
     "subMessage": "",
  },
  "msg":  "string"
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60005Unbind failed

3)Query the status of devices which has been bound to the shop

Interface name:

  • /v1/machine/queryBindMachine

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
timestampstringUnix timestamp (second)

Private parameter:

ParameterTypeSpecification
shop_idstringThe partner’s shop ID

Example on return result (success)

{
    "code": "10000",
    "data": [
        {
            "is_online": "1",//1 device online, 0 device offline
            "msn": "N302D94D40068"//Device SN
        }
    ],
    "msg": ""
}

Specification on return parameter (success):

ParameterTypeSpecification
dataObjectmsn: device SN; is online: whether the device is online. 1 – online; 2 – offline

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel
60006Invalid shop ID

4)Notification on new orders

Interface name:

  • /v1/printer/newOrderNotice

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters:

ParameterTypeSpecification
hasOrderint1-there is a new order
orderIdstringOrder ID

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
subDatastringContains success or failure information

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

5)Push Voice messages

Interface name:

  • /v1/printer/pushVoice

Request method:

  • POST

Common parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timestampstringUnix timestamp (second)

Private parameters

ParameterTypeSpecification
call_contentstringThe character string which is need to voice playback. You can only choose one between call_content with call_url. Please pass “” if there is no data
call_urlstringThe address of the voice file to be downloaded and played by the device. You can only choose one between call_content with call_url. Please pass “” if there is no data. The available formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
expTimestampintUnix timestamp which indicates when the voice message will expire
cycleintVoice playback times: 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
delayintThe time interval (second) between voice playback, and the default is 2s

Example on return result (success):

{
    "code": "10000",
    "data": null,
    "msg" : ""
}

Specification on the return parameter (success):

ParameterTypeSpecification
datastringContains success or failure information

Example on return result (failure):

{
    "code": "10000",
    "data": {
       "subCode": "60001",
       "subMessage": "",
    },
    "msg": ""
}

Specification on error codes (failure):

Error codeSpecification
60001The request is invalid due to a timeout
60002Invalid SN
60003The device does not belong to this channel

4.2 Partner cloud API

Due to protect partner data privacy, SUNMI cloud does not directly obtain the print data, but adopts the message passing method, and the printer directly connects to the partner cloud to pull the required data for printing. The following interfaces which is provided by partner cloud is for the printer to obtain order data and print.

Request URL address: to make sure that the printer can connect directly to the partner cloud API for completing print orders, an URL address which can be called should be provided to SUNMI cloud in advance.

Document of developing API demo(GO):https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter_CallBack_GO_DEMO.zip

1)Get order list

Interface name:

  • printTicket/getPrintTicketOrderId

Request method:

  • GET

Parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)

Example on return result (json):

{
    "code":1,
    "data":["id","id","id","id","id"],
    "msg":""
}

Return parameters:

ParameterSpecification
code1 request successful. -1 request failed
dataReturn five order ID sets in the database. If the request fails, the data will be null
msgIf the request fails, error information will be returned in the msg, If the request successful, “” will be returned in the msg

Note: To make sure that the printer won’t miss any order, the order ID list returns a list of up to 5 order ID sets at a time in chronological order. The printer will print all the orders in turn and then request the interface to get the list of order IDs to be printed again until the interface returns empty.

2)Get order details

Interface name:

  • printTicket/getPrintTicketInfo

Request method:

  • GET

Parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)
orderIdstringOrder ID

Example on return result (json):

{
    "code":1,
    "data":{
      "voiceCnt":1,  //Voice playback times, 0 0 – do not remind; 1 – play once; 3 – play 3 times; 999 – loop
      "voice":"Voice content",  //Voice playback content. Only one of voice and voiceUrl can be used. Please pass "" if there is no data
      "voiceUrl":"http://xxx.xxx.xxx/playaudio.MP3",  //The address for downloading the voice playback file. Only one of voice and voiceUrl can be used. Please pass “" if there is no data. Voice is the text contains the message to be played. VoiceUrl is the voice file to be played. The available file formats are MP3 (16bit mono, 8000Hz) and WAV (16bit mono, 8000Hz)
      "orderCnt":2,  //The number of orders to be printed
      "data":"1B21306D4B8BD5310A",//Use ESCPOS font (in double height and width) to print the content in “test 1", and there is a return command at the end of it
    },
    "msg":""
}

Specification on data: The content to be printed is transmitted in hexadecimal format and UTF8 encoding is adopted for all text contents. ESC/POS command set can be directly used in the contents to control printing, also for layout and format.

//PHP Sample code  

$str = chr(27).chr(33).chr(48)."Supermarket".chr(27).chr(33).chr(0).chr(0x0A);  //chr(27).chr(33).chr(48)are font effect (double height and width) in ESC/POS command; chr(27).chr(33).chr(0)are the standard font size in ESC/POS command; 0A is carriage return
$str = $str."Table:01       Employee ID:01".chr(0x0A);
$str = $str."Time:12:45:28".chr(0x0A);
$str = $str."Order No.:00554789713585".chr(0x0A);
$str = $str."Item     Price*Num       Amount".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."Item1       7.00*1      7.00".chr(0x0A);
$str = $str."Item2       8.00*1      8.00".chr(0x0A);
$str = $str."Item3       2.50*1      2.50".chr(0x0A);
$str = $str."Item4     10.00*1     10.00".chr(0x0A);
$str = $str."Item5     10.00*1     10.00".chr(0x0A);
$str = $str."--------------------------------".chr(0x0A);
$str = $str."Total items:5          Total RMB: 27.00".chr(0x0A);
$str = $str.chr(0x0A);
$str = $str.chr(27).chr(33).chr(16)."      Wish you a good day".chr(27).chr(33).chr(0).chr(0x0A);//The font shown is in double height and width; 0A is carriage return

$data = bin2hex(strToUtf8($str));  //$data is:1b2130e58d97e59bbde8b685e5b8821b21000ae58fb0e58fb73a303120202020202020e5b7a5e58fb73a30310ae697b6e997b43a31323a34353a32380ae58d95e58fb73a30303535343738393731333538350ae59586e59381e5908de7a7b020202020202020202020202020e58d95e4bbb72ae695b0e9878f202020202020e98791e9a29d0a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae799bee4ba8be588a9e7b2bee8a385e7b396e69e9c2020202020202020372e30302a312020202020202020372e30300ae697bae697bae99baae9a5bc2020202020202020202020202020382e30302a312020202020202020382e30300ae58fafe58fa3e58fafe4b9902020202020202020202020202020322e35302a312020202020202020322e35300ae5969ce4b98be69c97e69e9ce586bb202020202020202020202031302e30302a312020202020202031302e30300ae5b7a7e5858be58a9be9a5bce5b9b2202020202020202020202031302e30302a312020202020202031302e30300a2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d2d0ae680bbe4bbb6e695b02020342e303020202020202020202020e680bbe8aea1524d4220202020202032372e30300a0a1b2110202020202020e8b0a2e8b0a2e683a0e9a1bee6aca2e8bf8ee4b88be6aca1e58589e4b8b41b21000a

//The method can judge whether the character string content is UTF8 encoding. if so, it will be returned directly. Otherwise the character string will be turned into UTF8 encoding
function strToUtf8($str){
    $encode = mb_detect_encoding($str, array("ASCII",'UTF-8',"GB2312","GBK",'BIG5'));
    if($encode == 'UTF-8'){
        return $str;
    }else{
        return mb_convert_encoding($str, 'UTF-8', $encode);
    }
}

Return parameters:

Return parameterSpecification
code1 request successful. -1 request failed
dataReturn order content. If the request fails, the data will be null. If the request successful, the data will include voiceCnt (voice playback times), voice (voice playback content), orderCnt (print order number) and data (print order data) will be returned
msgIf the request fails, error information will be returned in the msg, otherwise “” will be returned in the msg

For the cloud printer is able to reprint an order, the interface should allow orders marked as printed and allow the printer to request order details per order ID to reprint an order.

3)Update order status

Interface name:

  • printTicket/updatePrintTicketStatus

Request method:

  • GET

Parameters:

ParameterTypeSpecification
signstringSignature. Refer to the content aforementioned for how it is generated. Note: a sign must be a 32-character string in upper case which is encrypted by MD5
app_idstringThe app_id which is provided by SUNMI
msnstringDevice SN
timeStampstringUnix timestamp (second)
orderIdstringOrder ID
statusintStatus: 1 – print order successful; 0 – print order failed; -1 – order json format error; -2 – the data field is empty

Example on return result (json):

{
    "code":1,
    "data":"success",
    "msg":""
}

Return parameters:

ParameterSpecification
code1 request successful. -1 request failed
data“success” will be returned if it is successful; “fail” will be returned if it failed
msgIf the request fails, error information will be returned in the msg, otherwise “” will be returned in the msg

Cloud Printer Product R&D Instruction

3.Download the SDK for network configuration

Download Android SDK DEMO url:https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter_AndroidSDK_Demo.zip
Download WeChat mini program SDK url:https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter_WeChatSDK.rar
Download IOS SDK DEMO url:https://file.cdn.sunmi.com/SUNMIDOCS/CloudPrinter_IOSSDK_Demo.rar

Introduction:You need conduct command communication with the Bluetooth on a phone for the process of cloud printer network distribution and cloud binding needs to be realized through Bluetooth. The processes of network configuration with Bluetooth has been encapsulated in the SunmiPrinterClient class of the SDK, with which you can complete the printer pairing through few steps in the APP. Before using this function, please make sure that your Bluetooth is on and the APP can access to your location. The following is the instruction of SDK interfaces. For details, please refer to DEMO.The newly-received printer has not configured WiFi, so it is not quite inconvenient during development. Therefore, we provide a network configuration tool which can be installed on Android phones for you to use. Please click to download WIFI configuration tool at DEMO Downoad

3.1 Network configuration SDK instruction (Android)

Android network configuration SDK package is BluetoothBinding.aar.

1)Class declaration

Function interface:

  • SunmiPrinterClient

Interface declaration:

   SunmiPrinterClient sunmiPrinterClicent = SunmiPrinterClient(Context context, IPrinterClient iPrinterClient);

Input parameter:

ParameterTypeSpecification
contextContext
iPrinterClientIPrinterClientThe callback class of the cloud printer bluetooth interface

2)Callback interface

In the process of configuring WiFi for printer, it is necessary to send messages to the printer through the BLE protocol. So we define a unified callback that is used to handle the Bluetooth data transmission.

Interface name:

  • sendDataFail

Callback method:

   public void sendDataFail(int code, String msg) {
       
    }

Callback parameter:

ParameterTypeSpecification
codeintMessage error code: 0 – failed to connect to Bluetooth; 1 – Bluetooth Notify failure
msgStringThe error message

3.2 Instruction of network configuration SDK interface(Android)

1)Start scanning the printer

Interface name:

  • startScan

Interface declaration:

   sunmiPrinterClient.startScan();

Callback method:

    public void onPrinterFount(PrinterDevice printerDevice) {
       
    }

Callback parameter:

ParameterTypeSpecification
printerDevicePrinterDeviceBluetooth printer class. The printer data which is scanned are only the default name and Bluetooth MAC address

2) Stop scanning the printer

Stopping scanning the printer before the current page is disposed or starts configurating the printer if there is no callback for the interface.

Interface name:

  • stopScan

Interface declaration:

   sunmiPrinterClient.stopScan();

3) Get printer SN

Interface name:

  • getPrinterSn

Interface declaration:

   sunmiPrinterClient.getPrinterSn(btAddress);

Input parameter:

ParameterTypeSpecification
btAddressStringThe Bluetooth MAC address of the printer

Callback methods:

  • Method 1:
   public void getSnRequestSuccess() {
        
    }

Specification: this method indicates that the command of getting the SN has been successfully sent and you can wait to get the SN. A timeout mechanism can be added to the method.

  • Method 2:
   public void onSnReceived(String sn) {
        
    }

Callback parameter:

ParameterTypeSpecification
snString打印机的sn

4)Get the list of WiFi which is searched by the printer

Interface name:

  • getPrinterWifiList

Interface declaration:

   sunmiPrinterClient.getPrinterWifiList(btAddress);

Input parameter:

ParameterTypeSpecification
btAddressStringThe Bluetooth MAC address of the printer

Callback methods:

  • Method 1:
   public void routerFound(Router router) {
        
    }

Callback parameters:

ParameterTypeSpecification
routerRouterThe WIFI class which is searched by the printer

Router class parameter specification

ParameterTypeSpecification
nameStringWIFI name
hasPwdbooleanWhether the WIFI has a password
pwdStringWIFI password
rssiintThe strength (0-4) of WIFI (the larger the value, the stronger the signal)
essidbyte[]WIFI essid which is needed in network configuration
  • Method 2:
public void onGetWifiListFinish() {
        
    }

Specification: printer scanning WiFi end.

  • Method 3:
public void onGetWifiListFail() {
        
    }

Specification: printer scanning WiFi failed.

5)Configure WIFI for the printer

Interface name:

  • setPrinterWifi

Interface declaration:

   sunmiPrinterClient.setPrinterWifi(btAddress, ssid, psw);

Input parameters:

ParameterTypeSpecification
btAddressStringThe Bluetooth MAC address of the printer
ssidbyte[]WIFI ESSID
pwdStringWIFI password

Callback methods:

  • Method 1:
   public void onSetWifiSuccess() {
       
    }

Specification: the printer receives the information of the WIFI to be configured and tries to connect to the WIFI. The timeout mechanism is recommended to be added here.

  • Method 2:
   public void wifiConfigSuccess() {
       
    }

Specification: the printer has successfully configured WIFI.

  • Method 3:
   public void onWifiConfigFail() {
      
    }

Specification: The reason why the printer configure WIFI failed is usually caused by a wrong password.

6)Exit network configuration

Specification: this method only has a unified callback for sending Bluetooth message failed. It is recommended to be called in onBackPressed method.

Interface name:

  • quitConfig

Interface declaration:

   sunmiPrinterClient.quitConfig(btAddress);

Input parameter:

ParameterTypeSpecification
btAddressStringThe Bluetooth MAC address of the printer

7)Request deleting WIFI configuration and using 2G network

Specification: this method only has a unified callback for sending Bluetooth message failed. This method can be called without WIFI if the printer is in 2G network.

Interface name:

  • deleteWifiInfo

Interface declaration:

   sunmiPrinterClient.deleteWifiInfo(btAddress);

Input parameter:

ParameterTypeSpecification
btAddressStringThe Bluetooth MAC address of the printer

8)Disconnect Bluetooth from printer

Specification: this method needs to be called when destroying the page

Interface name:

  • disconnect

Interface declaration:

   sunmiPrinterClient.disconnect(btAddress);

Input parameter:

ParameterTypeDeclaration
btAddressStringThe Bluetooth MAC address of the printer

3.3 Import the network configuration SDK (WeChat mini program)

Specification: please make sure the Bluetooth on your phone is on before using this function.

Please put the sdk.js file in the folder where you want to import the interface.

	const sdk = require('../blueConnect/sdk.js');

3.4 Instruction of network configuration SDK interface (WeChat mini program)

1)the Bluetooth module and start searching the devices nearby.

Interface name:

  • openBluetoothAdapter

Interface declaration:

  //the parameter of the interface is a callback function status
  sdk.openBluetoothAdapter((res) =› {
      console.log('the result of turning on Bluetooth', res);
    }); 

Callback parameter:

ParameterValueSpecification
status0Initialized the Bluetooth module successfully.
status10001Failed to initialize the Bluetooth module because the user has not turned on Bluetooth.

2)Get the list of the Bluetooth devices nearby

Interface name:

  • onBluetoothDeviceFound

Interface declaration:

  //The parameter of the interface is a callback function devicesList
  sdk.onBluetoothDeviceFound((devicesList) =› {
      console.log('devicesList', devicesList);
    })

Callback parameter:

ParameterValueSpecification
devicesList[ ]Array

3)Stop searching Bluetooth devices nearby

Interface name:

  • stopScanDevices

Interface declaration:

	sdk.startScanDevices();

4)Turn off the Bluetooth module. You can call this method to disconnect all established connection and release system resources.

Interface name:

  • closeBluetoothAdapter

Interface declaration:

	sdk.startScanDevices();

5)Connect to a Bluetooth device

Interface name:

  • createBLEConnection

Interface declaration:

	sdk.createBLEConnection(deviceId, (res) =› {
      this.setData({
        canWrite: res.canWrite,
        deviceId: res.deviceId,
        characteristicId: res.characteristicId,
        connected: res.connected,
      })
      console.log('the device is connected successfully', res)
    });

Interface parameter:

ParameterValueSpecification
deviceIdstringThe device list can be obtained through onBluetoothDeviceFound interface and the deviceId can be found in each device information.

Callback parameter:

parameterValueSpecification
status0Obtain eigenvalues after connect successfully. Parameter as follow
10001Connected failed
10002Connected successfully but failed to obtain eigenvalues (Device does not support R&W eigenvalues)
characteristicIdstringEigenvalues ID
deviceIdstringDevice ID
serviceIdstringService ID

6)Get the cloud printer SN

Interface name:

  • getSN

Interface declaration:

  //The parameter of the interface is a callback function
  sdk.getSN((data) =› {
      console.log('sn', data);
      this.setData({
        sn: data
      });
    });

Callback parameter:

ParameterValueSpecification
datastringSN character string

7)Get the list of WiFi which is searched by the cloud printer

Interface name:

  • getWifiList

Interface declaration:

  //The parameter of the interface is a callback function
	sdk.getWifiList((data) =› {
      this.setData({
        wifiList: data
      })
      console.log('wifiList', data);
    });

Callback parameter:

ParameterValueSpecification
data[ ]Array, among which each element stands for a piece of WIFI information including SSID (WIFI name), mode (WIFI mode), RSSI (WIFI strength) and complete (the complete information reply to the command)

8)Wi-Fi Connect to a specified WIFI

Interface name:

  • connectWifi

Interface declaration:

	sdk.connectWifi(essid, password, (res) =› {
      console.log('Print WIFI connection result', res);
    });

Interface parameter:

ParameterValueSpecification
essidstringWIFI name
passwordstringWIFI password

Callback parameter:

ParameterValueSpecification
status0Connect to WIFI successful
10001Connect to WIFI failed. Please check the WIFI ssid and password

9)Exit network setting

Interface name:

  • cancelConnect

Interface declaration:

	sdk.cancelConnect();

10)Delete WIFI configuration

Interface name:

  • deleteWifi

Interface declaration:

	sdk.cancelConnect();

11)Disconnect from Bluetooth

Interface name:

  • closeBLEConnection

Interface declaration:

	sdk.closeBLEConnection();

Cloud Printer Product R&D Instruction

2.Register a partner account

2.1 Register a partner account

  • a) To ensure the security of partners’ business, each partner needs to have a SUNMI partner account.

For how to register, please refer to: https://docs.sunmi.com/en/developers/registration-for-partners/

  • b) The channel of the printer must be under the account aforementioned when the printer is delivered from the warehouse, otherwise the printer cannot be bound to the account due to an ownership problem.

2.2 Register steps

  • a) Click “Register” at https://partner.sunmi.com. It is recommended to use the functions of partner platform through Google browser.
  • b) Fill the corresponding content on the register page and click “Register”.
  • c) There will be a prompt shows that the email with a button and a link to activate your account has been sent to the mailbox you filled in step 2. Click “Check mailbox” to activate your account.
  • d) The email is as below. Please click the button “Activate account” to complete activation. (Please check your spam box if you have not received the email)
  • e) After activation, please login to the partner page to complete your information (all blanks must be accurately and completely filled). Please submit your business license if you register as a company and click “Save”. Please wait for our verification and the result will be released through an email sent to you later.
  • f) SUNMI will distribute corresponding role when verifying each user. You will officially be our partner after receiving the email contains verification result and you can login the partner platform with the account you registered.

Cloud Printer Product R&D Instruction

Please notice:

For better protection of partners’ data privacy, also SUNMI cloud printer can realize the complete order printing functions. The following specifications are hereby established, which need the joint efforts of SUNMI and partners to realize the printing channel business.

1.Steps

1.1 Method 1: Device to Cloud

流程图1
  • ① Register a partner account at https://partner.sunmi.com/ . Subscribe for SUNMI cloud printer channel service and get the service APP_ID and APP_KEY, which will be used later in API calling. A partner cloud URL also needs to be provided to SUNMI cloud service after the partner interface is developed and released, which will be used by the printer to call the partner’s API back to complete printing.
  • ②We provide a network configuration SDK for printer link WiFi. Partner can integrate this SDK into their own apps.
  • ③The printer SN, which is an unique identifier of the printer, will be automatically obtained when you configure network with SDK. You can use it to bind the device to the corresponding merchant account and complete business communication.
  • ④Partners can use printer SN in their own apps to bind SUNMI printer with their shops.
  • ⑤SUNMI provide cloud API for establishing the relationship between printer SN & partner ID & shop ID. The cloud API will be requested by partner APP.
  • ⑥SUNMI provide cloud API for pushing order & voice. The cloud API will be requested by partner cloud.
  • ⑦SUNMI cloud will automatically push a business message to the printer after receiving the message from partner cloud.
  • ⑧The printer will get and print order data through requesting partner cloud API after receiving message from SUNMI cloud. Partner cloud address will use the URL that partner has registered in SUNMI partner platform.
  • ⑨SUNMI provide a device management service. Partner can directly call SUNMI “Device Management Interface” in their Business APP if partner need to manage their device. More features will be developed to provide merchants with better use experience.

1.2 Method 2: Cloud to Cloud

流程图2
  • ①Register a partner account at https://partner.sunmi.com/ ; subscribe for SUNMI cloud printer service and get the service APP_ID and APP_KEY, which will be used later in API calling; a cloud URL of a partner also needs to be provided to SUNMI cloud service after the partner interface is released, which will be used by the printer to call the partner’s API back to complete printing.
  • ②We provide a network configuration SDK for printer link WiFi. Partner can integrate this SDK into their own apps.
  • ③The printer SN, which is an unique identifier of the printer, will be automatically obtained during the SDK network configuration. You can use it to bind to the corresponding merchant account and complete business communication;
  • ④Partners can use printer SN in their own apps to bind SUNMI printer with their shops.
  • ⑤SUNMI provide cloud API for establishing the relationship between printer SN & partner ID & shop ID. The cloud API will be requested by partner APP.
  • ⑥SUNMI provide cloud API for pushing order & voice. The cloud API will be requested by partner cloud for pushing printing and voice data.
  • ⑦SUNMI cloud will automatically push a business message to the printer after receiving the message from partner cloud.
  • ⑧SUNMI provide a device management service. Partner can directly call SUNMI “Device Management Interface” in their Business APP if partner need to manage their device. More features will be developed to provide merchants with better use experience.

Special Codes Description

Special Codes Description

One. Obtain Sunmi device identification

Sunmi suggests to judge whether it’s Sunmi
device by obtaining the following content:

1.
Brand name of the device (for
example: Sunmi)

The brand name of all Sunmi devices is uniformly: Sunmi

2.
The system model of the device
(for example: V1-B18)

The composition of the system model is:

product model + hardware features + “-” + software features

Among these model names, those beginning with V、M、P、L are handheld
devices, those beginning with T、D、S are landscape devices (up to December, 2017)

3.
ROM version number of the
device (for example: 1.1.0).

4.
ROM sequence number of the
device (for example: 128).

You can download Demo,create new android.os package (fixed style
of writing), place

SystemProperties.java under this package,
and obtain the specified values according to the following methods:

The code to obtain brand is:

 String brand = SystemProperties.get("ro.product.brand");

The method to obtain model is:

   String model = SystemProperties.get("ro.product.model");

The code to obtain ROM version number is:

String versionname = SystemProperties.get("ro.version.sunmi_versionname");

The method to obtain ROM sequence number
is:

   String versioncode = SystemProperties.get("ro.version.sunmi_versioncode");

Two. Obtain SN number of the device
1.
Add the following permission in
AndroidManifest.xml.
 

2.
Obtain Sunmi SN number where
necessary with the following code.

public static String getSN() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            return Build.getSerial();
        } else
            return Build.SERIAL;
    }

Three. Hide and recover the navigation bar
at the bottom

(Note: Sunmi has newly developed Kiosk
screen occupy mode without any modification of App. Hiding status bar and
navigation bar can be realized merely via cloud setting and it cannot be
realized via gesture. This function has been realized on T2、K1 device, and please contact technical support in terms of other
devices’ online progress: 400-902-1168 (9:00-21:00). It is suggested that the
partner apply Sunmi Kiosk screen occupy mode, which has obtained better
experience)

Android system has provided by default the
method to hide the system’s navigation bar, but it has a poorer support to
Dialog, which leads to the problem that the navigation bar pops up first before
hiding when the full screen dialog box is opened (splash screen). SunmiOS has
carried out restoration against this problem (post support from V1 system
firmware of 252 version and T1 system firmware of 132 version ).

1.
Full screen of Activity

——Android default support

 
 public static void setStickFullScreen(View view) {
 int systemUiVisibility = view.getSystemUiVisibility();
    int flags = View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
    | View.SYSTEM_UI_FLAG_LAYOUT_STABLE
    | View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
    | View.SYSTEM_UI_FLAG_HIDE_NAVIGATION // hide nav bar
    | View.SYSTEM_UI_FLAG_FULLSCREEN // hide status bar
    | View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY;
     systemUiVisibility |= flags;
     view.setSystemUiVisibility(systemUiVisibility);
}

2.       Full screen of Dialog

——Under the primary system, the bug of AOSP
will lead to the problem that the navigation bar pops up first before hiding
when the full screen dialog box is opened (splash screen).

  @Override
  public void onWindowFocusChanged(boolean hasFocus) {
    super.onWindowFocusChanged(hasFocus);
    setStickFullScreen(getWindow().getDecorView());
}

3.The way descriped above didn’t hid the Notification Bar & Navicatoin Bar, those bar will show again while the Dialog popup, we suggest you using custom dialog , calling the setStickFullScreen in the create method as following to solve this problem:

public AlertDialog create(boolean fullscreen) {
  LayoutInflater inflater = LayoutInflater.from(context);
   final AlertDialog dialog = new AlertDialog(context,
   R.style.DialogStyle);
   if(fullscreen){
   setStickFullScreen(dialog.getWindow().getDecorView());
   }
}

3.       Display navigation bar after
setting hiding

3.1.  Swiping up of global bottom

——After swiping up, the bottom navigation
bar is displayed for 4 s. After 4 s, the bottom navigation bar will be hidden

3.2.  Switch App to other Apps (for example, jump to third party App
within App, third party

App popup, etc.)

——Switch to other Apps. Whether to display
bottom navigation bar or not is subject to third party App requirement. The
bottom navigation bar will disappear when switching to its own App

Notice:

  • Cause there may encounter some security problems, we has restrict that the Notification Bar & Navicaton Bar can’t be hidden completely, slide from the bottom will activate those bar again.
  • The bug of AOSP in Android will cause a problem that the Navication Bar will be hidden after a transient showing while the Dialog is popup, we have solve the problem in the latest version of SUNMI OS (After firmware version 332).
  • The Navication Bar will show as the Input software is popuped , we have solve the problem in the latest version of SUNMI OS (After firmware version 332).

Four. To avoid repeated claim for peripherals
permission

When App needs to realize business via USB related
peripherals (for example, connect USB printer to print receipt), the user is
required by Android to manually confirm device permission, to guarantee the
user information security and prevent Trojan viruses from hacking USB devices.
1.
How to avoid App’s repeated
claim for this peripherals permission when the USB device
plugs again the same peripheral
It is necessary to check “Applied to this
USB device by default” when the user confirms manually. It is impossible to bypass
this security mechanism via code

Screenshot-3.pngScreenshot-2.png

Add property manageSpaceActivity in application on app’s Manifest file, and specify an Activity Page you want to enter when click CLEAR DATA in System Setting.

  

  
    
  

PS You can create an auto-finish Activity to avoid your data to be cleared.

public class ManageSpaceActivity extends Activity {  
  
    @Override  
    protected void onCreate(Bundle savedInstanceState) {  
        super.onCreate(savedInstanceState);  
  
        finish();  
  
    }// onCreate  
}  

Debugging Devices

Debugging the Devices

About Sunmi device debugging

(This tutorial is only applicable to
non-financial devices. If you need to enable the debugging permission of Sunmi
series devices, please contact the sales
personnel
)

You can debug after plugging in USB line to
default Sunmi device. Sunmi has also provided the control function for device
debugging permission. After the partner has enabled debugging permission
control in the background (as shown in the following figure), it is necessary
to obtain debugging permission via E-mail or mobile phone number to debug this
device. If you cannot directly debug, please check whether the partner
backstage has enabled this permission.

e1

Note: the control of debugging permission
takes effect only to the devices that have bound partners (channels).

How to debug device while the permission is on

If the partner has enabled “debugging
permission control”, the developer need to obtain the debugging permission via
E-mail and mobile phone number on his/her own device to debug the device. The
partner can add the mobile phone number or E-mail of the debugging
personnel
(developer) on the Sunmi partner platform. Steps to obtain
the device debugging permission as follows:

1.Add debugging
personnel

Before debugging the device, the developer
is required to know the channel that the device belongs to. He/she can look for
the management personnel relevant to his/her own company for inquiry. The management
personnel needs to add the debugging
personnel
’s mobile phone number or E-mail in Sunmi partner platform
background.

e2

2. Plug in USB.(Please switch off the ‘debugging permission control’ temporarily on V1sV2M2L2)

Connect the device to the computer after
confirming that you have your own mobile phone number or E-mail for debugging
permission. It is suggested that the developer debug under windows. If the mobile
phone can be correctly recognized by the computer, the popup prompt as follows
will normally appear:

Screenshot_2017-02-16-11-00-42

    If the device has not been recognized by
    the computer, please confirm whether it is caused by the following causes.

  •  Poor contact. Please confirm by
    plugging & twisting USB port several times.
  •  Data line fault. Try to change
    one data line to see whether it can be recognized.
  •  If the computer has not
    installed mobile device driver, you may use third party tool software to install.

3.Get the veification code

Click the above “I want to debug” item, you
will enter the step of permission verification via mobile phone number or
E-mail. Meanwhile, the USB debugging mode of the device will be enabled by
customization (here it refers to the basic debugging mode, but not permission);
click “Got it” and it will quit the popup and USB debugging mode will not be
enabled.

e4

4. Verify the permission

Click “Obtain the verification code” after
entering the previously added mobile phone number or E-mail. Sunmi will send
the verification code to the mobile phone number or E-mail. Fill in the
verification code and click “Authorize and enable debugging”

e5

5.Open the permission.

After opening the permission, you can check whether there is output
in logcat to judge if it’s OK to debug the device.

e6