Opentcs 光灵开发手册 (三)

才情兼修、何谓生活

序言：

最深最深的地方，所有回忆被抹成空白的地方。当外在的一切依然并行无恙，生活继续以幸福而平常的姿态继续时，依然存在的无限寂静的地方。像停留在整个宇宙边缘的尽头，时光和记忆交融凝固在一起，依然能听到最完整最孤寂的声音。

 

3、内核的web API

除了特定于java的内核接口之外，openTCS还提供了一个web API。这个接口提供了以下功能:

3.1、可以创建运输任务

3.2、运输任务可以撤回

3.3、可以检索运输任务和车AGV小车的状态更新(通过长时间轮询)。

HTTP请求和响应的主体(如果适用)是JSON结构，描述结构的JSON模式是openTCS二进制发行版开发人员文档的一部分。使用的编码可以是UTF-8、UTF-16或UTF-32。使用时间戳的地方，使用iso8601进行编码，使用的时区是UTC。

 

用于HTTP请求的TCP端口与配置有关，默认情况下，它是55200。后半部分将描述各个函数的路径，默认情况下，不需要任何身份验证就可以接受请求。还可以在内核配置中设置访问键，然后，客户端会在一个名为X-Api-Access-Key的HTTP头文件中发送配置好的值。

3.1、创建一个运输任务

•路径:  （ /v1/transportOrders/<NAME>）

/ v1 / transportOrders / <名称>

•HTTP方法：POST

•查询参数：没有

•示例URL：http://opentcs.example.com:55200/v1/transportOrders/TOrder-1234

请求体将包含要创建的传输命令的描述，它应该包含如下内容:

 

示例1:创建传输顺序的JSON结构（关键）

 

PS：响应以200 (OK)的HTTP状态码成功，响应的主体是空的。

 

3.2、按照名称提取运输任务

•路径：/v1/transportOrders/<NAME>/withdrawal

•HTTP方法： POST

•查询参数：

•immediate (布尔型，可选)：是否应该尽快终止传输顺序(默认值:false)

•disableVehicle(布尔型，可选)：处理车辆是否不应被分配任何进一步的运输任务。(默认值:false)

•示例url:

• http://opentcs.example.com:55200/v1/transportOrders/TOrder-0075/withdrawal
• http://opentcs.example.com:55200/v1/transportOrders/TOrder0075/withdrawal?immediate=true
• http://opentcs.example.com:55200/v1/transportOrders/TOrder-

0075/withdrawal?disableVehicle=true

 

3.3、通过处理车辆收回运输任务

•路径： /v1/vehicles/<NAME>/withdrawal

•HTTP方法：POST

•查询参数:

•immediate(布尔型，可选):是否应该尽快终止传输顺序。(默认值:false)

•disableVehicle(布尔，可选):处理车辆是否不应被分配任何进一步的运输任务。(默认值:false)

•示例url:

• http://opentcs.example.com:55200/v1/vehicles/Vehicle-0001/withdrawal
• http://opentcs.example.com:55200/v1/vehicles/Vehicle-0001/withdrawal?immediate=true
• http://opentcs.example.com:55200/v1/vehicles/Vehicle-0001/withdrawal?disableVehicle=true

请求的主体被忽略，响应的主体是空的。

 

3.4、检索状态更新

•路径：  /v1/events

•HTTP方法：GET

•查询参数:

•minSequenceNo(整数，可选)：要检索的事件的最小序号。(默认值：没有最低)

•maxSequenceNo(整数，可选)：要检索的事件的最大序列号。(默认值：没有最大)

•timeout (整数，可选)：如果当前没有要返回的事件，则等待事件到达的时间(以毫秒为单位)，可能不大于10000。(默认值：1000)

•示例URLs：

• http://opentcs.example.com:55200/v1/events
• http://opentcs.example.com:55200/v1/events?timeout=5000
• http://opentcs.example.com:55200/v1/events?minSequenceNo=100
• http://opentcs.example.com:55200/v1/events?minSequenceNo=100&maxSequenceNo=200

请求的主体被忽略。响应的主体看起来如下：

示例1：获取事件/更新的JSON结构。

 

 

 

4、基于TCP/IP的其他系统接口

这个接口不赞成使用，为了支持内核的webAPI，它将被删除。除了java特有的内核接口之外，openTCS还提供了以下与其他系统通信的接口：一种是通过TCP/IP连接的双向接口，用于创建传输任务，另一种是通过TCP/IP连接接收状态消息的单向接口，例如关于正在处理的传输任务，下面将主要介绍一下TCP/IP接口。

4.1、创建任务通过TCP / IP

为了创建传输任务，openTCS内核接受到TCP端口的连接(默认端口55555)。openTCS与主机之间的通信工作如下:

4.1.1、主机建立一个新的TCP/IP连接到openTCS。

4.1.2、主机发送一个单一的XML 电报(在XML电报中详细描述，用于创建任务和引用任务批次的XML 电报)，它可以描述要创建的传输任务，或者识别内核中可用的批处理文件，并包含传输任务描述。

4.1.3、主机关闭TCP/IP连接的输出流，或发送两个连续的换行符。让内核知道没有进一步的数据将会跟随。

4.1.4、openTCS解释主机发送的电报，创建相应的传输命令并激活它们。

4.1.5、openTCS发送一份XML电报(详细描述了创建任务的证据)，以确认电报的处理。

4.1.6、openTCS关闭TCP/IP连接。应尊重以下几点:

•不打算通过相同的TCP连接传输多个传输任务，在处理一个集合并发送响应之后，openTCS关闭连接。要传输进一步的设置，需要由对等系统建立新的TCP/IP连接。

•openTCS只等待有限的输入数据(默认为10秒)。如果在较长一段时间内没有来自对等系统的传入数据，则在没有创建任何传输任务的情况下，openTCS将关闭连接。

•默认情况下，单个XML电报的最大长度限制为100 kb，如果更多的数据被传输，连接将被关闭，没有任何传输任务被创建。

 

 

4.2、用于创建任务的XML电报。

通过上面描述的接口发送给openTCS的每个XML电报都可以描述要创建的多个传输命令。

每个任务元素必须包含以下数据:

A、识别命令元素的字符串，此字符串需要对收据进行明确的匹配(见创建任务的证据)和任务。

B、定义实际任务的目的地和目的地操作序列，

 

此外，每个命令元素可能包含以下数据:

A、完成任务的最后期限/时间。

B、系统中要分配任务的AGV小车的名称，如果省略此信息，系统中的任何AGV小车都可以处理任务。

C、在新任务交付AGV小车之前必须完成的一组现有运输任务的名称，下面的示例展示了如何创建两个传输任务的XML 电报。

 

示例1：创建两个传输任务的XML 电报

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<tcsOrderSet>

    <order xsi:type="transport" deadline="2018-04-16T10:55:31.312+02:00"

intendedVehicle="Vehicle-01" id="TransportOrder-01" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance">

        <destination locationName="Storage 01" operation="Load cargo"/>

        <destination locationName="Storage 02" operation="Unload cargo"/>

        <property key="waitBefore" value="Unload"/>

    </order>

    <order xsi:type="transport" id="TransportOrder-02" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance">

        <destination locationName="Working station 01" operation="Drill">

            <property key="drillSize" value="3"/>

        </destination>

        <destination locationName="Working station 02" operation="Drill">

            <property key="drillSize" value="8"/>

        </destination>

        <destination locationName="Working station 03" operation="Cut"/>

    </order>

</tcsOrderSet>

 

4.3、XML电报参考任务批次

另外，XML 电报也可以参考openTCS系统中保存在文件中的任务批次。要创建的传输命令的(参数)将从引用的批处理文件中读取。批处理文件可以包含/创建任意数量的传输任务，并且需要放在内核应用程序的子目录脚本中。

在openTCS分发版中，该目录已经包含了一些批处理文件的模板(模板)，(template.tcs and test.tcs)，下面的示例演示如何引用批处理文件的XML 电报。

 

示例2：引用批处理文件的XML电报

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<tcsOrderSet>

    <order xsi:type="transportScript" fileName="test.tcs" id="test.tcs" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance"/>

</tcsOrderSet>

 

4.4、创建任务的证据

在响应XML电报创建传输任务时，XML 电报将被发送回对等点，报告操作的结果。在响应电报中，原始电报的每个任务元素都将由具有相同ID的响应元素引用。

•标志着创建相应任务的成功的标志。

•在内部分配给创建任务的openTCS的名称(此名称与在状态通道上解释消息有关——通过TCP/IP查看状态消息)，下面的示例显示了如何响应示例1中的电报。

 

示例3:具有创建任务的证据的XML 电报

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<tcsResponseSet>

    <response xsi:type="transportResponse" executionSuccessful="true" orderName=

"TOrder-0001" id="TransportOrder-01" xmlns:xsi="http://www.w3.org/2001/XMLSchema-

instance"/>

    <response xsi:type="transportResponse" executionSuccessful="true" orderName=

"TOrder-0002" id="TransportOrder-02" xmlns:xsi="http://www.w3.org/2001/XMLSchema-

instance"/> </tcsResponseSet>

 

4.5、任务批次证据

对于被引用的任务批次，证据也会被发送回对等点。响应中包含了每个批处理文件所引用的元素，如果批处理文件被成功地读取和处理，它所包含的每个任务定义的响应都将包括在内。下面的示例显示了示例2中的批处理文件引用的可能响应，在这种情况下，批处理文件包含两个已成功处理的传输任务定义。

示例4：在批处理文件中接收任务证据的XML电报

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<tcsResponseSet>

    <response xsi:type="scriptResponse" parsingSuccessful="true" id="test.tcs"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

        <transport executionSuccessful="true" orderName="TOrder-0003" id="test.tcs"/>         <transport executionSuccessful="true" orderName="TOrder-0004" id="test.tcs"/>

    </response>

</tcsResponseSet>

 

【生命在一点点的流逝~~但是微微一笑，不负如来不负卿~】

 

4.6、通过TCP / IP获取状态信息

要接收系统中传输任务的状态消息，可以建立与另一个TCP端口的连接(默认端口44444)。每当传输任务的状态发生变化时，就会发送一个XML电报给每个连接的客户端，描述任务的新状态。每一个电报后面都有一个字符串，它不会出现在电报本身(默认情况下，一个管道符号:“|”)，标记各自电报的结尾。状态消息将被发送，直到对等端关闭TCP连接。

我们开发人员应尊重以下几点:

•从对等端的观点来看，与这个状态通道的连接完全是被动的，即openTCS不期望来自对等方的任何消息，也不会处理通过此连接接收到的任何数据。

•对等端需要过滤收到的电报以获取相关数据，openTCS内核不为客户端提供任何状态消息的过滤。

•由于openTCS内的并发进程，在创建该任务的对等点收到相应的收据之前，可能会通过状态通道报告一个传输任务的创建和激活以及它对AGV小车的分配。下面的示例显示了一个状态消息，在示例1中定义的两个传输任务中的第一个已经创建并激活后，它将通过状态通道发送。

示例5：生成的任务的状态消息

 

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<tcsStatusMessageSet timeStamp="2018-04-16T10:55:31.730+02:00">

    <statusMessage xsi:type="orderStatusMessage" orderName="TOrder-0001" orderState=

"ACTIVE" processingVehicleName="Vehicle-0001" xmlns:xsi=

"http://www.w3.org/2001/XMLSchema-instance">

        <destination locationName="Storage 01" operation="Load cargo" state="PRISTINE

"/>

        <destination locationName="Storage 02" operation="Unload cargo" state=

"PRISTINE"/>

        <property key="waitBefore" value="Unload"/>

    </statusMessage>

</tcsStatusMessageSet>

 

4.7、用于电报和脚本的XML模式定义。

XML模式描述了XML任务电报和任务批处理文件的期望结构，以及openTCS发送的接收电报的结构，这是openTCS分发的一部分，可以在包含开发人员文档的目录中找到。