secs-gem/docs/02_the_cast.md

02 — The cast of characters

← 01 What is SECS/GEM? | Back to index | Next: 03 Vocabulary + a wafer's journey →

Chapter 01 explained that SECS/GEM is the protocol a fab uses to make ~100 tools talk to a central MES. That description hid a lot of structure. In reality, there are at least six distinct actors in a typical fab automation stack — six roles, each implemented by different software (often by different vendors), each with its own concerns.

This chapter introduces them all, draws who-talks-to-whom, and locates each one in this codebase. After this you'll be able to read any SECS conversation and know which actor is initiating, which is responding, and why.

---

The six actors

                          ┌──────────────────┐
                          │   Fab planner    │   "make 100 wafers
                          │   (MES upper)    │    of recipe R by
                          └────────┬─────────┘    Friday"
                                   │
                  recipes, lot     │   yields, KPIs,
                  assignments,     │   alarms, status
                  process programs │
                                   ▼
                          ┌──────────────────┐
                          │  MES (the host)  │   per-step orchestration
                          └────────┬─────────┘
                                   │
                  SECS/GEM         │   SECS/GEM
                  S2F41 RCMD,      │   S6F11 events,
                  S7F3 PP send,    │   S5F1 alarms,
                  S2F33 reports,   │   S1F4 status
                  …                │   …
                                   ▼
                          ┌──────────────────┐
                          │   EAP / equipment automation program     │
                          │   (vendor application layer)             │
                          ├──────────────────────────────────────────┤
                          │   THIS CODEBASE — the SECS/GEM runtime   │
                          │   secsgem::gem  /  secsgem::hsms  /  …   │
                          └────────┬─────────────────────────────────┘
                                   │
                  PLC / sensor / recipe-engine APIs (tool-specific)
                                   │
                                   ▼
                          ┌──────────────────┐
                          │  Equipment       │   the physical tool:
                          │  (the tool)      │   chambers, robots,
                          └────────┬─────────┘   sensors, recipes
                                   │
                  E84 8-line       │   (carrier moves, no SECS bytes)
                  parallel I/O     │
                                   ▼
                          ┌──────────────────┐
                          │  AMHS            │   robot rails / OHT
                          │  (the carriers)  │   that move FOUPs
                          └──────────────────┘

                  ←───── Operator ──────→  panel buttons,
                                           recipe overrides,
                                           Online/Offline/Local/Remote

Read the diagram top-down: a fab planner schedules work, the MES dispatches it tool by tool, each tool's EAP receives commands over SECS/GEM, the EAP drives the actual hardware, the AMHS robots feed carriers in and out. An operator can intervene at any layer.

Each actor has a section below.

---

1. Equipment — the tool itself

What it is. A physical processing tool — a chemical-vapor deposition (CVD) chamber, a plasma etcher, a wafer prober, a photolithography stepper, an ion implanter, an inspection microscope. Anywhere from one chamber the size of a microwave to a full lithography cluster the size of a small bus.

What it does in SECS/GEM terms.

• Reports state — its current control state (Equipment Offline, Online Remote, …), its processing state (IDLE, EXECUTING, …), its carrier slots, its current recipe.
• Emits events — when something happens worth recording (processing started, wafer processed, alarm raised, recipe completed), it fires an S6F11 to the host.
• Accepts commands — START, STOP, ABORT, PAUSE, CHANGE-RECIPE, CARRIER-PROCEED, etc., delivered as S2F41 Host Commands.
• Stores its data dictionary — every Status Variable (SVID), Equipment Constant (ECID), Data Variable (DVID), Collection Event (CEID), Alarm (ALID), and Process Program (PPID) it supports.
• Manages its own physical safety — it can refuse a host command if the requested action would damage hardware, and it can raise alarms autonomously.

In SECS/GEM, the equipment is almost always the "passive" side of the connection — it binds a TCP port and waits for the host to connect, rather than the other way around. This codebase reflects that: apps/secs_server.cpp is the equipment, and it listens.

Where it lives in this codebase.

• The equipment role's main binary: apps/secs_server.cpp.
• The data dictionary: include/secsgem/gem/data_model.hpp defines EquipmentDataModel, which composes every per-domain store (SVIDs, ECIDs, CEIDs, alarms, carriers, substrates, recipes, spool, …).
• A worked example with sensor simulation, recipe runner, and alarm monitoring: examples/pvd_tool/main.cpp.
• Tests covering equipment behaviour: tests/test_data_model.cpp, tests/test_control_state.cpp, tests/test_host_handler.cpp.

---

2. EAP — the equipment automation program

What it is. The vendor-written software layer that sits on top of the SECS/GEM runtime and makes the tool actually do things. The EAP is the glue between:

• The SECS/GEM library (this codebase),
• The tool's PLCs / sensors / recipe engine / robot controllers,
• The tool vendor's domain logic.

Every tool vendor ships their own EAP. Two CVD tools from different vendors both speak GEM, but their EAPs are entirely different codebases doing entirely different things internally.

Why it's a separate role. The SECS/GEM standards spell out what messages mean — "S2F41 with RCMD=START must initiate processing on the currently loaded recipe." They don't spell out how a specific CVD tool initiates processing on its specific hardware. The EAP is the layer that resolves that.

In particular:

• When S2F41 RCMD=START arrives, the EAP decides whether the tool is in a state to start (chamber pressure low enough? robot at home position? recipe loaded?), and if so, calls the tool's proprietary recipe engine to begin the cycle.
• When a sensor reads a temperature change, the EAP decides whether to update an SVID, fire a CEID, or raise an alarm — and the per-tool rules for that aren't in any SEMI standard.
• When a S7F3 arrives with a new recipe payload, the EAP decides how to validate the recipe against the tool's actual hardware capabilities.

Where it lives in this codebase.

This codebase provides the SECS/GEM runtime; the EAP is what a customer writes on top of it. We ship two reference EAPs:

• apps/secs_server.cpp — the demo server. Wires every Router handler the demo flow needs; uses static YAML data and doesn't simulate any sensors. Useful as a starting fork.
• examples/pvd_tool/main.cpp — a fictional PVD tool that adds a sensor simulator, a recipe runner, an alarm threshold monitor, EPT state cycling, and Prometheus metrics. This is the closest thing to "what a real EAP looks like" that we ship. See examples/pvd_tool/README.md for the section-by-section walk.

The integration tutorial — how to write an EAP for a real tool — is INTEGRATION.md. Chapter 41 in this series covers the same material with cross-references back to the standards.

---

3. MES — the host

What it is. The Manufacturing Execution System. A fab-wide server (or cluster) that orchestrates production across every tool, manages lots and recipes, collects yield and statistical process control (SPC) data, and provides the operator UI for the production floor.

Commercial MES vendors you'll meet: Applied Materials E3, Camstar InSite, Wonderware MES, Aegis FactoryWorks, Inficon FabGuard, Critical Manufacturing MES, and many in-house custom builds especially at the largest fabs.

What it does in SECS/GEM terms.

• Connects to each tool's equipment process. In SECS/GEM language, the MES is the active side of the HSMS connection (it initiates the TCP connect and sends Select.req).
• Establishes communications — sends S1F13 to which the equipment replies S1F14(COMMACK=Accept).
• Identifies the tool — sends S1F1 (Are You There), reads back the MDLN (model name) and SOFTREV (software revision) in S1F2.
• Reads the data dictionary — S1F11 for the SVID namelist, S2F29 for the ECID namelist, S1F23 for the CEID namelist, S5F5 for the alarm directory, S7F19 for the recipe list.
• Configures event reports — S2F33 defines a report, S2F35 links it to a Collection Event, S2F37 enables it. This is how the MES tells the tool "when CEID 300 fires, send me the values of SVIDs 1 and 2 along with it."
• Issues remote commands — S2F41 RCMD=START, S2F41 RCMD=PAUSE, S2F41 RCMD=ABORT, etc.
• Manages recipes — S7F3 to send a recipe, S7F19 to list, S7F17 to delete, S7F5 to read one back.
• Orchestrates process and control jobs — S16F11 to create a Process Job, S14F9 to wrap it in a Control Job, S16F27 CJSTART to begin execution.
• Receives alarms and events — S5F1 for alarm set/clear, S6F11 for collection events. Acknowledges with S5F2 and S6F12 respectively.
• Sets and reads the equipment's clock — S2F17/S2F18 to read, S2F31/S2F32 to set.

Where it lives in this codebase.

We don't implement an MES — that's a separate, much larger product category. We implement the host side of SECS/GEM so the codebase can drive equipment too, mainly for testing.

• apps/secs_client.cpp — the active host that drives the demo server through ~24 transactions.
• apps/secs_conformance.cpp — the host-driven conformance harness that runs the 47 wire-level checks.
• include/secsgem/gem/host_handler.hpp
  • src/gem/host_handler.cpp — symmetric handler module so the host side can decode equipment replies and act on equipment-initiated S5F1 / S6F11.
• interop/host_vs_cpp_server.py — the secsgem-py active host driving our C++ passive server.

For integrating against a commercial MES, MES_INTEROP.md is the day-1 punch list.

---

4. Fab planner / MES upper layer

What it is. The layer above the MES. Goes by many names: Advanced Planning and Scheduling (APS), Fab scheduler, Dispatcher, MES upper. Big fabs separate this from the operational MES; smaller ones bundle it in.

What it does. Decides which lot runs on which tool, in what order, against what recipe, by what deadline. This is fab-wide optimisation across hundreds of in-flight lots and dozens of routes.

SECS/GEM contact: none directly. The planner talks to the MES via REST / SQL / a message queue / a proprietary API. The MES translates planner decisions into SECS commands.

Where it lives in this codebase. Not implemented; out of scope. Mentioned here so the reader knows where the recipes and lot assignments ultimately come from, but no codebase artifact corresponds to this layer.

---

5. AMHS — Automated Material Handling System

What it is. The robot-rail network and overhead hoist transport (OHT) system that physically moves carriers (FOUPs holding ~25 wafers each) between tools. In a modern 300 mm fab the AMHS is always moving carriers between tools 24/7; humans never touch a substrate.

What it does in SECS/GEM terms.

• The AMHS itself doesn't speak SECS/GEM — it has its own control plane talking to a Material Control System (MCS) which is conceptually peer to the MES.
• But every time a carrier arrives at or departs from an equipment's load port, the AMHS-side robot and the equipment-side load port handshake over 8 parallel I/O lines defined by E84. This is a physical-layer handshake (CMOS-level voltages on real wires) with strict timing — TA1, TA2, TA3 timers — to make sure a $20 000 FOUP doesn't get dropped because both sides thought the other one was holding it.
• Once the carrier is physically docked, the equipment fires a S6F11(CarrierArrived) event to the MES and the MES sends back a S3F17(CarrierAction=ProceedWithCarrier) to authorise processing.

Where it lives in this codebase.

• The E84 handshake state machine: include/secsgem/gem/e84_state.hpp
  • src/gem/e84_state.cpp.
• The TA1/TA2/TA3 timer wiring (asio): include/secsgem/gem/e84_asio_timers.hpp.
• The per-port store: include/secsgem/gem/store/e84_ports.hpp.
• Tests covering the timing rules: tests/test_e84.cpp, tests/test_e84_timers.cpp, tests/test_e84_asio_timers.cpp, tests/test_e84_ports.cpp.

Chapter 18 covers E84 in full.

---

6. Operator — the human

What it is. The fab technician at the tool's local panel. Their job is to handle anything the automation can't: load a non-AMHS carrier, clear a jammed wafer, run a maintenance recipe, respond to an alarm the MES can't auto-clear.

What they do in SECS/GEM terms.

• Mode switch. The operator can push the equipment between control states: EquipmentOffline, OnlineLocal (commands accepted only from the local panel), OnlineRemote (commands accepted from the MES). This is E30 §6.2.
• Override. An operator can override an MES command (refuse to start, force-clear an alarm, manually unload a carrier). In SECS/GEM terms this is reflected by control-state transitions: OnlineRemote → OnlineLocal means "operator has taken control."
• Local alarm acknowledgement. Some alarms can be cleared at the panel without the MES being involved; the equipment then emits an S5F1 with the cleared bit so the MES catches up.

Where it lives in this codebase.

• The control state machine: include/secsgem/gem/control_state.hpp
  • src/gem/control_state.cpp.
• The transition table loaded from YAML: data/control_state.yaml.
• The operator-initiated transition handlers: ControlStateMachine::operator_online, ::operator_offline, ::operator_local, ::operator_remote in the same header.
• Tests: tests/test_control_state.cpp.

Chapter 13 walks through control state in detail.

---

Who talks to whom

A short reference table. "Init." marks who initiates the conversation; "Channel" marks the protocol layer.

Pair	Init.	Channel	Examples
Planner ↔ MES	Planner	REST / SQL / queue (out of scope)	"run lot L on tool T with recipe R"
MES ↔ EAP	MES	HSMS-SS (one TCP socket, equipment passive)	S1F1, S2F41, S6F11, S5F1, …
MES ↔ EAP (multi-MES)	MES	HSMS-GS (one TCP socket, multiple sessions)	Same messages, demuxed by session_id
EAP ↔ Equipment	Either	PLC / sensor APIs / recipe engine (tool-specific)	Out of scope of SECS/GEM
AMHS ↔ Load port	AMHS	E84 8-line parallel I/O	VALID/CS_0/CS_1/TR_REQ/READY/BUSY/COMPT/CONT/L_REQ/U_REQ/ES
MES ↔ EAP (carrier flow)	Equipment	HSMS	S6F11(CarrierArrived), S3F17(ProceedWithCarrier)
Operator ↔ Equipment	Operator	Local panel	Online/Offline buttons, alarm acks

The four interesting things in this table:

1. The MES is the active side, the equipment is the passive side. Always. Equipment binds the port; MES connects to it. Some MES want this reversed and will negotiate, but the GEM default is equipment-passive.
2. One TCP socket per (MES, equipment) pair. HSMS-SS doesn't multiplex; one connection serves one conversation. HSMS-GS adds session multiplexing on top.
3. Equipment-initiated traffic exists. S6F11 events and S5F1 alarms fire from equipment to MES autonomously, not in reply to a host command. An EAP that never emits unsolicited traffic is broken.
4. The AMHS handshake is out-of-band relative to SECS/GEM. E84's 8 parallel I/O lines are real wires with real voltages; the SECS messages that follow (S6F11, S3F17) are just the bookkeeping around a handoff that already happened in hardware.

---

A small mental check

If you've internalised the chapter, you should be able to answer:

1. When the MES sends S1F13, who initiates the TCP connection?
2. When a chamber pressure sensor reads out of range, who decides whether to fire S5F1?
3. What language does the AMHS speak to the equipment to coordinate a FOUP handoff?
4. Is the operator at the local panel a SECS/GEM actor?
5. Is the fab planner a SECS/GEM actor?

Answers, in order:

1. The MES. The equipment is passive; it binds and waits. TCP connect is the MES's first move.
2. The EAP (the vendor's application code on top of this library). The SECS/GEM library doesn't know what's a "normal" pressure; the EAP does. Once the EAP decides "this is alarm-worthy," it calls into the alarm store and the library emits S5F1.
3. E84 8-line parallel I/O — physical wires, not SECS. After the handoff, the bookkeeping SECS messages (S6F11, S3F17) flow between equipment and MES.
4. Yes — through E30 §6.2 control-state transitions. Not a SECS message sender, but a state-transition source the equipment has to report on.
5. No. The planner talks to the MES; the MES talks to the EAP. The planner is invisible from the SECS wire.

---

What's next

You now know who's in the room and who's talking to whom. The next chapter introduces the vocabulary — every SEMI acronym you'll read in a debug log (SVID, CEID, ALID, PPID, ALCD, HCACK, T-timers, …) — by tracing one wafer's journey end-to-end through a fab and labelling every SECS message that fires along the way.

Next: → 03 Vocabulary + a wafer's journey