Pricing/Info    Download   
MENU 
 Home Products About Support Contact

SmartGridware® 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

MacOSX/Linux GOOSE/SV Requirements

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)