tcp module¶
| Status | Last Update | API Version |
|---|---|---|
| Active | 2020-10-17 | V1.00.00 |
After firmware version V1.00.45, we provide a TCP port for user’s PC applications to communicate with his Lua scripts.
This is ideal for: Production line automation, customized data querying, etc.
Scheme¶
Connect the meter to PC, open Shizuku Toolbox application. When you open your multimeter, Shizuku Tool application will act as a TCP server, forwarding data flows from and into the meter. Your application communicates with your lua script with this TCP port.
What can user TCP do?¶
While other lua APIs provide access to hardware resources of the meter, the TCP API provides a way to establish connection with your host application on your PC.
Loopback test¶
Before you make use of this feature, we should make sure TCP forwarding functions normally:
If you haven’t installed Shizuku host App yet, download it here.
Connect the multimeter and your PC with a micro USB cable, run Shizuku Toolbox, and double-click your multimeter’s name to open the multimeter:
ClickLua Scriptpanel，and findLua TCP：
Set a proper local TCP port number, and click start button.
Copy the following code into code panel on the right side
function tcp_callback()
tcp.write(tcp.readAll())
end
tcp.open()
tcp.onReceived(tcp_callback)
Open PuTTY，config it as following, and click open button:
After this, when you type anything into the session, you should be able to read an echo, which means the loopback test works well:
You might think to launch an application for TCP forwarding is too cumbersome, you may use UserTCPUtils instead, which is installed in the same directory with Shizuku toolbox.
Usage and example:
Usage: UserTCPUtils.exe -s <Serial Port Name> -t <TCP Port Number>
Example: UserTCPUtils.exe -s COM1 -t 10000
tcp.open()¶
Description¶
Open user TCP port and allocate Rx/Tx buffer. If no size is specified, both Rx and Tx buffer is 64 bytes.
Parameters¶
| Name | Type | Range | Usage |
|---|---|---|---|
| [rx_buffer_size] | number | 1~2^32-1 | Specify Rx buffer size |
| [tx_buffer_size] | number | 1~2^32-1 | Specify Tx buffer size |
Return Value¶
nil
Example call¶
tcp.open() --Open user TCP
tcp.close()¶
Description¶
Close user TCP port.
Parameters¶
nil
Return Value¶
nil
Example call¶
tcp.close() --Close user TCP
tcp.read()¶
Description¶
Read n bytes from user TCP port.
Parameters¶
| Name | Type | Range | Usage |
|---|---|---|---|
| bytesToRead | number | 1~2^32-1 | Number of bytes that you want to read |
Behaviour¶
If existing data in Rx buffer is equal or greater than bytesToRead, the function fetch bytesToRead bytes of data from the buffer and return immediately. Otherwise the function waits until bytesToRead of data is received and return it. If the time waited is greater than the timeout (You can specify the timeout with vcp.setTimeout()), the function returns with all the data available.
Return Value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| content | string | Data received. | |
| actual_size | number | 1~2^32-1 | Length of data received. |
Example call¶
packet = tcp.read(20) --Read a packet with length 20.
tcp.readAll()¶
Description¶
Read all the data in the Rx buffer.
Parameters¶
nil
Behaviour¶
Read all existing data in the Rx buffer, the function returns immediately after calling. If the Rx buffer is empty, an empty string and a number 0 is returned.
Return Value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| content | string | Data received. | |
| bytesCount | number | 1~2^32-1 | Length of data received. |
Example call¶
packet,actual_size = tcp.readAll() --Read all
if(actual_size == 0) begin
print("We got nothing.")
end
tcp.write()¶
Description¶
Write content to Tx buffer.
Parameters¶
| Name | Type | Range | Usage |
|---|---|---|---|
| content | string | 1~2^32-1 | Content to send |
Behaviour¶
If there is enough empty space in the Tx buffer, the function write content into the Tx buffer and return immediately. If there is not enough space in the Tx buffer, the function write the Tx buffer to full, and wait for the data to be sent out, and write again until all the data is sent. If the tx buffer is full more than the timeout specified(You can specify the timeout with vcp.setTimeout()), the function returns.
Return value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| actual_size | number | 1~2^32-1 | Number of bytes actually sent. |
Example call¶
tcp.write("Hello World!!")
tcp.bytesToRead()¶
Description¶
Get number of bytes in the Rx buffer.
Parameters¶
nil
Return value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| bytesToRead | number | 1~2^32-1 | Number of bytes in the Rx buffer |
Example call¶
byteCount = tcp.bytesToRead() --Get size of data in rx FIFO
data = tcp.read(byteCount) --Read out data
tcp.bytesToWrite()¶
Description¶
Get number of bytes of data which is still in the Tx buffer.
Parameters¶
nil
Return value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| bytesToWrite | number | 1~2^32-1 | Number of bytes of data which is still in the Tx buffer |
Example call¶
if(tcp.bytesToWrite() > 0) then
tcp.flushTx()
end
tcp.rxOverflow()¶
Description¶
Check if an overflow event happened in the Rx buffer.
Parameters¶
nil
Return value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| overflowed | boolean | Overflowed |
Example call¶
if(tcp.rxOverflow()) then
print("Oh shit, we are in trouble.")
end
tcp.setTimeout()¶
Description¶
Set timeout of a write or read operation. The default Rx/Tx timeout is 500ms.
Parameters¶
| Name | Type | Range | Usage |
|---|---|---|---|
| read_timeout | number | 1~2^32-1 | Rx timeout (In milliseconds) |
| write_timeout | number | 1~2^32-1 | Tx timeout (In milliseconds) |
Return value¶
nil
Example call¶
tcp.setTimeout(1000,1000) --Set read & write timeout to 1000ms.
tcp.flushTx()¶
Description¶
Flush data in the Tx buffer.
Parameters¶
nil
Return value¶
nil
Example call¶
tcp.flushTx()
tcp.flushRx()¶
Description¶
Flush data in the Rx buffer.
Parameters¶
nil
Return value¶
nil
Example call¶
tcp.flushRx()
tcp.isOpen()¶
Description¶
Check if TCP port is allocated (This has nothing to do with the connection status of your host machine, it just makes sure you have opened the TCP module inside the meter).
Parameters¶
nil
Return value¶
| Name | Type | Range | Usage |
|---|---|---|---|
| open | boolean | Opened |
Example call¶
if(~tcp.isOpen()) then
tcp.open()
end
tcp.onReceived()¶
Description¶
Set the callback function when there is any data in the Rx buffer.
Parameters¶
| Name | Type | Range | Usage |
|---|---|---|---|
| callback | function | Specify the callback function | |
| [threshold] | number | Specify the threshold on which the callback function should be called |
Behaviour¶
Set the callback function when there is any data in the Rx buffer. After which, once the data in the Rx buffer is equal or more than the threshold, the callback function is called. If no threshold is specified, the threshold is 1 byte as default.
Hint¶
You must call tcp.read() or tcp.readAll() somewhere in your callback function, or the callback function is called again and agian as the trigger condition always satisfies.
Return value¶
nil
Example call¶
function tcp_callback()
tcp.write(tcp.readAll())
end
tcp.open()
tcp.onReceived(tcp_callback)