tcp模块¶

状态	最后更新	API版本
Active	2020-06-20	V1.00.00

在V1.00.45固件版本后，提供一个用户TCP端口，用于用户程序与用户自己的上位机进行交互。

用途：自动测试系统，自定义数据采集等。

实现概略¶

表头连接到上位机，用Shizuku Toolbox打开后，Shizuku Toolbox会启动一个TCP端口，您自己的上位机通过这个TCP端口与表头交互，Shizuku Toolbox将转发双向通讯。

vcp_implementation

用户TCP可以做什么¶

其他lua模块提供了对表头上资源的方便访问，但与外界交互的途径只有按钮，屏幕以及内部存储。部分客户想自己写上位机，并对表头发送命令及读取数据完成定制功能。这就需要一种上位机和用户lua程序的通信渠道，为此，我们提供一个用户TCP端口实现用户lua程序与用户上位机的双向通信。

回环测试¶

在开始您的应用之前，我们应该先确保TCP转发工作正常。请跟随以下步骤进行测试：

如果您还没有安装上位机（即Shizuku Toolbox），请到上位机下载。

连接表头与计算机（micro口为联机口），运行Shizuku Toolbox，双击设备名称打开表头：

loopback1

点击Lua脚本面板页，找到Lua TCP： loopback2

设置好本地TCP端口号（默认1000），点击开始按钮。

loopback3

在右侧代码区复制以下代码，并按左边的绿色运行按钮运行：

function tcp_callback()
    tcp.write(tcp.readAll())
end

tcp.open()
tcp.onReceived(tcp_callback)

loopback4

打开PuTTY，按以下设置（Port号与前面的端口号一致），并点击Open:

loopback4

此时，在PuTTY会话中输入字符，应当收到重复字符（即，输入”abcd”并回车,对方将回复abcd），说明回环测试成功：

loopback5

tcp.open()¶

描述¶

打开用户TCP端口，可指定收发缓冲区大小，若未指定，收发缓冲区大小均为64字节。注意，rx与tx是站在表头的角度说的。

参数¶

名称	类型	范围	用途
[rx_buffer_size]	number	1~2^32-1	指定接收缓冲区大小
[tx_buffer_size]	number	1~2^32-1	指定发送缓冲区大小

返回值¶

nil

调用例¶

tcp.open() --Open user TCP

tcp.close()¶

描述¶

关闭用户TCP端口。

参数¶

nil

返回值¶

nil

调用例¶

tcp.close() --Close user TCP

tcp.read()¶

描述¶

从TCP端口中读取指定字节数。

参数¶

名称	类型	范围	用途
bytesToRead	number	1~2^32-1	希望读取的字节数

行为¶

若调用时，接收缓冲区中的字节数大于或等于所指定的bytesToRead，则从接收缓冲区中取bytesToRead字节并立刻返回。若接收缓冲区中的字节数小于bytesToRead，则函数开始等待直到收到bytesToRead 为止，若等待时间超过读取超时时间(参见vcp.setTimeout()), 则函数返回。

返回值¶

名称	类型	范围	用途
content	string		读取到的内容
actual_size	number	1~2^32-1	实际取到的字节数

调用例¶

packet = tcp.read(20) --Read a packet with length 20.

tcp.readAll()¶

描述¶

读取接收缓冲区中的全部内容。

参数¶

nil

行为¶

读取接收缓冲区中的全部内容。此函数调用后立刻返回，即使接收缓冲区为空(此时返回一个空string及number0)。

返回值¶

名称	类型	范围	用途
content	string		读取到的内容
bytesCount	number	1~2^32-1	取到的字节数

调用例¶

packet,actual_size = tcp.readAll() --Read all 
if(actual_size == 0) begin
   print("We got nothing.")    
end

tcp.write()¶

描述¶

向串口写入内容。

参数¶

名称	类型	范围	用途
content	string	1~2^32-1	要发送的内容

行为¶

若调用时，发送缓冲区的空闲空间足够，则将发送内容写入发送缓冲区并立刻返回。若发送缓冲区的空闲空间不够，则等待发送缓冲区空闲，并装入数据，直到内容发送完为止。若等待时间超过发送超时时间(参见tcp.setTimeout()), 则函数返回。

返回值¶

名称	类型	范围	用途
actual_size	number	1~2^32-1	实际发送出的字节数

调用例¶

tcp.write("Hello World!!")

tcp.bytesToRead()¶

描述¶

获取接收缓冲区中的数据的字节数。

参数¶

nil

返回值¶

名称	类型	范围	用途
bytesToRead	number	1~2^32-1	接收缓冲区中数据的字节数

调用例¶

byteCount = tcp.bytesToRead() --Get size of data in rx FIFO
data = tcp.read(byteCount) --Read out data

tcp.bytesToWrite()¶

描述¶

获取发送缓冲区中尚未发送完毕的数据的字节数。

参数¶

nil

返回值¶

名称	类型	范围	用途
bytesToWrite	number	1~2^32-1	发送缓冲区中尚未发送完毕的数据的字节数

调用例¶

if(tcp.bytesToWrite() > 0) then
    tcp.flushTx()
end

tcp.rxOverflow()¶

描述¶

检查接收缓冲区是否溢出。

参数¶

nil

返回值¶

名称	类型	范围	用途
overflowed	boolean		接收缓冲区是否溢出

调用例¶

if(tcp.rxOverflow()) then
    print("Oh shit, we are in trouble.")
end

tcp.setTimeout()¶

描述¶

设置发送超时时间及接收超时时间。同时请参见tcp.read()与tcp.write()的行为。未调用此函数时，默认的发送超时时间及接收超时时间均为500ms。

参数¶

名称	类型	范围	用途
read_timeout	number	1~2^32-1	指定接收超时时间(毫秒)
write_timeout	number	1~2^32-1	指定发送超时时间(毫秒)

返回值¶

nil

调用例¶

tcp.setTimeout(1000,1000) --Set read & write timeout to 1000ms.

tcp.flushTx()¶

描述¶

清除发送缓冲区中的内容。

参数¶

nil

返回值¶

nil

调用例¶

tcp.flushTx()

tcp.flushRx()¶

描述¶

清除接收缓冲区中的内容。

参数¶

nil

返回值¶

nil

调用例¶

tcp.flushRx()

tcp.isOpen()¶

描述¶

检查TCP端口是否已打开。

参数¶

nil

返回值¶

名称	类型	范围	用途
open	boolean		是否已打开

调用例¶

if(~tcp.isOpen()) then
    tcp.open()
end

tcp.onReceived()¶

描述¶

设置接收到数据时的回调函数。

参数¶

名称	类型	范围	用途
callback	function		指定回调函数
[threshold]	number		指定触发回调函数时接收缓冲区中的字节数

行为¶

设置接收到数据时的回调函数。指定后，一旦接收缓冲区中的数据的字节数大于或等于threshold，回调函数callback将被调用。若未指定threshold，默认触发字节数为1。

提示¶

用户需要在回调函数中用tcp.read()或tcp.readAll()读取收到的内容，否则触发条件一直成立，将反复进入回调函数。

返回值¶

nil

调用例¶

function tcp_callback()
    tcp.write(tcp.readAll())
end

tcp.open()
tcp.onReceived(tcp_callback)