Project overview

 

Moka7 is the Java port of Snap7 Client. It’s not a wrapper, i.e. you don’t have an interface code that loads snap7.dll (or .so) but it’s a pure Java implementation of the S7Protocol.

Moka7 is deployed as a set of source code classes that you can use in your Java project to communicate with S7 PLCs.

Not all functions are ported but the list of the PLC managed is the same, it’s designed to work with small hardware java-based, Android phones or even for large projects which don’t needs of extended control functions.

Moka7 is part of Snap7 so it shares the same licensing.

Main features

 

·         Fully standard Java code without any dependencies.

·         Fully multiplatform, virtually every hardware with an Ethernet adapter able to run a JVM can be connected to an S7 PLC.

·         Packed protocol headers to improve performances.

·         Helper class to access to all S7 types without worrying about Little-Big endian convention.

 

Moka7 deploy

 

Moka7 is a classes library, for convenience the source files are included into two projects both containing also a demo program.

A NetBeans 4.7 project called Moka7-NetBeans.

A Eclipse Kepler project called Moka7-Eclipse.

The projects are absolutely the same and contain the same source files, choose the one you prefer.

Into the project you will find two packages :

·         Moka7, the main package.

·         Moka7Demo that contains a Client demo program

Many files contained into Moka7 package are only structure classes, i.e. the java port of the C structures, the same that you find into snap7.h (see snap7 project):

·         IntByRef.java (utility class to pass an integer by reference)

·         S7BlockInfo.java

·         S7CpInfo.java

·         S7CpuInfo.java

·         S7OrderCode.java

·         S7Protection.java

·         S7Szl.java

The main classes that we will analyze are:

·         S7Client, the client object.

·         S7 an helper class to read/write S7 types from/to a byte array.

 


 

S7Client reference

In the manual you will find detailed information about syntax, parameters and examples, please refer to it.

Administrative functions

 

These methods allow controlling the behavior a Client Object.

 

Function

Purpose

ConnectTo

Connects a Client Object to a PLC.

SetConnectionType

Sets the connection type (PG/OP/S7Basic)

SetConnectionParams

Sets Address, Local and Remote TSAP for the connection.

Connect

Connects a Client Object to a PLC with implicit parameters.

Disconnect

Disconnects a Client.

 

Data I/O functions

 

These functions allow the Client to exchange data with a PLC.

 

Function

Purpose

ReadArea

Reads a data area from a PLC.

WriteArea

Writes a data area into a PLC.

 

Block oriented functions

 

Function

Purpose

GetAgBlockInfo

Returns info about a given block in AG.

DBGet

Uploads a DB from AG.

 

Date/Time functions

 

These functions allow to read/modify the date and time of a PLC.

Imagine a production line in which each PLC saves the data with date/time field inside, it is very important that the date be up to date.

Both CP X43 and internal PN allow to synchronize date and time but you need an NTP server, and in some cases (old hardware or CP343-1 Lean or old firmware release) this doesn’t work properly.

Snap7 Client, using the same method of S7 Manager, always works.

 

Function

Purpose

Cli_GetPlcDateTime

Returns the PLC date/time.

Cli_SetPlcDateTime

Sets the PLC date/time with a given value.

Cli_SetPlcSystemDateTime

Sets the PLC date/time with the host (PC) date/time.

 

System info functions

 

these functions access to SZL (or SSL - System Status List) to give you all the same information that you can get from S7 Manager.

 

System Status List

The system status list (SSL) describes the current status of a programmable logic controller.

The contents of the SSL can only be read using information functions but cannot be modified. The partial lists are virtual lists, in other words, they are only created by the operating system of the CPUs when specifically requested.

You can access to system status list using SFC 51 too "RDSYSST."

To read a partial list you must specify its ID and Index.

For a detailed description of SZL see:

§33 of  "System Software for S7-300/400 System and Standard Functions".

 

Function

Purpose

ReadSZL

Reads a partial list of given ID and Index.

GetOrderCode

Returns the CPU order code.

GetCpuInfo

Returns some information about the AG.

GetCpInfo

Returns some information about the CP (communication processor).

 

PLC control functions

 

With these control function it’s possible to Start/Stop a CPU and read the PLC status.

 

Function

Purpose

PlcColdStart

Puts the CPU in RUN mode performing an COLD START.

PlcHotStart

Puts the CPU in RUN mode performing an HOT START.

PlcStop

Puts the CPU in STOP mode.

GetPlcStatus

Returns the CPU status (running/stopped).

 

 

Security functions

 

With these functions is possible to know the current protection level, and to set/clear the current session password.

The correct name of the below functions SetSessionPassword and ClearSessionPassword, would have to be Login and Logout to avoid misunderstandings about their scope.

Especially because, if you look at the source code, there is an encoding function that translates the plain password before send it to the PLC.

PASSWORD HACKING IS VERY FAR FROM THE AIM OF THIS PROJECT, MOREOVER YOU NEED TO KNOW THE CORRECT PASSWORD TO MEET THE CPU SECURITY LEVEL.

Detailed information about the protection level can be found in §33.19 of  "System Software for S7-300/400 System and Standard Functions".

 

Function

Purpose

SetSessionPassword

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

ClearSessionPassword

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

GetProtection

Gets the CPU protection level info.

 

Miscellaneous functions

 

These are utility functions.

 

Function

Purpose

PduLength

Returns info about the PDU length (requested and negotiated).

ErrorText

Returns a textual explanation of a given error number.


 

Public Fields

 

RecvTimeout

int, input – It’s the receiving timeout (in milliseconds) for a telegram.

LastError

int, output – Contains the last operation error.

Connected

bool, output – It’s true if the Client is connected.

 

S7 Helper syntax

In the manual you will find detailed information about syntax, parameters and examples, please refer to it.

 

Read functions

Function

Purpose

GetBitAt

Returns the Bit at given location in an user byte buffer

GetWordAt

Returns the Word at given location in an user byte buffer

GetShortAt

Returns the Short at given location in an user byte buffer

GetDWordAt

Returns the DWord at given location in an user byte buffer

GetDIntAt

Returns the DInt at given location in an user byte buffer

GetFloatAt

Returns the Float at given location in an user byte buffer

GetStringAt

Returns the String at given location in an user byte buffer

GetPrintableStringAt

Returns the String (in printable format) at given location in an user byte buffer

GetDateAt

Returns the Date and Time at given location in an user byte buffer

 

Write functions

Function

Purpose

SetBitAt

Writes a Bit at given location in an user byte buffer

SetWordAt

Writes a Word at given location in an user byte buffer

SetShortAt

Writes a Short at given location in an user byte buffer

SetDWordAt

Writes a DWord at given location in an user byte buffer

SetDIntAt

Writes a DInt at given location in an user byte buffer

SetFloatAt

Writes a Float at given location in an user byte buffer

SetDateAt

Writes a Date and Time at given location in an user byte buffer

 

 

Error codes

 

Mnemonic

HEX

Meaning

errTCPConnectionFailed

0x0001

TCP Connection error.

errTCPDataSend

0x0002

TCP error sending the data.

errTCPDataRecv

0x0003

TCP error receiving the data.

errTCPDataRecvTout

0x0004

A timeout occurred waiting a reply.

errTCPConnectionReset

0x0005

Connection reset by the peer.

errISOInvalidPDU

0x0006

Malformed PDU supplied.

errISOConnectionFailed

0x0007

ISO connection failed.

errISONegotiatingPDU

0x0008

ISO PDU negotiation failed.

errS7InvalidPDU

0x0009

Invalid PDU received.

errS7DataRead 

0x000A

Error during data read.

errS7DataWrite

0x000B

Error during data write.

errS7FunctionError 

0x000D

The PLC reported an error for this function.

errBufferTooSmall

0x000C

The buffer supplied is too small.

errInvalidParams

0x000E

An invalid parameter was supplied to the function.