# Setup

## Overview

This feature is responsible for configuring the HTTP broker connection between the Automation Driver and CAMX equipment. The Automation Driver operates in **active polling mode**: it connects to an HTTP broker and periodically polls for messages sent by the equipment.

## How To Configure

To configure the connection between the Automation Driver and the CAMX broker, a set of keys must be set in the `IoTMetadataDefinition` Smart Table.

- The broker must be running and accessible at a specific HTTP URL
- The HTTP address is the URL where the broker's GetMessage endpoint is listening
- The polling interval determines how frequently the driver checks for new messages
- The client name and broker name must match the values configured in the broker

### Relevant Artifacts

The table below describes the properties for this entity type:

| Name                  | Type       | Is Mandatory | Data Type | Description                                      |
| :-------------------- | :--------- | :----------: | :-------- | :----------------------------------------------- |
| IoTMetadataDefinition | SmartTable |     Yes      | -         | Metadata configuration for equipment integration |

## How It Works

You can set in `IoTMetadataDefinition` Smart Table the appropriate values for your setup.

!!! Warning "Every time you change Setup values in IoTMetadataDefinition you must restart the Automation Controller."

---

## Protocol

### Overview

The protocol used by the Automation Driver is named **CAMX_Protocol**.

The protocol operates in **active polling mode**:

- The MES ConnectIoT client periodically connects to the HTTP broker via POST requests
- Messages are polled from a message queue using the `GetMessage` operation
- The broker returns MIME-formatted messages containing XML payloads
- The driver acknowledges message receipt
- Responses are sent back to the equipment through the broker

### IoTMetadataDefinition Base Configuration

The following keys configure the base behavior of the CAMX driver:

| Name            | Value                       | Description                                                                                                                                                            |
| --------------- | --------------------------  | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CAMX_brokerUrl       | HTTP URL                    | HTTP endpoint for the broker's GetMessage operation. Must be a valid HTTP/HTTPS URL pointing to the broker's message queue endpoint.                                 |
| CAMX_brokerName      | String                      | Name used to identify the broker in message headers. This value is included in the `destination` field of CAMX messages. Defaults to `broker`.                       |
| CAMX_clientName      | String                      | Name of the ConnectIoT client registered with the broker. This value is included in the `sender` field of CAMX messages. Defaults to `ConnectIoT`.                  |
| CAMX_pollingInterval | Integer                     | Time (in milliseconds) between consecutive GetMessage requests to the broker. Controls how frequently the driver polls for new messages. Defaults to `500`.            |

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

??? Example "Configuration Example"
        A minimal IoTMetadataDefinition configuration that sets the broker URL, client name, and polling interval for CAMX equipment integration:

    | Resource     | Resource     | Area | Name                       | Value                              |
    | ------------ | ------------ | ---- | ---------------------------| ---------------------------------- |
    | _MES Resource_ |              |      | **camx_brokerUrl**             | http://127.0.0.1:23456             |
    | _MES Resource_ |              |      | **camx_brokerName**            | broker                             |
    | _MES Resource_ |              |      | **camx_clientName**            | ConnectIoT                         |
    | _MES Resource_ |              |      | **camx_pollingInterval**       | 500                                |

---

## How To Use

On Automation startup, the driver:

1. Retrieves configuration from `IoTMetadataDefinition`
2. Initializes the HTTP client with the broker URL
3. Establishes authentication with the broker (if required)
4. Enters a polling loop, sending GetMessage requests at the configured interval
5. Upon receiving a message, extracts the MIME envelope and XML payload
6. Routes the message to the appropriate automation workflow based on the event type
7. Sends an acknowledgment back to the broker

For details on how each event type is processed, see [Event Handling](events.md) for comprehensive documentation on all event types, processing flows, configuration, error handling, and troubleshooting.

## Message Transport Format

CAMX messages follow the **IPC-2501 MIME envelope structure**:

```text
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="<boundary>"

--<boundary>
Content-Type: application/soap+xml

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <MessageInfo sender="..." destination="..." messageId="..." 
                 messageSchema="http://webstds.ipc.org/2541/..." />
  </soap:Header>
  <soap:Body></soap:Body>
</soap:Envelope>

--<boundary>
Content-Type: text/xml

<EventName xmlns="http://webstds.ipc.org/2541">
  <!-- XML payload content -->
</EventName>

--<boundary>--
```

## **Troubleshooting**

Driver unable to connect to broker

### Verify broker connectivity

- Check `brokerUrl` is correct and accessible (e.g., http://broker.local:8080/message)
- Verify broker service is running: `curl -I http://broker.local:8080/`
- Verify network connectivity: `ping broker.local`

### Check firewall rules

- Ensure HTTP/HTTPS traffic allowed between MES and broker
- Verify no proxy blocking connections

### Review authentication

- Verify OAuth 2.0 credentials if broker requires authentication
- Check token refresh configuration

### Check logs

- Controller logs: check in
- Search for: "Error while calling API"

## **Message Processing Errors**

Messages received but not processed correctly

### Verify message format

- Check MIME envelope is properly formatted
- Verify XML payload matches CAMX schema
- Confirm message includes required fields (itemInstanceId, laneId, etc.)

### Check configuration

- Verify `IoTMetadataDefinition` entries exist for your resource
- Verify DEE names are correctly spelled (e.g. CAMX_ItemTransferIn_useDEE)