> 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/rt-lab/example-models/ehs-example-models/machine-drive-example-models/spsm-field-oriented-control.md).

# SPSM Field Oriented Control

## Description <a href="#description" id="description"></a>

The **SPSM Field Oriented Control** model illustrates the closed-loop control of a Salient Pole Synchronous Machine (SPSM) connected to a two-level voltage source converter developed in schematic editor software and solved using the eHS solver. This example is developed for execution on an OPAL-RT simulator, which houses a Real-Time CPU and an FPGA as its two major processing units. The SPSM and the converter are simulated on the FPGA, while the controller is simulated on the CPU in real-time. One RT-LAB model and one Schematic Editor model are provided to illustrate the exchange of information between the controller and plant.

## Detailed explanation

The RT-LAB model is composed of two subsystems:

1. The **SM\_Controller** (Master) subsystem contains the power network interface (eHS) and the field-oriented control of the machine.
2. The **SC\_UserInterface** (Console) subsystem is used to control set points, such as speed reference, mechanical torque, and control activation during real-time simulation. Users can also monitor voltages, currents, machine torque and speed of the machine at any point during the simulation.

The eHS solver solves the power network built using Schematic Editor software during the real-time simulation. The circuit built in the Schematic Editor can be edited or viewed by choosing the edit option available in the solver block.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-38839199a5d58e8eb70d9fed65a95cf06dee1cb2%2Fehs-modelSPSM-1.png?alt=media" alt=""><figcaption></figcaption></figure>

When the model is compiled in Simulink, the configuration of the eHS solver is generated according to the schematic editor circuit characteristics. Elements will be put into matrices and stored in .mat files that will be transferred into the solver when the model is run from the RT-LAB interface. Matrices are generated during model compilation in RT-LAB.

Field Oriented Control of the SPSM is implemented on the CPU, which runs at a sampling time of 25 microseconds. This has a standard outer loop speed control and inner loop current control implemented. The transformation used is Amplitude Invariant with Q axis aligned to phase A axis. The modulating waves are clamped to a value between 0 and 1 using a clamping circuit. Exchange of information between the controller and plant happens within the software model. Machine generated currents, speed and theta information are routed to the controller as an input.

Modulating waveforms generated by the controller are converted to PWM via PWMO IO block of OPAL-RT. These PWM pulses are fed back through digital loop-back cable to fire the eHS converter internally. In the Schematic Editor, the Half Bridge Converter blocks are set to receive gating signals from the Digital Input card of the OPAL-RT simulator.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-ebf97e4d5b439b54e539db926ca2b19b6f90c110%2Fehs-modelSPSM-2.png?alt=media" alt=""><figcaption></figcaption></figure>

The measurements in the Schematic Editor model can be mapped to the Analog Output channels of the selected chassis. Similarly, the inputs can be received from either the CPU model or the Analog Input channels. The measurements and sources in this circuit are all mapped to the CPU model.

## Requirements <a href="#requirements" id="requirements"></a>

**Required Software**

* RT-LAB
* Schematic Editor/Unified Database
* eHS Power Electronics Toolbox

**Required Hardware**

* OP4815-IO unit

## Simulation and results

### Setup and Connections <a href="#setup-and-connections" id="setup-and-connections"></a>

#### **Execution Settings**

This model must be run with both the Hardware Synchronized and XHP modes enabled. The firmware used in this model is generated using the RT-XSG tool, and it can be modified to generate firmware to fit another I/O hardware configuration. The CPU model simulation time step is set to 25 microseconds and all the variables required for the controller are defined in the “ParameterInitialization.m” file automatically loaded during simulation.

#### **Simulink Model Configuration**

This project utilizes a hardware configuration where a Versal Board is connected to another chassis through PCI-Express. The default value of the Board Index of the Versal Board is set to 255 and the default value of the Versal chassis IP Address is set to 192.168.3.5.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-f38e6c4d886a570b1b9443372a29a295587272bb%2Fehs-modelSPSM-3.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
In the Simulink Model, update the OpCtrl block parameters to correctly reflect the Board Index and IP Address of the Versal system, as specified in the System Description document.
{% endhint %}

#### **Loopback Cable Connection**

The gating signals from the field oriented controller are routed to the simulated inverter in eHS through the digital IO channels. However, because the Versal chassis contains a bi-directional digital IO card with an internal loopback mechanism, no external cabling is required. The Digital Out and Digital In mappings have been made on the same subsection of channels.

<details>

<summary><strong>S-function Workflow</strong></summary>

The **Mezzanine Option block** is an RT-LAB block used in the **S-Function workflow** to configure the settings of the I/O cards for each mezzanine. The available settings depend on the specific type of I/O card.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-f1b6053e49e0affae24fc2d39f5f8bcc8688cd6f%2Fboost-2levelinverter-exmodel-sfunction.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

<details>

<summary><strong>OpalBoard workflow</strong></summary>

[OPAL-RT Board](https://www.opal-rt.com/docs/rt-lab/configure-ios/analog-digital-and-sfp-ios/opal-rt-board-workflow.md) allow the configuration of I/O card settings for each mezzanine.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-2f4eed5a89d21acaca1e8426fce5331e36396a68%2Fboost-2levelinverter-exmodel-opalboard.png?alt=media" alt=""><figcaption></figcaption></figure>

If, for a given I/O mezzanine, this block is not used, then the corresponding settings will be kept at their default values. These default values are dependent on particularities of the bitstream, and they are not guaranteed to be exposed to the user loading their model. Further, the default values populating the Mezzanine Option block do not necessarily correspond to the default settings that will be seen if the Mezzanine Option block is not used.

Note that if a Mezzanine Option block is used, and the choice of mezzanine type is incorrect for the given slot, the model will still load and run. However, there will be errors in the load log in RT-LAB. For example, the following error is observed in the case that slot 1A on the simulator holds an OP5330-3, when we place a Mezzanine Option block that attempts to configure an OP5369 on slot 1A:

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

```
Mezzanine configurator: OP5369 Threshold configuration.
ERROR: OPAL-RT Board: The threshold control register for slot 1A is in an unexpected state. Please reprogram the bitstream.
ERROR: Mezzanine configurator: Threshold configuration failed...
```

{% endcode %}

Further, as documented in the aforementioned RT-LAB page, the block outputs its status: a 0 in the case when the block’s settings have been correctly applied, and a -1 otherwise. For example, in the below model I incorrectly configured one block by giving it the wrong I/O card, and set the other correctly. The result when we load the model reflects this:

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-a4fe002fb70685f86d0a022ad92068069ae7264d%2Fehs-opalboard-block-workflow.png?alt=media" alt="" width="188"><figcaption></figcaption></figure>

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-635a0707a1e24ec9979ba91be578dae9fe0d6dac%2Fehs-opalborad-model-blocks.png?alt=media" alt=""><figcaption></figcaption></figure>

</details>

### Run the model

To run the example, follow the procedure below:

1. In RT-LAB, select **File >> New >> RT-LAB Project** to create a new project.
2. In the RT-LAB Project window, provide a **Project name** and click **Next**. Navigate to **eFPGASIM >> Schematic\_Editor\_Workflow >> Machine Drives >> SPSM Field Oriented Control** and click **Finish**.
3. Expand the project folder in RT-LAB, select the SPSM model, and click **Build** to compile the model.
4. **Load** and **Execute** the model in RT-LAB to begin the real-time simulation.
5. Observe the results of the simulation in the Simulink Console:
   1. The machine initializes in Torque Mode (1).
   2. Manipulate the **Speed Setpoint** and **Torque**, then observe the resulting machine speed, voltages, and currents. Note that the machine can operate at positive speeds up to 800rpm.
   3. Put the machine in Speed Mode (0).
   4. Manipulate the **Iq Setpoint** and observe the results on the Idq graph.

<figure><img src="https://96827845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNRdpSk8kjn20gXAexnt6%2Fuploads%2Fgit-blob-7ed9154c71173ed70e66386c7598a6bb05e30d70%2Fehs-modelSPSM-4.png?alt=media" alt=""><figcaption></figcaption></figure>


---

# 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/rt-lab/example-models/ehs-example-models/machine-drive-example-models/spsm-field-oriented-control.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.
