The GEM Pass-Through Bridge

A pass-through sits between a fab host and a tool that already exists, and adds to it. The fab host connects to the pass-through instead of to the tool, sees one GEM interface, and is not changed. The tool is not changed either: nothing is installed on it and nothing is asked of its vendor.

What the pass-through adds are variables, events, alarms and traces the original tool cannot produce — a value read from a sensor the tool does not know about, an event derived from a signal on an MQTT topic, an alarm the tool has no ALID for. Everything the tool does report is relayed untouched, in both directions, including the host's configuration of reports, events, alarms and traces.

The whole of the configuration is one project, and the one thing in it you must set by hand is the range of ids the pass-through owns. Everything else follows from that range.

A pass-through is two GEM interfaces, and in TransSECS they are two tabs of the same project.

They are one project on purpose. The bridge holds direct object references to both controllers rather than talking to itself over a socket, so both must be in one JVM — and in a deployment only the PassThroughTool has a main. Its startup trigger, the StartBridge server, starts BridgeHost and then the bridge.

Two consequences of the single project that catch people out:

• Only the tab in front runs. Switching tabs stops the other interface. That is what this

needs: PassThroughTool starts BridgeHost itself, so BridgeHost must not also be running in its

  own tab.
* **Devices are live in the editor whether or not you press Run.** The StartBridge trigger
  therefore ticks while you are simply looking at the tab. It checks whether the tool interface is
  actually running and says so at debug level rather than connecting to the real tool behind your
  back.

The bridge has to know, for every id, whether it belongs to the existing tool or to the pass-through. That single fact decides everything it does:

It is declared in StartBridge, in the project, with one call:

bridge.setSideChannelIds("100000-");

setSideChannelVids, setSideChannelCeids and setSideChannelAlids override it for one kind of id and default to it, so a single range is normally all you write. VIDs, CEIDs and ALIDs are separate id spaces: an ALID 311 and a CEID 311 are unrelated.

There is deliberately one list, and it is this one — the ids the pass-through owns. Everything else the PassThroughTool knows is the existing tool's. The earlier design kept two lists (the characterization said what the tool owned, the project said what it knew) and nothing kept them in step: a PassThroughTool that was a subset of the real tool left the BridgeHost with a list that was wrong. Deriving both from one range removed that, and it is also why a tool that cannot be characterized needs no characterization and no model file at all.

<WRAP center round important 60%> Leave the range undeclared and the bridge falls back to the characterization on disk for ownership. An empty or stale BridgeHostModel.json then makes every ownership test false: nothing projects, nothing refreshes, nothing re-fires, and the bridge runs while doing none of its job — with no error to say so. Declare the range even when the tool below has been characterized. </WRAP>

Why a range and not, say, a device binding? Because a device binding is not a statement about ownership. A side-channel variable may have no device at all (a script writes it), and a tool-owned variable may be given a device for local simulation. A range says what you mean, and it reads at a glance in a review.

1. Open the sample project. It ships as Projects/PassThrough — two tabs, a bare

PassThroughTool, an MQTT side channel as the worked example, and the StartBridge trigger. Copy

  it to a new folder before you start work.
- **BridgeHost tab: point it at the tool.** Set ''HostName'' and the port, then **Run**.
- **Characterize — if you can, and it is worth it.** The host asks the tool what it has (S1F11,
  S1F21, S1F23, S2F29, S5F5, S6F17 per event) and writes ''BridgeHostModel.json'' into the project
  folder. This is **not** a precondition for the bridge: see the box below. Its value is that the
  next step imports it, which saves typing every id by hand, and that the bridge then reports
  where the file and the project disagree.
- **Stop BridgeHost, then Build it.** If you characterized, do it //before// you build: the build
  also produces ''BridgeHostDigitalTwin'', which carries the model. The PassThroughTool deployment
  needs BridgeHost's jar either way — so BridgeHost is always built first.
- **Switch to the PassThroughTool tab.** That stops BridgeHost.
- **Populate PassThroughTool** with what the tool reports — see section 4.
- **Add what this pass-through contributes** — see section 5.
- **Set the side-channel range** in StartBridge to match the ids you just added.
- **Build, then Run.** The trigger starts BridgeHost from the classes its build left behind,
  applies the range, and bridges the two. The fab host now connects to 41825.
- **Characterize the fab host against the pass-through**, exactly as if it were the tool.

<WRAP center round tip 60%> The characterization is optional, and the range is what makes it so. With SIDE_CHANNEL set in StartBridge, ownership comes from the range and BridgeHost's model is derived from the PassThroughTool, so the bridge starts with no BridgeHostModel.json at all and only the tool half is ever configured. A characterization that does exist is then used for two things: the import in section 4, and a cross-check — the bridge logs an id the file has and this project does not (one the tool below reports and the pass-through cannot carry), and an id this project has outside the range that the file does not. A host model that was characterized is kept rather than overwritten by the derived one, because it carries real value types.

The one case that needs the file is an undeclared range: then it is the only statement of ownership there is, and StartBridge defers rather than start a bridge that would do nothing. </WRAP>

The fab host sees the existing tool's ids plus the side channel, with no way to tell which is which — which is the point.

The PassThroughTool must know every id the fab host may ask about: the existing tool's as well as its own. That is what the fab host characterizes. The BridgeHost needs no ids of its own — its model is derived from the PassThroughTool minus the side-channel range.

There are three ways to get the tool's ids in, and they can be mixed.

File → Import Tool Model (JSON), and choose BridgeHostModel.json.

Every variable, event and alarm the tool reported is added, or updated in place if it is already there. Importing again after re-characterizing updates rather than duplicates, and leaves your own additions alone — so a tool that gains ids in a vendor upgrade is picked up by re-characterizing and re-importing.

An import deliberately leaves alone what a model cannot know:

• Event descriptions. A characterization has no event text.
• Alarm codes (ALCD). Characterization recorded 6 for every alarm until September 2026, so

older models carry wrong codes.

• Alarm names. A model's alarm name is its ALTX.
• The types of the variables TransSECS defines itself (MDLN, SOFTREV, the

control-state group).

Right-click the VIDs, CEIDs or ALIDs node and add what you need. Reasonable for a handful of ids; for a tool with two hundred, use an import and then edit.

Tools often come with a listing instead of a live interface: the console output of the vendor's own svidgen-style utility, a spreadsheet export, a report. One vendor's report format is one customer's file, so the reader for it is not part of TransSECS. It is delivered as a jar and a script, and TransSECS loads it.

If you have been given a jar and a .js:

1. Put the jar in the Builder's addons folder, MIStudioSuite/TransSECS/Builder/addons (the

project's own addons folder works too).

1. Restart TransSECS. Jars are read when it starts; one dropped in while it is running is not

seen.

1. Open the project and select the tab of the tool to import into. The import writes into the

tab in front of you.

1. File → Import UsingScript, and choose the .js.
2. The script then asks for the listing itself. Choose it, and the ids are written into the

equipment tree: status variables, equipment constants, alarms, events, and a data variable for

  each event whose text the tool substitutes at run time.

The same rules apply as to a JSON import: a second import of the same listing updates rather than adds, and the names TransSECS owns are not renamed by a file. Rows the parse did not understand are printed, not dropped — read the console, or wrapper.log, after an import. A listing that is quietly missing ids is the failure this path exists to make visible.

The reference implementation is GemIdListingImport.jar with ImportSvidListing.js, which reads a plain-text svidgen listing. Writing a reader for another format means subclassing ParseGemIdList and supplying parse(File) — the half that turns what was read into tree nodes without duplicating or renaming is already in TransSECS, and needs no editor, project or licence to test.

The variable's CEID field is the “change event”, and it is the most useful thing here: no wiring, no script. Two details decide whether it fires:

• Numeric variables honour the Deadband — a change smaller than the deadband is not a

change. -1 means no deadband.

• Setting LimitMin/LimitMax takes the change event away. A variable with limits becomes

limits-monitored (zone transitions, S2F45/F47) and no longer fires its CEID on change. You get

  one or the other.
* **Non-numeric variables** (a string, a boolean) fire on any change of value. This worked only
  from September 2026; before that a non-numeric variable with a CEID attached could never fire
  it.

A script belongs on the device tag, in the Devices tree — not on the GEM id. It runs when a value arrives at that tag, with the arriving value in scope as incomingValue, and it can read and write anything else in the project:

// script on the Tank2LotPresent side-channel tag
if (incomingValue.getQuality() == 0) {                       // 0 is good quality
  var TransSecsController = Java.type("com.ergotech.transsecs.secs.TransSecsController");
  var gem = TransSecsController.findController("PassThroughTool").getGemHandler();
 
  var temp = gem.getServerForName("VID.Tank2Temp").getFloatValue();
 
  // true sets the alarm and sends S5F1, false clears it
  gem.getServerForName("ALID.ColdBathWithLot").setBoolValue(temp < 90 && incomingValue.getBoolValue());
 
  // and/or fire an event
  gem.getServerForName("CEID.LotEnteredTank2").setIntValue(1);
}

• GEM ids are reached by name: VID.<name>, CEID.<name>, ALID.<name>. Case does not

matter.

• Other beans are reached with the arrow: /Devices/Group/Bean→getIntValue().
• output = … in a tag script replaces the value on its way through — useful for scaling a

raw reading.

• A script-scope variable does not survive to the next execution, so an edge has to be read

from a bean's own last value rather than remembered in the script.

Edge triggering applies to a CEID driven this way. With transsecs.ceidedgetrigger=true — the default in every shipped configuration — a trigger only fires on the transition to true; writing 1 over 1 is dropped (logged at debug). That is what you want for a level from a PLC and a nuisance when you mean “send it again”: for the latter, the event has to be sent forced, through GemHandler.sendEventReport(ceid, dvvals, true).

The runtime is capable of all of these — every GEM id is a scriptable bean and the script hook is already on the path the bridge delivers on — but the registration path only applies a script to an ECID. If a derived-from-the-tool event is what a job needs, that is a small, contained product change, not a workaround to be invented per project.

Set the deployment type to Pass-Through Tool. The build then puts BridgeHost, the bridge and the characterization into PassThroughToolDeployment, so the folder runs on its own:

cd PassThroughToolDeployment && sh run.sh

It needs GEMBridge.jar, which the GEMBridge module installs into MIStudio/jars. That jar is referenced only by the pass-through build, so an ordinary tool project neither needs nor sees it.

While the existing tool is unreachable the bridge closes the fab host's port rather than answering for a tool it cannot reach, and reopens it when the tool comes back. A fab host that prefers a connected-but-silent pass-through can turn that off with bridge.setStopListeningWhileToolDown(false) in StartBridge.

Projects/PassThrough is the two tabs, ready to work in:

• PassThroughTool — the variables every GEM tool has, plus an MQTT SideChannel device with

four tags wired to VIDs 100001-100004, and DemoECID at 100005, as the worked example of what

  a pass-through adds.
* **BridgeHost** — pointed at ''localhost:5010''.
* **StartBridge.js** — the readable copy of the startup trigger. The one that runs is the script
  property of the StartBridge server inside ''PassThroughTool.tsx''; **edit them together**.
* **PlasmaEtcherModel.json** — a characterization of a plasma etcher that does not exist: 56
  variables, 23 events, 12 alarms. Give it to a digital twin and you have a tool to bridge without
  needing a real one. ''README.md'' in the project folder says how.

Written 2026-10-24 (J Redman with Claude Opus 5).