node-snap7

Build status: Linux Windows

!!! node-snap7 is still a work in progress !!!

About

This is a node.js wrapper for snap7. Snap7 is an open source, 32/64 bit, multi-platform Ethernet communication suite for interfacing natively with Siemens S7 PLCs (See compatibility).

Installation

Install with:

npm install node-snap7

Requirements:

• Windows:
  • Visual Studio 2010 Express or higher e.g Visual Studio 2013 Express
  • Python 2.7
• Linux:
  • gcc & make
  • Python 2.7

Special thanks to

• Davide Nardella for creating snap7

How to use

Example

var snap7 = require('node-snap7');

var s7client = new snap7.S7Client();
s7client.ConnectTo('127.0.0.1', 0, 1, function(err) {
    if(err)
        return console.log(' >> Connection failed. Code #' + err + ' - ' + s7client.ErrorText(err));
    
    // Read the first byte from PLC process outputs...
    s7client.ABRead(0, 1, function(err, res) {
        if(err)
            return console.log(' >> ABRead failed. Code #' + err + ' - ' + s7client.ErrorText(err));
        
        // ... and write it to stdout
        console.log(res)
    });
});

API

• Control functions
  • Connect()
  • ConnectTo()
  • SetConnectionParams()
  • Disconnect()
  • GetParam()
  • SetParam()
• Data I/O functions
  • ReadArea()
  • WriteArea()
  • DBRead()
  • DBWrite()
  • ABRead()
  • ABWrite()
  • EBRead()
  • EBWrite()
  • MBRead()
  • MBWrite()
  • TMRead()
  • TMWrite()
  • CTRead()
  • CTWrite()
  • ReadMultiVars()
  • WriteMultiVars()
• Directory function
  • ListBlocks()
  • ListBlocksOfType()
  • GetAgBlockInfo()
  • GetPgBlockInfo()
• Block oriented functions
  • FullUpload()
  • Upload()
  • Download()
  • Delete()
  • DBGet()
  • DBFill()
• Date/Time functions
  • GetPlcDateTime()
  • SetPlcDateTime()
  • SetPlcSystemDateTime()
• System info functions
  • ReadSZL()
  • ReadSZLList()
  • GetOrderCode()
  • GetCpuInfo()
  • GetCpInfo()
• PLC control functions
  • PlcHotStart()
  • PlcColdStart()
  • PlcStop()
  • CopyRamToRom()
  • Compress()
• Security functions
  • SetSessionPassword()
  • ClearSessionPassword()
  • GetProtection()
• Properties
  • ExecTime()
  • LastError()
  • PduRequested()
  • PduLength()
  • PlcStatus()
  • Connected()
  • ErrorText()

API - Control functions

---

S7Client.Connect([callback])

Connects the client to the PLC with the parameters specified in the previous call of ConnectTo() or SetConnectionParams().

• The optional callback parameter will be executed after connection attempt

If callback is not set the function returns true on success or false on error.
If callback is set an error argument is given to the callback

S7Client.ConnectTo(ip, rack, slot, [callback])

Connects the client to the hardware at (IP, Rack, Slot) Coordinates.

• ip PLC/Equipment IPV4 Address ex. “192.168.1.12”
• rack PLC Rack number
• slot PLC Slot number
• The optional callback parameter will be executed after connection attempt

If callback is not set the function returns true on success or false on error.
If callback is set an error argument is given to the callback

S7Client.SetConnectionParams(ip, localTSAP, remoteTSAP)

Sets internally (IP, LocalTSAP, RemoteTSAP) Coordinates.

• ipP PLC/Equipment IPV4 Address ex. “192.168.1.12”
• localTSAP Local TSAP (PC TSAP)
• remoteTSAP Remote TSAP (PLC TSAP)

Returns true on success or false on error.

S7Client.Disconnect()

Disconnects “gracefully” the Client from the PLC.

Returns true on success or false on error.

S7Client.GetParam(paramNumber)

Reads an internal Client object parameter.

• paramNumber One from the parameter list below

Name	Value	Description
S7Client.RemotePort	2	Socket remote Port.
S7Client.PingTimeout	3	Client Ping timeout.
S7Client.SendTimeout	4	Socket Send timeout.
S7Client.RecvTimeout	5	Socket Recv timeout.
S7Client.SrcRef	7	ISOTcp Source reference.
S7Client.DstRef	8	ISOTcp Destination reference
S7Client.SrcTSap	9	ISOTcp Source TSAP.
S7Client.PDURequest	10	Initial PDU length request.

Returns the parameter value on success or false on error.

S7Client.SetParam(paramNumber, value)

Sets an internal Client object parameter.

• paramNumber One from the parameter list above
• value New parameter value

Returns true on success or false on error.

API - Data I/O functions

---

S7Client.ReadArea(area, dbNumber, start, amount, wordLen, [callback])

This is the main function to read data from a PLC. With it you can read DB, Inputs, Outputs, Merkers, Timers and Counters.

• area
• dbNumber
• start
• amount
• wordLen
• callback

S7Client.WriteArea(area, dbNumber, start, amount, wordLen, buffer, [callback])

This is the main function to write data into a PLC.

• area
• dbNumber
• start
• amount
• wordLen
• buffer
• callback

S7Client.DBRead(dbNumber, start, size, [callback])

This is a lean function of ReadArea() to read PLC DB.
It simply internally calls ReadArea() with area = S7Client.S7AreaDB and wordLen = s7client.S7WLByte.

• dbNumber
• start
• size
• callback

S7Client.DBWrite(dbNumber, start, size, buffer, [callback])

This is a lean function of WriteArea() to write PLC DB.
It simply internally calls WriteArea() with area = S7Client.S7AreaDB and wordLen = s7client.S7WLByte.

• dbNumber
• start
• size
• buffer
• callback

S7Client.ABRead(start, size, [callback])

This is a lean function of ReadArea() to read PLC process outputs.
It simply internally calls ReadArea() with area = S7Client.S7AreaPA and wordLen = s7client.S7WLByte.

• start
• size
• callback

S7Client.ABWrite(start, size, buffer, [callback])

This is a lean function of WriteArea() to write PLC process outputs.
It simply internally calls WriteArea() with area = S7Client.S7AreaPA and wordLen = s7client.S7WLByte.

• start
• size
• buffer
• callback

S7Client.EBRead(start, size, [callback])

This is a lean function of ReadArea() to read PLC process inputs.
It simply internally calls ReadArea() with area = S7Client.S7AreaPE and wordLen = s7client.S7WLByte.

• start
• size
• callback

S7Client.EBWrite(start, size, buffer, [callback])

This is a lean function of WriteArea() to write PLC process inputs.
It simply internally calls WriteArea() with area = S7Client.S7AreaPE and wordLen = s7client.S7WLByte.

• start
• size
• buffer
• callback

S7Client.MBRead(start, size, [callback])

This is a lean function of ReadArea() to read PLC Merkers.
It simply internally calls ReadArea() with area = S7Client.S7AreaMK and wordLen = s7client.S7WLByte.

• start
• size
• callback

S7Client.MBWrite(start, size, buffer, [callback])

This is a lean function of WriteArea() to write PLC Merkers.
It simply internally calls WriteArea() with area = S7Client.S7AreaMK and wordLen = s7client.S7WLByte.

• start
• size
• buffer
• callback

S7Client.TMRead(start, amount, [callback])

This is a lean function of ReadArea() to read PLC Timers.
It simply internally calls ReadArea() with area = S7Client.S7AreaTM and wordLen = S7Client.S7WLTimer.

• start
• amount
• callback

S7Client.TMWrite(start, amount, buffer, [callback])

This is a lean function of WriteArea() to write PLC Timers.
It simply internally calls WriteArea() with area = S7Client.S7AreaTM and wordLen = S7Client.S7WLTimer.

• start
• amount
• buffer
• callback

S7Client.CTRead(start, amount, [callback])

This is a lean function of ReadArea() to read PLC Counters.
It simply internally calls ReadArea() with area = S7Client.S7AreaCT and wordLen = S7Client.S7WLCounter.

• start
• amount
• callback

S7Client.CTWrite(start, amount, buffer, [callback])

This is a lean function of WriteArea() to write PLC Counters.
It simply internally calls WriteArea() with area = S7Client.S7AreaCT and wordLen = S7Client.S7WLCounter.

• start
• amount
• buffer
• callback

S7Client.ReadMultiVars(multiVars, [callback])

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.

• ...

S7Client.WriteMultiVars(multiVars, [callback])

This is function allows to write different kind of variables into a PLC in a single call. With it you can write DB, Inputs, Outputs, Merkers, Timers and Counters.

• ...

API - Directory functions

---

S7Client.ListBlocks([callback])

This function returns the AG blocks amount divided by type.

S7Client.ListBlocksOfType(blockType, [callback])

This function returns the AG list of a specified block type.

• blockType

S7Client.GetAgBlockInfo(blockType, blockNum, [callback])

Returns detailed information about an AG given block. This function is very useful if you need to read or write data in a DB which you do not know the size in advance (see MC7Size field)

• blockType
• blockNum

S7Client.GetPgBlockInfo(buffer)

Returns detailed information about a block present in a user buffer. This function is usually used in conjunction with FullUpload(). An uploaded block saved to disk, could be loaded in a user buffer and checked with this function.

• buffer

API - Block oriented functions

---

S7Client.FullUpload(blockType, blockNum, [callback])

Uploads a block from AG. The whole block (including header and footer) is copied into the user buffer.

• blockType
• blockNum
• callback

S7Client.Upload(blockType, blockNum, [callback])

Uploads a block body from AG. Only the block body (but header and footer) is copied into the user buffer.

• blockType
• blockNum
• callback

S7Client.Download(blockNum, buffer, [callback])

Downloads a block into AG. A whole block (including header and footer) must be available into the user buffer.

• blockNum
• buffer
• callback

S7Client.Delete(blockType, blockNum, [callback])

Deletes a block into AG.

!!! There is no undo function available. !!!

• blockType
• blockNum
• callback

S7Client.DBGet(dbNumber, [callback])

Uploads a DB from AG. This function is equivalent to Upload() with BlockType = Block_DB but it uses a different approach so it’s not subject to the security level set. Only data is uploaded.

• dbNumber
• callback

S7Client.DBFill(dbNumber, fillChar, [callback])

Fills a DB in AG with a given byte without the need of specifying its size.

• dbNumber
• fillChar
• callback

API - Date/Time functions

---

S7Client.GetPlcDateTime([callback])

Reads PLC date and time.

S7Client.SetPlcDateTime(dateTime, [callback])

Sets the PLC date and time.

• dateTime

S7Client.SetPlcSystemDateTime([callback])

Sets the PLC date and time in accord to the PC system Date/Time.

API - System info functions

---

S7Client.ReadSZL([callback])

Reads a partial list of given ID and INDEX.

S7Client.ReadSZLList([callback])

Reads the directory of the partial lists.

S7Client.GetOrderCode([callback])

Gets CPU order code and version info.

S7Client.GetCpuInfo([callback])

Gets CPU module name, serial number and other info.

S7Client.GetCpInfo([callback])

Gets CP (communication processor) info.

API - PLC control functions

---

S7Client.PlcHotStart([callback])

Puts the CPU in RUN mode performing an HOT START.

S7Client.PlcColdStart([callback])

Puts the CPU in RUN mode performing a COLD START.

S7Client.PlcStop([callback])

Puts the CPU in STOP mode.

S7Client.CopyRamToRom(timeout, [callback])

Performs the Copy Ram to Rom action.

S7Client.Compress(timeout, [callback])

Performs the Memory compress action.

API - Security functions

---

S7Client.SetSessionPassword(password, [callback])

Send the password to the PLC to meet its security level.

S7Client.ClearSessionPassword([callback])

Clears the password set for the current session (logout).

S7Client.GetProtection([callback])

Gets the CPU protection level info.

API - Properties

---

S7Client.ExecTime()

Returns the last job execution time in milliseconds.

S7Client.LastError()

Returns the last job result.

S7Client.PduRequested()

S7Client.PduLength()

Returns info about the PDU length.

S7Client.PlcStatus([callback])

Returns the CPU status (running/stopped).

S7Client.Connected()

Returns the connection status

S7Client.ErrorText(errNum)

Returns a textual explanation of a given error number.

• errNum

Licence & copyright

Copyright (c) 2015, Mathias Küsel

node-snap7 is licensed under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.

node-snap7 builds on the excellent work of the snap7 framework from Davide Nardella. Snap7 is issued under the GPL/LGPLv3 (see ./deps/snap7/gpl.txt ./deps/snap7/lgpl-3.0.txt).