> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/ehs/automation-api-and-scripting/matlab-simulink-ehs-api.md).

# Automate eHS with the API

## eHS API overview

The eHS API provides programmatic access to common eHS block operations in MATLAB/Simulink. It is primarily intended for automation workflows, scripting, model generation, and integration with custom toolchains.

The **API is available only in RT-LAB with an open Simulink model** and is supported by the **eHS\_SE\_SFunction\_Drivers** and **eHS\_SE\_OpalBoards\_Drivers** blocks. Some functions are also supported by **eHS Protected** block, as indicated in the documentation for each function. The API **is not supported with HYPERSIM.**

The API can be used to:

* Associate a Schematic Editor circuit with an eHS block.
* Load or reload a circuit automatically.
* Open generated build reports and log files.
* Configure selected eHS block settings.
* Retrieve information about eHS inputs and outputs for automated workflows.

{% hint style="info" %}
**Important:**

* Use backslashes (`\`) in file paths and forward slashes (`/`) in Simulink block paths.
* `eHSBlockPath` must contain the full Simulink block path, starting with the model name and ending with the name given to the eHS block. For example: `'CPU_model/SM_subsystem/eHS1'`
* `modelPath` must contain the file path to the Simulink model that contains the eHS block. For example: `'C:\Users\admin\OPAL-RT\RT-LAB_Workspace\eHS\models\CPU_model\CPU_model'`
  {% endhint %}

## Circuit management

These functions automate actions that are normally performed through the eHS block user interface.

### selectCircuit <a href="#selectcircuit" id="selectcircuit"></a>

The **`selectCircuit()`** function opens a file selection dialog and lets the user choose a circuit interactively.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.selectCircuit(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to select its circuit.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

### setCircuit <a href="#setcircuit" id="setcircuit"></a>

The **`setCircuit()`** function associates a circuit programmatically without displaying a user interface.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.setCircuit(ehsBlockPath, path)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

* **ehsBlockPath**: *String*. The block path to the eHS block of which you want to specify its circuit.
* **path**: *String*. The circuit path to the Schematic Editor model of which you want to associate with the eHS block.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

### loadCircuit <a href="#loadcircuit" id="loadcircuit"></a>

The **`loadCircuit()`** function loads the Schematic Editor circuit currently associated with the eHS block and generates the required configuration and binary files. This function is equivalent to selecting **Load Circuit** from the eHS block context menu. A successful load also generates an eHS Build Report for the selected circuit. This function is also avilable for the **eHS Protected** block.

{% code lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.loadCircuit(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to update the circuit.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

## Access generated files

The API provides utility functions to access files and folders associated with an eHS block.

### openBuildReport <a href="#openbuildreport" id="openbuildreport"></a>

The **`openBuildReport()`** function opens the most recently generated eHS Build Report associated with the specified eHS block. This function is also avilable for the **eHS Protected** block.

{% code lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.openBuildReport(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to access to the build report file.

</details>

<details>

<summary><strong>Returns</strong></summary>

The eHS build report printed in the MATLAB Command Window.

</details>

### openCircuitFolder <a href="#opencircuitfolder" id="opencircuitfolder"></a>

The **`openCircuitFolder()`** function opens the directory containing the Schematic Editor model associated with the eHS block.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.openCircuitFolder(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to open the folder of its circuit.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

### openLogFolder <a href="#openlogfolder" id="openlogfolder"></a>

The **`openLogFolder()`** function opens the folder containing logs associated with the eHS block. This function is also avilable for the **eHS Protected** block.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.openLogFolder(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to open the logs folder of its circuit.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

## Configure eHS block settings

### setAutoConfigureOpCtrl <a href="#setautoconfigureopctrl" id="setautoconfigureopctrl"></a>

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```
efs.ehs.api.setAutoConfigureOpCtrl(ehsBlockPath, mode)
```

{% endcode %}

The **`setAutoConfigureOpCtrl()`** function enables or disables automatic configuration of the associated OpCtrl block. This function is also avilable for the **eHS Protected** block.

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to set its controller's autoconfiguration mode.

**mode**: *Boolean*. on/off mode to set.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. If the operation completes successfully, `"Done"` is printed in the MATLAB Command Window and the requested action is performed. Otherwise, an error message is displayed.

</details>

### setControllerName <a href="#setcontrollername" id="setcontrollername"></a>

The **`setControllerName()`** function configures the controller name used by the eHS block. This function is also avilable for the **eHS Protected** block.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.api.setControllerName(ehsBlockPath, controllerName)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the eHS block of which you want to set its controller's name.

**controllerName**: *String*. The new controller name.

</details>

<details>

<summary><strong>Returns</strong></summary>

Nothing. It prints "Done" when the task has been performed correctly, setting the name or display errors.

</details>

## Retrieve eHS output information

The API can query the outputs currently defined for an eHS block without modifying the block configuration.

### getEhsHighLatencyOutputs <a href="#getehshighlatencyoutputs" id="getehshighlatencyoutputs"></a>

The **`getEhsHighLatencyOutputs()`** function returns the list of high-latency outputs in the order defined by the FLWS bus. The information is retrieved from the eHS block configuration and reflects the most recent successful update or circuit load. Calling this function does not update or rebuild the block.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.cpu.getEhsHighLatencyOutputs(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the ehs block from which you want the High Latency Outputs list.

</details>

<details>

<summary><strong>Returns</strong></summary>

A cell array (`N × 1`) of character vectors containing the names of the High-Latency Outputs. If no information is available, an empty cell array (`0 × 0`) is returned.

</details>

### getEhsLowLatencyOutputs <a href="#getehslowlatencyoutputs" id="getehslowlatencyoutputs"></a>

The **`getEhsLowLatencyOutputs()`** function returns the list of low-latency outputs in the order defined by the FLWS bus. The information is retrieved from the block configuration and does not update the block automatically.

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```matlab
efs.ehs.cpu.getEhsLowLatencyOutputs(ehsBlockPath)
```

{% endcode %}

<details open>

<summary><strong>Parameters</strong></summary>

**ehsBlockPath**: *String*. The block path to the ehs block from which you want the Low Latency Outputs list.

</details>

<details>

<summary><strong>Returns</strong></summary>

**Returns:** A cell array (`N × 1`) of character vectors containing the names of the Low-Latency Outputs. If no information is available, an empty cell array (`0 × 0`) is returned.

</details>

## Generate a Protected block

### generateProtectedBlock

The **`generateProtectedBlock()`** function creates Protected Blocks from MATLAB scripts. This method is intended for automation workflows and is particularly useful when generating or maintaining libraries of Protected Blocks.

<pre class="language-matlab" data-overflow="wrap" data-line-numbers data-expandable="true"><code class="lang-matlab"><strong>efs.ehs.cpu.generateProtectedBlock(originalModelPath, originalBlockPath, protectedModelPath, protectedBlockName)
</strong></code></pre>

<details open>

<summary><strong>Parameters</strong></summary>

**originalModelPath**: *String*. Path to the Simulink model containing the original eHS block.

**originalBlockPath**: *String*. Block path of the eHS block to export.

**protectedModelPath**: *String*. Output path of the library or model that will contain the Protected Block.

**protectedBlockName**: *String*. Name of the Protected Block to create.

</details>

<details>

<summary><strong>Returns</strong></summary>

**Returns:** Nothing. If the operation completes successfully, the Protected Block is created or updated in the specified output model/library. Otherwise, an error message is displayed.

</details>

#### Library generation behavior

The function automatically manages the destination library:

* If the output library does not exist, it is created automatically.
* If the library exists and a block with the specified name already exists, the existing block is replaced.
* If the library exists and the block name does not exist, the new block is added to the library.

As a result, `generateProtectedBlock()` can be called repeatedly using the same output library to build and maintain a collection of Protected Blocks programmatically.

#### Example

Assume a Simulink model named `machinemodel.slx` contains an **eHS\_SE\_SFunction\_Drivers** block name `eHS1` located in a top-level subsystem called `SM_subsystem`. The model path is `'C:\Users\admin\OPAL-RT\RT-LAB_Workspace\eHS\models\machinemodel\machinemodel'` and the eHS block path is `machinemodel/SM_subsystem/eHS1`

The following command creates an **eHS Protected** block named `My PMSM Protected Block` in a new library named `machinesLibrary.slx`:

```matlab
generateProtectedBlock('C:\Users\OPAL-RT\RT-LAB_Workspace\eHS\models\machinemodel\machinemodel', ...
'machinemodel/SM_subsystem/eHS1', ...
'C:\Users\admin\Desktop\machinesLibrary', ...
'My PMSM Protected Block');
```

Additional Protected blocks can then be added to the same library by calling the function again with a different block name:

```matlab
generateProtectedBlock('C:\Users\OPAL-RT\RT-LAB_Workspace\eHS\models\machinemodel\machinemodel', ...
'machinemodel/SM_subsystem/eHS1', ...
'C:\Users\admin\Desktop\machinesLibrary', ...
'My other PMSM Protected Block');
```

After both commands are executed, `machinesLibrary.slx` contains:

* `My PMSM Protected Block`
* `My Other PMSM Protected Block`

This approach makes it easy to build and maintain libraries containing multiple Protected Blocks through automated scripts.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/ehs/automation-api-and-scripting/matlab-simulink-ehs-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
