RCS-2000 API

RCS-2000 API

Legal Information

© 2021 Hangzhou Hikrobot Technology Co., Ltd. All rights reserved.

This Document (hereinafter referred to be "the Document") is the property of Hangzhou Hikrobot
Digital Technology Co., Ltd. or its affiliates (hereinafter referred to as "Hikrobot"), and it cannot be
reproduced, changed, translated, or distributed, partially or wholly, by any means, without the
prior written permission of Hikrobot. Unless otherwise expressly stated herein, Hikrobot does not
make any warranties, guarantees or representations, express or implied, regarding to the
Document, any information contained herein.
LEGAL DISCLAIMER
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE DOCUMENT IS PROVIDED "AS IS"
AND "WITH ALL FAULTS AND ERRORS". HIKROBOT MAKES NO REPRESENTATIONS OR WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. IN NO EVENT WILL HIKROBOT BE
LIABLE FOR ANY SPECIAL, CONSEQUENTIAL, INCIDENTAL, OR INDIRECT DAMAGES, INCLUDING,
AMONG OTHERS, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION OR LOSS
OF DATA, CORRUPTION OF SYSTEMS, OR LOSS OF DOCUMENTATION, WHETHER BASED ON BREACH
OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, IN CONNECTION WITH THE USE
OF THE DOCUMENT, EVEN IF HIKROBOT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES OR LOSS.

i
 RCS-2000 API

Contents
Chapter 1 Overview .................................................................................................................... 1
1.1 Introduction ........................................................................................................................... 1
1.2 Update History ....................................................................................................................... 1
1.3 Notice ..................................................................................................................................... 2
Chapter 2 API Description ........................................................................................................... 4
2.1 API Format ............................................................................................................................. 4
2.2 Operation Method ................................................................................................................. 5
2.3 Message Format .................................................................................................................... 5
2.4 Others .................................................................................................................................... 6
Chapter 3 Security ...................................................................................................................... 7
3.1 Authentication ....................................................................................................................... 7
Chapter 4 Typical Application ..................................................................................................... 8
4.1 AMR Carries Rack and Leaves without Rack .......................................................................... 8
4.2 AMR Carries Rack and Backs with Rack ................................................................................. 8
4.3 Roller AMR Receives Materials ............................................................................................ 10
Chapter 5 API Reference ........................................................................................................... 11
5.1 API List ................................................................................................................................. 11
5.2 API Provided by RCS-2000 .................................................................................................... 12
5.2.1 genAgvSchedulingTask ................................................................................................ 12
5.2.2 continueTask ............................................................................................................... 15
5.2.3 cancelTask ................................................................................................................... 17
5.2.4 setTaskPriority ............................................................................................................. 19
5.2.5 bindPodAndBerth ....................................................................................................... 20
5.2.6 bindPodAndMat .......................................................................................................... 22
5.2.7 bindCtnrAndBin .......................................................................................................... 23
5.2.8 lockPosition ................................................................................................................. 25

ii
 RCS-2000 API

5.2.9 syncMapDatas ............................................................................................................. 26

5.2.10 queryPodBerthAndMat ............................................................................................. 29
5.2.11 queryTaskStatus ........................................................................................................ 31
5.2.12 queryAgvStatus ......................................................................................................... 33
5.2.13 stopRobot .................................................................................................................. 35
5.2.14 resumeRobot ............................................................................................................ 36
5.2.15 setAreaState .............................................................................................................. 38
5.2.16 blockArea .................................................................................................................. 39
5.2.17 genPreScheduleTask ................................................................................................. 41
5.3 API Provided by Third-Party ................................................................................................. 42
5.3.1 agvCallback ................................................................................................................. 42
5.3.2 warnCallback ............................................................................................................... 44
5.3.3 bindNotify ................................................................................................................... 46
Appendix A. Status Code .......................................................................................................... 49
Appendix B. AMR Status ........................................................................................................... 50

iii
 RCS-2000 API

Chapter 1 Overview

1.1 Introduction
This manual provides some open APIs designed on RESTful style for the third-party platform to
connect to Robot Control System (hereafter referred as to "RCS-2000") and control Automatic
Mobile Robots (AMRs) for logistics scheduling in the factory. Some typical applications developed
by these open APIs are also provided for reference.
The RCS-2000 is a logistics scheduling system used in the smart factory, it can generate and assign
tasks to different kinds of AMRs to carry the racks, materials, goods, and so on, according to the
task conditions. It can also monitor the task executing status to processing the exception situations
in time, which makes sure the regular and accurate working of AMRs.

1.2 Update History

Summary of Changes in Version 3.1.4_May/2021

Version Summary of Changes

Version 3.1.4_May/ 1. Edited the request message of API genAgvSchedulingTask :
2021 deleted one field sceneTyp;
added 3 location types to the field type of positionCodePath: "07"
(container ID), "08" (roadway strategy), and "09" (roadway area).
2. Edited the request message of API bindPodAndBerth :
added one field characterValue (trait value).
3. Added one API for binding or unbinding a container and a bin:
bindCtnrAndBin .
4. Added one API for emptying or unblocking the specified area:
blockArea .
5. Added one API for sending the pre-schedule: genPreScheduleTask .
6. Added one API for notifying the third-party platform of the binding or
unbinding operation: bindNotify .

1
 RCS-2000 API

Summary of Changes in Version 3.1.0_July/2020

Version Summary of Changes

Version 3.1.0_July/ 1. Edited the API absolute address to "/rcms/services/rest/
2020 hikRpcService/[apiName]".
2. Edited the default port No. in the API to 8182.
3. Updated the API genAgvSchedulingTask :
added the forklift function.
4. Extended the request message of API cancelTask :
added one parameter forceCancel (task cancel mode).
5. Extended the request message of API bindPodAndBerth :
added one parameter podDir (rack direction).
6. Added one API for stopping the specified AMR or all AMRs:
stopRobot .
7. Added one API for resuming the AMR: resumeRobot .
8. Added one API for blocking or unblocking the area: setAreaState .
9. Edited the API for searching for the AMR status queryAgvStatus :
edited the request URL to "http:/​/​[address]:8083/​rcms-dps/​rest/
queryAgvStatus".

Summary of Changes in Version 2.5_May/2020

Version Summary of Changes

Version 2.5_May/2020 1. Edited the API absolute address to "/cms/services/rest/hikRpcService/
[apiName]".
2. Deleted one API for sending data synchronization requirement to the
third-party platform when the information has changed: syncNotify.

Summary of Changes in Version 2.2.3_June/2019

New document.

1.3 Notice
• When the RCS-2000 calls the APIs provided by the third-party platform, the default connection
timeout threshold is 30 seconds, and the default returning timeout threshold is 60 seconds. If
the timeout is longer than the default thresholds, the RCS-2000 will return the information of
connection failed.

2
 RCS-2000 API

If connecting to the third-party platform failed, you can try again after five seconds, and by
default, up to 5 failure connection attempts are allowed.
• When calling an API, make sure the reqCode (request IDs) in the request and response message
are same.
• If the third-party platform is developed by C# or JAVA language, we have provided demos to
quickly start, please contact our technical supports to get the demos.
• The exhaustive request and response parameters are more than that introduced in this manual,
the third-party platform can choose required parameters according to the business.
• REST (REpresentational State Transfer) is a protocol design method which abstracts all
information as the resources. The abstracted resources are marked by the uniform identifies,
i.e., URI (Uniform Resource Identifiers) for simple and extendable management.

3
 RCS-2000 API

Chapter 2 API Description

2.1 API Format

The APIs in this manual are all in URL format, which defines and provides a unique address for
resources to access and implement different functions.
The detailed API format definition is shown below:
<protocol>://[address][:port][abs_path]

protocol
Protocol type that designing APIs based on, in this manual, the protocol type is "http".
address
Domain name or IP address of network device.
port
Port No.: for web server, the default port No. is 8182.
abs_path
An absolute address to define a resource, you can connect to and operate the resource via this
address. It varies according to different platform.
• For RCS-2000, the absolute address of its resources is "/rcms/services/rest/hikRpcService/
[apiName]".
• For the third-party platform, the absolute address of its resources is "/xxx/[apiName]".

Note
• The [apiName] in the absolute address is used to distinguish the resources and functions, such
as genAgvSchedulingTask, whose function is to generate task.
• To simplify the description in this manual, we use apiName to replace the complete API format.
• For API of searching for AMR status, the request URL is "http://[address][:port]/rcms-dps/rest/
queryAgvStatus", and the port No. is 8083.

Base Access Address

To simplify API calling, you can define the path before apiName as the base access address
baseURL. See the table below for details:

Platform baseURL
RCS-2000 http:/​/​IP:PORT/​rcms/​services/​rest/​hikRpcService

4
 RCS-2000 API

Platform baseURL

Note
The default web server port No. is 8182.

RCS-2000 (AMR status http:/​/​IP:PORT/​rcms-dps/​rest

search)
Note
The default port No. is 8083.

2.2 Operation Method

To implement different functions of resources represented by each API, operation method is
required. As the APIs in this manual is designed based on HTTP, the operation methods are same as
that supported by HTTP.

Method Description
POST Create or add resources.
GET Search or get resources.
PUT Update or set resources.
DELETE Delete resources.

Note
In this manual, only the POST operation method is available.

2.3 Message Format

During the development based on the open APIs, the request and response message for
communication and interaction is in JSON format, and the fields in the message are named by
lower camel case.
JSON format is a subset of JAVA script, which is a lightweight data format, and this format can be
quickly parsed. See the example below.
{
"code": "0",
"data": "F01169C808C317111G",
"message": "successful",
"reqCode": "468513"
}

5
 RCS-2000 API

2.4 Others

Time Format
The time appeared in the interaction between device and system adopts ISO8601 format, that is,
"YYYY-MM-DD hh:mm:ss". For example, 2019-06-01 08:30:00.
Error Processing
When calling the open APIs, if error occurs, the response message will directly return the error
code, you can get the error description and reason according to the returned response message.
See Status Code (Appendix. A) for detailed error codes and description.

6
 RCS-2000 API

Chapter 3 Security

3.1 Authentication
The authentication of the open API is based on token (tokenCode) transmitted during request and
response. The token is a string generated by Hikrobot system and will be transmitted to the third-
party platform for authentication when calling APIs.

7
 RCS-2000 API

Chapter 4 Typical Application

4.1 AMR Carries Rack and Leaves without Rack

In this application scene, the AMR carries a rack from the location A to a specific location B after
the third-party platform calling an API to set task parameters and generate task. When arriving at
location B, the AMR puts down the rack and directly leave. This application scene is usually
available when the time consumption of processing goods on rack is long.
Steps

Figure 4-1 Flow of AMR Carrying Rack and Leaving without Rack
1. The third-party platform calls genAgvSchedulingTask to generate task via the RCS-2000.
The AMR starts executing the task and carrying a rack to a specified location.
2. The AMR puts down the rack when it arrived at the location.
3. The RCS-2000 calls agvCallback to send task executing status to the third-party platform for
notifying the AMR to leave.

4.2 AMR Carries Rack and Backs with Rack

In this application scene, the AMR carries a rack from the location A to a specific location B after
the third-party platform calling an API to set task parameters and generate task. When arriving at
location B, the AMR keeps carrying the rack and waits until the third-party platform call an API to
continue the task. And then the AMR carries back the rack whose goods has been processed to

8
 RCS-2000 API

location A. This application scene is usually available when the time consumption of processing
goods on rack is short.
Steps

Figure 4-2 Flow of AMR Carrying Rack and Backing with Rack
1. The third-party platform calls genAgvSchedulingTask to generate task via the RCS-2000.
The AMR starts executing the task and carrying out a rack to a specified location.
2. The RCS-2000 calls agvCallback to send task executing status to the third-party platform when
the rack is carried to the location.
3. The third-party platform starts performing some operations, such as pickup, tally, and so on.
4. The third-party platform calls continueTask when all operations are completed to continue
executing task.
The AMR carries back the rack.
5. The RCS-2000 calls agvCallback to send task executing status to the third-party platform when
the rack is carried back.

9
 RCS-2000 API

4.3 Roller AMR Receives Materials

The roller AMR is mainly applied to improve the automatic level of factory logistics. It can reduce
the length of conveyor belt during long distance transportation; for the workshop which can not
use forklift, it can convey very heavy material. Here introduces the progress of controlling roller
AMR to complete the task of receiving materials.
Steps

Figure 4-3 Flow of Roller AMR Receiving Materials

1. The third-party platform calls genAgvSchedulingTask to generate task via the RCS-2000.
The roller AMR executes the task, arrives at the transferring point, and starts rolling to get ready
for receiving materials.
2. The RCS-2000 calls agvCallback to send the task executing status to the third-party platform
when the AMR is ready for receiving materials.
3. The third-party platform notifies the transferring area to start rolling and sending materials to
the roller AMR.
4. The third-party platform calls continueTask to continue executing task when the materials is
received by roller AMR..
The roller AMR stops rolling and leaves the transferring point with received materials.

10
 RCS-2000 API

Chapter 5 API Reference

5.1 API List

List of Commonly Used APIs

Function API Name Provider

Create a task genAgvSchedulingTask RCS-2000
Continue executing the next sub task. continueTask RCS-2000
Cancel a task cancelTask RCS-2000
Send the task executing status to third-party agvCallback Third-party
platform Platform

List of Optional APIs

Function API Name Provider

Set the task priority setTaskPriority RCS-2000
Bind and unbind the rack and location bindPodAndBerth RCS-2000
Bind and unbind the material batch and rack bindPodAndMat RCS-2000
Enable or disable the location lockPosition RCS-2000
Synchronize map information with that in RCS-2000 syncMapDatas RCS-2000
Search relations among rack, location, and material queryPodBerthAndMat RCS-2000
batch
Search for the task executing status queryTaskStatus RCS-2000
Search for the AMR status queryAgvStatus RCS-2000
Stop AMR(s) stopRobot RCS-2000
Resume a AMR resumeRobot RCS-2000
Block or unblock a area setAreaState RCS-2000
Bind or unbind the container and bin bindCtnrAndBin RCS-2000
Empty or unblock the specified area blockArea RCS-2000
Send the pre-schedule genPreScheduleTask RCS-2000

11
 RCS-2000 API

Function API Name Provider

Send the alarm to the third-party platform warnCallback Third-party
Platform
Notify the third-party platform of the binding or bindNotify Third-party
unbinding operation Platform

5.2 API Provided by RCS-2000

5.2.1 genAgvSchedulingTask
Robot Control System (RCS) creates a task and the third-party platform applies the task to AMR.

API Definition
Table 5-1 POST http://[address][:port]/rcms/services/rest/hikRpcService/genAgvSchedulingTask
API Name genAgvSchedulingTask
Function Robot Control System (RCS) creates a task and the third-party platform applies the
task to AMR.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
taskTyp String 16 Req. Task type, which is the same as the major task
type configured in RCS-2000:
• Build-in task type:
"F01"-carry and transfer rack,

12
 RCS-2000 API

"F02"-empty/full rack exchange,

"F03"-carry and transfer by CMR,
"F04"-rack outbound,
"F05"-rotate rack,
"F06"-elevator task.
• Fork lift task type:
"F11"-transfer from high bay rack to
workstation,
"F12"-transfer from workstation to high bay
rack,
"F13"-transfer from roadway to
workstation,
"F14"-transfer from workstation to
roadway,
"F15"-shuttle from high bay rack to
workstation,
"F16"-shuttle from workstation to high bay
rack,
"F17"-shuttle from roadway to workstation,
"F18"-shuttle from workstation to roadway,
"F20"-cross-floor forklift main task.
ctnrTyp String 16 Opt. Container type, this field is required for
forklift/​CTU (carton to you) task.
ctnrCode String 32 Opt. Container ID, this field is required for forklift/
CTU (carton to you) task.
wbCode String 32 Opt. Workstation ID, which consists of letters and
digits, and it must be same with that
configured by RCS-2000.
positionCo Objec 50 Opt. Rack moving pattern, which consists of
dePath t[] multiple locations (up to 50 locations are
allowed).
positionCode: Location ID, which is
predefined with detailed coordinate
information on map; the maximum string
length is 64 bytes.
type: Location types:
"00"-actual location on map,
"01"-​location of a specific material batch,
"02"-available location of area selection
strategy,

13
 RCS-2000 API

"03"-rack No.,
"04"-available location in an area,
"05"-bin ID (for forklift/​CTU only),
"06"-roadway ID,
"07"-container ID,
"08"-roadway strategy,
"09"-roadway area
podCode String 16 Opt. Rack ID, it can be empty if no rack specified.
podDir String 4 Opt. Rack directions: "180"-leftward, "0"-
rightward, "90"-upward, "-90"-downward; it
can be empty if no direction specified.
podTyp String 16 Opt. Rack types:
"1"-empty rack of all types (default),
"2"-type of rack linked with configured
workstation (if the linked rack is empty, it also
represents empty rack of all types),
other values-empty rack with a specific type.
Rack type No.: empty rack of the specified
type.
materialLo String 32 Opt. Material batch ID.
t You can set materialLot and podCode at same
time to bind the rack with material lot, or you
can set materialLot and wbCode to bind the
material lot with the rack at the specified
workstation.
For roadway tasks, this field is used for
configuring the material trait value.
priority String 3 Opt. Task priority, range: [1,127], and larger
number corresponds to higher priority. If it is
not configured, the task template priority
takes effect.
taskCode String 64 Opt. Task ID, if it is not configured, the system will
generate automatically.
agvCode String 16 Opt. AMR ID, if it is not configured, the RCS-2000
will automatically select an optimal AMR to
execute the task.

14
 RCS-2000 API

data String 2000 Opt. Custom content, up to 2000 characters are

allowed.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned, such as task
ID.
Remarks One of wbCode and positionCodePath must be configured to confirm the location
information in task. If you want to specify multiple locations in the task, e.g., start
location and end location, the field positionCodePath should be configured.
Sample Request {
"reqCode": "468513",
"taskTyp": "F01",
"positionCodePath": [{
"positionCode": "p01",
"type": "00"
},
{
"positionCode": "x02",
"type": "02"
}],
"podCode": "100001",
"podDir": "0",
"priority": "1"
}

Response {
"code": "0",
"data": "F01169C808C317111G",
"message": "successful",
"reqCode": "468513"
}

5.2.2 continueTask
Continue executing the next sub task.

15
 RCS-2000 API

API Definition
Table 5-2 POST http://[address][:port]/rcms/services/rest/hikRpcService/continueTask
API Name continueTask
Function Continue executing the next sub task.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
wbCode String 32 Opt. Workstation ID, it must be same with that
configured by RCS-2000.
podCode String 16 Opt. Rack ID
agvCode String 16 Opt. AMR ID, if it is not configured, the RCS-2000
will automatically select an optimal AMR to
execute the task.
taskCode String 64 Opt. Task ID (UUID). If it is not configured, it will be
automatically generated by RCS-2000, and it is
64 bits UUID.
taskSeq String 32 Opt. Sub task No. to be specified to continue
executing. If this field is not configured, by
default, the next sub task will be executed.
nextPositio Object 40 Opt. The location information of sub tasks. This
nCode field is required when the task type is
externally configured.
positionCode: position ID, which is predefined
with detailed coordinate information on map.

16
 RCS-2000 API

type: location types: "00"-actual location on

map, "02"-strategy
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful"
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Remarks Only one of wbCode, agvCode, taskCode, and podCode should be configured at one
time, and the parameter to be configured depends on the trigger type configured in
the task template. The parameter taskCode is recommended.
Sample Request {
Codes "reqCode": "123",
"taskCode": "123456",
"nextPositionCode": {
"positionCode": "p02",
"type": "00"
}
}

Response {
"code": "0",
"message": "successful",
"reqCode": "123"
}

5.2.3 cancelTask
Cancel the task that is executing or is generated but waiting for being executed.

API Definition
Table 5-3 POST http://[address][:port]/rcms/services/rest/hikRpcService/cancelTask
API Name cancelTask
Function Cancel the task that is executing or is generated but waiting for being executed.
Protocol REST
Provider RCS-2000
Caller Third-party platform

17
 RCS-2000 API

Request Parameter Data Max. Req. Description

Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
forceCance String 16 Opt. Task cancel mode:
l "0" (default)-AMR puts down the rack at any
location, and its status turns to "idle",
"1"-AMR carries the rack and executes
inbound, this mode is supported by latent
mobile robot only.
matterArea String 16 Opt. Inbound area No., it is valid only when the
value of forcecancel is "1"; if this field is not
configured, the inbound area is the
warehouse area.
agvCode String 16 Opt. AMR ID, whose executing task will be
canceled.
taskCode String 64 Opt. ID (UUID) of task to be canceled.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Remarks One of taskCode and agvCode must be configured to confirm the task to be canceled
or the AMR to be freed. If both the two parameters are configured, only the value of
agvCode will take effect.
Sample Request {
Codes "reqCode": "1541954B96B1112",
"forceCancel": "1",
"matterArea": "abc",

18
 RCS-2000 API

"taskCode": "123456"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

Remarks
• If an AMR is executing a task and carrying a rack, when the task is canceled and the cancel mode
is "0", the AMR will put down the rack at any location, and its status turns to "idle"; when the
cancel mode is "1", the AMR will carry the rack and execute inbound, if there is no space of
inbound area, the error will be returned and canceling failed.
• Forklift only supports the cancel mode "0".

5.2.4 setTaskPriority
Set the task priority from 1 to 127, and the larger the value, the higher the priority. The priority
takes effect only when the AMRs are not enough and there are multiple tasks with different
priorities. The tasks will be assigned to the AMR according to priority order.

API Definition
Table 5-4 POST http://[address][:port]/rcms/services/rest/hikRpcService/setTaskPriority
API Name setTaskPriority
Function Set task priority from 1 to 127, and the larger the value, the higher the priority.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS

19
 RCS-2000 API

tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for

third-party platform.
priorities List
taskCode String 64 Req. Task ID (UUID)
priority String 32 Req. Task priority, range: [1,127], the larger the
value, the higher the priority.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful"
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned, such as task
ID.
Remarks You can set the priority for the tasks that are not assigned to the AMR only; If the
task has been assigned to AMR, it is invalid for setting task priority.
Sample Request {
Codes "reqCode": "1234567",
"priorities": [{
"priority": "1",
"taskCode": "1232"
},
{
"priority": "2",
"taskCode": "3214"
}]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1234567"
}

5.2.5 bindPodAndBerth
Bind or unbind the rack and location.

20
 RCS-2000 API

API Definition
Table 5-5 POST http://[address][:port]/rcms/services/rest/hikRpcService/bindPodAndBerth
API Name bindPodAndBerth
Function Bind or unbind a rack and one location.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks When unbinding, to avoid misoperation, both parameters podCode and
positionCode should be configured for verification.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
podCode String 16 Req. Rack ID
positionCo String 32 Req. Position ID, which is predefined with detailed
de coordinate information on map, and it is a
unique string configured via RCS-2000.
podDir String 6 Opt. Rack direction: "0"-horizontal (default), "1"-
vertical. If this field is not configured, the rack
direction is horizontal by default.
characterV String 64 Opt. Trait value (only for racks on the roadway)
alue
indBind String 1 Req. Bind or unbind: "1"-bind, "0"-unbind.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".

21
 RCS-2000 API

reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "12345678",
"podCode": "100001",
"positionCode": "p05",
"podDir": "0",
"indBind": "1"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "12345678"
}

5.2.6 bindPodAndMat
Bind and unbind the material batch and rack.

API Definition
Table 5-6 POST http://[address][:port]/rcms/services/rest/hikRpcService/bindPodAndMat
API Name bindPodAndMat
Function Bind and unbind material batch and rack.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks When unbinding, to avoid misoperation, both parameters podCode and materialLot
should be configured for verification.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS

22
 RCS-2000 API

tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for

third-party platform.
podCode String 16 Req. Rack ID
materialLo String 32 Req. Material batch ID
t
indBind String 1 Req. Bind or unbind: "1"-bind, "0"-unbind.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned, such as task
ID.
Sample Request {
Codes "reqCode": "1541954B96B1112",
"podCode": "100001",
"materialLot": "123",
"indBind": "1"
}

Response {
"code": "0",
"data": "",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.2.7 bindCtnrAndBin
Bind or unbind the container and bin. For CTU (carton to you) and forklift tasks, you can call this
API to write in the container type and ID to the bin.

Request URL Definition

Table 5-7 POST http://[address][:port]/rcms/services/rest/hikRpcService/bindCtnrAndBin
API Name bindCtnrAndBin
Function Bind or unbind the container and bin.
Protocol REST

23
 RCS-2000 API

Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
ctnrCode String 16 Req. Container ID
ctnrTyp String 16 Req. Container type
stgBinCode String 32 Opt. Bin ID.

Note
One of stgBinCode and positionCode is
required.

binName String 32 Opt. Custom bin ID, which will be verified by the
RCS-2000.
For example, when the system configuration
number 10110 is set to true, it indicates that
the custom bin ID and bin ID should be one-
to-one, if one custom bin ID corresponds to
multiple bin ID, an error will be reported.
characterV String 64 Opt. Trait value (only for the forklift roadway)
alue
positionCo String 32 Req. Position ID, which is predefined with detailed
de coordinate information on the map, and it is a
unique string configured via RCS-2000.
This field is used for binding or unbinding
containers and the bin of virtual racks.

24
 RCS-2000 API

Note
One of stgBinCode and positionCode is
required.

indBind String 1 Req. Bind or unbind: "1"-bind, "0"-unbind.

Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
data String 2000 Opt. Custom content to be returned.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "12345678",
"ctnrTyp": "C1",
"stgBinCode": "p05",
"indBind": "1"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "12345678"
}

5.2.8 lockPosition
Enable or disable the location. When the location is disabled, it cannot be found in the area.

API Definition
Table 5-8 POST http://[address][:port]/rcms/services/rest/hikRpcService/lockPosition
API Name lockPosition
Function Enable or disable the location. When the location is disabled, it cannot be found in
the area.
Protocol REST
Provider RCS-2000
Caller Third-party platform

25
 RCS-2000 API

Request Parameter Data Max. Req. Description

Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
positionCo String 32 Req. Position ID, which is predefined with detailed
de coordinate information on map, and it is a
unique string configured via RCS-2000.
indBind String 1 Req. Enable or disable: "1"-enable, "0"-disable.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned, such as task
ID.
Sample Request {
Codes "reqCode": "1541954B96B1112",
"positionCode": "p02",
"indBind": "1"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.2.9 syncMapDatas
Synchronize map information with that in RCS-2000.

26
 RCS-2000 API

API Definition
Table 5-9 POST http://[address][:port]/rcms/services/rest/hikRpcService/syncMapDatas
API Name syncMapDatas
Function Synchronize map information with that in RCS-2000.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
mapDataC String 32 Opt. Unique location code on map
ode
mapShortN String 32 Req. Alias of the map that needs to be
ame synchronized
dataTyp String 6 Opt. Map element type, when this field is not
configured, all location codes of the map will
be synchronized.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data List
cooX String 8 Req. X-coordinate of location code, unit: mm
cooY String 8 Req. Y-coordinate of location code, unit: mm

27
 RCS-2000 API

dataTyp String 2 Req. Map element types: "1"-storage section, "10"-

workstation, "11"-charge station, "20"-interim
storage area, "55"-roadway storage area
direction String 8 Opt. Working station direction, in which a staff
faces a rack to pickup: "180"-​leftward, "0"-
rightward, "90"-upward,"-90"-downward.
mapCode String 16 Req. Map ID
mapDataC String 32 Req. Unique location code on map
ode
positionCo String 32 Req. Position ID, which is predefined with detailed
de coordinate information on map, and it is a
unique string configured via RCS-2000.
berthType String 2 Opt. Storage section types:
"1"-outer storage section,
"2"-inner storage section,
"3"-normal storage section.

Note
This field is required when the value of
dataTyp is 1.

Sample Request {
Codes "reqCode": "1541954B96B1112",
"reqTime": "",
"clientCode": "",
"tokenCode": "",
"mapDataCode": "xxxxxx",
"mapShortName": "xxxxxx",
"dataTyp": ""
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112",
"data": [{
"berthType": "3",
"cooX": "17000.0",
"cooY": "18000.0",
"dataTyp": "1",
"direction": "0",
"mapCode": "AA",
"mapDataCode": "011724AA012414",

28
 RCS-2000 API

"positionCode": "011724AA012414"
},
{
"berthType": "3",
"cooX": "11000.0",
"cooY": "21999.0",
"dataTyp": "10",
"direction": "0",
"mapCode": "AA",
"mapDataCode": "007586AA015172",
"positionCode": "104"
}]
}

5.2.10 queryPodBerthAndMat
Search the relations among rack, location, and material batch.

API Definition
Table 5-10 POST http://[address][:port]/rcms/services/rest/hikRpcService/
queryPodBerthAndMat
API Name queryPodBerthAndMat
Function Search the relations among rack, location, and material batch.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks At least one of the following parameters should be configured: podCode,
materialLot, positionCode, and mapShortName.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.

29
 RCS-2000 API

podCode String 16 Opt. Rack ID

materialLo String 32 Opt. Material batch ID
t
positionCo String 16 Opt. Position ID, which is predefined with detailed
de coordinate information on map, and it is a
unique string configured via RCS-2000.
areaCode String 16 Opt. Area ID
mapShortN String 16 Opt. Map alias
ame
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data Object
areaCode String 16 Opt. Area ID
materialLo String 64 Opt. Material batch ID
t
podCode String 16 Req. Rack ID
mapDataC String 32 Req. Unique location code on map
ode
positionCo String 32 Req. Position ID, which is predefined with detailed
de coordinate information on map, and it is a
unique string configured via RCS-2000.
Sample Request {
Codes "reqCode": "1541954B96B1110",
"mapShortName": "test"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1110",
"data": [{
"podCode": "100001",
"mapDataCode": "P02",
"positionCode": "P02"
},

30
 RCS-2000 API

{
"podCode": "100002",
"mapDataCode": "P03",
"positionCode": "P03"
}]
}

5.2.11 queryTaskStatus
Search for the task executing status according to the task ID or AMR ID, or search for executing
statuses of multiple tasks in batch.

API Definition
Table 5-11 POST http://[address][:port]/rcms/services/rest/hikRpcService/queryTaskStatus
API Name queryTaskStatus
Function Search for the task executing status according to the task ID or AMR ID, or search for
executing statuses of multiple tasks in batch.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
taskCodes String[ 64 Opt. Array of task IDs, and at least one of
] taskCodes and agvCode should be configured.
agvCode String 16 Opt. AMR ID, and at least one of taskCodes and
agvCode should be configured.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.

31
 RCS-2000 API

data Object
taskCode String 64 Req. Task ID (UUID)
taskTyp String 16 Req. Task type
taskStatus String 2 Req. Task status:
"0"-sending exception,
"1"-created,
"2"-​executing,
"3"-sending,
"4"-canceling,
"5"-canceled,
"6"-resending,
"9"-completed,
"10"-interrupted.
Common values are: "0", "1", "2", "5", "9".
agvCode String 16 Opt. AMR ID, this field exists when the task has
been assigned to.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1110",
"taskCodes": ["123", "234"]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1110",
"data": [{
"taskCode": "234",
"taskStatus": "2",
"taskTyp": "F01"
},
{
"taskCode": "123",
"taskStatus": "9",
"taskTyp": "F01"
}]
}

32
 RCS-2000 API

5.2.12 queryAgvStatus
Search for AMR status, including the AMR battery.

API Definition
Table 5-12 POST http://[address]:8083/rcms-dps/rest/queryAgvStatus
API Name queryAgvStatus
Function Search for AMR status, including the AMR battery.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks • API calling frequency:
number of AMRs is less than 100: 5 seconds;
number of AMRs is between 100 and 200: 10 seconds;
number of AMRs is between 200 and 300: 15 seconds.
• The request URI is "http://[address]:8083/rcms-dps/rest/queryAgvStatus"
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
mapShortN String 32 Opt. Alias of the map where the AMR locates.
ame
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
data Object
robotCode String 16 Req. AMR ID
robotDir String 4 Req. AMR direction, range: [-180,360] degrees
robotIp String 64 Opt. AMR IP address

33
 RCS-2000 API

battery String 4 Req. AMR battery, range: [0,100]

posX String 8 Req. AMR X-coordinate, unit: millimeter
posY String 8 Req. AMR Y-coordinate, unit: millimeter
mapCode String 32 Req. ID of map where the AMR locates
speed String 6 Req. AMR current speed, unit: mm/s
status String 6 Req. AMR status, see AMR Status for details.
exclType String 1 Req. Whether the AMR is excluded: "1"-excluded,
"0"-not excluded.

Note
No task will be assigned to the excluded
AMR.

stop String 1 Req. Whether the AMR is stopped: "0"-no, "1"-yes.

podCode String 16 Opt. Carried rack ID
podDir String 6 Opt. Direction of move with rack
path String[ 300 Opt. Task execution path, unit: millimeter, format:
] [x-coordinate, y-coordinate, direction], e.g.,
["[x,y,dir]","[x,y,dir]", "[x,y,dir]"]
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1112",
"reqTime": "2020-04-03 10:08:06",
"mapShortName": "test"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112",
"data": [{
"robotCode": "1001",
"robotDir": "180",
"battery": "80",
"posX": "1.0",
"posY": "2.0",
"mapCode": "AA",
"speed": "100",

34
 RCS-2000 API

"status": "1",
"exclType": "0",
"stop": "1",
"podCode": "200001",
"podDir": "90",
"path": [
"[10000,20000,90]",
"[20000,30000,-90]",
"[20000,30000,180]",
"[30000,40000,0]"
],
},
{
"robotCode": "1001",
"robotDir": "180",
"battery": "80",
"posX": "1.0",
"posY": "2.0",
"mapCode": "AA",
"speed": "100",
"status": "1",
"exclType": "0",
"stop": "1",
"podCode": "200001",
"podDir": "90",
}]
}

5.2.13 stopRobot
Stop the specified AMR or all AMRs.

API Definition
Table 5-13 POST http://[address][:port]/rcms/services/rest/hikRpcService/stopRobot
API Name stopRobot
Function Stop the specified AMR or all AMRs.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.

35
 RCS-2000 API

reqCode String 32 Req. Request ID, if a request is repeatedly

submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
robotCoun String 64 Opt. The number of AMRs to be stopped, "-1"-all
t AMRs.
mapShortN String 32 Opt. Alias of the map where the AMR locates.
ame
Note
This field is required when the value of
robotCount is "-1".

robots String[ 16 Opt. List of AMR IDs.

]
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1112",
"robotCount": "2",
"robots": [
"1001",
"1002"
]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.2.14 resumeRobot
Resume the AMR, the resumed AMR will continue executing the uncompleted task.

36
 RCS-2000 API

API Definition
Table 5-14 POST http://[address][:port]/rcms/services/rest/hikRpcService/resumeRobot
API Name resumeRobot
Function Resume the AMR, the resumed AMR will continue executing the uncompleted task.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
robotCoun String 64 Opt. The number of AMRs to be resumed, "-1"-all
t AMRs.
mapShortN String 32 Opt. Alias of the map where the AMR locates.
ame
Note
This field is required when the value of
robotCount is "-1".

robots String[ 16 Opt. List of AMR IDs

]
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1112",
"robotCount": "2",

37
 RCS-2000 API

"robots": [
"1001",
"1002"
]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.2.15 setAreaState
Block or unblock the specified area.

API Definition
Table 5-15 POST http://[address][:port]/rcms/services/rest/hikRpcService/setAreaState
API Name setAreaState
Function Block or unblock the specified area.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks You can configure the area via RCS-2000
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
matterArea String 16 Req. ID of the area to be blocked or unblocked
indBind String 1 Req. Block or unblock: "1"-block, "0"-unblock.

38
 RCS-2000 API

Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1112",
"matterArea": "2",
"indBind": "1"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.2.16 blockArea
Empty or unblock the specified area. Emptying an area is to remove all objects from the area and
block the area.

API Definition
Table 5-16 POST http://[address][:port]/rcms/services/rest/hikRpcService/blockArea
API Name blockArea
Function Empty or unblock the specified area. Emptying an area is to remove all objects from
the area and block the area.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Remarks • You can configure the area via RCS-2000
• When the area is emptied, the AMRs in the area leaves, and the AMRs to enter
the area will bypass.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.

39
 RCS-2000 API

reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD

hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
matterArea String 16 Req. ID of the area to be emptied or unblocked
indBind String 1 Req. Empty or unblock the area: "1"-empty, "0"-
unblock.
pause String 1 Req. Whether to pause emptying the area: "0" (no,
default value) , 1 (yes).
controlMo String 2 Req. Scheduling mode: "0" (move out of the area,
d default value), "1" (move to the interim park
area), "2" (move the specified area)
targetArea String 16 Opt. The specified area ID. This node is required
when the value of controlMod is "2".
noticeThird String 2 Req. Whether to notify the third-party platform
when the area is emptied: 0 (no), 1 (yes).
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
Sample Request {
Codes "reqCode": "1541954B96B1112",
"matterArea": "2",
"indBind": "1",
"pause": "0",
"controlMod": "2"，
"targetArea":"HF002"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

40
 RCS-2000 API

5.2.17 genPreScheduleTask
Robot Control System (RCS) applies the pre-schedule after verifying the request sent by the third-
party platform. The pre-schedule is to notify RCS of the actual task in advance so that RCS can send
a free AMR to the target position and the AMR is in standby for the upcoming actual task. It
improves the scheduling efficiency.

API Definition
Table 5-17 POST http://[address][:port]/rcms/services/rest/hikRpcService/genPreScheduleTask
API Name genAgvSchedulingTask
Function Robot Control System (RCS) applies the pre-schedule after verifying the request sent
by the third-party platform.
Protocol REST
Provider RCS-2000
Caller Third-party platform
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
positionCo String 32 Req. Task position call sign
de
nextTask String 32 Req. Pre-schedule time period. Remaining seconds
before the actual task is generated: "-1" (clear
the pre-schedule of a position).
agvTyp String 256 Req. AMR type, with which the complete the actual
task.
priority String 3 Opt. Task priority, range: [1,127], and larger
number corresponds to higher priority. If it is
not configured, the task template priority
takes effect.

41
 RCS-2000 API

clearPreTas String 2 Opt. Whether to clear the previous pre-schedule:

k "0" (no, default value), 1 (yes).
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned.
Sample Request {
"reqCode": "123",
"tokenCode":"128654"",
"positionCode": "p01",
"nextTask": "20",
"agvTyp": "01",
"clearPreTask": "0"
}

Response {
"code": "0",
"data": "F01169C808C317111G",
"message": "successful",
"reqCode": "468513"
}

5.3 API Provided by Third-Party

5.3.1 agvCallback
Send the task executing status to the third-party platform.

API Definition
Table 5-18 POST http://[address][:port]/xxx/agv/agvCallbackService/agvCallback
API Name agvCallback
Function Send the task executing status to the third-party platform.
Protocol REST
Provider Third-party platform
Caller RCS-2000

42
 RCS-2000 API

Remarks The exhaustive request parameters are more than parameters listed in the following
table, the third-party platform can choose required parameters according to the
business.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Req. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
cooX String 8 Opt. X-coordinate of location code, unit: mm. This
field exists when the task has been
completed.
cooY String 8 Opt. Y-coordinate of location code, unit: mm. This
field exists when the task has been
completed.
currentPosit String 32 Req. Current position ID
ionCode
data String 2000 Opt. Custom content
mapCode String 16 Opt. Map ID
mapDataC String 32 Opt. Location code on map, and it is unique. This
ode field exists when the task has been
completed.
method String 16 Req. Name to describe the task executing status:
"start"-task started, "outbin"-executing,
"end"-task completed, "cancel"-cancel task; it
is provided by RCS-2000
podCode String 16 Opt. Rack ID, this field exists when the rack is
carried.
podDir String 4 Opt. Rack directions: "180"-leftward, "0"-
rightward, "90"-upward, "-90"-downward; this
field exists when the task has been
completed.
robotCode String 16 Req. AMR ID
taskCode String 64 Req. Current task ID (UUID)

43
 RCS-2000 API

wbCode String 32 Opt. Workstation ID, which consists of letters and

digits, and it must be same with that
configured by RCS-2000. This field exists when
the task has been completed, and it is same
with parameter wbCode of API
genAgvSchedulingTask .
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message
data String 2000 Opt. Custom content to be returned, such as task
ID.
Sample Request {
Codes "reqCode": "1541954B96B1112",
"reqTime": "2019-04-03 10:08:06",
"cooX": "3000",
"cooY": "21999",
"currentPositionCode": "p02",
"mapCode": "AA",
"mapDataCode": "002069AA015172",
"method": "end",
"podCode": "100001",
"robotCode": "6001",
"taskCode": "test169E0F39740116Q",
"wbCode": "p02"
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112",
"data":""
}

5.3.2 warnCallback
RCS-2000 sends the severe alarm which causes AMR stopping to the third-party platform. The
alarm sending frequency is 10 seconds per time.

44
 RCS-2000 API

API Definition
Table 5-19 POST http://[address][:port]/service/rest/agvCallbackService/warnCallback
API Name warnCallback
Function RCS-2000 sends the severe alarm which causes AMR stopping to the third-party
platform.
Protocol REST
Provider Third-party platform
Caller RCS-2000
Remarks The request URL should be "http:/​/​[address][:port]/​service/​rest/​agvCallbackService/
warnCallback", of which the "http:/​/​[address][:port]/​service/​rest" can be configured
in the system parameters configuration of RCS-2000, and the corresponding
configuration numbers are: 10012, 10013, and 10014.
Request Parameter Data Max. Req. Description
Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
data Object
robotCode String 16 Req. AMR ID
beginTime String 64 Req. Alarm start time
warnConte String 64 Req. Alarm content, see AMR Status (Appendix B)
nt for details.
taskCode String 64 Opt. Task No.
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.
message String 64 Req. Returned status description, e.g., "successful".
reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message.

45
 RCS-2000 API

Sample Request {
Codes "reqCode": "1541954B96B1112",
"data:": [{
"robotCode": "1001",
"beginTime": "2020-04-02 23:12:12",
"warnContent": "Platform disconnected",
"taskCode": "C002WWQQRR"
},
{
"robotCode": "1002",
"beginTime": "2020-04-02 23:12:12",
"warnContent": "Guidance alarm",
"taskCode": "C002WWQQRR33"
}]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

5.3.3 bindNotify
Notify the third-party platform of the binding or unbinding operation between racks and locations,
material batches and racks, or containers and bins.

API Definition
Table 5-20 POST http://[address][:port]/service/rest/bindNotify
API Name bindNotify
Function Notify the third-party platform of the binding or unbinding operation between racks
and locations, material batches and racks, or containers and bins.
Protocol REST
Provider Third-party platform
Caller RCS-2000
Remarks • The request URL should be "http://[address][:port]/service/rest/bindNotify", of
which the "http://[address][:port]/service/rest" can be configured in the system
parameters configuration of RCS-2000, and the corresponding configuration
numbers are: 10012, 10013, and 10014.
• You can specify the binding or unbinding type via the system configuration
number 10026.

46
 RCS-2000 API

Request Parameter Data Max. Req. Description

Type Length or
Opt.
reqCode String 32 Req. Request ID, if a request is repeatedly
submitted, the request ID must be same.
reqTime String 20 Opt. Request timestamp, format: YYYY-MM-DD
hh:mm:ss
clientCode String 16 Opt. Third-party platform ID, e.g., PDA, HCWMS
tokenCode String 64 Opt. Token ID, which is provided by RCS-2000 for
third-party platform.
method String 16 Req. API name:
"bindPodAndBerth" (bind and unbind rack
with location),
"bindPodAndMat" (bind and unbind material
batch and rack),
"bindCtnrAndBin" (bind and unbind container
and bin).
indBind String 2 Req. Bind or unbind: "1" (bind), 0 (unbind).
bindParam Object[list]
Up to 2000 characters are allowed.
podCode String 32 Opt. Rack ID. It is valid when the value of method
is "bindPodAndBerth" or "bindPodAndMat".
berthCode String 32 Opt. Position ID, which is predefined with detailed
coordinate information on map. It is valid
when the value of method is
"bindPodAndBerth".
materialLo String 32 Opt. Material batch ID. It is valid when the value of
t method is "bindPodAndMat".
ctnrCode String 32 Opt. Container ID. It is valid when the value of
method is "bindCtnrAndBin".
ctnrType String 32 Opt. Container type. It is valid when the value of
method is "bindCtnrAndBin".
stgBinCode String 32 Opt. Bin ID. It is valid when the value of method is
"bindCtnrAndBin".
Response code String 6 Req. Status code, see Status Code (Appendix A) for
details.

47
 RCS-2000 API

message String 64 Req. Returned status description, e.g., "successful".

reqCode String 64 Req. Request ID, which is the same with that in
corresponding request message.
Sample Request {
Codes "reqCode": "1541954B96B1112",
"reqTime": "2020-09-17 13:48:58",
"method": "bindPodAndBerth",
"indBind": "0",
"bindParam": [{
"berthCode": "AB1",
"podCode": "111111"
}]
}

Response {
"code": "0",
"message": "successful",
"reqCode": "1541954B96B1112"
}

48
 RCS-2000 API

Appendix A. Status Code

The status code returned in the response message are defined in the table below.

Status Code Description

code Description
0 Succeeded.
1 Incorrect parameters.
6 No need to resend (the task of the same reqCode is not completed).
99 Unknown error, try again.
100 The task does not exist.

49
 RCS-2000 API

Appendix B. AMR Status

The AMR common statuses are list in the table below.

AMR Common Status

status Description
1 Task completed
2 Executing task
3 Abnormal task
4 Idle task
5 Robot stopped
6 Lifting shelf status
7 Charging status
8 Battery arcing in progress
9 Fully charged, entering maintenance mode
11 Carried item not recognized
12 Excessive shelf angle divergence
13 Motion library exception
14 Unable to recognize product code
15 Product code mismatch
16 Lift abnormal
17 Charging post abnormal
18 No increase in current
20 Angle error in charging directive
21 Platform decentralisation directive error
23 External force, unloading
24 Misaligned shelf
25 Trolley not in designated zone
26 Decentralisation failed
27 Uneven shelf

50
 RCS-2000 API

status Description
28 Lift battery current too low
29 Wide reversing angle
30 No rack detected
31 Failed to lock zone
33 Rotation request temporarily failed
34 Unable to recognize coordinates to switch maps

51
UD15364B