GEM300 Scripts [ErgoTech Systems, Inc. TechWiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== GEM300 Scripts ======


GEM300 standards consist of state models.  This [[https://slideplayer.com/slide/13207475/|Intel transcript]] provides an overview. As you move product, or carriers through your tool the control system must update the current state to ensure that the host can correctly manage tool operation.

Implementation of these standards will require reference to the appropriate standard and state model in the standard.  The implementations will vary based on your needs and the capabilities of the tool.  A wide range of possible scenarios are provide in the SEMATECH document [[https://www.ergotech.com/files/guides/ISMI%20Operational%20Flows%20and%20Scenarios.pdf|300 mm Operational Flowcharts and Scenarios, V. 10]]

===== TransSECS implementation =====


In all the TransSECS GEM300 implementations there are two, fundamental part.  

  - "Callback" interface - this is how you are notified of the host's requests
  - "Service Wrapper" - this is how you indicate that changes at the tool.

Individual standards have other components, E40 Process Jobs, E87 Carriers, E90 Substrates, E94 Control Jobs, etc.

**Note:** You do not need to implement, or parse SECS messages.  This is all done for you within the interface.  Do not add GEM300 messages to the TransSECS interface.

==== E39 ====

E39 is a required standard to support GEM300, however the implementation and operation of E39 is completely transparent to the TransSECS GEM300 operation.  You need only initiailize the interface.

==== E40 ====

Provides a model of the process state within the tool, primarily through the management of "Process Jobs".  A Process Job is created by the host, or on rare occasions by the tool.  In a simple example, the process job may go through the following steps:

  * Allocated - state transition 2 - the Process Job is removed from the queue in preparation for execution - processJob.allocated();
  * Material Arrived - no state transition - indicate that the material for the Process Job is at the tool - processJob.materialArrived();
  * Start the Job - state transition 4 - start execution of the Process Job - processJob.readyToStart();  (Note: If the process job is not set to start automatically a "Start" command will be required from the host - see below).
  * Processing Complete - state transition 6 - The material processing is complete - processJob.complete();
  * Material Departed - state transition 7 - The material has been removed from the tool.  The process job is complete and will be deleted - processJob.materialDeparted();
  * 
=== E40 Service Wrapper ===

The E40 Service Wrapper provides access to control the flow of E40.  Most importantly, it provides access to the individual Process Jobs.

A listing of all process jobs is provided by:
<code>
E40ServiceWrapper.getInstance().getAllPRJobs();
</code>
A particular process job can be obtained by the job id:
<code>
E40ServiceWrapper.getInstance().getPRJob(jobID)
</code>

=== E40 Callback Interface ===

The E40 Callback Interface provides notification of activity from the host.  There are four methods:

 prStateChange : function (prJob, oldState, newState)
  Indicates that the state of a process job has change.
 prJobCreate : function (prJob)
  A request to create a process job.  No action is required if the creation of the process job is acceptable.  If not, throw an E40Exception with the reason it's not acceptable.   prSetRecipeVariable : function (prJob, recVarList)
  This method provides recipe variable.  Support is option, if supported this must set the provided recipe variables on the job id.
 prSetMtrlOrder : function (prCurrentMtrlOrder, prNewMtrlOrder)
    Set the order in which process jobs should be processed. Possible options are:
  1 = ARRIVAL   process whichever material first arrives
  2 = OPTIMIZE   process in an order that maximizes throughput
  3 = LIST   follow the order in the list 
 prCommandCallback : function (prJob, prCmd, prCmdParameterList)
    Called when the host requests that a command be executed on the process job. Possible commands are ABORT,STOP,CANCEL,PAUSE,RESUME,STARTPROCESS
    Only ABORT must be supported. If the command is not supported, throw an E40Exception
    
== Sample Implementation ==
 
<code javascript>
var E39MessageHandler = Java.type("com.ergotech.secs.e39.E39MessageHandler");
var E40MessageHandler = Java.type("com.ergotech.secs.e40.E40MessageHandler");
var E40ServiceWrapper = Java.type("com.ergotech.secs.e40.E40ServiceWrapper");
var E40CallbackInterface = Java.type("com.ergotech.secs.e40.E40CallbackInterface");
var ProcessJob = Java.type("com.ergotech.secs.e40.ProcessJob");
var TransSecsController = Java.type("com.ergotech.transsecs.secs.TransSecsController");
var Thread = Java.type("java.lang.Thread");

// create the callback interface.
var E40Callback = new E40CallbackInterface() {
   
 prStateChange : function (prJob, oldState, newState ) {
  print ("State Change for " + prJob.getPrJobId() + " From: " + ProcessJob.getStateName(oldState) + " to " + ProcessJob.getStateName(newState));
  // send the new state for the process job to the PLC
  /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());
  /GEM300PLC/CurrentProcessJobState->setIntValue(newState);
 },
 prJobCreate : function (prJob) {
  // a request to create a process job.  It;s possible to query the PLC (or any other subsystem
  // to determine if this process job is allowable.  If not, throw an E40Exception with the
  // reason it's not acceptable.  Here's we'll always accept it
   print ("Job Creation of " + prJob.getPrJobId() + " permitted");
   // indicate that this job is not allocated
   /GEM300PLC/Allocated->setIntValue(0);
   // record the id
   /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());
 },
 prSetRecipeVariable : function (prJob, recVarList) {
  // set the provided recipe variables on the job id.
  // that is, send the recVarList to the PLC
  if ( recVarList != null ) {
  for ( counter = 0 ; counter < recVarList() ; counter++ ){
     print("Host Requested Recipe Variable \"" + recVarList(counter).getStringValue() + "\" on " + prJob );    
  }
  }
 },
 prSetMtrlOrder : function (prCurrentMtrlOrder, prNewMtrlOrder) {
   // Set the order in which process jobs should be processed
   // possible options are:
  //1 = ARRIVAL   process whichever material first arrives
  //2 = OPTIMIZE   process in an order that maximizes throughput
  //3 = LIST   follow the order in the list 
  
 },
 prCommandCallback : function (prJob, prCmd, prCmdParameterList) {
  print("Host Requested \"" + prCmd + "\" on " + prJob + " with parameters " + prCmdParameterList);    
  
  // called when the host reequests that a command be executed on the process job
  // possible commands are    ABORT,STOP,CANCEL,PAUSE,RESUME,STARTPROCESS;
  cmds = ['NONE','ABORT','STOP','CANCEL','PAUSE','RESUME','STARTPROCESS'];  // should never be 'NONE'
  // A different PLC register could be used for each of these and so the command 
  // could be indicated by, for example:
  //  /ModbusE4/STARTPROCESS->setIntValue(1);
  // Here we use a single register and indicate the commands, ABRORT=1, STOP=2, etc.
  
  // first indicate which process job the command is being executed on
  /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());
  // send the parameters - here we just print them
  if ( prCmdParameterList != null ) {
      for ( counter = 0 ; counter < prCmdParameterList.size() ; counter++ ){
         print("Host Requested Parameter \"" + prCmdParameterList.get(counter).getStringValue() + "\" on " + prJob );    
      }
  }
  
  // get the index of the command
  cmdId = cmds.indexOf(prCmd);
  /GEM300PLC/PrCmd->setIntValue(cmdId);
 }
  };
  
 /// START OF MAIN JAVASCRIPT CODE ///
print("Register GEM300");
 
    var controller = null;
    do { 
        //print("host is still null");  
        Thread.sleep(50); //wait 50 ms
        controller = TransSecsController.findController("GEM300PLCTool");
    } while (controller == null);
      
    try {
        E39MessageHandler.addMessageHandler(controller.getControllerName());
        E40MessageHandler.addMessageHandler();
    } catch ( e) {
        print (e);
    }
    E40ServiceWrapper.getInstance().registerCallback(E40Callback);
    
    print("E40 Registered");
   
   

 
</code>

As noted above, if the process job is not set to auto start, you will need to start the job at the tool after the host sends the start command.  In this case, you may want to check the transition to "PROCESSING" in the state change function.  Here's a quick code snippet.
<code>
 prStateChange : function (prJob, oldState, newState) {

   if (newState ==  ProcessJobStates.PROCESSING.getStateId() && oldState == ProcessJobStates.WAITINGFORSTART.getStateId() ) {
      // send the commands to the control system to start executing the process job
   }
    // similar checks may be needed for transitions from PAUSED
    // additional state-change related code.
  
 }
</code>
==== E40 Java Example ====
=== E40 Java Using the Service wrapper calls to process a job ===
Executing a job through E40 requires indicating to the process job the current state of the process. For example:
<code java>
Initialize the handlers:
    try {
      E39MessageHandler.addMessageHandler(equipmentController.getControllerName());
      E40MessageHandler.addMessageHandler();
      E94MessageHandler.addMessageHandler();
      E87MessageHandler.addMessageHandler(2,4);
    } catch (BadParameterException e) {
      e.printStackTrace();
    }
    E40ServiceWrapper.getInstance().registerCallback(new E40Callback());
[...]
 /** Process a Job. */
  protected void processJob() {
    ProcessJob[] allProcessJobs = E40ServiceWrapper.getInstance().getAllPRJobs();
    if ( allProcessJobs.length > 0 ) {
      ProcessJob processJob = allProcessJobs[0];
      processJob.allocated();
      processJob.materialArrived();
      wait500();
      processJob.readyToStart();
      while ( processJob.getPrJobState() == ProcessJobStates.WAITINGFORSTART.getStateId() ) {
        wait500();
      }
      wait500();   
      try {
        processJob.complete();
        processJob.materialDeparted();
      } catch (InvalidStateTransitionException e) {
        e.printStackTrace();
      }
    }
  }
</code>
Notification of changes in process are sent through the 
<code java>
import com.ergotech.secs.e39.E39MessageHandler;
import com.ergotech.secs.e40.E40MessageHandler;
import com.ergotech.secs.e40.E40ServiceWrapper;
import com.ergotech.secs.e40.E40CallbackInterface;
import com.ergotech.secs.e40.ProcessJob;
import com.ergotech.transsecs.secs.TransSecsController;

public class E40Callback {
    public E40Callback() {
        System.out.println("Register GEM300");

        TransSecsController controller = TransSecsController.findController("GEM300Tool");
        } while (controller == null);

        try {
            E39MessageHandler.addMessageHandler(controller.getControllerName());
            E40MessageHandler.addMessageHandler();
        } catch (Exception e) {
            System.out.println(e);
        }

        E40ServiceWrapper.getInstance().registerCallback(new E40CallbackInterface() {
            @Override
            public void prStateChange(ProcessJob prJob, int oldState, int newState) {
                System.out.println("State Change for " + prJob.getPrJobId() + " From: " +
                        ProcessJob.getStateName(oldState) + " to " + ProcessJob.getStateName(newState));
                
             }

            @Override
            public void prJobCreate(ProcessJob prJob) {
                System.out.println("Job Creation of " + prJob.getPrJobId() + " permitted");
                
             }

            @Override
            public void prSetRecipeVariable(ProcessJob prJob, List<?> recVarList) {
                if (recVarList != null) {
                    for (Object recVar : recVarList) {
                        System.out.println("Host Requested Recipe Variable \"" + recVar.toString() + "\" on " + prJob);
                    }
                }
            }

            @Override
            public void prSetMtrlOrder(int prCurrentMtrlOrder, int prNewMtrlOrder) {
                // Handle material order settings
            }

            @Override
            public void prCommandCallback(ProcessJob prJob, String prCmd, List<?> prCmdParameterList) {
                System.out.println("Host Requested \"" + prCmd + "\" on " + prJob + " with parameters " + prCmdParameterList);
                
                String[] cmds = {"NONE", "ABORT", "STOP", "CANCEL", "PAUSE", "RESUME", "STARTPROCESS"};
                int cmdId = Arrays.asList(cmds).indexOf(prCmd);
                
                 
                // Send the parameters
                if (prCmdParameterList != null) {
                    for (Object param : prCmdParameterList) {
                        System.out.println("Host Requested Parameter \"" + param.toString() + "\" on " + prJob);
                    }
                }

            }
        });

        System.out.println("E40 Registered");
    }
}
</code>
==== E40 Python Example ====
<code python>
#!/usr/bin/python3
import jpype
from jpype import JProxy, JArray, JInt
import jpype.imports
from jpype.types import *

jpype.startJVM(classpath=['.', './GEMTool.jar'])

# Importing the necessary Java classes
from com.ergotech.secs.e39 import E39MessageHandler
from com.ergotech.secs.e40 import E40MessageHandler, E40ServiceWrapper, E40CallbackInterface, ProcessJob
from com.ergotech.transsecs.secs import TransSecsController
from java.lang import Thread

# Create the callback interface using a proxy
class E40CallbackImplementation(E40CallbackInterface):
    def prStateChange(self, prJob, oldState, newState):
        print(f"State Change for {prJob.getPrJobId()} From: {ProcessJob.getStateName(oldState)} to {ProcessJob.getStateName(newState)}")
        # Send the new state for the process job to the PLC
        # /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());
        # /GEM300PLC/CurrentProcessJobState->setIntValue(newState);

    def prJobCreate(self, prJob):
        print(f"Job Creation of {prJob.getPrJobId()} permitted")
        # Indicate that this job is not allocated
        # /GEM300PLC/Allocated->setIntValue(0);
        # Record the id
        # /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());

    def prSetRecipeVariable(self, prJob, recVarList):
        if recVarList is not None:
            for counter in range(recVarList.size()):
                print(f"Host Requested Recipe Variable \"{recVarList.get(counter).getStringValue()}\" on {prJob}")

    def prSetMtrlOrder(self, prCurrentMtrlOrder, prNewMtrlOrder):
        # Set the order in which process jobs should be processed
        pass

    def prCommandCallback(self, prJob, prCmd, prCmdParameterList):
        print(f"Host Requested \"{prCmd}\" on {prJob} with parameters {prCmdParameterList}")
        cmds = ['NONE', 'ABORT', 'STOP', 'CANCEL', 'PAUSE', 'RESUME', 'STARTPROCESS']
        # First indicate which process job the command is being executed on
        # /GEM300PLC/ProcessJobId->setStringValue(prJob.getPrJobId());

        if prCmdParameterList is not None:
            for counter in range(prCmdParameterList.size()):
                print(f"Host Requested Parameter \"{prCmdParameterList.get(counter).getStringValue()}\" on {prJob}")

        # Get the index of the command
        cmdId = cmds.index(prCmd)
        # /GEM300PLC/PrCmd->setIntValue(cmdId);

# Instantiate the callback
E40Callback = E40CallbackImplementation()

# Main Python code
print("Register GEM300")

controller = None
while controller is None:
    Thread.sleep(50)  # wait 50 ms
    controller = TransSecsController.findController("GEM300PLCTool")

try:
    E39MessageHandler.addMessageHandler(controller.getControllerName())
    E40MessageHandler.addMessageHandler()
except Exception as e:
    print(e)

# Register the callback
E40ServiceWrapper.getInstance().registerCallback(E40Callback)

print("E40 Registered")

</code>
==== E94 ====

Provides a model of a "Control Job".  Control Jobs are created and managed by the host, or on rare occasions by the tool.  Control Jobs contain Process Jobs (E40) which perform that actual processing of product.

=== E94 Service Wrapper ===

The E94 Service Wrapper provides access to control the flow of E94, however there are no actions required by the tool controller to manage a control job.

=== E94 Callback Interface ===

The E94 Callback Interface provides notification of activity from the host.  A sample implementation of the interface is provided below. The tool control system should implement as many of the methods are required to progress the Control Job through the tool.  Each of the control job actions acts on the underling Process Jobs.

<code javascript>
// create the callback interface.
var E94Callback = new E94CallbackInterface() {
    
    // objID is the ID of the control job
    // cntrlJob is the control job instance.
    
    cjStart : function (objID, cntrlJob) {
    // Host has sent the CJStart Message

    },

    cjPause : function (objID, cntrlJob) {
        // Host has sent the CJPause Message
    },

    cjResume : function (objID, cntrlJob) {
        // Host has sent the cjResume Message
    },

    cjCancel : function (objID, cntrlJob) {
        // Host has sent the cjCancel Message
    },

    cjDeselect : function (objID, cntrlJob) {
        // Host has sent the cjDeselect Message
    },

    cjStop : function (objID, cntrlJob) {
        // Host has sent the cjStop Message
    },

    cjAbort : function (objID, cntrlJob) {
        // Host has sent the cjAbort Message
    },

    cjHOQ : function (objID, cntrlJob) {
        // Host has sent the cjHOQ Message
    },

    cjCreate : function (objID, cntrlJob) {
        // Host has sent the cjCreate Message
    },

    cjStateChange : function (objID, oldState, newState) {
        // The control job has changed states.  states can be as defined in the E94
        // specification and the defined constants in ControlJob
    }
	
}

</code>

==== E87 ====

Provides control of a carrier.  Carriers can be entered manually or automatically and can be verified at the tool - for example by reading an RFID tag, or by the host.  The slot map of the carrier can be read by the tool and verified by the host or provided by the host.

=== E87 Service Wrapper ===

The E87 Service Wrapper provides access to control the flow of E87.  Because there are many paths through the tool, E87 must provide for all these options, however, a particular tool is unlikely to require all the features.  A basic flow, might looks something like this

<code>
      e87ServiceWrapper = E87ServiceWrapper.getInstance();
        // mark the carrier as arrived...
        e87ServiceWrapper.carrierArrived(carrier.getCarrierId(), carrier.getLoadPortId(), true, false);

      // set the slot map.  This slot map and the host slotmap will match
      carrier.setSlotMap(slotMap);  // transition 11 - the host and equipment slot map match.
      if ( carrier.getSlotMapStatus().getIntValue() != Carrier.SlotMapE87State.SLOT_MAP_VERIFICATION_OK.getSlotmapE87StateId() ) {
        System.out.println ("Failed To Verify SlotMap");
      }

      // start processing the carrier
      e87ServiceWrapper.accessCarrier(carrier.getCarrierId(), Carrier.CarrierAccessE87State.IN_ACCESS);
      wait500();
      // carrier access is complete
      e87ServiceWrapper.accessCarrier(carrier.getCarrierId(), Carrier.CarrierAccessE87State.CARRIER_COMPLETE);
      // ending access is not the same as the carrier being ready to unload.  
      e87ServiceWrapper.setLoadPortTransferState(1,9);  // transition the load port to "ready to unload"
      wait500();
      // when unloading starts (manual or auto) transition to "TransferBlocked - 7
      e87ServiceWrapper.setLoadPortTransferState(1,7);  // transition the load port to "ready to unload"
      //carrier.transition21(); // carrier is removed from tool
      // could also be the "cancelBind" service which simply executes transition21 after verifying the carrier and port.
      //e87ServiceWrapper.cancelBind(carrier.getLoadPortId(),carrier.getCarrierId());
      // carrier has departed
      e87ServiceWrapper.carrierDeparted(carrier.getLoadPortId(), carrier.getCarrierId());
</code>

The most commonly used methods to manage an E87 carrier are contained in the Facade interface:
<code java>
package  com.ergotech.secs.e87;


import com.ergotech.secs.SecsException;
import com.ergotech.secs.SecsFormat00;
import com.ergotech.secs.e39.InvalidStateTransitionException;
import com.ergotech.secs.e87.E87ServiceWrapper.CMStatus;
import com.ergotech.vib.exceptions.BadParameterException;



/** This implements the E87 services. It is normally called from E39. */
public interface E87ServiceWrapperFacadeInterface {
  /** Creates the load port object for the specific id.
   * @param loadPortId the id of the load port to create
   * @param readyForService true if the load port is ready for service, otherwise false.
   * If this parameter is true then the load port will transition to "IN SERVICE"
   * and so to "READY TO LOAD" as soon as it is created.
   * @return a new LoadPort
   * @throws BadParameterException thrown if a load port with the given id already exists.
   */
  public void createLoadPort(int loadPortId, boolean readyForService)throws BadParameterException;

  /** This service shall associate a CarrierID to a load port and shall cause 
   * the load port to transition to the RESERVED state.
   * @param portId the port id where the carrier is expected.
   * @param carrierId the expected carrierID.
   * @return CMStatus information concerning the result of the service
   */
  public CMStatus bind ( int portId, String carrierId);


  /** This service cancels a CarrierID to load port association and shall cause
   *  the load port to transition to the NOT RESERVED state.
   * @param loadPortId the portID for which to cancel the load port to carrier 
   * association.  Either PortID or CarrierID must be specified.
   * @param carrierId the CarrierId for which to cancel the load port to carrier 
   * association.  Either PortID or CarrierID must be specified.
   * @return information concerning the result of the service
   */
  public CMStatus cancelBind ( int loadPortId, String carrierId );

  /** This service shall Cancel the current carrier related action, and the 
   * production equipment shall return the carrier to the unload position
   * of the load port.
   * @param carrierId the carrierID to cancel
   * @param portId the PortID where the carrier object is located.  This
   * parameter is not required if the carrier object has previously been 
   * instantiated.
   @return information concerning the result of the service
   */
  public CMStatus cancelCarrier ( int portId, String carrierId);

  /** This service shall Cancel the current carrier related action,
   * and the production equipment shall return the carrier to the unload 
   * position of the load port.
   * @param portId any carrier that exist on the load port specified shall be 
   *  made ready for unloading.
   * @return information concerning the result of the service
   */
  public CMStatus cancelCarrierAtPort ( int portId );

  /** Create a carrier.  This can be mocked for unit testing. 
   * @throws BadParameterException thrown if a Carrier with the given ID already
   * exists.
   * @throws SecsException thrown if the properties list contains a slot map 
   * or a content map who's size does not match the capacity of the carrier.
   */
  public Carrier createCarrier (String carrierId, int loadPortId,  SecsFormat00 propertiesList, int transition ) throws BadParameterException, SecsException;

  /** Stores the callback object.
   * @see com.ergotech.secs.e87.E87Interface#registerCallBack(com.ergotech.secs.e87.E87CallbackInterface)
   */
  public void registerCallBack(E87CallbackInterface callback);

  /** Attempt the state transition on the port.  The port is not checked for
   * validity and an attempt to call this method on an invalid port will cause
   * a null pointer exception.
   */
  public void setLoadPortTransferState(int port, int stateTransition) throws InvalidStateTransitionException;

  /** Return the transfer state of the port.  The port is not checked for
   * validity and an attempt to call this method on an invalid port will cause
   * a null pointer exception.
   * @see com.ergotech.secs.e87.E87Interface#getLoadPortTransferState(int)
   */
  public int getLoadPortTransferState(int port);

  /** Attempt the state transition on the port.  The port is not checked for
   * validity and an attempt to call this method on an invalid port will cause
   * a null pointer exception.
   */
  public void setLoadPortAccessState(int port, int state) throws InvalidStateTransitionException, SecsException;

  /** Returns the current access state of the port.  The port is not checked for
   * validity and an attempt to call this method on an invalid port will cause
   * a null pointer exception.
   * @see com.ergotech.secs.e87.E87Interface#getLoadPortAccessState(int)
   */
  public int getLoadPortAccessState(int port);

  /** 
   * Change the carrier access status.  There are three states:<p>
   *   begin=0<p>
   *   complete=1<p>
   *   stopped=2<p>
   * The carrier is not checked for validity and an attempt to access an invalid
   * carrier will result in a null pointer exception.
   * @throws InvalidStateTransitionException thrown if the access attempt is invalid
   * @throws SecsException thrown if the status is an invalid request.
   */
  public void accessCarrier(String carrierID, Carrier.CarrierAccessE87State state) throws InvalidStateTransitionException, SecsException;

  /** Request to put the port in service.  The port is not checked for
   * validity and an attempt to call this method on an invalid port will cause
   * a null pointer exception.
   * @throws InvalidStateTransitionException
   * @see com.ergotech.secs.e87.E87Interface#getLoadPortAccessState(int)
   */
  public void requestInService(int port) throws InvalidStateTransitionException;

  /** Request to put the port in service.  
   * The port is not checked for validity and an attempt to call this 
   * method on an invalid port will cause a null pointer exception.
   * @throws InvalidStateTransitionException
   * @see com.ergotech.secs.e87.E87Interface#requestOutOfService(int)
   */
  public void requestOutOfService(int port) throws InvalidStateTransitionException;

   /**
   * The application will invoke this when a carrier has arrived at a given port,
   * after it has read the carrier id.
   * 
   * @param carrierId
   * @param port The load port.  The port is not checked for validity and an 
   *             attempt to call this method on an invalid port will cause a 
   *             null pointer exception.
   * @param	readOK the carrier id read is valid.
   * @param bypassReadId if this is true, the carrierID and readOK flags
   *        are ignored and processing continues with the carrier that is at the
   *        provided port.
   * @return 0:verified, 2:waiting for host proceed (or cancel), 3: duplicate id
   * @throws InvalidStateTransitionException
   * @throws BadParameterException
   */
  public int carrierArrived(String carrierId, int port, boolean readOK, boolean bypassReadId, boolean hostVerification ) throws InvalidStateTransitionException, BadParameterException;

  /** When the carrier arrives, the LoadPort may already be in the "Transfer Blocked" state (eg as part of E84).
   * This method will check the current state of the load port.  If it is not in "Transfer Blocked" it will attempt
   * the transition 6.  If that transition is invalide, the method will throw.
   * 
   * @param loadPort the load port on which to execute the transition.
   * @throws InvalidStateTransitionException thrown if load port transition 6 is not a valid transition.
   */
  public void conditionalLoadPortTransition6(LoadPort loadPort) throws InvalidStateTransitionException;

  /** When the carrier departs, the LoadPort may not be in the "Transfer Blocked" state (eg as part of E84).
   * This method will check the current state of the load port.  If it is not in "Transfer Blocked" it will attempt
   * the transition 6.  If that transition is invalide, the method will throw.
   * 
   * @param loadPort the load port on which to execute the transition.
   * @throws InvalidStateTransitionException thrown if load port transition 6 is not a valid transition.
   */
  public void conditionalLoadPortTransition8(LoadPort loadPort) throws InvalidStateTransitionException;

  /** Execute transition21 to indicate that the carrier has departed.  This also destroys the 
   * carrier instance.
   * Set the carrier to null to indicate that it has departed.
   * The port is not checked for validity and an attempt to call this 
   * method on an invalid port will cause a null pointer exception.
   * @throws InvalidStateTransitionException
   * @see com.ergotech.secs.e87.E87Interface#carrierDeparted(int)
   */
  public void carrierDeparted(int port, String carrierId ) throws InvalidStateTransitionException;

  /** 
   * The port is not checked for validity and an attempt to call this 
   * method on an invalid port will cause a null pointer exception.
   * @throws InvalidStateTransitionException
   * @see com.ergotech.secs.e87.E87Interface#carrierDeparted(int)
   */
  public void carrierDeparted(int port) throws InvalidStateTransitionException;

  /** Cancel the carrier at the port.
   * The port is not checked for validity and an attempt to call this 
   * method on an invalid port will cause a null pointer exception.
   * @throws InvalidStateTransitionException
   */
  public void cancelCarrier(int port) throws InvalidStateTransitionException;
  
  /** Returns all carriers
   * @return  an array of all carriers.
   */
  public Carrier[] getAllCarriers();

  /** Return the carrier instance for the ID, or null if the carrier does not exist. 
   * 
   * @param carrierId the carrier id
   */
  public Carrier getCarrier ( String carrierId );

}
</code>

=== E87 Callback Interface ===

The E87 Callback Interface provides notification of activity from the host.  A sample implementation of the interface is provided below. The tool control system should implement as many of the methods are required to progress the carrier through the tool.

<code>
var E87Callback = new E87CallbackInterface() {
  

 cancelCarrierNotification : function (carrierID) {
	//Host has requested to cancel carrier notification.
},
 cancelCarrier : function (portID, carrierID) {
  //Host has requested to cancel the carrier.  We will move to ready to unload.
},
 bind : function (portID, carrierID) {
	// The host has sent a carrier bind message.
},
 cancelCarrierAtPort : function (portID) {
	 // The host has sent a cancel carrier message for the given port.
},
 carrierRelease : function (locationID, carrierID) {
	 // The host has sent a carrier release message.
},
 carrierTagReadData : function (locationID, carrierID, dataSeg, dataLength, pData) {
	 // The Host has sent a carrier read tag request.
   // locationId the id for the location of the carrier.  Either the locationID or the carrier ID must be used.
   // carrierId the carrierID ofthe carrier. Either the locationID or the carrier ID must be used.
   // dataSeg Indicates a specific section of the data
   // dataSize Indicates the number of bytes to read
},
 cancelAllCarrierOut : function () {
	 // The Host has sent a cancel all carrier out message.
},
 changeServiceStatus : function (portID, status) {
	 // The Host has sent a change service status message.
},
 cancelCarrierOut : function (carrierID) {
	 // The Host has canceled its previous carrier out message.
},
 carrierOut : function (portID, carrierID) {
	// Host has requested a carrier out
},
 reserveAtPort : function (portID) {
	 // The Host has sent a reserve at port message.  We will reserve the port or nack this message.
},
 cancelBind : function (portID, carrierID) {
	 // The Host has canceled its previous bind message.
},
 carrierNotification : function (carrierID) {
   // request to instantiate a carrier
},
 cancelReserveAtPort : function (portID) {
	 // The Host has canceled its previous reserve at port message.
},
 carrierRecreate : function (carrierID, propertiesList) {
 // request to recreate a carrier.  propertiesList is a SecsFormat00 
},
 changeAccessMode : function (newMode, portID) {
  // request to change the access mode for the port .  Modes are MANUAL =0 or AUTO = 1
},
 proceedWithCarrier : function (portID, carrierID, propertiesList) {
},
 carrierTagWriteData : function (locationID, carrierID, dataSeg, dataLength, pData) {
	 // The Host has sent a carrier read tag request.
   // locationId the id for the location of the carrier.  Either the locationID or the carrier ID must be used.
   // carrierId the carrierID ofthe carrier. Either the locationID or the carrier ID must be used.
   // dataSeg Indicates a specific section of the data
   // dataSize Indicates the number of bytes to read
   // data the data to write
	public void  carrierTagWriteData(String locationID, String carrierID, String dataSeg, int dataLength, String data) throws CallbackException;

},
 carrierIDVerified : function (portID, carrierID, carrier) {
 // carrier ID has been verified by the host
},
 slotMapVerified : function (portID, carrierID, carrier) {
 // slot map for the carrier has been verifed by the host
},
 carrierIDAndSlotMapVerified : function (portID, carrierID, carrier) {
 // slot map and carrier have been verifed by the host
},
 alarmChanged : function (alarmID, isSet) {
 // an E87 alarm has been set or cleared
},
 stateChange : function (stateModel, state, portID, carrierID) {
     // An E87 State has changed
	 // stateModel will be one of the following indicate which state model has changed state.
	 // 1: LoadPortTransferStateMachine
	 // 2: Carrier ID
	 // 3: Carrier Slot Map
	 // 4: Carrier Accessing State
	 // 5: Access Mode  (Manual/Auto)
	 // 6: Load Port Reservation.  One per port.  Distinguished by port ID.
	 // 7: Load Port Carrier Association
	 // The state will be a valid state for the provided state model
},
 createCarrier : function (carrierID, portID, propertiesList, transition) {
	// Carrier creation.   propertiesList is a SecsFormat00 representing host-provided properties for the carrier
},
 capacityUpdated : function (carrier, capacity) {
	// The Host has sent a new capacity for the carrier.
},
 contentMapUpdated : function (carrier, propertiesList) {
  // The Host has sent a new content map for the carrier.   propertiesList is a SecsFormat00 representing host-provided properties for the carrier
},
 hostSlotMapUpdated : function (carrier, hostSlotMap) {
  // The Host has sent a new slot map for the carrier. 
},
 substrateCountUpdated : function (carrier, substrateCount) {
   // The Host has sent a new substrate count for the carrier. 
},
 usageChangeRequest : function (carrier, usage) {
  // The Host has sent a new usage for the carrier. 
  // Usage is equipment defined, examples: "TEST", "DUMMY", "PRODUCT"
 }
}

</code>