In a recent Ignition 8.3 project, we had two gateways in a single Git repository that needed to share library elements. While 8.3 enables a more Git-centric workflow, it does not provide a built-in mechanism to keep shared resources synchronized across multiple gateways. Without an automatic way to manage this, shared libraries can quickly drift and become difficult to maintain.

We addressed this by creating symbolic links from each gateway’s library folders to a shared “source of truth” directory. A symbolic link (symlink) is a special file that points to another file or folder—like a shortcut at the filesystem level. When you access it, the system transparently redirects you to the target location. This approach allows both gateways to reference the same underlying files while still fitting cleanly into a Git-based workflow, making it a simple, low-friction way to keep shared resources consistent.

This blog walks through how to set up shared libraries between two Ignition gateways in a single Git repository using symlinks on Windows, helping you avoid duplication and keep shared code synchronized in one place.

With this setup, any time a symlinked file is modified in a Designer and saved, it’s immediately overwritten in the shared “source of truth” location. After changes are made and tested in one gateway project’s Designer, the files can be committed and pushed to the repo as usual.

We’ll walk through setting up a shared script library folder as an example. You can use the same pattern to share views, styles, and additional files as needed for your project.

What are Symbolic Links?

A symbolic link, often referred to as a symlink, is a reference point in a filesystem that points one file or folder to another location. Instead of duplicating the files, a symlink acts as a pointer. When an application accesses the symlinked path, the operating system (OS) redirects it to the target destination.

In Ignition 8.3, a symlinked folder behaves exactly like a project directory. Associated scripts, views, and resources load as one would expect; however, the actual files live somewhere else in the filesystem.

Sample Repository Structure

Here is a visual representation of what the structure would look like after the symlinks are set up. The file structure for gateway1 and gateway2 down to script-python is default to ignition. You will have to create the “shared” folder location and structure manually in your repo, and you can organize it anyway you want.

repo/
└── gateways/
   ├── shared/
   │   └── script-python/
   │       └── library/ (real files live here for this example)
   │
   ├── gateway1/
   │   └── projects/
   │       └── project1/
   │           └── ignition/
   │               └── script-python/
   │                   └── library/ -> symlink to ../../../../../shared/script-python/library
   │
   └── gateway2/
       └── projects/
           └── project2/
               └── ignition/
                   └── script-python/
                       └── library/ -> symlink to ../../../../../shared/script-python/library

Setup Steps for Windows

Before creating any symbolic links, complete the following one-time setup steps. Every developer working with this repository must perform these steps on their local machine. Skipping them can result in broken links when the repo is cloned or checked out.

Prerequisites

1. Enable Git symlink support

By default, Git on Windows may treat symlinks as plain text files. This setting ensures symlinks are created and checked out correctly.

Run the following command in Git Bash:

git config --global core.symlinks true

git config --global core.symlinks true

2. Enable Windows Developer Mode

Developer Mode allows non-admin users to create symbolic links without permission-related issues.

Settings > Privacy & Security > For Developers > Developer Mode

Turn Developer Mode on.

3. Restart your computer

Restarting your computer ensures Developer Mode is fully applied before creating symlinks.

Initial Creation of Symbolic Links

Follow the steps below to set up the initial symlinks for the script-python library folder in our example. The same approach can be used for other shared resources.

Gateway 1:

1. Open Command Prompt as an Administrator

2. Navigate to the target directory for your symbolic links

Move to the directory where the symlink will live in Gateway 1: cd gateways\gateway1\projects\project1\ignition\script-python

3. Move any existing library files:

If you already have files in the library folder and/or the library folder exists, move the entire library folder to the shared directory at gateways/shared/script-python. If not, skip this step.

If you leave the library folder here: \gateways\gateway1\projects\project1\ignition\script-python. The following error will occur because Windows cannot create a link where a directory already exists:

4. Create the symbolic link

Run the command below to create the symlink linked to the actual files in the shared location:

mklink /D library ……….\shared\script-python\library

5. Verify the symlink was created successfully

Verify the link has been created by running the command dir at the symlink location in the command prompt. If the symlink was created correctly, then you should see it in your output.

In addition, you can visually verify that the folder was created correctly in File Explorer by looking for the arrow icon in the bottom left. When you double-click into this symlinked folder, it will take you to the location it is linked to.

Gateway 2

Repeat the same steps for Gateway 2, adjusting the path as needed:

cd gateways\gateway2\projects\project2\ignition\script-python

Create the symlink pointing to the same library location.

Once both gateways are linked, the shared library folder is ready for use. Any changes made through one gateway’s Ignition Designer will be written directly to the shared directory and can be committed to Git as usual.

Ignition Designer/Gateway Refresh and Test

After creating the symbolic links, the final step is to confirm that Ignition detects and uses the shared files properly. Because Ignition doesn’t automatically reload filesystem changes, users must manually initiate file and project scans to update each gateway.

1. Close all open Ignition Designer sessions

Closing active sessions of Designer resolves any potential validation interference caused by cached projects.

2. Trigger file and project scans on both Gateways

On each gateway, run the following:

• Platform → Overview → Scan File System
• Platform → System → Projects → Scan Projects

3. Open Ignition Designer for Gateway 1

• Create a new script or modify an existing script in the share library.
• Save the changes.

4. Refresh Gateway 2

• From the Gateway 2 web UI, trigger both the file system scan and project scan again.

5. Open Ignition Developer for Gateway 2

• Open Ignition Developer for the second Gateway and verify that the adjustments are present.

Now the library symlinks are set up and ready for use. If the changes appear as expected, the symbolic link configuration is working correctly, and both gateways are pulling from the same shared source of truth. Once validated, follow your project’s specific git workflow to push these changes to your repository.

Final Thoughts and Best Practices

It’s important to keep in mind that whenever a file in the gateway filesystem is changed, the gateway doesn’t automatically update to reflect those changes. You will need to perform two file scans for the latest changes to be reflected. The screenshots below show where to trigger these scans.

At some point during testing, you may need to view/test a library file in both gateways. In this scenario, it is important to regularly perform the above file and project scans, as changes are being made and saved. Below is an example of a possible order of operations:

1. Make changes to library file in Gateway 1 project designer.
2. Save changes to library file in Gateway 1 project designer.
3. Open Gateway 2 webpage UI.
4. Press Scan File System on both Platform > Overview page and Platform > System > Projects page for Gateway 2.
5. Open a fresh designer session of Gateway 2’s project to view latest changes.

Keep in mind that if changes are made in both gateways to the same library object, the last place it was saved will be the effective, latest state of the file. In the above example, if a change is made in Gateway 2’s project designer session and saved there, Gateway 1 would have stale library files internally, requiring file scans to refresh them.

To avoid accidentally overwriting changes, the best practice is to separate work into separate commits and modify a given shared file from only one gateway at a time.

Finally, make sure the other developers run through the setup steps on their machines to avoid accidentally breaking any symbolic links during initial setup.

The post Setting Up Symbolic Links for Shared Project Libraries Across Ignition 8.3 Gateways appeared first on DMC, Inc..

• Part 1: Creating and Opening a Project
• Part 2: Folder Structure and Gedi Layout
• Part 3: Panels | The Basics
• Part 4: Panel Scripting Environments and QuickTest
• Part 5: Scripting Syntax
• Part 6: Para Overview and Datapoint Creation
• Part 7: Interacting with Datapoints via Scripting

Now that we have a basic understanding of scripting and how to interact with datapoints, we’re ready to move beyond panel scripting environments and create globally accessible code. In Part 8 of “Getting Started with WinCC OA,” we’ll explore how we can use libraries to create globally accessible functions, enumerations, constants, etc.

What are Libraries?

Control libraries are files that hold code that may be accessed by other scripts within a project. Simply put, they hold globally usable code. One may ask, “Why would we want to use libraries?”

Libraries prevent developers from having to rewrite or copy/paste existing code, allow changes to be made quickly and efficiently, and ensure consistency within a project. Let’s jump back quickly to the example used in “Part 7: Interacting with Datapoints via Scripting.” Say we used the same enumeration “StatusType” in several panels in addition to the one we created.

Without libraries, we’d need to copy and paste this enumeration in all of our panels’ ScopeLibs for further use. If we wanted to alter the enumeration to:

We’d need to remember every instance of where this function was used, go back in the code, and modify StatusType appropriately. When the number of places we use StatusType increases, the more re-work would be needed to make the change.

How are Libraries Made?

To create a control library, simply right click “Libraries” in the project view tree and select “Add New CTRL Library.”

Anything created in the resulting .ctl file can be appropriately referenced throughout the program. To continue from Part 7’s example, we’ll generate two .ctl files: one for a global StatusType and another for device colors.

StatusType.ctl should contain:

ColorConst.ctl should have:

None of these libraries do anything, however, if they’re not implemented within a program.

How is Library Content Implemented?

Libraries are not initially accessible from a program’s script. The control library file must first be loaded into a project for it to be usable. To do so, you must implement the following line:

	#uses <.ctl file>

Once a control file is specified, a script may use any and all items within said .ctl file. To implement our control libraries within our example, we’ll modify our ScopeLib’s code as follows:

#uses "StatusType"
#uses "ColorConst"

//=============================== Panel initialization =========================================
initializePanel()
{
  //Whenever rSpeed or rMaxSpeed changes, call the function "onSpeedChange"
  dpConnect("onSpeedChange", "myMotor.rSpeed", "myMotor.rMaxSpeed");

  //Whenever iStatus changes, call the function "onStatusChange"
  dpConnect("onStatusChange", "myMotor.iStatus");
}


//=============================== Text Field Command =========================================
//Textbox is selected and user keys "Enter"
void textboxCmd()
{
  //Assign the textbox's text value to rMaxSpeed
  dpSet("myMotor.rMaxSpeed", maxSpeedTextbox.text);
}


//=============================== On Speed / Max Speed Value Change =================================
void onSpeedChange(string speedDp, float speedValue, string maxSpeedDp, float maxSpeedValue)
{
  //Define the variable whose value will be assigned to iStatus
  int iStatusValue;

  //Determine what value to assign iStatusValue (and subsequently "myMotor.iStatus")
  switch (speedValue)
  {
    //If "myMotor.rSpeed" is 0, set iStatusValue to 0
    case 0:
      iStatusValue = (int)StatusType::Stopped;
      break;

    //Otherwise, if "myMotor.rSpeed" > "myMotor.rMaxSpeed", set iStatusValue to Estop status int
    //           if not, set iStatusValue to Forward status int
    default:
      iStatusValue = (speedValue >= maxSpeedValue) ? (int)StatusType::Estop : (int)StatusType::Forward;
      break;
  }

  //Assign iStatusValue's value to "myMotor.iStatus"
  dpSet("myMotor.iStatus", iStatusValue);

  //Set the maxSpeedTextbox and speedTextbox's test to their respective values
  //NOTE: dpValToString ensures the units we assigned earlier in the series are displayed.
  //      Simply using <Textbox>.text = <speedValue> will work, but will not display appropriate units
  maxSpeedTextbox.text = dpValToString("myMotor.rMaxSpeed", maxSpeedValue, true);
  speedTextbox.text = dpValToString("myMotor.rSpeed", speedValue, true);
}

//=============================== On Status Change =========================================
void onStatusChange(string statusDp, int statusValue)
{
  //Define the variable whose value will be assigned to the rectangle's color property
  string rectangleColor;

  //Determine color to assign to rectangle based off iStatus
  if (statusValue == (int)StatusType::Stopped)
  {
    rectangleColor = STOPPED_COLOR;
  }

  if (statusValue == (int)StatusType::Estop)
  {
    rectangleColor = ESTOPPED_COLOR;
  }

  if (statusValue == (int)StatusType::Forward)
  {
    rectangleColor = FORWARD_COLOR;
  }

  //Assign selected color to rectangle
  setValue("rectangle", "backCol", rectangleColor);
}

#uses "StatusType"
#uses "ColorConst"

//=============================== Panel initialization =========================================
initializePanel()
{
  //Whenever rSpeed or rMaxSpeed changes, call the function "onSpeedChange"
  dpConnect("onSpeedChange", "myMotor.rSpeed", "myMotor.rMaxSpeed");

  //Whenever iStatus changes, call the function "onStatusChange"
  dpConnect("onStatusChange", "myMotor.iStatus");
}


//=============================== Text Field Command =========================================
//Textbox is selected and user keys "Enter"
void textboxCmd()
{
  //Assign the textbox's text value to rMaxSpeed
  dpSet("myMotor.rMaxSpeed", maxSpeedTextbox.text);
}


//=============================== On Speed / Max Speed Value Change =================================
void onSpeedChange(string speedDp, float speedValue, string maxSpeedDp, float maxSpeedValue)
{
  //Define the variable whose value will be assigned to iStatus
  int iStatusValue;

  //Determine what value to assign iStatusValue (and subsequently "myMotor.iStatus")
  switch (speedValue)
  {
    //If "myMotor.rSpeed" is 0, set iStatusValue to 0
    case 0:
      iStatusValue = (int)StatusType::Stopped;
      break;

    //Otherwise, if "myMotor.rSpeed" > "myMotor.rMaxSpeed", set iStatusValue to Estop status int
    //           if not, set iStatusValue to Forward status int
    default:
      iStatusValue = (speedValue >= maxSpeedValue) ? (int)StatusType::Estop : (int)StatusType::Forward;
      break;
  }

  //Assign iStatusValue's value to "myMotor.iStatus"
  dpSet("myMotor.iStatus", iStatusValue);

  //Set the maxSpeedTextbox and speedTextbox's test to their respective values
  //NOTE: dpValToString ensures the units we assigned earlier in the series are displayed.
  //      Simply using <Textbox>.text = <speedValue> will work, but will not display appropriate units
  maxSpeedTextbox.text = dpValToString("myMotor.rMaxSpeed", maxSpeedValue, true);
  speedTextbox.text = dpValToString("myMotor.rSpeed", speedValue, true);
}

//=============================== On Status Change =========================================
void onStatusChange(string statusDp, int statusValue)
{
  //Define the variable whose value will be assigned to the rectangle's color property
  string rectangleColor;

  //Determine color to assign to rectangle based off iStatus
  if (statusValue == (int)StatusType::Stopped)
  {
    rectangleColor = STOPPED_COLOR;
  }

  if (statusValue == (int)StatusType::Estop)
  {
    rectangleColor = ESTOPPED_COLOR;
  }

  if (statusValue == (int)StatusType::Forward)
  {
    rectangleColor = FORWARD_COLOR;
  }

  //Assign selected color to rectangle
  setValue("rectangle", "backCol", rectangleColor);
}

Note that:

• I added the #uses prompts
• I removed StatusType enum definition from ScopeLib (since it’s applied via library)
• I added color constants (also applied via library)

With the color constants and StatusType enum defined in libraries, other panels and scripts may use them at will.

Now that we have a solid understanding of how to make and implement control libraries, we’ll continue in our OA exploration by investigating color databases and learning how we can use them to create and use custom colors.

Topics to look forward to in this series: 

• Part 9: Color Database & High-Performance Best Practices
• Part 10: Panels | Panel Nesting and $-Parameters
• Part 11: Panels | Child Panels (Popups)
• Part 12: Modules & Embedded Modules

Contact DMC to get started on your next WinCC project and learn more about our Siemens SIMATIC WinCC Programming as well as our WinCC Open Architecture Development.

The post Getting Started with WinCC OA: Part 8 – Libraries appeared first on DMC, Inc..