This tutorial will demonstrate how to add a new simulation signal to the PSCAD simulation that can be read by an instance of the FREEDM-DGI. To aid the explanation, the tutorial will provide an example on how to add a new DESD to the simulation model.

Each device in the FREEDM-DGI has a C++ class associated with it. Each device class has a different set of device signals that it recognizes. For instance, an SST recognizes the gateway signal and a LOAD recognizes the drain signal. A device will not work if it is specified with a signal name that it does not recognize.. The first step is then to determine the set of signal names associated with the new simulation device.

A list of the possible device types can be found in [Broker/include/device/types] (https://github.com/scj7t4/FREEDM/tree/master/Broker/include/device/types). Each device type has a list of accessor and mutator functions that manipulate its associated signals. For the DESD, these functions are:

/// Determine the energy storage of this DESD.
SettingValue GetStorage() const;

/// Increases the storage of this DESD by the specified amount.
void StepStorage(const SettingValue step = 1.0);

The signal names associated with these functions can be located inside of the source file in Broker/src/device/types. The accessor functions make a call to IDevice::Get(string) and the mutator functions make a call to IDevice::Set(string,float). For both functions, the string in the function call is a signal name recognized by the device type. For the DESD:

float CDeviceDesd::GetStorage() const
{
    // the signal name is "storage"
    return Get("storage");
}

void CDeviceDesd::StepStorage(float step)
{
    // the signal name is "storage"
    Set("storage", GetStorage() + step);
}

Note that the accessor functions that call IDevice::Get(string) read the simulation state while the mutator functions that call IDevice::Set(string,float) send a command to the simulation. Although both of these functions use the same signal name of "storage", these are two different signals: one is an output, while the other is an input.

The first step to add a new DESD is to have the FREEDM-DGI recognize the device. A device is specified in Broker/config/freedm.cfg using the add-device=name:Type command. An example of freedm.cfg might look like:

# Specify device name followed by ':' followed by device type.
add-device=sst:Sst
add-device=fid77:Fid

# The address used by the DGIs for communication.
address=0.0.0.0
port=1870

# Global verbosity. Higher is more output.
verbose=5

This example specifies two devices: one named "sst" of type CDeviceSst and another named "fid77" of type CDeviceFid. Note that the device type in this specification file is the portion of the class name after the prefix "CDevice": Sst for CDeviceSst and Fid for CDeviceFid. This is true for all device types. The device type for the DESD, of class CDeviceDesd, would then be Desd.

To add the new DESD, another add-device=name:Type line must be added to this file. The name can be any unique identifier. This identifier must be unique across all instances of the FREEDM-DGI. Therefore, if the system consists of three DGI nodes, and each DGI node has an Sst device, no other node could use the identifier "Sst". To use the same identifier would mean that two instances of the DGI have access to the same simulation device.

For this example, the identifier "desd1" will be used. The configuration line should then be add-device=desd1:Desd to specify a new device of class CDeviceDesd identified by the string "desd1". This results in the file:

# Specify device name followed by ':' followed by device type.
add-device=sst:Sst
add-device=fid77:Fid
add-device=desd1:Desd

# The address used by the DGIs for communication.
address=0.0.0.0
port=1870

# Global verbosity. Higher is more output.
verbose=5

This change is sufficient to add the new device to the FREEDM-DGI.

The simulation server is the middle man between the PSCAD simulation and the FREEDM-DGI. Each device must be specified in the simulation server to allow communication between these two processes. A detailed tutorial on configuration of the simulation server can be found on the wiki page Simulation Server Tutorial. This section will cover the bare essentials to add a new DESD.

Configuration of the simulation server occurs in an XML specification file located in PSCAD-Interface/config. This file tends to be quite long and follows a strict format detailed on the wiki page linked above. An example of the file might be:

<root>
<adapter type = "simulation" port = "5000">
    <state>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
        <entry index="2">
            <device>fid77</device>
            <signal>state</signal>
            <value>1</value>
        </entry>
    </state>
    <command>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
    </command>
</adapter>
<adapter type="pscad" port="5001">
    <state>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
        <entry index="2">
            <device>fid77</device>
            <signal>state</signal>
            <value>1</value>
        </entry>
    </state>
    <command>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
    </command>
</adapter>
</root>

This XML specification corresponds to the freedm.cfg in the previous section. It specifies that the simulation communicates with the server over port 5000 and sends a value for a device called "sst" and another device called "fid77". The simulation receives commands for a single device called "sst". The second adapter on port 5001 refers to an instance of the FREEDM-DGI. The specification of this adapter is identical to the previous, which means all of the data used by the simulation belongs to one DGI node. The DGI adapter specifications will always be a subset of the simulation specification, although rarely a proper subset unless there is only one DGI node in the system.

To add a new DESD to the simulation server, there are two steps to consider. First, the data for the DESD device must pass through the PSCAD simulation adapter. That means the adapter on port 5000 associated with the simulation must be modified to handle additional data. Second, the DESD device must be sent to an instance of the FREEDM-DGI. That means the adapter on port 5001 associated with the DGI must also be modified to handle additional data. It is always the case when adding a new device that at least two adapters must be modified, as the device data must pass from the simulation adapter through some FREEDM-DGI adapter.

Recall that a DESD device has two signal names it recognizes: a "storage" that is read from the simulation state and a "storage" that is issued as a simulation command. Therefore, to specify a new DESD, the specification must be modified to recognize a new <state> entry for storage as well as a new <command> entry for storage. These entries will use the <signal> name storage and the <device> name that corresponds to the freedm.cfg modifications above. For the example, the device name would be desd1 given the unique identifier used in the previous section. The <value> tag is optional and is not required for a DESD.

The full XML entry will then resemble the format:

<entry index="NEXT_INDEX">
    <device>desd1</device>
    <signal>storage</signal>
</entry>

where NEXT_INDEX is the next consecutive number within the adapter specification. Note that this index is not used by the simulation server, but will be required when the simulation is modified and is used behind the scenes in the FREEDM-DGI implementation. The XML specification can then be modified:

<root>
<adapter type = "simulation" port = "5000">
    <state>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
        <entry index="2">
            <device>fid77</device>
            <signal>state</signal>
            <value>1</value>
        </entry>
        <entry index="3">
            <device>desd1</device>
            <signal>storage</signal>
        </entry> 
    </state>
    <command>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
       <entry index="2">
            <device>desd1</device>
            <signal>storage</signal>
        </entry>
    </command>
</adapter>
<adapter type="pscad" port="5001">
    <state>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
        <entry index="2">
            <device>fid77</device>
            <signal>state</signal>
            <value>1</value>
        </entry>
        <entry index="3">
            <device>desd1</device>
            <signal>storage</signal>
        </entry> 
    </state>
    <command>
        <entry index="1">
            <device>sst</device>
            <signal>gateway</signal>
        </entry>
        <entry index="2">
            <device>desd1</device>
            <signal>storage</signal>
        </entry> 
    </command>
</adapter>
</root>

Note that a new entry for desd1 was added to both <state> and <command> of each adapter as per the explanation given above. The index for each entry was set to be one greater than the index of the entry before it in the specification. The actual index does not matter at this point, but indices must begin with 1 and must be consecutive. This is sufficient to allow the simulation server to recognize the new DESD.

The final step is to add the device to the PSCAD simulation. Often this is the first step performed when adding a new device, and the order of this tutorial is reversed, but the order presented makes more sense when first introduced to the process. Refer to the wiki page PSCAD Socket Tutorial for details on how to add new simulation signals.

The DESD requires two signals according to its device class in the FREEDM-DGI. Therefore, one signal must be added to pscad_send and one signal must be added to pscad_recv. After the signals are added, the indices in the simulation server XML specification must be modified to refer to the index of the signal inside of PSCAD. Inside of the simulation adapter, each entry should have the same index as it does within the PSCAD simulation.