DLL

Purpose

Interface with externally generated dynamic-link library

Library

Control / Functions & Tables

Description

The DLL block allows you to load a user generated DLL. The DLL may be implemented in any programming language on any development environment that the system platform supports. For convenience, all code snippets in this description are given in C.

The DLL must supply two functions, plecsSetSizes and plecsOutput. Additionally it may implement the functions plecsStart and plecsTerminate.

The complete DLL interface is described in the file include/plecs/DllHeader.h in the PLECS installation directory. This file should be included when implementing the DLL.

void plecsSetSizes(struct SimulationSizes* aSizes)

This function is called once during the initialization of a new simulation.

The parameter struct SimulationSizes is defined as follows:

struct SimulationSizes {
  int numInputs;
  int numOutputs;
  int numStates;
  int numParameters;
};

In the implementation of plecsSetSizes the DLL has to set all the fields of the supplied structure.

numInputs: The width of the input signal that the DLL expects. The length of the input array in the SimulationState struct is set to this value.
numOutputs: The number of outputs that the DLL generates. The width of the output signal of the DLL block and the length of the output array in the SimulationState struct is set to this value.
numStates: The number of discrete states that the DLL uses. The length of the states array in the SimulationState struct is set to this value.
numParameters: The length of the parameter vector that the DLL expects. A vector with numParameters elements must be supplied in the Parameters field of the component parameters of the DLL block. The parameters are passed in the parameters array in the SimulationState struct.

void plecsOutput(struct SimulationState* aState)

This function is called whenever the simulation time reaches a multiple of the Sample time of the DLL block.

The parameter struct SimulationState is defined as follows:

struct SimulationState {
  const double* const inputs;
  double* const outputs;
  double* const states;
  const double* const parameters;
  const double time;
  const char* errorMessage;
  void* userData;
};

inputs: The values of the input signal for the current simulation step. The values are read-only. The array length is the value of the numInputs field that was set in the plecsSetSizes method.
outputs: The output values for the current simulation step. These values must be set by the DLL. The array length is the value of the numOutputs field that was set in the plecsSetSizes method.
states: The values of the discrete states of the DLL. These values can be read and modified by the DLL. The array length is the value of the numStates field that was set in the plecsSetSizes method.
parameters: The values of the parameters that were set in the Parameters field in the component parameters of the DLL block. The values are read-only. The array length is the value of the numParameters field that was set in the plecsSetSizes method.
time: The simulation time of the current simulation step, in seconds \((\mathrm{s})\).
errorMessage: The DLL may indicate an error condition by setting an error message. The simulation will be stopped after the current simulation step.
userData: A pointer to pass data from one call into the DLL to another. The value is not touched by PLECS.

void plecsStart(struct SimulationState* aState)

This function is called once at the start of a new simulation. It may be used to set initial outputs or states, initialize internal data structures, acquire resources etc.

The values of the inputs array in the SimulationState struct are undefined in the plecsStart function.

void plecsTerminate(struct SimulationState* aState)

This function is called once when the simulation is finished. It may be used to free any resources that were acquired by the DLL.

Note

The processor architecture of the DLL must match the processor architecture of PLECS. For a 64-bit version of PLECS, a 64-bit DLL must be built. The processor architecture used by PLECS is displayed in the About PLECS … dialog, accessible from the File menu.

Parameters

Filename

The filename of the DLL. If the filename does not contain the full path of the DLL, the DLL is searched relative to the directory containing the model file. If no DLL is found with the given filename, a platform specific ending will be attached to the filename and the lookup is retried. The endings and search order are listed in the table below.

Platform	Filename search order
Windows 64-bit	filename, filename.dll, filename_64.dll
macOS 64-bit	filename, filename.dylib, filename_64.dylib
Linux 64-bit	filename, filename.so, filename_64.so

Sample time

A scalar specifying the sampling period or a two-element vector specifying the sampling period and offset, in seconds \((\mathrm{s})\). This parameter determines the time steps, at which the output function of the DLL is called. Valid inputs are a Discrete-Periodic or an Inherited sample time. See also section Sample Times.

Output delay

Allows you to delay the output in each simulation step. This is useful when modeling, for example, a DSP that needs a certain processing time to calculate the new outputs. The output delay must be smaller than the sample time. If the output delay is a positive number, the DLL block has no direct feedthrough, i.e. its outputs can be fed back to its inputs without causing an algebraic loop. If an inherited sample time is specified, the output delay must be zero.

Parameters

Array of parameter values to pass to the DLL. The length of the array must match the value of the numParameters field that the DLL sets in the plecsSetSizes method.

Probe Signals

Input: The input signal.
Output: The output signal.