# State Change

## Overview

The `EquipmentChangeState` event is triggered when CAMX equipment state changes. The integration automatically processes this event through the `StateChange` automation workflow, which validates the state transition and updates the resource state in MES via the SEMI-E10 state model.

### Message Fields

| Field | Type | Description |
|-------|------|-------------|
| eventId | String | Event identifier for traceability |
| currentState | String | New equipment state (IPC-2541 format) |
| previousState | String | Previous equipment state (IPC-2541 format) |
| Extensions | Object | Optional custom data from equipment |

### Workflow Processing

```text
Equipment Event (EquipmentChangeState)
    ↓
equipmentEvent task → Parse currentState, previousState, eventId
    ↓
doStateChange subworkflow
    ↓
IoTStateModelContext → Map equipment state to SEMI-E10
    ↓
AdjustObjectState → Update resource state in MES
    ↓
Result logging
```

### Detailed Steps

1. **Message Reception**: Driver receives `EquipmentChangeState` message from broker
2. **State Extraction**: equipmentEvent task extracts `currentState`, `previousState`, `eventId`, and `Extensions`
3. **Validation**: codeExecution task validates:
   - `useCAMXToChangeState` feature flag is enabled
   - `currentState` is not null or empty
   - `previousState` is not null or empty
4. **Resource Resolution**: retrieve task gets ResourceName for the resource context
5. **Subworkflow Invocation (if validation passes)**: Triggers `doStateChange` subworkflow with:
   - currentState (IPC-2541 format, e.g., "READY-PROCESSING-ACTIVE")
   - previousState (IPC-2541 format)
6. **State Mapping**: Maps equipment state to SEMI-E10 state using `IoTStateModelContext` configuration
7. **State Update**: Calls `AdjustObjectState` API with mapped SEMI-E10 state
8. **Error Handling**: Connection errors evaluated for retry eligibility; non-retriable errors logged
9. **Event Logging**: Logs state transition with eventId for traceability

### State Mapping

Equipment states are mapped to SEMI-E10 states using `IoTStateModelContext`:

| Equipment State (IPC-2541) | Description |
| -------------------------- | -----------|
| READY-PROCESSING-ACTIVE    | Equipment actively processing material |
| READY-IDLE-STARVED         | Equipment ready but waiting for input material |
| READY-IDLE-BLOCKED         | Equipment blocked and unable to process |

??? example "IoTStateModelContext Example IPC-2541 to SEMI E10"
    ``` JSON
    {
        "<ST>IoTStateModelContext": {
            "1": {
                "Driver": "CAMX",
                "StateModel": "SEMI E10",
                "ResourceType": "",
                "Resource": "",
                "StateModelState": "Productive",
                "Values": "READY-PROCESSING-ACTIVE"
            },
            "2": {
                "Driver": "CAMX",
                "StateModel": "SEMI E10",
                "ResourceType": "",
                "Resource": "",
                "StateModelState": "Standby",
                "Values": "READY-IDLE-STARVED"
            },
            "3": {
                "Driver": "CAMX",
                "StateModel": "SEMI E10",
                "ResourceType": "",
                "Resource": "",
                "StateModelState": "Scheduled Down",
                "Values": "READY-IDLE-BLOCKED"
            }
        }
    }
    ```

    !!! Warning "Resource Instantiation"
        An instantiated **MES resource** is required to properly assign the properties to it

### Configuration

For state change processing, configure the following:

#### 1. Feature Flag in `IoTMetadataDefinition`

| Configuration Key            | Type | Description                                                        |
| ----------------------------- | ---- | ------------------------------------------------------------------ |
| useCAMXToChangeState         | String | Enable state change processing; set to "EquipmentChangeState" to enable |

!!! warning "Validation Flow"
    State changes are only processed if `useCAMXToChangeState` is configured in `IoTMetadataDefinition`. Without this configuration, state change events are logged but not processed by the `StateChange` workflow.

### Error Handling

#### Pre-Validation Errors (No API Call)

These errors prevent `AdjustObjectState` API invocation:

| Error | Cause | Behavior |
|-------|-------|----------|
| Feature Disabled | `useCAMXToChangeState` not configured | Log validation error, complete without API call |

#### API Errors (After AdjustObjectState Call)

| Error | Cause |
|-------|-------|
| Connection Refused | MES system unavailable |
| Invalid State | State not valid for resource |
| Resource Locked | Resource currently locked |

### Troubleshooting

#### State Changes Not Processed

Equipment sends EquipmentChangeState but resource state doesn't update in MES

- Verify `useCAMXToChangeState` configuration exists in `IoTMetadataDefinition`
- Restart Automation Controller after adding configuration
- Check controller logs for validation errors
- Verify state mapping exists in `IoTStateModelContext` for the equipment state

#### Validation Errors

Controller logs show validation error messages

- Ensure both currentState and previousState are provided in message
- Verify states are not null or empty strings

#### AdjustObjectState Failures

State update called but fails in MES

- Verify resource exists in MES and is correctly configured
- Check resource has SEMI-E10 state model assigned
- Check that mapped SEMI-E10 state is valid for the resource type