Sharp7读写数据API

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 ex. “192.168.1.12”
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.

 

 

Block oriented functions

 

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.