XScript 手册 · Chapter 16
COMMUNICATION — 通信通道控制
通过 COM["名称"] 访问在 Communication Editor 中注册的通信通道(TCP Server/Client、
Serial、Modbus、MES、AWS S3 等)。使用事件函数接收异步接收/连接事件,
并通过 WriteStr 或 SendCustomData 进行发送。
基本示例
xscript
// 连接接收事件
COM["MES"].LinkModuleName = "MES";
COM["MES"].LinkFunctionName = "OnReceiveFromServer";
// 连接连接事件
COM["MES"].ConnectedLinkModuleName = "MES";
COM["MES"].ConnectedLinkFunctionName = "OnConnected";
FUNCTION OnReceiveFromServer(string data)
{
Log("READ: '{0}'", data);
array items = STR.ParseCommaString(data);
for (i, 0, items.Count - 1)
{
string line = items[i];
if (line == "")
{
continue;
}
array pair = STR.ParseSplitString(line, ":");
string name = pair[0];
string value = pair[1];
if (TodoSomething(name, value) == false)
{
continue;
}
}
return true;
}
FUNCTION SendToServer(string data)
{
if (COM["MES"].WriteStr(data) == false)
{
return false;
}
return true;
}实战示例 — TCP 客户端帧收发
构造带有 STX/ETX 的长度+单元编号帧并发送,解析响应后 进行超时等待。
xscript
FUNCTION Send(int unit, string cmd, string data, bool wait)
{
if (COM["Cube"].IsOpen() == false)
{
return false;
}
int unit_no = Common::GetUnitNo(unit);
ResponseOk = false;
string sendData;
if (STR.IsNullOrWhiteSpace(data))
{
sendData = MakeSendData(unit_no, cmd);
}
else
{
sendData = MakeSendData(unit_no, cmd + "," + data);
}
LastCommand = cmd;
if (COM["Cube"].WriteStr(sendData) == false)
{
return false;
}
if (wait == false)
{
return true;
}
int start = SYS.GetTickCount();
while (true)
{
if (ResponseOk)
{
break;
}
Sleep(20);
if (SYS.GetTickCount() - start > TCP_TIMEOUT)
{
return false;
}
}
return ReplyOk;
}主要方法
连接控制
| 签名 | 说明 |
|---|---|
bool Open(void) | 开始连接 |
void Close(void) | 结束连接 |
bool IsOpen(void) | 连接状态 |
bool IsLiveConnection(void) | 活动检查 |
bool OpenTcpIpServer(void) / void CloseServer(void) / bool IsOpenServer(void) | 服务器模式 |
int GetCount(void) | 已连接客户端数量 |
发送
| 签名 | 说明 |
|---|---|
bool WriteStr(string data) | 字符串发送(协议封装) |
bool WriteStrRaw(string data) | 原始发送 |
bool SendCustomData(string data) | 自定义格式发送 |
bool SendCustomData(string group, string data) | 指定分组发送 |
bool SendCommand(string command, string data = "") | 命令发送 |
接收 · 解析
| 签名 | 说明 |
|---|---|
string ReceiveCustomData(string option = "") | 自定义格式接收 |
bool Parse(string data) | 执行已注册的解析器 |
void SeparateData(void) | 帧分离 |
void StartCustomReadThread(void) / void StopCustomReadThread(void) | 读取线程 |
bool ReadCustom(void) | 单次读取 |
值通道(计量设备)
| 签名 | 说明 |
|---|---|
bool SetValue(double value) / double GetValue(bool wait = false) | 单一值 |
bool SetChannelValue(int channel, double value) | 按通道设置值 |
double GetChannelValue(int channel) | 查询通道值 |
bool SetChannelAll(double value) | 全部通道 |
void SetChannelMinMaxValue(int channel, double min, double max) | 通道范围 |
其他
| 签名 | 说明 |
|---|---|
bool SetCustomConnectionParameters(void) | 重新设置连接参数 |
void SetPort(string portName) | 指定 Serial 端口 |
void IdleCheckFunc(void) | Idle 检查回调 |
void SendLinkTest(void) | 发送链路测试帧 |
string GetDesc(void) / string ToString(void) | 信息字符串 |
主要属性
| 属性 | 类型 | 说明 |
|---|---|---|
Name / ClassName | string | 标识 |
Address / PortName / BaudRate / IsBaudRateFix | 连接参数 | |
Url / AccessKey / SecretKey / Region | string | HTTP/S3 参数 |
OpenOnStart | bool | 启动时自动打开 |
Filter | string | 接收过滤器 |
MinDataSize | int | 最小帧大小 |
CurrentChannel / MaxChannel / IsChannel | 多通道 | |
PacketStartDelimiter / PacketEndDelimiter / DataDelimiter | string | 帧分隔符 |
MaxValue / MinValue | int | 值范围 |
IdleCheckTimeSec / LinkTestTimeMsec | int | 周期 |
UseDebugLog / UseLinkTest / UseIdleTimeOut / UseInternalTimer | bool | 选项 |
OnIdle / IsLinkTestOk / ResponseOk | bool | 状态 |
事件函数约定
| 连接字段 | 调用时机 |
|---|---|
LinkModuleName + LinkFunctionName | 数据接收 |
ConnectedLinkModuleName + ConnectedLinkFunctionName | 连接状态变化 |
OnParseFunctionName | 自定义解析器 |
提示
- 接收回调在通信线程中被调用 — UI 更新务必通过调度器(dispatcher)进行。
- 切勿使用无超时的
while等待 → 用SYS.GetTickCount()管理已用时间(elapsed)。 - 二进制协议采用
WriteStrRaw+PacketStartDelimiter/EndDelimiter组合更稳定。 - 服务器 API 调用优先使用
SYS.SendHttpGet/Post/Delete辅助函数(检查SYS.HTTP_ERROR_STR返回值)。