SmartGridwareSmartGridware® Java IEC 61850 Client SDK
High Level Java API for IEC 61850 Client Software Development
Product Overview
The SmartGridware® Java IEC 61850 Client Software Development Kit (SDK) provides a high level ACSI (Abstract Communication Service Interface: IEC61850-7-2) model and service interface for implementing client IEC 61850 compliant applications in the Java programming language. All protocol specific details (e.g. MMS) are hidden such that the API user develops at the ACSI model layer without needing to understand the underlying communication protocol.
Product Features
The client API is a feature rich interface that makes developing IEC 61850 client applications quick and easy. See some of the many features below:
- one call server discovery (names, data definitions and data)
- data-definition discovery from device or SCL ICD
- URI based server addressing
- text based authentication support
- local caching of server data (from a single LN to the complete device)
- report based cache updates
- single code line polling
- Protocol independent API, MMS details independent of interface
- includes MMS protocol provider supported
- other protocol mappings to be added (XML WebServices, etc)
- API model interface hierarchy mirrors server data model
- all model interface toString() methods generate user friendly format
- ACSI data model interfaces:
- Logical Device (LD),
- Logical Node (LN),
- Functional Contraint(FC),
- Data Object (DO),
- Data Attribute (DA),
- DataSet,
- Buffered Report Control Block (BRCB),
- Unbuffered Report Control Block (URCB),
- Control Objects
- IEC 61850-7-2 Model Services
- Server (GetServerDirectory)
- Association (Associate, Abort, ...)
- Logical Device (GetLogicalDeviceDirectory, ...)
- Logical Node (GetAllDataValues, GetLogical Node Directory, ...)
- Data (GetDataValues, SetDataValues, GetDataDirectory, ...)
- Data Set (GetDataSetValues, SetDataSetValues, CreatedDataSet, ...)
- Setting Group CB (SetActiveSG, SelectEditSG, ...);
- Report Control Block (Report, GetBRCBValues, ...)
- LOG Control Block (GetLCBBalues, SetLCBValues, ...)
- GOOSE (GetGoCBValues, SetGoCBValues)
- File Transfer (GetFile, SetFile, DeleteFile, ...)
- Control (Select,SelectWithValue, Operate, ...)
- uses the SmartGridware™ Java MMS Stack as the MMS provider
Supported Standards
The functionality provided by the SmartGridware® IEC 61850 Client SDK is implemented in compliance with the following standards (click to view):
IEC 61850 Standards
- IEC 61850-7-1: Principles and models
- IEC 61850-7-2: Abstract Communication Service Interface (ACSI)
- IEC 61850-7-3: Common Data Classes
- IEC 61850-7-4: Logical Node Classes
- IEC 61850-8-1: Service Mapping: ACSI Mappings to MMS & GOOSE
- IEC 61850-9-2: Sampled Values over ISO/IEC 8802-3
- IEC 61850-6: Configuration Description Language (SCL)
IEC 61850 Upper Layer Protocol Support
- IEC 61850-8-1 Client/Server Services (MMS) (6.2.1)
- IEC 61850-8-1 Client/Server A-Profile (6.2.2)
- IEC 61850-8-1 GOOSE/GSE A-Profile (6.2.2)
- IEC 61850-8-1 TCP/IP T-Profile (RFC1006) (6.2.3)
- IEC 61850-8-1 GOOSE over ISO/IEC 8802-3 (No link redundancy)
- IEC 61850-9-2 Sampled Values over ISO/IEC 8802-3 (No link redundancy)
Manufacturing Message Specification (MMS) Standards
- ISO 9506-1: Manufacturing Message Specification - Service Definitions
- ISO 9506-2: Manufacturing Message Specification - Protocol Definitions
OSI Stack and Lower Layer Standards
- RFC 1006: OSI over TCPIP (CMIP/OSI over TCP/IP)
- ITU-T X.214 | ISO/IEC 8072: OSI - Transport Service Definition
- ITU-T X.224 | ISO/IEC 8073: OSI - Transport Protocol Specification
- ITU-T X.215 | ISO/IEC 8326: OSI - Session Service Definition
- ITU-T X.225 | ISO/IEC 8327: OSI - Session Protocol Specification
- ITU-T X.216 | ISO/IEC 8822: OSI - Presentation Service Definition
- ITU-T X.226 | ISO/IEC 8823-1: OSI - Presentation Protocol Specification
- ITU-T X.217 | ISO/IEC 8649: ACSE Service
- ITU-T X.227 | ISO/IEC 8650-1: ACSE Protocol
- ITU-T X.680 | ISO/IEC 8824-1..4: Abstract Syntax Notation One (ASN.1)
- ITU-T X.690 | ISO/IEC 8825-1: ASN.1 Encoding Rules (BER/DER/CER)
Client API Examples
The following examples show some of the core components of the SmartGridware® Java IEC61850 Client API (click to view):
Server Discovery
// -- initialize the API
IEC61850ClientApi api = IEC61850ClientApi.newInstance("mms");
//-- create the server address URI
String uri =
"rfc1006://host:102/0x0001/0x0001/0x00000001/1,1,9999,1/12";
// -- create a new client object
IEC61850Client client = api.newClient(uri);
//-- perform a 'discovery' of the IED. This includes retreiving
//-- all data definitions, all data values, and all information
//-- about data-sets, report control blocks, etc.
DiscoverOp discover_op = client.newDiscoverOp();
//-- perform the discover synchronously
DiscoverOp.Response rsp = discover_op.perform();
// -- print out ENTIRE data model from IED
System.out.println(client.getIED());
Server Discovery, Initialized from SCL ICD File
// -- initialize the API
IEC61850ClientApi api = IEC61850ClientApi.newInstance("mms");
//-- This will load the ICD file and populate the local
//-- model from the ICD file data.
IEC61850Client client = api.newClientFromScl("DynDevice.icd");
//-- Print out the complete SCL data model
System.out.println(client.getIED());
//-- perform a 'discovery' of the IED. This includes retreiving all
//-- data definitions, all data values, and all information about
//-- data-sets, report control blocks, etc.
DiscoverOp discover_op = client.newDiscoverOp();
DiscoverOp.Response rsp = discover_op.perform();
// -- print out the current data from the IED
System.out.println(client.getIED());
Data Model Hierarchy
LD ld = client.getDefaultLD();
// -- Iterate over the LNs,FCs, DOs and DAs
for (LN ln : ld.getLNs())
{
for( FC fc : ln.getFCs())
{
for(DO dobj: fc.getDOs())
{
for(DA da: dobj.getDAs())
{
// -- print out the name and value.
System.out.println("DA: " + da.getName()
+ " == " + da.value());
}
}
}
}
Control Example (sbo-with-enhanced-security)
//-- Get a new Control object for the AnOut1 controllable object
Control control = client.newControl("DynGGIO1$AnOut1");
//-- For enhanced security, use a CommandTerminationListener
control.setCommandTerminationListener(
new Control.TerminationListener()
{
public void handleTermination(Control control)
{ /** SUCCESS **/ }
public void handleTerminationError(Control control,
AddCause cause, ApplError appl_error)
{ /** ERROR **/ }
});
//-- Access the control parameters for the transaction
Control.CtlParams params = control.params();
params.refControlValue().get("i").setValue(500); // -- ctl value
params.setCheck(Check.BOTH); // -- both synchro and interlocking
params.setTest(false); // -- set the 'test' flag to 'false'
control.performSelectWithValue(); // -- perform SelectWithValue
control.performOperate(); // -- perform Operate
control.shutdownControl(); // -- shutdown the control
Reserve a Buffer Report Control Block (BRCB)
// -- Get the list of BRCBs contained by LLN0
List<BRCB> brcb_list = client.getDefaultLD().getLLN0().getBRCBs();
for (BRCB brcb : brcb_list)
{
if (!brcb.isReportEnabled())
{
// -- not reserved, lets reserve this one
try
{
BRCB.SetOp set_op = brcb.newSetOp();
set_op.setDataSetName("DynGGIO1$IOMeasuredValues");
set_op.setBufferTime(1000);
set_op.setReservationTime(5000);
set_op.setIntegrityPeriod(30000);
set_op.setTriggerOptions( TrgOps.DATA_CHANGE,
TrgOps.DATA_UPDATE, TrgOps.QUALITY_CHANGE);
set_op.setOptionalFields( OptFlds.REASON_FOR_INCLUSION,
OptFlds.BUFFER_OVERFLOW, OptFlds.DATASET_NAME);
set_op.setReportEnabled(true);
set_op.perform(); // Attempt to reserve the BRCB
System.out.println(" [reserved]: \n" + brcb);
break; // reserved okay, can stop iterating..
}
catch (ModelException me)
{
// -- Exception, reserve failed... try next...
}
}
}
Association Monitor
IEC61850ClientApi api = IEC61850ClientApi.newInstance("mms");
IEC61850Client client = api.newClientFromScl("DynDevice.icd", uri);
client.addAssociationListener(new IEC61850Client.AssociationListener()
{
public void associationUp(IEC61850Client client)
{
System.out.println("-- association up --");
}
public void associationDown(IEC61850Client client)
{
System.out.println("-- association down --");
}
});
ACSI Report Listener
//--
//-- Attach a Report Listener to the client to receive reports
//--
client.addReportListener(new IEC61850Client.ReportListener()
{
public void handleReport(IEC61850Client client, Report report)
{
String report_id = report.getReportID();
String data_set_name = report.getDataSetName();
...
for(Report.EntryData entry : report.getEntryData())
{
System.out.println(entry.getValue());
}
}
});
Get DataSet Values
LD ld = client.getDefaultLD();
for (LN ln : ld.getLNs())
{
for (DataSet ln_ds : ln.getDataSets())
{
// -- print out the DataSet info
System.out.println(ln_ds);
}
}
//-- get the DataSet object from the local data model
DataSet io_status_set = ld.getDataSet("DynGGIO1$IOStatusSet");
//-- Create a new GetOp to get the attributes for this DataSet.
GetOp get_op = io_status_set.newGetOp();
//-- Perform a synchronous send/receive of the GetDataValues
GetOp.Response rsp = get_op.perform();
// -- iterate over the attribute results in the response
for (GetOp.AccessResult result : rsp.getResults())
{
GetOp.Attribute attr = result.getAttribute();
System.out.println(" attr[" + result.isSuccess() + "]: "
+ attr.getDataRef() + " ==> " + result.getValue());
}
GetDataSet and SetDataValues
//-- Create a general GetOp and add 4 attributes to get
GetOp get_op = client.newGetOp();
get_op.addAttribute("DynGGIO1$CF$AnIn1$smpRate");
get_op.addAttribute("DynGGIO1$MX$AnOut1$mxVal");
get_op.addAttribute("DynGGIO1$MX$AnOut1$t");
get_op.addAttribute("DynGGIO1$MX$AnOut1$q");
//-- perform the GetDataValues and print the result
System.out.println("GET-RESULT: " + get_op.perform());
//-- Create a general SetOp and add 3 attributes to set
SetOp set_op = client.newSetOp();
set_op.addAttribute("DynGGIO1$CF$AnIn1$smpRate",500);
set_op.addAttribute("DynGGIO1$CF$AnOut1$sboTimeout",10000);
set_op.addAttribute("DynGGIO1$DC$NamPlt$d","some description");
//-- perform the operation and print the result
System.out.println("SET-RESULT: " + set_op.perform());
Data Node toString() Output Example
// The following output shows the containment hierarcht for a functional
// constraing along with the value of DAs and each DA's source,
// time since last update and triggers.
[FC] MX
[DO] AnIn1
[DA] instMag
[DA] i (rmt,0s,cqua) {i32} 0
[DA] mag
[DA] i (rmt,0s,cqua) {i32} 0
[DA] range (rmt,0s,cqua) {i8} 0
[DA] q (rmt,0s,cqua) {Quality} [0000000000000]()
[DA] t (rmt,0s,cqua) {time}
u01/01/1970_00:00:00.000[00000000]
[DO] AnOut1
[DA] origin
[DA] orCat (rmt,0s,cqua) {i8} 0
[DA] orIdent (rmt,0s,cqua) {oct64} ''h
[DA] ctlNum (rmt,0s,cqua) {i8u} 0
[DA] mxVal
[DA] i (rmt,0s,cqua) {i32} 800
[DA] q (rmt,0s,cqua) {Quality} [0000000000000]()
[DA] t (rmt,0s,cqua) {time}
u01/01/1970_00:00:00.000[00000000]
Platform Requirements
Java Platform Requirements:
The Core SmartGridware® Java IEC 61850 software requires
the following Java Development Kit
in order to develop applications:
In order to install or upgrade your installed JDK version, please visit the Oracle Java Developers page at:
GOOSE and Sampled Value Requirements:
GOOSE and/or Sampled Value
components are supported
for Windows, Linux and MacOS with the following requirements :
Windows GOOSE/SV Requirements
- Java SE Development Kit Version 1.5 or newer (See above)
- WinPCAP Packet Capture Library (See: www.winpcap.org)
MacOSX/Linux GOOSE/SV Requirements
- Java SE Development Kit Version 1.5 or newer (See above)
- Libpcap Packet Capture Library
- Linux and MacOSX distributions may already have libpcap installed.
- On MacOSX, libpcap is part of the Xcode package.
- On Linux, libpcap may be installed or updated through the platform's installer like 'yum'
Operating System Requirements:
The core Client API will work on any operating system which supports the Java versions
listed in the Java Platform Requirements section above.
Some of the operating systems commonly used with SmartGridware™ products are:
- Microsoft Windows (95,98,XP,NT,2000,7,8)
- Linux (Redhat, etc)
- Hewlett Packard HP-UX
- Sun Solaris (SPARC & x86)
- IBM AIX
- Apple MacOS X
Note that for GOOSE and Sampled Value support, only Windows, MacOSX and Linux are supported and require the use of the PCAP library as detailed above
Hardware Requirements:
Minimum Hardware
- Physical memory (RAM): 256MB
- Disk space: 30MB (distribution package size)
