===== Architecture Overview =====

TransSECS acts as a translation hub that turns every SECS/GEM interaction into MQTT + Sparkplug B payloads that any IIoT or SCADA application can consume in real-time.

    • SECS/GEM Link – TransSECS runs the GEM host role over HSMS-TCP.
    • Sparkplug Broker – an external MQTT broker (Ignition, HiveMQ, Mosquitto, …) distributes the data.
    • Mapping Rule –
        ◦ One GEM host ⇢ One Sparkplug Node
            ▪ The Node ID is normally the host name or its DeviceID (e.g. ‘’GEMHost’’).
        ◦ Every GEM message or data collection object ⇢ One Sparkplug Device
            ▪ Static constructs: configuration snapshots, constant templates (e.g. ‘’SecsAlarmTemplate’’).
            ▪ Dynamic constructs: SxFy commands/replies, event reports, traces, polls, VIDs, ECIDs.
            
    • Lifecycle –
        ◦ NBIRTH declares the Node and publishes common templates.
        ◦ DBIRTH is sent once per Device at session start, providing a self-describing schema.
        ◦ DDATA updates flow continuously as the host exchanges SECS messages with the tool.
        ◦ DCMD topics (host-initiated) let external clients trigger host commands or polling cycles.
        ◦ NDEATH/DDEATH occur if the HSMS link drops or the host project is stopped.
        
This mapping keeps MQTT topic trees flat, avoids massive tag explosions, and preserves full GEM semantics—including primary/secondary pairs and structured parameter lists—without custom parsers on the subscriber side.

===== Project Summary =====

TransSECS bridges SECS/GEM automation with modern Sparkplug B IIoT ecosystems.
By treating a GEM host as a Sparkplug node and every GEM interaction (messages, traces, polls, reports) as separate devices, the project delivers:

    Loss-less, real-time visibility of all tool communications over standard MQTT topics.
    Plug-and-play tag discovery for SCADA, MES and analytics platforms—no SECS expertise required.
    Bidirectional control, allowing higher-level applications to issue GEM remote commands simply by writing to Sparkplug metrics.

The result is a unified data pipeline that preserves the rigor of SEMI E30 while unlocking the scalability and openness of MQTT for next-generation smart-factory deployments.
    • Goal – expose all GEM data (events, variables, alarms, host commands, traces, polls) as native Sparkplug tags so analytics, dashboards, or MES extensions can subscribe with zero GEM knowledge.
    • Key Features –
        ◦ Template-driven DBIRTHs ensure every field is typed and documented.
        ◦ Real-time DDATA keeps OT applications in sync with the tool at millisecond resolution.
        ◦ DCMD path provides a secure, auditable way to drive tool commands from MQTT clients.
    • Outcome – manufacturers gain AI-ready, broker-based access to rich equipment data while protecting existing GEM investments; integrators can write once to Sparkplug and deploy everywhere—from edge gateways to cloud analytic pipelines.

===== Birth Messages Begin =====
Objective – announce the GEM host to Sparkplug clients and publish a schema (“templates”) for every GEM object that may appear later in the session.

NBIRTH – brings the Node “GEMHost” online and sets the ''Node Control/Rebirth'' flag to //false// (fresh start).

''bdSeq'' is the node’s monotonic sequence counter; clients can detect missed packets if the counter ever skips.

Template blocks

''SecsAlarmTemplate'' → provides the canonical field order for any S5 alarm (''ALID, ALCD, SET, ALTX'').

”00” and ”ArrayValue” templates cover raw SECS-II data and array values, respectively.

One DBIRTH per GEM construct – each message that the host can issue or accept (e.g. ''ECIDRequest'', ''HostCommandSTART'') is given its own Device under the node.

''Device Control/Rebirth'' (Boolean) tells subscribers whether the driver is merely updating values or requesting that the message be resent over SECS.

''responseStatus'' (Int32) is the TransSECS driver’s internal return code (''0 = OK'').

''sendMessage'' (Boolean) is //true// only when the host actively asks the driver to transmit the payload (DCMD → S2F41, S1F3, …).

Most-important DBIRTHs in this sequence

''ECIDRequest'' – schema for S2F13 requests (defaults to ECID 2000).

''SVIDListReply'' – placeholder for the massive list returned by S1F12.

''configuration'' – snapshot of every host-level setting that was mapped to VIDs (timeouts, link speed, host IP etc.).

''HostCommandSTART/PPSELECT/STOP'' – expose parameter names expected by the tool.

''Enable All Alarms'', ''Request OnLine'', ''CEIDList'' – control and discovery primitives.

<note tip> Treat each DBIRTH as a tag definition. Runtime values arrive via DDATA on the same topic hierarchy.</note>


{{:puml.png?500&align=center}}

===== Host Startup =====

 STATE topic check – the broker publishes ''spBv1.0/STATE/Servers_HostNode'' once the NBIRTH has been accepted and TTL monitoring is active.

 "online=true" confirms that the node is considered healthy; TransSECS will not generate DCMD traffic until this flag is true.

 Timestamp – given in POSIX ms; it matches the SECS driver’s local clock and can be used for coarse latency measurements.
    
{{?puml_001.png?500}}

===== Good Host Commands =====

 Flow – the host sends PP-SELECT (DCMD/GEMHost/HostCommandPPSELECT, ''sendMessage=true'') → TransSECS forwards S2F41 W → the tool replies S2F42 (''HCACK 0'').

 Sparkplug updates:

     * The driver immediately publishes a ''DDATA/…/HostCommandPPSELECT'' echo with ''sendMessage=false'' to show the command as sent.
  * 
  *    The tool’s S2F42 is translated to ''DDATA/…/HostCommandReply'' where ''HCACK=0'' indicates success.
       
 Parameters – ''LOTIDParamValue'' and ''PPIDParamValue'' appear exactly as entered by the host; on success they are echoed back unchanged.

 <note tip>SCADA / MES clients should subscribe to ''…HostCommandReply'' and check ''HCACK'' before assuming the tool accepted the command</note>

{{puml_002.png?500|}}

===== Bad Host Commands =====

Scenario – the host issues PP-SELECT with an invalid PPID; the tool rejects it with ''HCACK 3'' and a populated ''ReasonList''.

ReasonList structure – an array of tuples ''<ParameterName, ErrorCode>''.

  * In this example → ''PPID, 1'' (= “parameter unknown or out of range” in many GEM implementations).

Error detection – any non-zero ''HCACK'' must be treated as a transaction failure; the associated ''HostCommandPPSELECT'' echo still appears but only confirms that the message was transmitted, not that it succeeded.

<note tip>log ''ReasonList_*'' for root-cause analysis and surface a human-readable alarm where appropriate.</note>
  
{{puml_003.png?500|}}

===== Triggering COMPLETED Event =====

Event 7502 (COMPLETED) – the tool raises S6F11 with ''ReportID 100 (LotEndReport)''.

TransSECS actions

  * Updates ''Variables'' with the content of the lot-end report (''CLOCK, LOTID, PPID, WaferCount'').

  * Publishes ''EventMessage'' → ''LastEvent = 7502'', ''LastEventName = COMPLETED''.

  * Sends S2F23/S2F24 to terminate any active trace whose end-event is “COMPLETED” (here: ''TRID 3000'').

Why two COMPLETED bursts? – the example shows two sequential lots finishing quickly; both follow the identical publish path, proving that templates survive across lot boundaries without requiring a new DBIRTH.
    
{{puml_004.png?400|}}
    
===== STARTED Event → Polling Initiation =====

Event 7501 (STARTED) – triggers both a ”DataReport” (ID 101) and a ”LotEndReport” snapshot.

* Key process parameters (''GasFlow, ProcessTemperature, SetPoint'') are captured immediately.

Poll activation – on STARTED, TransSECS enables the S1F3 poll group ''S1F3Poll'' (1.5 s cadence).

 * Each poll produces a pair of messages:

    * Over SECS: S1F3 W / S1F4 reply.
    * Over Sparkplug:
      * ''DDATA/…/Variables'' → updated ''CLOCK, GasFlow, LOTID''.
      * ''DDATA/…/SendS1F3Poll'' → simple heartbeat for debugging.

Continuation – polling repeats until the next COMPLETED event; note the broker-side comments (“Polling Continues…”, “End Polling”) that bracket the captured sequence.

Trace shutdown – when COMPLETED fires, TransSECS also issues S2F23/S2F24 to end the 1 s ''ProcessTrace'' (Loaded ➜ Completed) and stops the S1F3 poll in the same second.

{{puml_005.png?500|}}