Basic usage

Basic usage of Sally7

This page details the S7Connection API to get you started with connecting, reading and writing using Sally7. Be sure to await the async (OpenAsync, ReadAsync, WriteAsync) methods to get the actual results and exceptions.

Creating a connection

There are multiple options to create connections:

Using default connection ID's builtin to PLC's:

using Sally7.Plc;

...

int rack = 0;
int slot = 1;
var conn = ConnectionFactory.GetConnection(ipOrHostName, CpuType.S7_1500, rack, slot);

Use the ConnectionFactory when you don't want to explicitly setup connections in the PLC programming software (TIA Portal). Keep in mind only 1 connection can be opened to a PLC this way, even when using multiple computers.

Manually supplying TSAP identifiers:

using Sally7;
using Sally7.Protocol.Cotp;

...

var conn = new S7Connection(ipOrHostName, new Tsap(0x01, 0x01), new Tsap(0x03, 0x01));

Using manual TSAP identifiers multiple connections can be made. Keep in mind that the PLC also verifies the source IP for the connection, so for this to work you need to create a PC-station (in TIA Portal) that matches the computer's IP-address. Add an Application component to the PC-station and then create S7 connections between the Application component and the PLC. In the connection details you can find (and change) the TSAP identifiers.

Opening the connection

await conn.OpenAsync();

Creating DataItems to read or write

// 32 bit integer at DB9,DINT0
var dataItem1 = new DataBlockDataItem<int> {DbNumber = 9};

// 16 bit integer at DB9,INT4
var dataItem2 = new DataBlockDataItem<short> {DbNumber = 9, StartByte = 4};

// Bit at DB9,3.0. Note that this bit is part of the 32bit integer configured in dataItem1.
// The PLC doesn't care about this, it allows reads of any type at any address (at least for DataBlock access)
// as long as the address and DataBlock number is valid.
var dataBit30 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 3, Bit = 0};

// Bits at DB9,5.0 - DB9,5.4
var dataBit50 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 5, Bit = 0};
var dataBit51 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 5, Bit = 1};
var dataBit52 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 5, Bit = 2};
var dataBit53 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 5, Bit = 3};
var dataBit54 = new DataBlockDataItem<bool> {DbNumber = 9, StartByte = 5, Bit = 4};

// Byte array at DB9,0, 10 bytes long
var dataItemByteArr = new DataBlockDataItem<byte[]> { DbNumber = 9, Length = 10};

// Float (32 bit floating point number) array at DB9,0, 4 floats (!) / 16 bytes long
var floatArr = new DataBlockDataItem<float[]> {DbNumber = 9, Length = 4};

// Int (32 bit) array at DB9,0, 4 ints / 16 bytes long
var intArr = new DataBlockDataItem<int[]> {DbNumber = 9, Length = 4};

// Short (16 bit) array at DB9,0, 8 shorts / 16 bytes long
var shortArr = new DataBlockDataItem<short[]> {DbNumber = 9, Length = 8};

Reading data

Using the DataItems as defined above, you can pass them to the Read method. The values are strongly typed, conversion of the data from PLC to C# is handled internally by Sally7. After reading the Value property of each dataItem will contain the value read from PLC. If there is any error, an exception will be thrown. If there are any errors specific to a DataItem, an AggregateException will be thrown with InnerExceptions for every DataItem where the read failed.

await conn.ReadAsync(dataItem1, dataItem2, dataBit30);
Console.WriteLine($"Read values dataItem1: {dataItem1.Value}, dataItem2: {dataItem2.Value}, dataBit30: {dataBit30.Value}.");

Writing data

Reading data is very similar to writing data, just set the values on the DataItems and pass them to the write method. As with reading, an AggregateException will be thrown with InnerExceptions for every DataItem where the write failed.

dataItem1.Value = 312;
dataItem2.Value = short.MaxValue;
dataBit30.Value = true;

await conn.WriteAsync(dataItem1, dataItem2, dataBit30);

Closing the connection

Closing the connection is pretty straightforward, just call the S7Connection.Close() method to close the underlying connection.

conn.Close();