SUNMI Electronic Shelf Label (ESL) can be used in supermarkets, warehouses, hospitals,
meeting rooms and other scenarios to show product prices, stock information and
attendee information, etc.
Users can directly manage ESLs on SUNMI Store open
platform, but in some real cases, they need to interact their software system
with SUNMI Store to send product information to SUNMI Store and manage the
functionalities of ESLs in order to complete the final ESL integration.
To meet our clients’ needs and empower our partners, SUNMI
Store provides ESL-related openAPIs to integrate ESLs with a 3rd
party software in different levels.
SUNMI Store is available in 3 editions (SUNMI Cloud Edition,
Private Cloud Version and Private Local Server Version), and APIs
of different editions vary.
Note: This
document is written to illustrate how to realize product information display,
but it also can be a reference for more ESL uses in different scenarios.
2 Integration Process
1. Communication. After determining to use SUNMI openAPIs,
please first read openAPI documents (on SUNMI Store) and discuss with SUNMI
team on the level of integration,
business process design, matters
need attention, schedule and other matters through a messaging app.
2. Send the name of the software to be integrated
with and email address to SUNMI technical support team which then will email
parameters including app_id, secret_key and ESL
App in the UAT environment to you.
3. Integration. SUNMI provides technical support through
the messaging app.
4. Testing. Once the integration in UAT environment is
completed, you can test by yourself and provide a test account for SUNMI to
verify at the same time.
5. SUNMI sends the parameters in onl environment and complete integration in onl
environment.
3 Levels of Integration
SUNMI Store provides multiple ESL-related openAPIs and you
can integrate as needed.
Frankly speaking, we have set four integration levels,
which are listed in the table below:
Level
Object
Functionalities Realized
L1
Product data
Integration at this level enables the synchronization of product data and store binding information. After successful integration, the 3rd party software uploads product data to the digital store or the digital store automatically acquires product data from the software. A managed ESL can automatically update its display with price modification in the third-party software. ESL management functions, such as ESL binding, ESL unbinding, and template editing, are only available in SUNMI Store and SUNMI Assistant App.
L2
Basic operations
Based on L1 integration, L2 integrates ESL binding and unbinding APIs to the 3rd party software. After successful integration, basic operations, such as ESL binding and unbinding, can be performed in the 3rd party software directly.
L3
Device
Based on L2 integration, L3 level allows the integration of specific device APIs to the 3rd party software. After successful integration, the third-party software supports basic ESL management operations, such as template switching, ESL flashing, and data repushing. Template editing and AP management functions are only available in SUNMI Store and SUNMI ESL App.
L4
ESL management system
Based on L3 integration, L4 implements a comprehensive integration between the ESL system and the 3rd party software. After successful integration, all ESL management functions are available in the 3rd party software except the independent template Studio (login to the Studio is not required). SUNMI Store is not necessary for routine operations.
L1 integration is sufficient in most cases, and some
clients may need an L2 integration. Please thoroughly communicate on business
scenarios before selecting any higher level integration.
4 APIs of Different Modules and Corresponding Documents
APIs are categorized in accordance with different
modules, please refer to the modules and corresponding documents listed below.
Module & Doc
Description
Authentication
It contains the general authentication rules of SUNMI Store, please read carefully before commencing development.
Shop APIs
SUNMI devices and services are managed per store under a company, please bind the store on SUNMI Store and the store on the 3rd party software before starting function integration.
Product APIs
It contains the APIs to add, delete and modify a product, which is included in the L1 integration. In addition to ESL, these APIs also can be used for other devices and services.
ESL APIs
It contains APIs to manage ESLs, what are included in the L2 integration and levels higher.
5 APIs and Corresponding Modules
ESL-related openAPIs are categorized in accordance with
modules, and you can combine different modules as needed.
APIs included in L1-L4 are listed below. Whether to
enable some functions (e.g.: flash LED, upgrade, etc.) is up to your needs.
Module
API
name
API
L1
L2
L3
L4
Description
Store Binding
Binding a SUNMI store
/shop/bind
√
√
√
Manually bind the store that has already been
created on SUNMI Store.
Search the corresponding store information
thorough shop_id.
Product APIs
Creating a product
/product/create
√
√
√
√
Updating a product
/product/update
√
√
√
√
This API can also be used to create a
product.
Deleting a product
/product/delete
√
√
√
√
Getting all software product info
api/getProductList
An API you provided to SUNMI to pull all product information from the 3rd
party software.
ESL – Product
Binding an ESL with a product
/product/bindEsl
√
√
√
Bind ESL, product and template. After
binding, the display will be updated and the ESL will be bound to a store.
Unbinding an ESL from a product
/product/unbindEsl
√
√
√
Getting the list of ESLs bound to a product
/product/getBindEslList
√
√
More than one ESL can be included.
Modifying the ESL template bound to a
product
/product/updateTemplate
ESL ID, template.
Getting product list
/product/getList
√
√
Getting product information
/product/getInfo
√
√
ESL – shelf label
Adding an ESL to a store
/device/esl/bind
This is only used to add an ESL to a store
(binding it to a product is not included).
Removing an ESL from a store
/device/esl/unbind
√
√
Only the ESL that has been unbound can be
removed.
Getting ESL list
/device/esl/getList
√
√
ESL status is included.
Getting ESL info
/device/esl/getInfo
√
√
Get basic information, bind to products or
use templates through ESL ID.
Pushing a certain image to an ESL
/device/esl/pushImage
The 3rd party software can generate
and push images to ESLs (there is a limit to image size).
Getting overview statistics
/device/getOverview
√
√
The number of ESLs in the system, the number
of products and the number of each push status.
ESL – flash LED
Flashing an ESL‘s LED
/device/esl/flashLed
√
√
Flash certain ESL’s LED in a certain way.
ESL – AP
Getting AP list
/device/ap/getList
√
Please bind an AP using ESL App.
Getting AP info
/device/ap/getInfo
√
Changing AP info
/device/ap/updateName
√
Restarting an AP
/device/ap/reboot
√
ESL – template
Uploading a newly created template
/template/create
√
Upload the json file you created in the
independent template Studio to the ESL system.
Updating a specified template
/template/update
√
Getting template list
/template/getList
√
Getting template info
/template/getInfo
√
Deleting a template
/template/delete
√
6 Develop Environments
SUNMI Store runs in more than one environment. Developing and jointly debugging
in uat environment is recommended, and release it to onl environment after the
joint debugging has been completed.
This tutorial will show you how to test the IPC OpenAPI with Postman.
Consult the Sunmi Technology Customer Service and get materials in the table below except the IP and SN of your device. And please connect your IPC to the Internet and make sure the blue LED is solid before going through the following steps.
Download Postman: Link, we use v7.27.1 in this tutorial.
And just follow the Installation Wizard.
3. Collection Import and Configuration
Launch Postman
Click File -> Import -> Upload Files, And open the Postman collection from Sunmi, i.e. “Sunmi_IPC_OpenAPI_Postman_Collection_202007001_en.json”, confirm and click “Import”.
Click File -> Settings -> Certificate, add the certificate file and its password, put the IP in the Host filed.
4. Open the General page, set “SSL certificate verificatio” to `OFF`.
5. Back to homepage of Postman, right click on “Sunmi IPC OpenAPI” collections, “Edit”, and update the corresponding settings at “CURRENT VALUE” in page “Variables”.
4. Activation Example
Activation use the activation code as the secret key, Make sure the value of secret_key in the Variables page is your activation code.
Open Sunmi IPC OpenAPI -> Basic -> 0. Activation, modify the “sn” to your device’s SN in the Body tab, click Send, activations succeed with “code” 0 in the response.
Please find the detailed docment about activation in Device Management.
5. API Test
This collection only includes several API example for testing. Each request needs to be correctly signed, see the Sign Rules.
Sign script are included in this collection in “Pre-request Scripts”, it will calculate the value of “app_id”, “timestamp”, “random” and “sign” in every request.
Order APIs
1 Background
SUNMI Store system is a store management system provided by SUNMI for merchants based on the IoT devices in stores.
As an open platform, SUNMI Store can do data interchange for third-party SaaS providers, including the interchange of product information, transaction information and membership system.
Multiple SUNMI IOT device will help customers digitalize their shop. Based on these data, such as passenger flow and statistic info, combined with the saas order, SUNMI will be able to create a multi-dimensional analysis and chart.
This document describes how to syncronize the order information with the Saas provider to make sure our customer can obtain data as soon as possible for future process or BI analysis
2 API Specifications
2.1 Protocol
All APIs use HTTPS Protocol with POST method
Note: The size of the request body should be no more than 1 MB. If this size is exceeded, open platform will deny it.
unique identifier provided by SUNMI store open platform
random
yes
string
6-10 digit random string with number and alphabets
timestamp
yes
int
10 digit current unix timestamp
sign
yes
string
see chapter 2.2
3 APIs
3.1 ORDER APIs
3.1.1 Order properties
Properties shown below are SUNMI order properties. Those are just for demonstration. Saas providers will need to provide their properties list to SUNMI.
The table below is the basic properties of an order. For specific orders, there will be more properties
order
group
parameter
type
description
required
unique
description
order basic info
order_id
string
order id
●
●
unique order id from saas provider
order_type
int
order type
●
type of the order ( 1-normal 2-refund 3-exchange 4-on hold 5-list 6-payment failed 7-canceled 8-etc
Description: This API is used for Saas provider to notify SUNMI when a new order is created. SUNMI store will save a copy of order in the database and provide some visualization of such order.
API Address：/order/create
API version：v2.0
Parameter：
parameter
required
type
description
example
sunmi_shop_no
no
string
Sunmi shop number
100939070408
shop_id
no
string
sunmi shop id (used for version before v2.0. After v2.0, please use sunmi_shop_no
Return value will be returned as part of the http response. If the sign validation failed, an HTTP code 401 will be returned. Otherwise, a http code of 200 will be returned
Rest of the error will be returned in the json response, normal response type will be:
There are two ways to get IPC message. Firstly, if some event is subscribed, the IPC will post a message to related callback url. Secondly, we can maintain a TCP connection to get related message.
1. Post Message
We can subscribe some topic to IPC, and the IPC will post a http message to the subscribers when something relative happened. It has the same function as Message Channel.
This API is used to subscribe some topic to IPC. The IPC will post a http message to the callback url passed in by this API when something related happened, thus the subscribe is informed.
Request link
https://192.168.0.1/openapi/hook/add, 192.168.0.1 needs to be replaced by the IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
event_list
array[string]
Topic list, the following is allowed. “face_recog_event” is only supported by “FM020”. [“face_recog_event”,”dynamic_detect_event”]
Y
http_callback
string
Callback url. The IPC will post a message to this url when something related happened.
Y
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 5, 310, 311, see Error Code for further details.
Request Example
POST openapi/hook/add HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
This api is used to unsubscribe some topic that is already subscribed. The subscriber will not receive relative messages once relative topic unsubscribed.
Request link
https://192.168.0.1/openapi/hook/delete, 192.168.0.1 needs to be replaced by the IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
event_list
array[string]
opic list, the following is allowed. “face_recog_event” is only supported by “FM020”. [“face_recog_event”,”dynamic_detect_event”]
Y
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 5, 310, see Error Code for further details.
Request Example
POST openapi/hook/delete HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
This API is used to query all topics and callbacks that subscribed to the IPC. When something related happened, the IPC will post a http message to relative callback urls.
Request link
https://192.168.0.1/openapi/hook/query, needs to be replaced by the IP address of IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 5, see Error Code for further details.
sub_event
array
Subscriber list
event
string
Topic
http_callback
array
Http callback of the topic
num
string
Number of the subscriber of the topic
Request Example
POST openapi/hook/query HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
The IPC will post a http message to inform subscribers. The http post is formed in form table, the “Content-Type” is “multipart/form-data”, the payload of message is packaged in “payload”.
Age, if it’s blank, it means that the age of this face has not set yet
age_range
int
Range of age 1 — 1 to 6 years old 2 — 7 to 12 years old 3 — 13 to 18 years old 4 — 19 to 28 years old 5 — 29 to 35 years old 6 — 36 to 45 years old 7 — 45 to 55 years old 8 — 55 to 100 years old
gender
int
Gender 0 — Undefined 1 — Male 2 — Female
arrive_times
int
Total times of arrival
pic_url
string
Url of face picture
item1
string
User-defined attribute, only returned if exist
item2
string
User-defined attribute, only returned if exist
item3
string
User-defined attribute, only returned if exist
item4
string
User-defined attribute, only returned if exist
item5
string
User-defined attribute, only returned if exist
2. Message Channel
Message channel allows user to maintain a tcp connect with IPC to communicate with IPC, it has the same function as Post Message.
2.1. Protocol
Protocol
The message channel use TCP connection with SSL to ensure the security of data. The protocol is implemented as Client/Server mode where the IPC is the server on port 10021.
Protocol Format
The protocol message, which consists of header, payload and CRC checksum, is described briefly in this section, as shown in the figure below.
Header
Flag
The “Flag” is fixed to 0xFF3E3EFF indicating it is using message channel.
Version
The “Version” describes the version of the protocol, it’s 0x01 for the moment. The protocol is backward compatible.
Packet Type
Type
Value
Direction
Description
Reserved
0
Prohibit
Reserved
CONNECT
1
Client to Server
Client send this message to establish connection
CONNACK
2
Server to Client
Connection acknowledge message sent by server, the content marks whether the connection is legal or not
PINGREQ
3
Client to Server
Heartbeat request
PINGRESP
4
Server to Client
Heartbeat response
SUBSCRIBE
5
Client to Server
Client send this message to subscribe events
SUBACK
6
Server to Client
Confirmation of subscription
UNSUBSCRIBE
7
CLient to Server
Client send this message to unsubscribe events
UNSUBACK
8
Server to Client
Confirm of unsubscription
PUBLISH
9
Client to Server, or Server to Client
Only server can publish message to client for the moment
PUBACK
10
Client to Server, or Server to Client
Acknowledge to published message
DISCONNECT
11
Client to Server, or Server to Client
Disconnect
Length
“Length” is the length of the payload, which range from 0 to 65535.
Payload
“Payload” is the actual content of the message, which formatted with json. The payload is different for each packet type.
CRC Checksum
“CRC” is the CRC(Cyclic Redundancy Check) checksum of payload, which occupies 4 bytes.
2.2 Connection Establishment
The connection is initiated by client, and IPC act as server.
Initiate connection
The Packet Type of the message is 0x01, and the payload is formatted as bellow. The client will insert some parameters in payload, and sign the payload with secret key. The signature rule is described in Sign Rules section. The server check whether the content is legal with the same signature rule.
keep_alive: The period of heartbeat in unit of second, which can be specified by client.
Acknowledge to connection
The Packet Type of the message is 0x02, and the payload is formatted as bellow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, refer to Error Code for more details.
{
"code": 0
}
2.3 Heartbeat
The client send heartbeat message to server with specified period, and the server will disconnect after 3 heartbeat messages.
Heartbeat request
The header of the message is 0x03, and the payload is empty.
Heartbeat response
The header of the message is 0x04, and the payload is empty.
2.4 Subscribe
The client subscribes message to server.
Subscribe or unsubscribe
The header of the message is 0x05 or 0x07, and the payload is formatted as bellow.
The header of the message is 0x06 or 0x07, and the payload is formatted as follow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, 310, 311, refer to Error Code for more details.
{
"code": 0
}
2.5 Publish message
Publish
The IPC server publishe messages to client. The header of the message is 0x09, and the payload is different with event.
Age, if it’s blank, it means that the age of this face has not set yet
age_range
int
Range of age 1– 1 to 6 yeares old; 2– 7 to 12 years old; 3– 13 to 18 years old; 4– 19 to 28 years old; 5– 29 to 35 years old; 6– 36 to 45 years old; 7– 45 to 55 years old; 8– 55 to 100 years old.
gender
int
Gender 0– Undefined; 1– Male; 2– Female.
arrive_times
int
Total times of arrival
pic_url
string
Url of face picture
item1
string
User-defined attribute, only returned if exist.
item2
string
User-defined attribute, only returned if exist.
item3
string
User-defined attribute, only returned if exist.
item4
string
User-defined attribute, only returned if exist.
item5
string
User-defined attribute, only returned if exist.
Acknowledge to publish
If the subscriber received this message, it should return acknowledge. The header of the message is 0x0a, and the payload is formatted as fellow.
{
"event_id": 1
}
The fields of the payload is described as follow.
Name
Type
Description
event_id
long
Event ID
2.6 Disconnect
The header of this message is 0x11, and the payload is empty.
https://192.168.0.1/openapi/peopleFlow/getDoorLine, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 260, 261, 262, 263, 264, 276, 277, 279, see Error Code for further details.
resolution
int
Resolution of the image, 0 for 1080p, 1 for 720P
start_x
int
The x-coordinate of the starting point of the door threshold, range is [0, 1920] for 1080p, and range is [0, 1280] for 720p
start_y
int
The y-coordinate of the starting point of the door threshold, range is [0, 1080] for 1080p, and range is [0, 720] for 720p
end_x
int
The x-coordinate of the end point of the door threshold, range is [0, 1920] for 1080p, and range is [0, 1280] for 720p
end_y
int
The y-coordinate of the end point of the door threshold, range is [0, 1080] for 1080p, and range is [0, 720] for 720p
Request Example
POST openapi/peopleFlow/getDoorLine HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Set flow statistics settings. The parameter “facerecog_interval” is the deduplication time of face recognition, in which period only the first entry of a face will be reported. The parameter “customer_judgemode” sets the customer flow mode. The events will be reported depending on the movement and size change of faces if in normal mode, while in snapshot mode they will be reported immediately once faces show up.
Request Link
https://192.168.0.1/openapi/peopleFlow/setConfig, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
facerecog_interval
int
The deduplication time of face recognition in seconds, range is [0,86400].
customer_judgemode
int
Customer flow mode, 0 is snapshot mode and 1 is normal mode.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, see Error Code for further details.
Request Example
POST openapi/peopleFlow/getDoorLine HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
5.Get Inflow Customer Statistics For A Specified Time
Description
Get inflow customer statistics in a specified time. Error will be returned if no record is found.
Request link
https://192.168.0.1/openapi/peopleFlow/getPeopleStat, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
start_time
long
Start time, UNIX format timestamp in second.
Y
1578969264
end_time
long
End time, UNIX format timestamp in second.
Y
1579055640
period
int
Time granularity, 1: half an hour; 2: one hour; 3: one day.
Y
2
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
total
int
Total number of people
start_time
long
Start time of Statistics
end_time
long
End time of Statistics
male_num_stat
array
There are 8 integers in the integer array, representing the male statistical
data of 1-6 years old, 7-12 years old, 13-18 years old, 19-28 years old, 29-35
years old, 36-45 years old, 46-55 years old and 56-100 years old respectively.
female_num_stat
array
There are 8 integers in the integer array, representing the female statistical
data of 1-6 years old, 7-12 years old, 13-18 years old, 19-28 years old, 29-35
years old, 36-45 years old, 46-55 years old and 56-100 years old respectively.
Request Example
POST openapi/peopleFlow/getPeopleStat HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
6.Get Pass-by Customer Statistics For A Specified Time
Description
Get pass-by customer statistics in a specified time. Error will be returned if no record is found.
Request link
https://192.168.0.1/openapi/peopleFlow/getPeopleStatPass, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
start_time
long
Start time, UNIX format timestamp in second.
Y
1578969264
end_time
long
End time, UNIX format timestamp in second.
Y
1579055640
period
int
Time granularity, 1: half an hour; 2: one hour; 3: one day.
Y
2
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
total
int
Total number of people
start_time
long
Start time of Statistics
end_time
long
End time of Statistics
Request Example
POST openapi/peopleFlow/getPeopleStatPass HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
7.Get Outflow Customer Statistics For A Specified Time
Description
Get outflow customer statistics in a specified time. Error will be returned if no record is found.
Request link
https://192.168.0.1/openapi/peopleFlow/getPeopleStatOut, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
start_time
long
Start time, UNIX format timestamp in second.
Y
1578969264
end_time
long
End time, UNIX format timestamp in second.
Y
1579055640
period
int
Time granularity, 1: half an hour; 2: one hour; 3: one day.
Y
2
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
total
int
Total number of people
start_time
long
Start time of Statistics
end_time
long
End time of Statistics
Request Example
POST openapi/peopleFlow/getPeopleStatOut HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Get the list of vistors sorted by arrival times in a specified time.
Request link
https://192.168.0.1/openapi/peopleFlow/getVisitorList, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
start_time
long
UNIX format timestamp in second.
Y
1578969264
end_time
long
UNIX format timestamp in second.
Y
1579055640
order
int
Number of records sorted by arrival times.
Y
50
group_name
string
Specify a face group, default to all face groups.
N
vip
gender
int
Gender, 1 for male, 2 for female, both male and female if this parameter not provided.
N
1
age_range
int
Age group: 1 for [1,6], 2 for [7,12], 3 for [13,18], 4 for [19,28], 5 for [29,35], 6 for [36,45], 7 for [46,55], 8 for [56, 100]
N
4
age
int
Age and age range are mutually exclusive. First query the faces that meet the age. If the
age is not provided but the age range is provided, query the faces that meet the age range;
if the age and the age range are not provided, query the faces of all ages.
N
4
item1
string
It can be matched according to the custom attribute, and the match of the custom attribute 1.
If you need to use the custom attribute query, make sure that the specified face group has added
the corresponding custom attribute, otherwise the query fails (you cannot add the custom attribute
for the group of strangers and regular)
N
value1
item2
string
Match of custom attribute 2
N
value2
item3
string
Match of custom attribute 3
N
value3
item4
string
Match of custom attribute 4
N
value4
item5
string
Match of custom attribute 5
N
value5
page_num
int
Current page number, default and minimum is 1
N
1
page_size
int
Current page entries, default is 10, range is [1, 100]
N
10
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 266, 267, 268, 269, 270, 271, 272, 273, 274, 277, 280, 281, 282, see Error Code for further details.
total_num
int
Total number of faces meeting the specified conditions
return_num
int
Current number of faces
faceid
string
Face ID
group_name
string
Group name
age
string
Age. If it is blank, the real age is not set
age_range
int
1 for [1,6], 2 for [7,12], 3 for [13,18], 4 for [19,28], 5 for [29,35], 6 for [36,45], 7 for [46,55], 8 for [56, 100]
gender
int
Gender, 0 for unknown, 1 for male, 2 for female
arrive_times
int
Number of arrivals
item1
string
Custom attribute 1, which will be returned only after the user has added it
item2
string
Custom attribute 2, which will be returned only after the user has added it
item3
string
Custom attribute 3, which will be returned only after the user has added it
item4
string
Custom attribute 4, which will be returned only after the user has added it
item5
string
Custom attribute 5, which will be returned only after the user has added it
Request Example
The following is a list of face ID information obtained from 30-year-old male VIP guests who have visited most times in two days from June 14, 2019 to June 15, 2019.
POST openapi/peopleFlow/getVisitorList HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Get the visit records of a specified face ID within a specified time.
Request link
https://192.168.0.1/openapi/peopleFlow/getFaceVisitDetail, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
start_time
long
UNIX format timestamp in second.
Y
1578969264
end_time
long
UNIX format timestamp in second.
Y
1579055640
faceid
string
Face ID
Y
000001
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 266, 267, 275, 277, 280, see Error Code for further details.
total_times
int
Total visits
came_in_time
long array
List of visit times
Request Example
POST openapi/peopleFlow/getFaceVisitDetail HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Create a new face group via this interface and configure its attributes. The IPC supports up to 10 face groups including the default stranger group and regular group and maximum 8 user groups.
Request link
https://192.168.0.1/ openapi/face/createGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
name
string
The name of group, maximum 96 characters. The system has two default group, stranger and regular.
Y
vip
capacity
int
Capacity of group, the sum of all group capacities shall not exceed 30000.
Y
10000
Description
string
Description of group, maximum 150 characters.
Y
Customers with gold card.
Note:
1. The first character of name shall not be a blank space;
2. By default, the name of stranger group is stranger, the name of regular group is regular.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 211, 212, 220, see Error Code for further details.
Request Example
POST openapi/face/createGroup HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& name=vip&capacity=10000&description=Customers with gold card.
Response Example
{
"code": 0
}
2. Edit Face Group
Description
This API is used to edit attributes of a face group.
Request link
https://192.168.0.1/openapi/face/updateGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
old_name
string
The name of Face Group you want to modify.
Y
vip
name
string
The new name of Face Group, can be same with old_name.
Y
svip
capacity
int
The new capacity of Face Group, can be same with the old capacity.
Y
10000
Description
string
Description of group, maximum 150 characters.
Y
Customers with platinum card.
Note:
1.name must be same with old_name when you edit stranger group or regular group, in other words, the name of default groups art not allowed to be modified;
2.The first character of name shall not be a blank space.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 204, 211, 212, 220, see Error Code for further details.
Request Example
POST openapi/face/updateGroup HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K& old_name=vip&name=svip&capacity=10000&description=Customers with platinum card.
Response Example
{
"code": 0
}
3. Configure The Stranger-to-regular Conditions
Description
Stranger and regular face groups will be created once the IPC is activated. The records in stranger face group will be moved to the regular face group when they meet the moving conditions which is 5 times in 7 days by default. This API is used to Configure The Stranger-to-regular Conditions.
Request Link
https://192.168.0.1/openapi/face/updateMigration, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
arrive_times
int
value range 1~10.
Y
5
period
int
value range 1~100, unit: day.
Y
20
Note:
It means that record will be move from stranger to regular while the face was captured more than [arrive_times] times in [period] days. So this api is only applicable to the stranger face group.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.
Request Example
POST openapi/face/updateMigrationHTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Each face group has 5 user-defined fields or attributes that can be filled with string with up to 50 characters for every records, except the default groups.
It is strongly recommended to add user-defined attributes after creating the face group and before adding any record with this interface.
Request Link
https://192.168.0.1/openapi/face/addFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
num
int
Number of attributes to add.
Y
1
group_name
string
Name of group.
Y
vip
name_list
string array
Attribute name list, maximum 50 characters in length for each name.
Y
[“hobby”]
Note:
1. The default groups (stranger and regular) are not allowed to add attributes;
2. The following names are reserved and can not be used as attribute names: group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num。
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, see Error Code for further details.
Request Example
POST openapi/face/addFaceInfoItem HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
This interface is used to delete user-defined attributes in a specified face group.
Request Link
https://192.168.0.1/openapi/face/removeFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
num
int
Number of attributes to delete.
Y
1
group_name
string
Name of group
Y
vip
name_list
string
Attribute name list, maximum 50 characters in length for each name.
Y
[“hobby”]
Note: ID of default group cannot be deleted.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, 243, see Error Code for further details.
Request Example
POST openapi/face/removeFaceInfoItem HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
This API is used to add a face record in the specified group.
Request Type
Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.
Request Link
https://192.168.0.1/openapi/face/addFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
faceid
string
Faceid, a positive 64-bit numeric string, the device will generate if not supply.
N
123456
pic
file
Face photo file in jpg/png format, maximum resulution is 1920*1080, the size of file must not exceed 1M bytes.
Y
example.jpg
group_name
string
name of group
Y
stranger
age
int
preset attribute, age
N
14
gender
int
preset attribute , gender, 0 for unknown, 1 for male, 2 for female
N
1
item1
string
user-defined attribute 1
N
value1
item2
string
user-defined attribute 2
N
value2
item3
string
user-defined attribute 3
N
value3
item4
string
user-defined attribute 4
N
value4
item5
string
user-defined attribute 5
N
value5
Note:
1.The preset attributes above are built-in attribute of face record in the databse, and others include item1/item2/item3/item4/item5 are user-defined attributes. Users must call the interface to add user-defined attributes before using; The IPC will ignore the parameters if the corresponding attributes are not found.
2.If the attribute age is not provided, the age range will be set automatically by the IPC;
3. If the attribute gender is not provided, this field will be set automatically by the IPC.
Response Parameters
Parameter
Type
Description
Example
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 206, 208, 210, 211, 220, see Error Code for further details.
faceid
string
faceid
123456
Request Example
POST /openapi/face/addFace HTTP/1.1 Host: 192.168.0.1 Content-Type: multipart/form-data; boundary=————————–962974737227706390007700 Content-Length: 1683
Update the information of the specified face record.
Request Link
https://192.168.0.1/openapi/face/updateFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Method
Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
group_name
string
Name of group
Y
svip
faceid
string
Face ID
Y
21
new_group_name
string
New group name, the record will be moved to this group if provided.
N
vip
pic
file
Face photo file in jpg/png format, maximum resulution is 1920*1080, the size of file must not exceed 1M bytes.
N
example.jpg
age
int
preset attribute, age
N
10
gender
int
preset attribute , gender, 0 for unknown, 1 for male, 2 for female
N
1
item1
string
user-defined attribute 1
N
value1
item2
string
user-defined attribute 2
N
value2
item3
string
user-defined attribute 3
N
value3
item4
string
user-defined attribute 4
N
value4
item5
string
user-defined attribute 5
N
value5
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 204, 207, 208, 210, 211, 220, see Error Code for further details.
Request Example
POST /openapi/face/addFace HTTP/1.1 Host: 192.168.0.1 Content-Type: multipart/form-data; boundary=————————–962974737227706390007700 Content-Length: 1683
The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.
Response Example
{
"code": 0
}
12. Get Face Record
Description
Get information of the face record by face ID.
Request Link
https://192.168.0.1/openapi/face/getFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
faceid
string
faceid
Y
123456
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
faceid
string
Face ID
group_name
string
Group name
age
int
age, NULL means user has not set the age of the face record.
age_range
int
age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender
int
gender, 0 means unknown, 1 means male, 2 means female
arrive_count
int
Total number of arrivals
arrive_time
int
Timestamp of the last arrival
item1
string
User-defined attribute 1, only returned if exist.
item2
string
User-defined attribute 2, only returned if exist.
item3
string
User-defined attribute 3, only returned if exist.
item4
string
User-defined attribute 4, only returned if exist.
item5
string
User-defined attribute 5, only returned if exist.
Request Example
POST openapi/face/getFace HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.
13. Get List of Face Records
Description
Get list of the face records in the specified group.
Request Link
https://192.168.0.1/openapi/face/getFaceList, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
group_name
string
name of group
Y
vip
page_num
int
Current page number, default and minimum is 1
N
4
page_size
int
Current page entries, default is 10, range is [1, 100]
N
10
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
total_num
int
Total number of face records
return_num
int
Number of face records currently returned
faceid
string
Face ID
age
int
age, NULL means user has not set the age of the face record.
age_range
int
age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender
int
gender, 0 for unknown, 1 for male, 2 for female
arrive_count
int
Total number of arrivals
arrive_time
int
Timestamp of the last arrival
item1
string
User-defined attribute 1, only returned if exist.
item2
string
User-defined attribute 2, only returned if exist.
item3
string
User-defined attribute 3, only returned if exist.
item4
string
User-defined attribute 4, only returned if exist.
item5
string
User-defined attribute 6, only returned if exist.
Request Example
POST openapi/face/getFaceIDList HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
14. Get Face Records That Don’t Arrive For The Longest Time
Description
Get list of last N face records sorted by the “last arrival” time.
Request Link
https://192.168.0.1/openapi/face/getFaceByArrival, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
group_name
string
Name of group
Y
vip
num
int
Number of face records, range is 1~10, default is 1.
N
2
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 207, 211, see Error Code for further details.
return_num
int
Number of face records currently returned
faceid
string
Face ID
age
int
Age, NULL means user has not set the age of the face record.
age_range
int
age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender
int
Gender, 0 for unknown, 1 for male, 2 for female
arrive_count
int
Total number of arrivals
arrive_time
int
Timestamp of the last arrival
item1
string
User-defined attribute 1, only returned if exist.
item2
string
User-defined attribute 2, only returned if exist.
item3
string
User-defined attribute 3, only returned if exist.
item4
string
User-defined attribute 4, only returned if exist.
item5
string
User-defined attribute 5, only returned if exist.
Request Example
POST openapi/face/getFaceByArrival HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.
Request Link
https://192.168.0.1/openapi/face/getFaceByPicture, 192.168.0.1 needs to be replaced with the actual IP address of IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
pic
file
Face photo file in jpg/png format, maximum resulution is 1920*1080, the size of file must not exceed 1M bytes.
Y
11024.jpg
Response Parameters
Parameter
Type
Description
Example
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 210, 211, 283, see Error Code for further details.
faceid
string
Face ID
group_name
string
Group name
age
int
age, NULL means user has not set the age of the face record.
age_range
int
age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18 years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means 36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender
int
gender, 0 means unknown, 1 means male, 2 means female
arrive_count
int
Total number of arrivals
arrive_time
int
Timestamp of the last arrival
item1
string
User-defined attribute 1, only returned if exist.
item2
string
User-defined attribute 2, only returned if exist.
item3
string
User-defined attribute 3, only returned if exist.
item4
string
User-defined attribute 4, only returned if exist.
item5
string
User-defined attribute 5, only returned if exist.
Request Example
POST /openapi/face/getFaceByPicture HTTP/1.1 Host: 192.168.0.1 Content-Type: multipart/form-data; boundary=————————–962974737227706390007700 Content-Length: 1683
Get a video clip before and after a period of time.
When this api called, the IPC will get a video clip which the period is a multiple of 4 seconds. The spanning of the video clip depends on the parameters passed in. The return parameter of the api is the download link of the video clip.
The download link of the video clip will take effect in 4 to 12 seconds. The Effective time is related to parameters passed in.
Request link
https://192.168.0.1/openapi/media/getCurVideos
Request Parameters
Blow are private parameters for this API, please refer to Public Parametersfor more details.
Parameter
Type
Description
Required
Example
preceding
int
Time period before current. 0, 4, and 8 allowed only.
Y
0
following
int
Time period after current. 0, 4, and 8 allowed only.
Y
8
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 236, 237, see Error Code for further details.
url
string
Download link of the video clip, which will take effect after 4 to 12 seconds.
Dynamic detection on the IPC supports detection and alarm motional and audio events. This API is used to set dynamic detection thresholds and period.
Request Link
https://192.168.0.1/openapi/config/setDynamicDetect, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
motion_level
int
Motion detection level, range is [0, 3] where 3 is most sensitive.
Y
2
audio_level
int
Audio detection level, range is [0, 3] where 3 is most sensitive.
Y
2
weekday
int
Detection period in a week. Bits are used to represent the weekdays:
bit 0 is for Monday, bit 1 is for Tuesday, bit 2 is for Wednesday,
bit 3 is for Thursday, bit 4 is for Friday, bit 5 is for Saturday,
bit 6 is for Sunday and bit 7 is for 7 x 24 hours. For example,
0b00001111 means detection is on from Monday to Thursday,
0b00010101 means detection is on at Monday, Wednesday and Friday.
Y
128 (decimal value of 0b10000000), 21 (decimal value of 0b00010101)
start_time
long
Start time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Y
200
stop_time
long
Stop time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Y
400
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 3, 5, 7, 114, 115, 116, 117, see Error Code for further details.
Request Example
POST /openapi/config/setDynamicDetect HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded
https://192.168.0.1/openapi/config/getDynamicDetect, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
motion_level
int
Motion detection level, range is [0, 3] where 3 is most sensitive.
audio_level
int
Audio detection level, range is [0, 3] where 3 is most sensitive.
weekday
int
Detection period in a week. Bits are used to represent the weekdays:
bit 0 is for Monday, bit 1 is for Tuesday, bit 2 is for Wednesday,
bit 3 is for Thursday, bit 4 is for Friday, bit 5 is for Saturday,
bit 6 is for Sunday and bit 7 is for 7 x 24 hours. For example,
0b00001111 means detection is on from Monday to Thursday,
0b00010101 means detection is on at Monday, Wednesday and Friday.
start_time
long
Start time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
stop_time
long
Stop time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Request Example
POST /openapi/config/getDynamicDetect HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
In order to use the IPC through OpenAPI, the user need to get the IP address of the IPC first.
The first step is to connect the IPC to the network. There are two ways to connect the device to Internet, wired and wireless. Wired network is preferred for its high stability and reliability.
1. Wired Network
For an IPC device with an Ethernet Port, you can connect it to a gateway, such as a wireless router, with an Ethernet cable, then the device will obtain an IP address from the DHCP server.
If the network is available, the LED on the IPC will soon turn blue, indicating the IPC has connected to the Internet.
2. Wireless Network
The steps to connect to a wireless network are as follows:
Use your mobile phone or PC to scan the wireless hotspot of the IPC. The SSID of the wireless hotspot is SUNMI_XXXX, where XXXX is the hexadecimal number of the last 2 bytes of the MAC address. The MAC address can be found on the label on the back of the device or on the packaging box.
Use your mobile phone or PC to connect to the wireless hotspot. The mobile phone or PC will obtain an IP address assigned by the IPC, which is usually 192.168.200.XXX. The gateway address of mobile phone or PC is the address of IPC, which is usually 192.168.200.1.
Use the wireless configuration API to connect to wireless network. If everything is done correctly, the IPC will obtain the IP address from the gateway.
If the network is available, the LED on the IPC will soon turn blue, indicating that the IPC has connected to the Internet.
3. Get the Device’s IP address
After the setup of IPC’s network, the next step is to get the IP address of the IPC.
SUNMI provides Device Discovery Protocol for discovering all SUNMI devices that support this protocol on the same LAN. It’s used to scan and collect the basic information of the SUNMI devices, including serial number and IP addresss.
4. SUNMI Device Discovery Protocol
The SUNMI Device Discovery Protocol is for one device to broadcast UDP messages to find SUNMI devices in the same LAN, and other devices supporting this protocol will respond to those messages, which include basic informations of themselves.
4.1 Message Format
The Payload of UDP message is shown in the figure below. The whole message consists of header, Payload and CRC checksum.
4.1.1 Header
The Message Header, including flag, protocol version, message type and length.
Flag: currently fixed to 0xFFFF33FF.
Version: protocol version, currently only version 0x1 is supported.
Type: message type, 0x1 for the discovery request message and 0x2 for the discovery response message.
Len: length of the payload after base64 encoding.
4.1.2 Payload
This field contains the final payload. The raw data is in json format, and it needs to be base64 encoded before put on the payload.
4.1.3 CRC
This field contains the CRC32 (32-bit Cyclic Redundancy Check) value calculated from the header and payload fields. The receiver use this value to verify the message.
4.2 Protocol Port
Both sender and receiver use port 10001.
4.3 Discovery Request
When the sender wants to find devices support the SUNMI Device Discovery Protocol in the LAN, it need to send UDP broadcast message. The details are as follows:
In this message, field Type is 0x01, Len is 0x0, it means that the payload is empty.
4.4 Discovery Response
This message is sent by the receiver. It is used to tell the sender the informations of itself. The type is 0x02, and the length is calculated according to the data.
The payload content is shown in the figure below, which is the device information in json format.
ip: the IP address of the device.
mac: the MAC address of the device.
firmware: the firmware version of the device, such as 1.0.0
name: device name, currently fixed as SUNMI.
model: device model, such as FM020.
type: device type, currently fixed as IPC.
network: the mode of network connection about the sender. If the sender is connected to the wireless hotspot of IPC, the value is “AP”. If the sender is connected to same LAN of router with IPC, the value is “LAN”.
deviceid: device serial number.
4.5 Timeout handling
It is suggested to send Discovery Request messages with an interval of 1s, and 3 times at most. This is to prevent loss of messages from some devices.
After sending 3 Request Messages, the sender should set a timeout period of 2s, after which the Discovery Response message will not be received. That means the Discovery Response message can only be received in 5s after the first Discovery Request message.
After receiving a Discovery Request message, the receiver should reply with a Discovery Response message in unicast mode immediately.
