1、ConnectTo
Description
Connects the client to the hardware at (IP, Rack, Slot) Coordinates.
Declaration
public int ConnectTo(String Address, int Rack, int Slot)
Parameters
| Type | Dir. |
|
Address | String | In | PLC/Equipment IPV4 Address |
Rack | int | In | PLC Rack number (see below) |
Slot | int | In | PLC Slot number (see below) |
Return value
· 0 : The Client is successfully connected (or was already connected).
· Other values : see the Errors Code List.
Rack and Slot
In addition to the IP Address, that we all understand, there are two other parameters that index the unit : Rack (0..7) and Slot (1..31) that you find into the hardware configuration of your project, for a physical component, or into the Station Configuration manager for WinAC.
There is however some special cases for which those values are fixed or can work with a default as you can see in the next table.
| Rack | Slot |
|
S7 300 CPU | 0 | 2 | Always |
S7 400 CPU | Not fixed | Follow the hardware configuration. | |
WinAC CPU | Not fixed | Follow the hardware configuration. | |
S7 1200 CPU | 0 | 0 | Or 0, 1 |
S7 1500 CPU | 0 | 0 | Or 0, 1 |
WinAC IE | 0 | 0 | Or follow Hardware configuration. |
Disconnect
Description
Disconnects “gracefully” the Client from the PLC.
Declaration
public void Disconnect()
Remarks
This function can be called safely multiple times.
After calling this function LastError = 0 and Connected = false.
2、ReadArea
Description
This is the main function to read data from a PLC.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.
Declaration
public int ReadArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer)
public int ReadArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer, ref int BytesRead)
Parameters
ReadArea
Description
This is the main function to read data from a PLC.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.
Declaration
public int ReadArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer)
public int ReadArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer, ref int BytesRead)
Parameters
| Type | Dir. | Mean |
Area | int | In | Area identifier. |
DBNumber | int | In | DB Number if Area = S7AreaDB, otherwise is ignored. |
Start | int | In | Offset to start |
Amount | int | In | Amount of elements to read (1) |
Wordlen | int | In | Word size (2) |
Buffer | Byte Buffer | In | Buffer |
BytesRead | int | Out | Number of bytes read (3) |
(1) Note the use of the parameter name “amount”, it means quantity of elements, not byte size.
Area table
| Value | Mean |
S7Consts.S7AreaPE | 0x81 | Process Inputs. |
S7Consts.S7AreaPA | 0x82 | Process Outputs. |
S7Consts.S7AreaMK | 0x83 | Merkers. |
S7Consts.S7AreaDB | 0x84 | DB |
S7Consts.S7AreaCT | 0x1C | Counters. |
S7Consts.S7AreaTM | 0x1D | Timers |
WordLen table
| Value | Mean |
S7WLBit | 0x01 | Bit (inside a word) |
S7WLByte | 0x02 | Byte (8 bit) |
S7WLWord | 0x04 | Word (16 bit) |
S7WLDWord | 0x06 | Double Word (32 bit) |
S7WLReal | 0x08 | Real (32 bit float) |
S7WLCounter | 0x1C | Counter (16 bit) |
S7WLTimer | 0x1D | Timer (16 bit) |
Return value
· 0 : The function was accomplished with no errors.
· Other values : see the Errors Code List.
Remarks
As said, every data packet exchanged with a PLC must fit in a PDU, whose size is fixed and varies from 240 up to 960 bytes.
This function completely hides this concept, the data that you can transfer in a single call depends only on the size available of the data area (i.e. obviously, you cannot read 1024 bytes from a DB whose size is 300 bytes).
If this data size exceeds the PDU size, the packet is automatically split across more subsequent transfers.
If either S7AreaCT or S7AreaTM is selected, WordLen must be either S7WLCounter or S7WLTimer (However no error is raised and the values are internally fixed).
Your buffer should be large enough to receive the data.
Particularly:
Buffer size (byte) = Word size * Amount
Where:
| Word size |
S7Consts.S7WLBit | 1 |
S7Consts.S7WLByte | 1 |
S7Consts.S7WLWord | 2 |
S7Consts.S7WLDWord | 4 |
S7Consts.S7WLReal | 4 |
S7Consts.S7WLCounter | 2 |
S7Consts.S7WLTimer | 2 |
Notes
(2) When WordLen=S7WLBit the Offset (Start) must be expressed in bits.
Ex. The Start for DB4.DBX 10.3 is (10*8)+3 = 83.
(3) Since Amount is the number of elements read, BytesRead returns the effective number of bytes.
3、WriteArea
Description
This is the main function to write data into a PLC. It’s the complementary function of ReadArea(), the parameters and their meanings are the same.
The only difference is that the data is transferred from the byte buffer into PLC.
Declaration
public int WriteArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer)
public int WriteArea(int Area, int DBNumber, int Start, int Amount, int WordLen, byte[] Buffer, ref int BytesWritten)
See ReadArea() for parameters and remarks.
Use S7 helper methods to insert S7 data types (int, word, real …) into the byte buffer.
4、ReadMultiVars
Description
This is function allows to read different kind of variables from a PLC in a single call.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.
Declaration
public int ReadMultiVars(S7DataItem[] Items, int ItemsCount)
Parameters
| Type | Dir. |
|
Item | S7DataItem[] | In | See below |
ItemsCount | integer | In | Number of Items to read. |
S7DataItem struct
| Type | Dir. |
|
Area | int | In | Area identifier. |
Wordlen | int | In | Word size |
Result | int | Out | Item operation result (2) |
DBNumber | int | In | DB Number if Area = S7AreaDB, otherwise is ignored. |
Start | int | In | Offset to start |
Amount | int | In | Amount of words to read (1) |
pData | IntPtr | In | Pointer to user Buffer |
(1) Note the use of the parameter name “amount”, it means quantity of words, not byte size.
Return value
· 0 : The function was accomplished with no errors.
· Other values : see the Errors Code List.
(2) Since could happen that some variables are read, some other not because maybe they don't exist in PLC. Is important to check the single item Result.
Remarks
To use ReadMultiVars a special class is supplied S7MultiVar that avoids the use of unsafe code (since there is a IntPtr)
Due the different kind of variables involved , there is no split feature available for this function, so the maximum data size must not exceed the PDU size.
The advantage of this function becomes big when you have many small noncontiguous variables to be read.
5、WriteMultiVars
Description
This is function allows to write different kind of variables from a PLC in a single call.
With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.
Declaration
public int WriteMultiVars(S7DataItem[] Items, int ItemsCount)
Parameters
| Type | Dir. |
|
Item | S7DataItem[] | In | See below |
ItemsCount | integer | In | Number of Items to write. |
S7DataItem struct
| Type | Dir. |
|
Area | int | In | Area identifier. |
Wordlen | int | In | Word size |
Result | int | Out | Item operation result (2) |
DBNumber | int | In | DB Number if Area = S7AreaDB, otherwise is ignored. |
Start | int | In | Offset to start |
Amount | int | In | Amount of words to write (1) |
pData | IntPtr | In | Pointer to user Buffer |
(2) Note the use of the parameter name “amount”, it means quantity of words, not byte size.
Return value
· 0 : The function was accomplished with no errors.
· Other values : see the Errors Code List.
(2) Since could happen that some variables are written, some other not because maybe they don't exist in PLC. Is important to check the single item Result.
Remarks
To use WriteMultiVars a special class is supplied S7MultiVar that avoids the use of unsafe code (since there is a IntPtr)
Due the different kind of variables involved , there is no split feature available for this function, so the maximum data size must not exceed the PDU size
The advantage of this function becomes big when you have many small noncontiguous variables to be written.
Lean Data I/O functions
These are utility functions that simplify the use of ReadArea and WriteArea.
I.e. they call internally ReadArea and WriteArea passing the correct Area and WordLen.
Function | Purpose |
DBRead | Reads a part of a DB from a PLC. |
DBWrite | Writes a part of a DB into a PLC. |
ABRead | Reads a part of IPU area from a PLC. |
ABWrite | Writes a part of IPU area into a PLC. |
EBRead | Reads a part of IPI area from a PLC. |
EBWrite | Writes a part of IPI area into a PLC. |
MBRead | Reads a part of Merkers area from a PLC. |
MBWrite | Writes a part of Merkers area into a PLC. |
TMRead | Reads timers from a PLC. |
TMWrite | Write timers into a PLC. |
CTRead | Reads counters from a PLC. |
CTWrite | Write counters into a PLC. |
Function | Purpose |
GetAgBlockInfo | Returns info about a given block in PLC memory. |
DBGet | Uploads a DB from the PLC |
DBFill | Fills a DB into the PLC with a given value. |
(1) Note the use of the parameter name “amount”, it means quantity of elements, not byte size.
Area table
| Value | Mean |
S7Consts.S7AreaPE | 0x81 | Process Inputs. |
S7Consts.S7AreaPA | 0x82 | Process Outputs. |
S7Consts.S7AreaMK | 0x83 | Merkers. |
S7Consts.S7AreaDB | 0x84 | DB |
S7Consts.S7AreaCT | 0x1C | Counters. |
S7Consts.S7AreaTM | 0x1D | Timers |
WordLen table
| Value | Mean |
S7WLBit | 0x01 | Bit (inside a word) |
S7WLByte | 0x02 | Byte (8 bit) |
S7WLWord | 0x04 | Word (16 bit) |
S7WLDWord | 0x06 | Double Word (32 bit) |
S7WLReal | 0x08 | Real (32 bit float) |
S7WLCounter | 0x1C | Counter (16 bit) |
S7WLTimer | 0x1D | Timer (16 bit) |
Return value
· 0 : The function was accomplished with no errors.
· Other values : see the Errors Code List.