search

siemens / simatic-s7-webserver-api

A .NET API Client Library for the SIMATIC S7 PLC Webserver API
https://www.nuget.org/packages/Siemens.Simatic.S7.Webserver.API/
MIT License
107 stars 23 forks source link
api client-library controller dotnet embedded embedded-systems factory-automation json-api jsonrpc2 plc plcsim s7-plc siemens siemens-s7 siemens-s7-1200 siemens-s7-plcs simatic sps

readme

1518F

WebserverApi Client Library for .NET

This package targeting .NET Framework: 4.8, 6.0, 7.0 and .NET Standard 2.0 and above provides the user with Method calls to the PLC Webserver Api using the HttpClient to make the usage of Api functionalities easier.

Table of contents

License

Introduction

Overview

This package provides an easy way to use the functionalities of the S7 Webserver API without taking care of the HTTP requests.

In the area of the requesthandling following comfort is in place:

So generally all available methods of the S7 Web API can be called easily without taking care of RequestHandling, Id generation, result parsing, etc. Furthermore some comfort functionality is implemented:

Functionality

The Functionalities come together in the ApiHttpClientRequestHandler that implements the IAsyncApiRequesthandler (and also in any implementation of the IApiRequestHandler - not given by example).

Further examples of usage are also provided in the UnitTests of the component.

Dependencies

Package Name Nuget Package URL Project URL(s)
NETStandard.Library https://www.nuget.org/packages/NETStandard.Library/ https://dot.net/, https://github.com/dotnet/runtime
Microsoft.SourceLink.GitHub https://www.nuget.org/packages/Microsoft.SourceLink.GitHub/ https://github.com/dotnet/sourcelink
System.Net.Http https://www.nuget.org/packages/system.net.http/ https://dot.net/, https://github.com/microsoft/referencesource/tree/master/System/net/System/Net/Http
Newtonsoft.Json https://www.nuget.org/packages/Newtonsoft.Json/ https://www.newtonsoft.com/json, https://github.com/JamesNK/Newtonsoft.Json
GitVersioning https://www.nuget.org/packages/Nerdbank.GitVersioning/ https://github.com/dotnet/Nerdbank.GitVersioning
MimeMapping https://www.nuget.org/packages/MimeMapping/ https://github.com/zone117x/MimeMapping

Engineering

Hardwaresetup

Depending on the plc you are having a different number of sessions can co-exist during operation. For details please check the manual.

Configuration

See ApiHttpClientRequestHandler.

Operation

See ApiHttpClientRequestHandler, if you are able to successfully send the ApiBrowse request and log the responses the setup is fine.

Errorhandling

Depending on the requests sent and the plc state there might be errors occurring. As an example there can only be 1 ApiTicket which needs to be closed after use. Therefore when calling e.g. WebApp.CreateResource the result might look like the following:
{"error":{"code":4,"message":"No Resources"},"id":"81dcdb3c-0704-454f-94a3-364a75b7eb4d","jsonRpc":"2.0"}
In this case the ApiHttpClientRequestHandler will throw an ApiNoResourcesException containing different scenarios when this exception might occur.

Topics (Web API methods)

ApiHttpClientRequestHandler

In the following example code you'll have to adjust the IpAddress ("192.168.1.1") and the login for your system - the Login "Everybody" with the password "" is a default user that is downloaded to the plc for the webserver once the webserver is activated in TIA portal. The used functions would fail for the default case that he doesn't have the permissions call the method (that he tried to call). It is not good practice to give a lot of rights to the user "Everybody" therefore please adjust the connectionconfiguration to your configured user with a safe password that should be able to call the methods.

To use e.g. the Api Method "Api.Browse" to get all the Methods supported by the PLC Api do the following

var serviceFactory = new ApiStandardServiceFactory();
var reqHandler = await serviceFactory.GetApiHttpClientRequestHandlerAsync("192.168.1.1", "Everybody", "");
var apiBrowseResponse = await reqHandler.ApiBrowseAsync();
foreach(var method in apiBrowseResponse.Result)
{
    Console.WriteLine(method.Name);
}

Hint: The PLC Certificate is by default not accepted by your PC - therefor you have to either download and store the certificate in the trusted root ca certificates (preferably!) or implement the validation callback for your system - a "plain" check for => true is not good practice but it will get you started in case you dont want to download and install the certificate.

...
using System.Net;
...
// For .net48
ServicePointManager.ServerCertificateValidationCallback += (sender, certificate, chain, sslPolicyErrors) => true;
// For .net6.0 and greater
Siemens.Simatic.S7.Webserver.API.Services.ServerCertificateCallback.CertificateCallback = (sender, cert, chain, sslPolicyErrors) => true;

Of course you can also implement a check for the sender and so on.

WebApps

Gif_WebApp For the PLC WebApps Further Comfort can be accomplished by using the ApiWebAppData and ApiWebAppResource implementations: Generally you are free to configure everything on your own:

public static DirectoryInfo CurrentExeDir
{
    get
    {
        string dllPath = System.Reflection.Assembly.GetExecutingAssembly().Location;
        return (new FileInfo(dllPath)).Directory;
    }
}
...
var app = new ApiWebAppData() { Name = "customerExample", State = ApiWebAppState.Enabled };
await requestHandler.WebAppCreateAsync(app);
app = (await requestHandler.WebAppBrowseAsync(app)).Result.Applications.First();
var ticketForCreation = await requestHandler.WebAppCreateResourceAsync(app, "index.html", "text/html", "2020-07-29T14:52:22Z");
await requestHandler.UploadTicketAsync(ticketForCreation.Result, Path.Combine(CurrentExeDir.FullName, "_WebApps", "customerExample", "index.html"));
// (optional) check for the Ticket state
var ticket = (await requestHandler.ApiBrowseTicketsAsync(ticketForCreation.Result)).Result.Tickets.First();
// close the ticket again!
await requestHandler.ApiCloseTicketAsync(ticket.Id);
if (ticket.State != ApiTicketState.Completed)
{
    throw new ApiTicketNotInCompletedStateException(ticket);
}
await requestHandler.WebAppSetDefaultPageAsync(app, "index.html");
// do this in a loop for all resources and perform management yourself OR

but further comfort can be accomplished with:

AsyncWebAppDeployer, WebAppConfigParser

You can use Implementations to comfortably deploy the apps to the plc with a Deployer and FileParser for your WebAppDirectory:

var parser = new WebAppConfigParser(Path.Combine(CurrentExeDir.FullName, "_WebApps", "customerExample"), "WebAppConfig.json");
app = parser.Parse();
var deployer = serviceFactory.GetApiWebAppDeployer(reqHandler);
await deployer.DeployOrUpdateAsync(app);
var apiWebAppBroseResourcesResponse = await requestHandler.WebAppBrowseResourcesAsync("customerExample");
foreach(var resource in apiWebAppBroseResourcesResponse.Result.Resources)
{
    Console.WriteLine(JsonConvert.SerializeObject(resource, new JsonSerializerSettings() { ContractResolver = new CamelCasePropertyNamesContractResolver(), NullValueHandling = NullValueHandling.Ignore }));
}

The Parser and Deployer also use a set of comfort functions - in case you want to know or take a look they are using:

namespace Siemens.Simatic.S7.Webserver.API.Services.WebApp {
public class ApiResourceHandler {}
public class ApiWebAppResourceBuilder {}
}

Hint: It is possible to add another parameter to the new WebAppConfigParser(,,bool ignoreBOMDifference = false): This is the case because uploading files using javascript on a webpage has shown that the BOM (Byte Order Mark) is not transmitted! Therefor if you upload a file using javascript and then make the deployer do the comparison between the file locally (windows explorer) and the one on the server(plc) the files would be different since the size is different by three bytes. To get rid of this "false positive" on a difference you can set the ignoreBOMDifference to true - but keep in mind that a change of 3 bytes would then also be accepted as no difference. The deployer would still reupload the file since the last_modified dates would not match!

PlcProgram Browse Read and Write

The PlcProgram Methods can be used to Browse available variables and to read or write their value.

...
using Siemens.Simatic.S7.Webserver.API.Models;
using Siemens.Simatic.S7.Webserver.API.RequestHandler;
using Siemens.Simatic.S7.Webserver.API.Responses;
using Siemens.Simatic.S7.Webserver.API.Models.ApiPlcProgramDataTypes;
...
// PlcProgramRead example: object will work for any plcdatatype that is implemented by the api, you could also provide "bool" here
var boolReadResult = await requestHandler.PlcProgramReadAsync<object>("\"DataTypes\".\"Bool\"");
Console.WriteLine(boolReadResult.Result);
// Tia Data Type "Date_And_Time" and "S5Time" are returned as objects - therefore an Implementation is done as the "ApiDateAndTime" and "ApiS5Time"
ApiResultResponse<ApiDateAndTime> dateAndTimeReadResult = 
    await requestHandler.PlcProgramReadAsync<ApiDateAndTime>("\"DataTypes\".\"TIA_Dates\".\"Date_And_Time\"");
DateTime myDt = dateAndTimeReadResult.Result.GetDateTime();
myDt = (new DateTime(2021, 04, 26, 16, 53, 22).AddMilliseconds(13));
await requestHandler.PlcProgramWriteAsync("\"DataTypes\".\"TIA_Dates\".\"Date_And_Time\"", new ApiDateAndTime(myDt));
dateAndTimeReadResult = 
    await requestHandler.PlcProgramReadAsync<ApiDateAndTime>("\"DataTypes\".\"TIA_Dates\".\"Date_And_Time\"");
Console.WriteLine(dateAndTimeReadResult.Result.GetDateTime().ToString("dd/MM/yyyy hh:mm:ss.fff tt"));
ApiResultResponse<ApiS5Time> s5TimeReadResult = 
    await requestHandler.PlcProgramReadAsync<ApiS5Time>("\"DataTypes\".\"TIA_Dates\".\"S5Time\"");
Console.WriteLine(s5TimeReadResult.Result.GetTimeSpan());
// TIA Data types like "Date", "Time", "LTime", "Time_Of_Day", "LTime_Of_Day" are returned as int/uint values when using
// the "simple" mode for PlcProgram.Read => it makes sense to know how to get those into a DateTime/TimeSpan:
// Example for "Date" (you'll have to adjust this for "Time","LTime",...)
var dateReadResult = await requestHandler.PlcProgramReadAsync<uint>("\"DataTypes\".\"TIA_Dates\".\"Date\"");
DateTime date = new DateTime(1990, 1, 1) + TimeSpan.FromDays(dateReadResult.Result);
date = new DateTime(2021, 04, 26);
// for writing: determine the amount of days that is between 1/1/1990 and the time you want to write => write the value as a uint
// or int or long, ... a number that is no double/float => (2 not 2.0) - thats what the plc expects
TimeSpan ts = date - new DateTime(1990, 1, 1);
await requestHandler.PlcProgramWriteAsync("\"DataTypes\".\"TIA_Dates\".\"Date\"", (uint)ts.TotalDays);

Also for these PlcProgram methods there is an Implementation for an ApiPlcProgramData object that can be used for the Api methods:

...
using System.Collections.Generic;
...
// Do not provide any variable when browsing to browse the "root" "directory" of the plc program data:
List<ApiPlcProgramData> allMyPlcProgramBlocks = (await requestHandler.PlcProgramBrowseAsync(ApiPlcProgramBrowseMode.Children)).Result;
// A DB called "DataTypes" has the variables we care about:
var myPlcProgramDataBlock = allMyPlcProgramBlocks.First(el => el.Name == "DataTypes");
var myPlcProgramDataBlockChildren = (await requestHandler.PlcProgramBrowseAsync(ApiPlcProgramBrowseMode.Children, myPlcProgramDataBlock)).Result;
myPlcProgramDataBlock.Children = myPlcProgramDataBlockChildren;
// It is important to set the Parent list correctly so the variable name will be provided correctly to read/write the value of the variable
foreach(var child in myPlcProgramDataBlock.Children)
{
    child.Parents = new List<ApiPlcProgramData>() { myPlcProgramDataBlock };
}
// now we want to read the value of a variable called "Bool":
var myBool = myPlcProgramDataBlock.Children.First(el => el.Name == "Bool");
myBool.Value = (await requestHandler.PlcProgramReadAsync<bool>(myBool)).Result;
Console.WriteLine(myBool.Value);
// write the "Bool" variable
await requestHandler.PlcProgramWriteAsync(myBool, true);
// and read the value again:
myBool.Value = (await requestHandler.PlcProgramReadAsync<bool>(myBool)).Result;
Console.WriteLine(myBool.Value);

Compatibility

Use the following table to find the correct client version for each Plc version (server)

SIMATIC S7-1500:

Plc Version Client Library Version
2.9.x 1.0.x
2.9.x 2.0.x
3.0.x 2.1.x
3.1.x 2.2.x

SIMATIC S7-1200:

Plc Version Client Library Version
4.5.x 1.0.x
4.5.x 2.0.x
4.6.x 2.1.x

Hint: This Library supports more API calls than the current S7-1200 does - the S7-1200 will likely(!) support the API calls of last version of the s7-1500 but this does NOT necessarily have to be the case - for details please always check the manual for the according version.

Limitations

Currently some Features are not implemented yet. Check out the Issues to get further information about open issues.

OPC UA or Web API?

To be honest, I'm not sure that a hard comparison between OPC UA and the Web API is that useful.

Both flavors of open interoperability to other systems are fully supported and continuously developed by Siemens. Some features are supported by either one or the other, and for the features that are supported by both, it's ultimately up to your preferences.

OPC UA is a widely known and supported industry standard developed and maintained by the OPC Foundation that was created for a variety of Plug&Play communication use cases. Quite in the sense of a strategic orientation of a cross vendor interoperability. The focus here is set on data exchange in the most interoperable and efficient way (subscriptions, companion specifications, …). This also includes plc-to-plc-communication via OPC Client and Server.

The focus of the Web API rather is maintenance, problem finding and offering the possibility to implement small and medium-sized Web Applications. This API is based on standardized JSON-RPC via HTTPS communication with a Simatic-specific data model.

Unfortunately a general performance expectation is hard to calculate as this is highly dependent on use cases, requirements, the given environment and the used system.

For feature-specific details and evaluation of what best suits your use case, please also take a look into the manuals of OPC UA or the Webserver.

Further Information about PLC (Webserver)

See Also:

SIMATIC S7-1500:

SIMATIC S7-1200: