ErgoTechWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
=====Scripting to Handle Host Messages in TransSECS Devices=====

====Receiving the Host Message=====

Make sure you have keyed your host message on the command name data item in the message definition. The script in the matching host message will be run when the host message is received. If you are having trouble with message matching, read the article on [[Message Matching]]. 

As a quick test of message matching, enter a script which just prints out a simple message when the message is received, for example:

<code javascript>
print("Received Host Message START");
</code>

====Handling the Message====

This example uses the host command "STOP" as an example of message handling. The STOP command has no parameters for simplicity. The goal is to tell the control application that the STOP has been requested and send an S2F42 reply to the host with a code indicating whether or not the host command is accepted.

Here is how this STOP command is defined in TransSECS:


{{:pasted:20200927-121815.png}}

The highlighted node is the command name parameter with the value "STOP". This is the "key" for the message matching. This parameter is also "published". Publishing a parameter in the message allows access to the value using a "get" method or setting the value using a "set" method in a script. The name of the get or set method is the name of the parameter with get or set prepended. For example, to access the value of the Command parameter in the incoming message, use "getCommand()". 

<note important>
The "getParameterName()" and "setParameterName(xxx)" methods for a message are case sensitive. If you define your message with a parameter name "command", use getcommand() and not getCommand() to get this value from the incoming message.
</note>

<code javascript>
print("Received Host Message STOP");
//write a flag to the device so that the control application knows that the STOP was received
/Devices/ModbusTCP_Severs/StopReceived->setIntValue(1);

//wait for the control application to reset this flag to "99" 
//we will wait up to 2 seconds (2000 ms), and check every 200 ms

//wait up to 2000 ms for the controller to acknowledge the STOP command and set the hcack

count=0;
flag=1; //when the flag changes to a different value, controller has finished processing

while ((flag==1) && (count<10)) { { //repeat up to 10 times for 2000 ms total
    java.lang.Thread.sleep(200);//wait 200 ms
    count++;
    flag=/Devices/ModbusTCP_Servers/StopReceived->getIntValue(); 
    //if flag is still 1, repeat wait, otherwise exit
 }

//get the hcack from the controller. 

if (flag!=1) { //controller acknowledged STOP command and calculated the hcack
  hcack=/Devices/ModbusTCP_Servers/StopCommandHCACK->getIntValue();
 } else {
 hcack=99; //controller timeout
}
</code>


====Send the Host Command Reply====

The next step to handling the host command is to send the host command reply with the HCACK read from the device, or set to "99" if the controller timed out waiting for the message to be processed.

<code javascript>

var TransSecsController = Java.type("com.ergotech.transsecs.secs.TransSecsController");

secsInterface=TransSecsController.findController("PLCTool"); 
//replace the parameter in findController with the name set for your tool in the TransSECS project

reply = secsInterface.getMessageBean("HostCommandReply"); 
//This will use the message defined in TransSECS called "HostMessageReply"

reply.setHCACK(Java.to([hcack],"byte[]")); //this sets the HCACK parameter in the HostMessageReply with the hcack read from the device (or "99" if the controller timed out)

//send the reply message

reply.sendMessage(); 

</code>


====Getting the Command Values from the Message====

As an example, the host command START message in the PLCTool has a single parameter, PPID.

Here is how this message is defined:

{{:pasted:20200927-124722.png}}

The value of the PPID parameter, CPValue, is published so it can be obtained from the incoming message using "getCPValue()".

Here is a script example of handling the incoming START command message:

<code javascript>
secsInterface=TransSecsController.findController("PLCTool");
hostcommand=secsInterface.getMessageBean("HostCommandSTART"); //match exactly the name of the message as set in the TransSECS project

print("Received Host Message START");

//the CPValue data item of the message is the recipe name (PPID)
recipeName = hostcommand.getCPValue();


//set the incoming PPID in the controller so it can be processed
/Devices/ModbusTCP_Servers/RecipeName->setStringValue(recipeName);


//signal the controller that a START command has been received
/Devices/ModbusTCP_Severs/StartReceived->setIntValue(1);

//wait for the controller application to change this flag value
//we will wait up to 2 seconds (2000 ms), and check every 200 ms
 
//wait up to 2000 ms for the controller to acknowledge the STOP command and set the hcack
 
count=0;
flag=1; //when the flag changes to a different value, controller has finished processing
 
while ((flag==1) && (count<10)) { { //repeat up to 10 times for 2000 ms total
    java.lang.Thread.sleep(200);//wait 200 ms
    count++;
    flag=/Devices/ModbusTCP_Servers/StartReceived->getIntValue(); 
    //if flag is still 1, repeat wait, otherwise exit
 }
 
//get the hcack from the controller. 
 
if (flag!=1) { //controller acknowledged START command and calculated the hcack
  hcack=/Devices/ModbusTCP_Servers/StartCommandHCACK->getIntValue();
 } else {
 hcack=99; //controller timeout
}

</code>

The next step is to send the host command reply. This is done the same way as for the STOP command, see example above.

<note important>
There is a possibility that the recipe name is not acceptable. This can be best determined by a flag read from the controller. If the hcack calculated by the controller is value "3", then the recipe name was not accepted. In this case the host command reply "HostCommandRejectedBadParam" should be sent to the host indicating this problem.
</note>





====Host Command Reply with Bad Parameter====

It may be necessary to send the host command reply with a bad parameter indicated. In the TransSECS message definition there is a message called "HostCommandRejectedBadParam". Two parameters need to be set before this message can be sent. The first one is the bad parameter name and the second one is the bad parameter reason code from the SEMI E05 specification.

{{:pasted:20200927-134206.png}}

<code javascript>
//send host command reply with a bad parameter name and reason code

secsInterface=TransSecsController.findController("PLCTool");

reply = secsInterface.getMessageBean("HostCommandRejectedBadParam");
reply.setHCACK(Java.to([3],"byte[]"));
reply.setCPName("PPID");
reply.setCPACK(Java.to([2],"byte[]"));//1=unknown parameter, 2=bad value, etc.

reply.sendMessage(); 


</code>

====Send an Event Related to the Host Command ====

The script which handles the host command can optionally send a related event. Events are usually sent from the device by setting the device's tag which is connected to the CEID trigger. This script provides an optional way to send the same event.

<code javascript>
//trigger the STARTED Event (as an example of triggering an event). The event will only 
//be triggered if the STARTED CEID has been enabled by the host and if the hcack is 0 or 4 (OK to execute command)

if (hcack==0 || hcack==4) {
startedEvent = secsInterface.getGemHandler().getServerForName("ceid.STARTED");
startedEvent.setIntValue(1); //triggers the event
}

</code>