philipp2604.S7OPCUA.Lib 1.2.0

S7.Net-OPCUA Service Library

A high-level .NET service library for simplified Siemens S7 OPC UA communication.

The S7.Net-OPCUA library is a specialized wrapper around the official OPC Foundation .NET libraries, purpose-built to simplify access to Siemens S7 controller data via OPC UA. Its primary goal is to abstract away the complexity of browsing nodes and managing vendor-specific data types, offering a high-level, service-oriented approach for .NET developers.

Key Concepts & Features

This library is built around a few core concepts that make it powerful:

• Service-Oriented Architecture: The primary entry point is the S7Service, which orchestrates all operations. It encapsulates the client, a data store, and file operations.
• Configuration Management: Discover the entire PLC data structure once, and then save it to a JSON configuration file (s7_config.json). On subsequent application starts, you can load this configuration in seconds, avoiding a lengthy re-discovery process.
• In-Memory Data Store: The library maintains an in-memory "digital twin" of the PLC's structure and values. This store is indexed, providing extremely fast access to any variable using its full symbolic path (e.g., "DataBlocksGlobal.MyDb.Settings.Speed").
• Rich Type Conversion: Built-in support for a wide range of S7-specific data types, automatically converting them to and from intuitive .NET types. This includes:
  • DATE, TIME, LTIME, S5TIME, DATE_AND_TIME, TIME_OF_DAY → .NET DateTime / TimeSpan
  • CHAR, WCHAR → .NET char
  • Arrays of all supported types, including complex types like ARRAY OF DATE_AND_TIME.
• Deep Structure Discovery: The client correctly discovers and represents complex S7 structures, including Instance Data Blocks with their Input, Output, InOut, and Static sections, as well as nested Function Block instances.
• Strongly Typed & Tested: The library is well-structured with interfaces and includes a comprehensive suite of unit tests, ensuring reliability.

Important License Notice

This project depends on the OPC Foundation .NET Standard Libraries. For non-members of the OPC Foundation, these libraries are licensed under the GNU General Public License v2.0 (GPL-2.0-only).

Consequently, this S7.Net-OPCUA project is also licensed under the GPLv2. This means any project that uses this library (i.e., any "derivative work") must also be open-sourced and made available under the GPLv2 license. If you intend to use this in a closed-source, commercial application, you must become a member of the OPC Foundation to be covered by their commercial license (RCL) for the underlying OPC UA libraries.

The Workflow: Discover, Configure, Use

The library is designed around a three-step workflow:

1. Discover (First Run): On the first connection, the service browses the entire S7 OPC UA server to discover all data blocks, I/O, memory areas, and their variables. This state is then saved to a s7_config.json file.
2. Configure (First Run): After discovery, you may need to manually adjust data types. For example, a generic STRUCT needs to be explicitly typed as such so the library can browse its members. These changes are saved back to the configuration file.
3. Use (Subsequent Runs): On all future runs, the application simply loads the s7_config.json file, instantly rebuilding the entire data store. It then performs a single bulk-read to synchronize all values with the live server state, making startup extremely fast.

Installation

This library will be available via NuGet. You can add it to your project using the .NET CLI:

dotnet add package philipp2604.S7OPCUA.Lib

Quick Start

The following example demonstrates the core workflow of connecting, loading or discovering a configuration, and manipulating a variable.

using S7OPCUA.Lib.Services;
using S7OPCUA.Lib.S7.Types;

const string serverEndpointUrl = "opc.tcp://172.168.0.1:4840";
const string configFilePath = "s7_config.json";
const string variablePath = "DataBlocksGlobal.MyDataBlock.MyBooleanTag";

Console.WriteLine("--- S7 OPC UA Service Example ---");

// The S7Service is the main entry point and should be treated as a singleton
// for the lifetime of your application. It manages the session and data store.
// A proper DI container is recommended for real applications.
using var service = new S7Service(/* Pass ApplicationConfiguration etc. */);

try
{
    // 1. Connect to the server
    Console.WriteLine($"Connecting to {serverEndpointUrl}...");
    if (!await service.ConnectAsync(serverEndpointUrl))
    {
        Console.WriteLine("Connection failed.");
        return;
    }
    Console.WriteLine("Connection successful.");

    // 2. Load configuration or discover from scratch
    if (File.Exists(configFilePath))
    {
        Console.WriteLine("Loading configuration from file...");
        await service.LoadConfigurationAsync(configFilePath);
        Console.WriteLine("Configuration loaded. Syncing all live values...");
        service.ReadAllValues();
        Console.WriteLine("Store is now synchronized.");
    }
    else
    {
        Console.WriteLine("No configuration file found. Discovering full PLC structure...");
        service.DiscoverFullStructure();
        Console.WriteLine("Structure discovered. Saving to new configuration file...");
        await service.SaveConfigurationAsync(configFilePath);
        Console.WriteLine($"Configuration saved to {configFilePath}");
    }

    // 3. Interact with variables using their full symbolic path
    Console.WriteLine($"\n--- Manipulating Variable: {variablePath} ---");
    
    // Get the variable from the local store (very fast)
    var myVar = service.GetVariableByPath(variablePath);
    
    if (myVar.Value is bool currentValue)
    {
        Console.WriteLine($"Current value is: {currentValue}");
        var newValue = !currentValue;
        
        // Write the new value back to the PLC
        Console.WriteLine($"Writing new value: {newValue}...");
        bool success = await service.WriteVariableAsync(myVar, newValue);
        
        if(success)
        {
            Console.WriteLine("Write successful. Re-reading values to confirm...");
            // Update the local store with the new live values
            service.ReadAllValues();
            var updatedVar = service.GetVariableByPath(variablePath);
            Console.WriteLine($"Confirmed value is now: {updatedVar.Value}");
        }
        else
        {
             Console.WriteLine("Write failed. Check server logs or permissions.");
        }
    }
    else
    {
        Console.WriteLine($"Variable value was not a boolean. It was '{myVar.Value ?? "null"}'. Is the S7Type correct in your configuration?");
    }
}
catch (Exception ex)
{
    Console.ForegroundColor = ConsoleColor.Red;
    Console.WriteLine($"An error occurred: {ex.Message}");
    Console.ResetColor();
}
finally
{
    Console.WriteLine("\nPress any key to exit.");
    Console.ReadKey();
}

Building from Source

To contribute or build the library yourself, follow these steps:

# 1. Clone the repository
git clone https://github.com/philipp2604/S7OPCUA.git
cd S7OPCUA

# 2. Restore .NET dependencies
dotnet restore

# 3. Build the solution
dotnet build

# 4. Run the tests
dotnet test

Contributing

Contributions are welcome! If you find a bug or have an idea for a new feature, please follow these steps:

1. Open an Issue: Describe the bug or feature request in detail.
2. Fork the repository: Create your personal copy.
3. Create a feature branch: git checkout -b feature/my-new-feature
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin feature/my-new-feature
6. Create a new Pull Request.