SmartGridwareSmartGridware® Java IEC 61850 Server SDK
High Level Java API for IEC 61850 Server Software Development
Product Overview
The SmartGridware® Java IEC 61850 Server Software Development Kit (SDK) provides a high level ACSI (Abstract Communication Service Interface: IEC 61850-7-2) server side interface for implementing IEC 61850 compliant server 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 server framework provides built-in server role support for the common IEC 61850 ACSI services such that all the user application needs only to implement is the data access. Server initialization is performed through the loading of an SCL ICD file to provide all data definitions, initial data values, server addressing and configuration of some server behavior. In order to extend the server framework, the API user simply provides hooks into the data model to implement behavior such as control object behavior, on-demand data access, etc.
See some of the many features below:
- initialized from SCL ICD file
- text based authentication support
- simple API representation of ACSI data model
- built-in support for common ACSI services
- automatic report generation
- 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, ...)
- Default CDC behavioral support for: APC, BCR, DPC, DPL,DPS,ENC,ENS, INC,INS,LPL,MV,ORG,SPC,SPG,SPS with more to come.
- uses the SmartGridware™ Java MMS Stack as the MMS provider
Supported Standards
The functionality provided by the SmartGridware® IEC 61850 Server 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)
Server API Examples
The following examples show some of the core components of the SmartGridware™ Java IEC 61850 Server API (click to view):
IEC 61850 Server Initialization
// -- Create a new IEC61850 API instance
IEC61850ServerApi api = IEC61850ServerApi.newInstance("mms");
// -- Create a new IEC61850 server instance
IEC61850Server server = api.newServer();
ACSIServices services = new ACSIServices(
ACSIServices.SERVICE.Basic,
ACSIServices.SERVICE.GetFile,
ACSIServices.SERVICE.GetDataValues,
ACSIServices.SERVICE.SetDataValues);
// -- Enable specified available ACSI services
server.setServerServices(services);
//-- Load in the provided ICD file
server.loadSCL("MyDevice.icd");
//-- Start listening on the associated ConnectedAPs
server.startListening();
Data Model Traversal
for (SvLD ld : server.getLDs())
{
System.out.println("LD: " + ld.getName());
for (SvLN ln : ld.getLNs())
{
System.out.println(" LN: " + ln.getName());
for (SvVDO vdo : ln.getVDOs())
{
System.out.println(" DO: " + vdo.getName());
for (SvDA da : vdo.getDAs())
{
System.out.println(" DA: " + da.getName());
}
for (SvVDO cvdo : vdo.getVDOs())
{
System.out.println(" DO: " + vdo.getName());
for (SvDA da : cvdo.getDAs())
{
System.out.println(" DA: " + da.getName());
}
}
}
}
}
Server Authentication Processor
//-- check authentication info in incoming associations
server.setAuthenticationListener(
new IEC61850Server.AuthenticationListener()
{
@Override
public AuthInfo authenticateAssociation(IEC61850Server server,
ConnectedAP local_cap,
ConnectedAP remote_cap,
AuthInfo auth_info)
throws ModelServiceException
{
try
{
String auth_value = (String) auth_info.getAuthValue();
System.out.println("\n [ authenticate-assoc ]:" + auth_value);
// -- can perform authentication operation here, if authentication
// -- fails, just throw an ModelServiceException
// -- May return a response auth value as well.
// -- for now, lets just return null
// auth_info.setAuthValue(auth_value);
// return auth_info;
return null;
}
catch (Exception e)
{
throw new ModelServiceException("authentication failed");
}
}
});
Server Data Change Listener
SvLD default_ld = server.getDefaultLD();
//-- Set up a change listener to print out changes to the data model
default_ld.addChangeListener(new SvDataNode.ChangeListener()
{
public void dataChange(SvModelNode listener_node,
SvDataNode.ChangeEvent event)
{
System.out.println(" [da-change]: "
+ event.getDA().getObjectRef() + " :: "
+ event.getOldValue() + " ==> " + event.getNewValue()
+ "(" + event.getReasonCode() + ")");
}
});
Server Control Behavior
final SvXtAPC anout1_apc = (SvXtAPC) anout1.getXtCDC();
anout1_apc.setControlHandler(new SvXtSPC.ControlHandler()
{
public boolean performTest(ControllableSvXtCDC cdc,
ControllableSvXtCDC.ControlOperation op,
ControllableSvXtCDC.TEST_TYPE test_type)
throws SvControlException
{
System.out.println("performTest: "+cdc.getVDO().getLogicalRef()+op);
return false; // force default tests to be performed...
}
public boolean performOperate(ControllableSvXtCDC cdc,
ControllableSvXtCDC.ControlOperation op,
ControllableSvXtCDC.PendingOperate po,
boolean is_blocked) throws SvControlException
{
System.out.println("performOperate: " + cdc.getVDO().getLogicalRef() + op);
try
{
// perform the actual value update on the controllable CDC instance.
anout1_apc.setMxVal(new AnalogueValue(
operation.getRequest().getControlValue()));
}
catch (Exception ex)
{
throw new SvControlException(AddCause.UNKNOWN);
}
return true; // we handled the operate...
}
});
Custom GetDataValues Handler
//-- attach a GetDataValues listener to the instMag.i
//-- attribute so we can update it with current value on access.
SvDA inst_mag_i =
default_ld.getVDO("DynGGIO1.AnIn1").getDA("instMag.i");
inst_mag_i.setGetDataValueListener(new InstMagListener());
...
/**
* The InstMagListener is invoked just prior to a GetDataValues
* access on the 'instMag.i' DA. This allows us to update the DA
* value on demand.
*/
private class InstMagListener implements SvDA.GetDataValueListener
{
public void prepareValue(SvDA target, DataValue current_value)
{
// could update the value manually here prior to an
// incoming GetDataValues
try
{
// -- update the instMag value.
target.setValue(getInstMag());
}
catch (Exception e)
{
}
}
}
Custom SetDataValues Handler
//-- attach a SetDataValues listener to the 'smpRate'
//-- attribute so we can update it with current value on access.
SvDA smp_rate_da =
default_ld.getVDO("DynGGIO1.AnIn1").getDA("smpRate");
smp_rate_da.setSetDataValueListener(new SmpRateListener());
private class SmpRateListener implements SvDA.SetDataValueListener
{
//-- invoked to validate the value before setting
public void validateValue(SvDA target,
DataValue current_value,
DataValue new_value)
throws ACSIServiceErrorException
{
try
{
int new_smp_value = new_value.intValue();
//-- make sure the new smpRate is in range of 1 and 20
if ((new_smp_value < 1) || (new_smp_value > 20))
{
throw new ACSIServiceErrorException(
ACSIServiceError.PARAMETER_VALUE_INAPPROPRIATE,
"invalid type");
}
}
catch (ModelValueException e)
{
throw new ACSIServiceErrorException(
ACSIServiceError.TYPE_CONFLICT, "invalid type");
}
}
//-- invoked to commit the new value to the model
public boolean commitValue(SvDA target,
DataValue current_value,
DataValue new_value)
throws ACSIServiceErrorException
{
try
{
//-- update the model with the new value..
//-- change the DA value, perform any local updates
target.setValue(new_value);
return true; // we processed the value so return 'true'
}
catch (ModelValueException e)
{
throw new ACSIServiceErrorException(
ACSIServiceError.PARAMETER_VALUE_INAPPROPRIATE,
"commit value failed");
}
}
};
Platform Requirements
Java Platform Requirements:
The Core SmartGridware® Java IEC61850 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 Server 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)
