Configuring The DGI

Configuration Files

You will need to copy some sample configuration files from Broker/config/samples/ into Broker/config/ and then edit them to your needs.

The following files are mandatory:

  • Broker/config/freedm.cfg
  • Broker/config/logger.cfg
  • Broker/config/timings.cfg

Alternate locations for all configuration files can be specified in freedm.cfg, and an alternate location for freedm.cfg can be specified when running DGI: ./PosixBroker –config config/alternate-freedm.cfg


freedm.cfg is the main configuration file for the DGI. The most important settings here specify the hostnames and ports of the other DGI to attempt to form groups with, and the port to use for outgoing communications with other DGI. Be very careful to ensure that each hostname you specify here is resolvable on your network. We recommend simply using the same port for every DGI in the network; the sample configuration uses port 51870 for every DGI and you probably will not need to change this. Start by copying the sample freedm.cfg from the samples directory down into the main config directory. A freedm.cfg should look something like this:

# Add some hosts to the peer list

# Specify device name followed by ':' followed by device type.
# Device type must now be specified - it is no longer optional!

# The address used by the DGIs for communication.

# Global verbosity. Higher is more output.
# See logger.cfg for verbosity levels and per-file configuration.

# Host and port that the PSCAD/RTDS client will connect to.

# Filename of the FPGA message specification.
# Used only when compiled with DUSE_DEVICE_RTDS=ON

# Force this DGI's UUID to the specified value, instead of relying on the
# autogenerated UUID. Note that this option cannot be set by command line.
# Important: Each host's UUID must be unique.


Lines with beginning with # are not parsed by the configuration file loader.

You should edit the freedm.cfg, adding one add-host directive for each DGI you wish to run, and making sure the port is set to the desired value. In the example, the DGI will coordinate with the other DGIs listed in add-host. An add-host directive for the current instance of the DGI will be ignored, so you can write the file once and copy it to all your machines, if you desire.

After building the DGI you can run ./PosixBroker -u to print the ID of the current DGI and ensure it exactly matches an add-host directive of each peer DGI. For example:

[michael@victory-road Broker]$ ./PosixBroker -u

More information about the options for freedm.cfg can be found in freedm.cfg options.


logger.cfg is useful for overriding the global verbosity level of the simulation (specified in freedm.cfg) for specific source files. This is primarily useful for developers at Missouri S&T, or those creating their own modules. You can leave this file unaltered.

More information about configuring the logger can be found in Using The DGI Logger.


timings.cfg contains timings for the DGI; we recommend simply pointing to one of the provided timings samples in freedm.cfg; see Configuring Timings. Each host in the simulation must use the same timings which must be appropriate for the slowest DGI in the system, so if a system has two Core-2 computers and a TS-7800, all should use the slow timing set.

file minimum CPU Number of DGI Cumulative time
timings-slow-5.cfg TS7800 <=5 4950 ms
timings-slow-10.cfg TS7800 <=10 7750 ms
timings-slow-30.cfg TS7800 <=30 19150 ms
timings-fast-5.cfg P4 2.4Ghz <=5 1240 ms
timings-fast-10.cfg P4 2.4Ghz <=10 1990 ms
timings-fast-30.cfg P4 2.4Ghz <=30 4770 ms

Where minimum CPU is the performance of the slowest DGI in the group. Cumulative time is the time the DGI will take to configure a group, collect the global state and perform 10 migrations, before checking the system configuration again.

Test Your Configuration

At this point, you should be able to run the DGI. The DGI’s should form a group, however, because devices have not been configured yet, they won’t manage any devices or interact with simulations.

When the DGI is running, it will log various messages to the screen. To verify that the DGI is working correctly, watch for the Group Management or Load Balance status messages that list the current group. It may take up to a minute for the first groups to form when the DGIs are started. This is what the status message looks like from Group Management:

[raichu.freedm] out:    - SYSTEM STATE
[raichu.freedm] out: Me: raichu.freedm:30000, Group: 1804289384 Leader:raichu.freedm:30000
[raichu.freedm] out: SYSTEM NODES
[raichu.freedm] out: Node: galvantula.freedm:30000 State: Up (In Group)
[raichu.freedm] out: Node: manectric.freedm:30000 State: Unknown
[raichu.freedm] out: Node: raichu.freedm:30000 State: Up (Me, Coordinator)
[raichu.freedm] out: Node: zapdos.freedm:30000 State: Up (In Group)

The message lists all the processes in the system. Ideally, your message should say that all the hosts defined in your freedm.cfg should be listed as “In Group”. A similar message is also logged by the Load Balancing module:

[galvantula.freedm] out:        ------- LOAD TABLE (Power Management) -------
[galvantula.freedm] out:        Net DRER (00):  0.00
[galvantula.freedm] out:        Net DESD (00):  0.00
[galvantula.freedm] out:        Net Load (00):  0.00
[galvantula.freedm] out:        ---------------------------------------------
[galvantula.freedm] out:        SST Gateway:    0.00
[galvantula.freedm] out:        Net Generation: 0.00
[galvantula.freedm] out:        Predicted K:    0.00
[galvantula.freedm] out:        ---------------------------------------------
[galvantula.freedm] out:        (NORMAL) galvantula.freedm:30000
[galvantula.freedm] out:        (NORMAL) raichu.freedm:30000
[galvantula.freedm] out:        (NORMAL) zapdos.freedm:30000
[galvantula.freedm] out:        ---------------------------------------------

In this case, the list only includes processes that are correctly configured.

If processes are missing, verify your freedm.cfg files: it is a common issue that a machine’s hostname hasn’t be correctly specified. If the issue persists, or a DGI appears and disappears from the list, consider selecting a different timing configuration – the one you selected may not be appropriate for your configuration.

Once you have verified you have correctly configured the DGI and your DGI can form a group, you should move on to DGI Device Framework.