General dynamic model creation functions

Functions to dynamically create IEC 61850 data models without using SCL or configuration files. More...

Functions
LIB61850_API IedModel *	IedModel_create (const char *name)
	create a new IedModel instance More...
LIB61850_API void	IedModel_setIedNameForDynamicModel (IedModel *self, const char *name)
	Set the name of the IED (use only for dynamic model!) More...
LIB61850_API void	IedModel_destroy (IedModel *model)
	destroy a dynamically created data model More...
LIB61850_API LogicalDevice *	LogicalDevice_create (const char *name, IedModel *parent)
	Create a new logical device and add it to the IED model. More...
LIB61850_API LogicalDevice *	LogicalDevice_createEx (const char *inst, IedModel *parent, const char *ldName)
	Create a new logical device and add it to the IED model. More...
LIB61850_API LogicalNode *	LogicalNode_create (const char *name, LogicalDevice *parent)
	Create a new logical mode and add it to a logical device. More...
LIB61850_API DataObject *	DataObject_create (const char *name, ModelNode *parent, int arrayElements)
	create a new data object or array data object and add it to a parent model node More...
LIB61850_API DataAttribute *	DataAttribute_create (const char *name, ModelNode *parent, DataAttributeType type, FunctionalConstraint fc, uint8_t triggerOptions, int arrayElements, uint32_t sAddr)
	create a new data attribute and add it to a parent model node More...
LIB61850_API DataAttributeType	DataAttribute_getType (DataAttribute *self)
	Get the data type of the data attribute. More...
LIB61850_API FunctionalConstraint	DataAttribute_getFC (DataAttribute *self)
	Get the functional constraint (FC) of the data attribute. More...
LIB61850_API uint8_t	DataAttribute_getTrgOps (DataAttribute *self)
	Get the trigger options of the data attribute. More...
LIB61850_API void	DataAttribute_setValue (DataAttribute *self, MmsValue *value)
	Set the value of the data attribute (can be used to set default values before server is created) More...
LIB61850_API ReportControlBlock *	ReportControlBlock_create (const char *name, LogicalNode *parent, const char *rptId, bool isBuffered, const char *dataSetName, uint32_t confRef, uint8_t trgOps, uint8_t options, uint32_t bufTm, uint32_t intgPd)
	create a new report control block (RCB) More...
LIB61850_API void	ReportControlBlock_setPreconfiguredClient (ReportControlBlock *self, uint8_t clientType, const uint8_t *clientAddress)
	Set a pre-configured client for the RCB. More...
LIB61850_API const char *	ReportControlBlock_getName (ReportControlBlock *self)
	Get the name of the RCB instance. More...
LIB61850_API bool	ReportControlBlock_isBuffered (ReportControlBlock *self)
	Is the RCB buffered or unbuffered? More...
LIB61850_API LogicalNode *	ReportControlBlock_getParent (ReportControlBlock *self)
	Get the parent (LogicalNode) of the RCB instance. More...
LIB61850_API char *	ReportControlBlock_getRptID (ReportControlBlock *self)
	Get the name of the currently set report ID. More...
LIB61850_API bool	ReportControlBlock_getRptEna (ReportControlBlock *self)
	Check if RCB instance is enabled. More...
LIB61850_API char *	ReportControlBlock_getDataSet (ReportControlBlock *self)
	Get the name of the currenlty set data set. More...
LIB61850_API uint32_t	ReportControlBlock_getConfRev (ReportControlBlock *self)
	Get the confRev value. More...
LIB61850_API uint32_t	ReportControlBlock_getOptFlds (ReportControlBlock *self)
	Get the currently set OptFlds value. More...
LIB61850_API uint32_t	ReportControlBlock_getBufTm (ReportControlBlock *self)
	Get the BufTm value (buffer time) More...
LIB61850_API uint16_t	ReportControlBlock_getSqNum (ReportControlBlock *self)
LIB61850_API uint32_t	ReportControlBlock_getTrgOps (ReportControlBlock *self)
	Get the currently set trigger options. More...
LIB61850_API uint32_t	ReportControlBlock_getIntgPd (ReportControlBlock *self)
LIB61850_API bool	ReportControlBlock_getGI (ReportControlBlock *self)
LIB61850_API bool	ReportControlBlock_getPurgeBuf (ReportControlBlock *self)
LIB61850_API MmsValue *	ReportControlBlock_getEntryId (ReportControlBlock *self)
LIB61850_API uint64_t	ReportControlBlock_getTimeofEntry (ReportControlBlock *self)
LIB61850_API int16_t	ReportControlBlock_getResvTms (ReportControlBlock *self)
LIB61850_API bool	ReportControlBlock_getResv (ReportControlBlock *self)
LIB61850_API MmsValue *	ReportControlBlock_getOwner (ReportControlBlock *self)
LIB61850_API LogControlBlock *	LogControlBlock_create (const char *name, LogicalNode *parent, const char *dataSetName, const char *logRef, uint8_t trgOps, uint32_t intgPd, bool logEna, bool reasonCode)
	create a new log control block (LCB) More...
LIB61850_API const char *	LogControlBlock_getName (LogControlBlock *self)
LIB61850_API LogicalNode *	LogControlBlock_getParent (LogControlBlock *self)
LIB61850_API Log *	Log_create (const char *name, LogicalNode *parent)
	create a log (used by the IEC 61850 log service) More...
LIB61850_API SettingGroupControlBlock *	SettingGroupControlBlock_create (LogicalNode *parent, uint8_t actSG, uint8_t numOfSGs)
	create a setting group control block (SGCB) More...
LIB61850_API GSEControlBlock *	GSEControlBlock_create (const char *name, LogicalNode *parent, const char *appId, const char *dataSet, uint32_t confRev, bool fixedOffs, int minTime, int maxTime)
	create a new GSE/GOOSE control block (GoCB) More...
LIB61850_API SVControlBlock *	SVControlBlock_create (const char *name, LogicalNode *parent, const char *svID, const char *dataSet, uint32_t confRev, uint8_t smpMod, uint16_t smpRate, uint8_t optFlds, bool isUnicast)
	create a new Multicast/Unicast Sampled Value (SV) control block (SvCB) More...
LIB61850_API void	SVControlBlock_addPhyComAddress (SVControlBlock *self, PhyComAddress *phyComAddress)
LIB61850_API void	GSEControlBlock_addPhyComAddress (GSEControlBlock *self, PhyComAddress *phyComAddress)
LIB61850_API PhyComAddress *	PhyComAddress_create (uint8_t vlanPriority, uint16_t vlanId, uint16_t appId, uint8_t dstAddress[])
	create a PhyComAddress object More...
LIB61850_API DataSet *	DataSet_create (const char *name, LogicalNode *parent)
	create a new data set More...
LIB61850_API const char *	DataSet_getName (DataSet *self)
	Get the name of the data set. More...
LIB61850_API int	DataSet_getSize (DataSet *self)
	returns the number of elements (entries) of the data set More...
LIB61850_API DataSetEntry *	DataSet_getFirstEntry (DataSet *self)
LIB61850_API DataSetEntry *	DataSetEntry_getNext (DataSetEntry *self)
LIB61850_API DataSetEntry *	DataSetEntry_create (DataSet *dataSet, const char *variable, int index, const char *component)
	create a new data set entry (FCDA) More...

Detailed Description

Functions to dynamically create IEC 61850 data models without using SCL or configuration files.

Function Documentation

DataAttribute_create()

LIB61850_API DataAttribute* DataAttribute_create	(	const char *	name,
		ModelNode *	parent,
		DataAttributeType	type,
		FunctionalConstraint	fc,
		uint8_t	triggerOptions,
		int	arrayElements,
		uint32_t	sAddr
	)

create a new data attribute and add it to a parent model node

The parent model node has to be of type DataObject or DataAttribute

Parameters

name	the name of the data attribute (e.g. "stVal")
parent	the parent model node
type	the type of the data attribute (CONSTRUCTED if the type contains sub data attributes)
fc	the functional constraint (FC) of the data attribute
triggerOptions	the trigger options (dupd, dchg, qchg) that cause an event notification
arrayElements	the number of array elements if the data attribute is an array or 0
sAddr	an optional short address

Returns

the newly create DataAttribute instance

DataAttribute_getFC()

LIB61850_API FunctionalConstraint DataAttribute_getFC

(

DataAttribute *

self

)

Get the functional constraint (FC) of the data attribute.

Parameters

self	the data attribute instance

Returns

the functional constraint (FC) of the data attribute

DataAttribute_getTrgOps()

LIB61850_API uint8_t DataAttribute_getTrgOps

(

DataAttribute *

self

)

Get the trigger options of the data attribute.

Parameters

self	the data attribute instance

Returns

the trigger options (dupd, dchg, qchg) that cause an event notification

DataAttribute_getType()

LIB61850_API DataAttributeType DataAttribute_getType

(

DataAttribute *

self

)

Get the data type of the data attribute.

Parameters

self	the data attribute instance

Returns

the data attribute type

DataAttribute_setValue()

LIB61850_API void DataAttribute_setValue	(	DataAttribute *	self,
		MmsValue *	value
	)

Set the value of the data attribute (can be used to set default values before server is created)

Parameters

self	the data attribute instance
value	the new default value

DataObject_create()

LIB61850_API DataObject* DataObject_create	(	const char *	name,
		ModelNode *	parent,
		int	arrayElements
	)

create a new data object or array data object and add it to a parent model node

The parent model node has to be of type DataObject or LogicalNode.

NOTE: When the data object is an array the array elements will also be created by this function. This will result in child DataObject instances for each array element.

Parameters

name	the name of the data object (e.h. "Mod", "Health" ...)
parent	the parent model node
arrayElements	the number of array elements if the data object is an array or 0

Returns

the newly create DataObject instance

DataSet_create()

LIB61850_API DataSet* DataSet_create	(	const char *	name,
		LogicalNode *	parent
	)

create a new data set

Parameters

name	the name of the data set
parent	the logical node that hosts the data set (typically a LLN0)

Returns

the new data set instance

DataSet_getFirstEntry()

LIB61850_API DataSetEntry* DataSet_getFirstEntry

(

DataSet *

self

)

DataSet_getName()

LIB61850_API const char* DataSet_getName

(

DataSet *

self

)

Get the name of the data set.

Parameters

self	the instance of the data set

Returns

the name of the data set (not the object reference).

DataSet_getSize()

LIB61850_API int DataSet_getSize

(

DataSet *

self

)

returns the number of elements (entries) of the data set

Parameters

self	the instance of the data set

Returns

the number of data set elements

DataSetEntry_create()

LIB61850_API DataSetEntry* DataSetEntry_create	(	DataSet *	dataSet,
		const char *	variable,
		int	index,
		const char *	component
	)

create a new data set entry (FCDA)

Create a new FCDA reference and add it to the given data set as a new data set member.

Note: Be aware that data set entries are not IEC 61850 object reference but MMS variable names that have to contain the LN name, the FC and subsequent path elements separated by "$" instead of ".". This is due to efficiency reasons to avoid the creation of additional strings.

If the variable parameter does not contain a logical device name (separated from the remaining variable name by the "/" character) the logical device where the data set resides is used automatically.

Parameters

dataSet	the data set to which the new entry will be added
variable	the name of the variable as MMS variable name including FC ("$" used as separator!)
index	the index if the FCDA is an array element, otherwise -1
component	the name of the component of the variable if the FCDA is a sub element of an array element. If this is not the case then NULL should be given here.

Returns

the new data set entry instance

DataSetEntry_getNext()

LIB61850_API DataSetEntry* DataSetEntry_getNext

(

DataSetEntry *

self

)

GSEControlBlock_addPhyComAddress()

LIB61850_API void GSEControlBlock_addPhyComAddress	(	GSEControlBlock *	self,
		PhyComAddress *	phyComAddress
	)

GSEControlBlock_create()

LIB61850_API GSEControlBlock* GSEControlBlock_create	(	const char *	name,
		LogicalNode *	parent,
		const char *	appId,
		const char *	dataSet,
		uint32_t	confRev,
		bool	fixedOffs,
		int	minTime,
		int	maxTime
	)

create a new GSE/GOOSE control block (GoCB)

Create a new GOOSE control block (GoCB) and add it to the given logical node (LN)

Parameters

name	name of the GoCB relative to the parent LN
parent	the parent LN
appId	the application ID of the GoCB
dataSet	the data set reference to be used by the GoCB
confRev	the configuration revision
fixedOffs	indicates if GOOSE publisher shall use fixed offsets (NOT YET SUPPORTED)
minTime	minimum GOOSE retransmission time (-1 if not specified - uses stack default then)
maxTime	GOOSE retransmission time in stable state (-1 if not specified - uses stack default then)

Returns

the new GoCB instance

IedModel_create()

LIB61850_API IedModel* IedModel_create

(

const char *

name

)

create a new IedModel instance

The IedModel object is the root node of an IEC 61850 data model.

Parameters

name	the name of the IedModel

Returns

the new data model instance

IedModel_destroy()

LIB61850_API void IedModel_destroy

(

IedModel *

model

)

destroy a dynamically created data model

This function will free all the memory allocated for the data model.

NOTE: Do not use this function when using a static data model (static_model.c create by static model generator).

Parameters

model

the model instance to destroy

IedModel_setIedNameForDynamicModel()

LIB61850_API void IedModel_setIedNameForDynamicModel	(	IedModel *	self,
		const char *	name
	)

Set the name of the IED (use only for dynamic model!)

This will change the default name (usually "TEMPLATE") to a user configured values. NOTE: This function has to be called before IedServer_create ! NOTE: For dynamic model (and configuration file date model) this function has to be used instead of IedModel_setIedName.

Parameters

model	the IedModel instance
the	name of the configured IED

Log_create()

LIB61850_API Log* Log_create	(	const char *	name,
		LogicalNode *	parent
	)

create a log (used by the IEC 61850 log service)

Parameters

name	name of the LOG relative to the parent LN
parent	the parent LN

Returns

the new LOG instance

LogControlBlock_create()

LIB61850_API LogControlBlock* LogControlBlock_create	(	const char *	name,
		LogicalNode *	parent,
		const char *	dataSetName,
		const char *	logRef,
		uint8_t	trgOps,
		uint32_t	intgPd,
		bool	logEna,
		bool	reasonCode
	)

create a new log control block (LCB)

Create a new log control block (LCB) and add it to the given logical node (LN).

Parameters

name	name of the LCB relative to the parent LN
parent	the parent LN.
dataSetName	name (object reference) of the default data set or NULL if no data set is set by default
logRef	name (object reference) of the default log or NULL if no log is set by default. THe LDname doesn't contain the IED name!
trgOps	the trigger options supported by this LCB (bit set)
intgPd	integrity period in milliseconds
logEna	if true the log will be enabled by default, false otherwise
reasonCode	if true the reasonCode will be included in the log (this is always true in MMS mapping)

Returns

the new LCB instance

LogControlBlock_getName()

LIB61850_API const char* LogControlBlock_getName

(

LogControlBlock *

self

)

LogControlBlock_getParent()

LIB61850_API LogicalNode* LogControlBlock_getParent

(

LogControlBlock *

self

)

LogicalDevice_create()

LIB61850_API LogicalDevice* LogicalDevice_create	(	const char *	name,
		IedModel *	parent
	)

Create a new logical device and add it to the IED model.

Parameters

name	the name of the new logical device
parent	the parent IED model

Returns

the newly created LogicalDevice instance

LogicalDevice_createEx()

LIB61850_API LogicalDevice* LogicalDevice_createEx	(	const char *	inst,
		IedModel *	parent,
		const char *	ldName
	)

Create a new logical device and add it to the IED model.

Parameters

name	the name of the new logical device
parent	the parent IED model
ldName	when not NULL functional naming is used for this LD (ldName <= 64 chars)

Returns

the newly created LogicalDevice instance

LogicalNode_create()

LIB61850_API LogicalNode* LogicalNode_create	(	const char *	name,
		LogicalDevice *	parent
	)

Create a new logical mode and add it to a logical device.

Parameters

name	the name of the new logical node
parent	the parent logical device

Returns

the newly created LogicalNode instance

PhyComAddress_create()

LIB61850_API PhyComAddress* PhyComAddress_create	(	uint8_t	vlanPriority,
		uint16_t	vlanId,
		uint16_t	appId,
		uint8_t	dstAddress[]
	)

create a PhyComAddress object

A PhyComAddress object contains all required addressing information for a GOOSE publisher.

Parameters

vlanPriority	the priority field of the VLAN tag
vlanId	the ID field of the VLAN tag
appId	the application identifier
dstAddress	the 6 byte multicast MAC address to specify the destination

Returns

the new PhyComAddress object

ReportControlBlock_create()

LIB61850_API ReportControlBlock* ReportControlBlock_create	(	const char *	name,
		LogicalNode *	parent,
		const char *	rptId,
		bool	isBuffered,
		const char *	dataSetName,
		uint32_t	confRef,
		uint8_t	trgOps,
		uint8_t	options,
		uint32_t	bufTm,
		uint32_t	intgPd
	)

create a new report control block (RCB)

Create a new report control block (RCB) and add it to the given logical node (LN).

Parameters

name	name of the RCB relative to the parent LN
parent	the parent LN.
rptId	of the report. If NULL the default report ID (object reference) is used.
isBuffered	true for a buffered RCB - false for unbuffered RCB
dataSetName	name (object reference) of the default data set or NULL if no data set is set by default
confRef	the configuration revision
trgOps	the trigger options supported by this RCB (bit set)
options	the inclusion options. Specifies what elements are included in a report (bit set)
bufTm	the buffering time of the RCB in milliseconds (time between the first event and the preparation of the report).
intgPd	integrity period in milliseconds

Returns

the new RCB instance.

ReportControlBlock_getBufTm()

LIB61850_API uint32_t ReportControlBlock_getBufTm

(

ReportControlBlock *

self

)

Get the BufTm value (buffer time)

The buffer time is the maximum value between an event and the actual report generation.

Parameters

self	the RCB instance

Returns

bufTm value

ReportControlBlock_getConfRev()

LIB61850_API uint32_t ReportControlBlock_getConfRev

(

ReportControlBlock *

self

)

Get the confRev value.

Parameters

self	the RCB instance

Returns

confRev value

ReportControlBlock_getDataSet()

LIB61850_API char* ReportControlBlock_getDataSet

(

ReportControlBlock *

self

)

Get the name of the currenlty set data set.

Parameters

self	the RCB instance

Returns

a null terminated string containing the current data set name (the string has to be released by the caller!)

ReportControlBlock_getEntryId()

LIB61850_API MmsValue* ReportControlBlock_getEntryId

(

ReportControlBlock *

self

)

ReportControlBlock_getGI()

LIB61850_API bool ReportControlBlock_getGI

(

ReportControlBlock *

self

)

ReportControlBlock_getIntgPd()

LIB61850_API uint32_t ReportControlBlock_getIntgPd

(

ReportControlBlock *

self

)

ReportControlBlock_getName()

LIB61850_API const char* ReportControlBlock_getName

(

ReportControlBlock *

self

)

Get the name of the RCB instance.

NOTE: the returned string is only valid during the lifetime of the ReportControlBlock instance!

Parameters

self	the RCB instance

Returns

the RCB instance name

ReportControlBlock_getOptFlds()

LIB61850_API uint32_t ReportControlBlock_getOptFlds

(

ReportControlBlock *

self

)

Get the currently set OptFlds value.

The OptField (option field) value is a bit field with the following fields:

• RPT_OPT_SEQ_NUM
• RPT_OPT_TIME_STAMP
• RPT_OPT_REASON_FOR_INCLUSION
• RPT_OPT_DATA_SET
• RPT_OPT_DATA_REFERENCE
• RPT_OPT_BUFFER_OVERFLOW
• RPT_OPT_ENTRY_ID
• RPT_OPT_CONF_REV

Parameters

self	the RCB instance

Returns

OptFlds options value

ReportControlBlock_getOwner()

LIB61850_API MmsValue* ReportControlBlock_getOwner

(

ReportControlBlock *

self

)

ReportControlBlock_getParent()

LIB61850_API LogicalNode* ReportControlBlock_getParent

(

ReportControlBlock *

self

)

Get the parent (LogicalNode) of the RCB instance.

Parameters

self	the RCB instance

Returns

the parent (LogicalNode) of the RCB instance

ReportControlBlock_getPurgeBuf()

LIB61850_API bool ReportControlBlock_getPurgeBuf

(

ReportControlBlock *

self

)

ReportControlBlock_getResv()

LIB61850_API bool ReportControlBlock_getResv

(

ReportControlBlock *

self

)

ReportControlBlock_getResvTms()

LIB61850_API int16_t ReportControlBlock_getResvTms

(

ReportControlBlock *

self

)

ReportControlBlock_getRptEna()

LIB61850_API bool ReportControlBlock_getRptEna

(

ReportControlBlock *

self

)

Check if RCB instance is enabled.

Parameters

self	the RCB instance

Returns

true when the RCB instance is enabled, false otherwise

ReportControlBlock_getRptID()

LIB61850_API char* ReportControlBlock_getRptID

(

ReportControlBlock *

self

)

Get the name of the currently set report ID.

Parameters

self	the RCB instance

Returns

a null terminated string containing the current data set name (the string has to be released by the caller!)

ReportControlBlock_getSqNum()

LIB61850_API uint16_t ReportControlBlock_getSqNum

(

ReportControlBlock *

self

)

ReportControlBlock_getTimeofEntry()

LIB61850_API uint64_t ReportControlBlock_getTimeofEntry

(

ReportControlBlock *

self

)

ReportControlBlock_getTrgOps()

LIB61850_API uint32_t ReportControlBlock_getTrgOps

(

ReportControlBlock *

self

)

Get the currently set trigger options.

The trigger option value is a bit field with the following fields:

• TRG_OPT_DATA_CHANGED
• TRG_OPT_QUALITY_CHANGED
• TRG_OPT_DATA_UPDATE
• TRG_OPT_INTEGRITY
• TRG_OPT_GI

Parameters

self	the RCB instance

Returns

trigger options value

ReportControlBlock_isBuffered()

LIB61850_API bool ReportControlBlock_isBuffered

(

ReportControlBlock *

self

)

Is the RCB buffered or unbuffered?

Parameters

self	the RCB instance

Returns

true, in case of a buffered RCB, false otherwise

ReportControlBlock_setPreconfiguredClient()

LIB61850_API void ReportControlBlock_setPreconfiguredClient	(	ReportControlBlock *	self,
		uint8_t	clientType,
		const uint8_t *	clientAddress
	)

Set a pre-configured client for the RCB.

If set only the pre configured client should use this RCB instance

Parameters

self	the RCB instance
clientType	the type of the client (0 = no client, 4 = IPv4 client, 6 = IPv6 client)
clientAddress	buffer containing the client address (4 byte in case of an IPv4 address, 16 byte in case of an IPv6 address, NULL for no client)

SettingGroupControlBlock_create()

LIB61850_API SettingGroupControlBlock* SettingGroupControlBlock_create	(	LogicalNode *	parent,
		uint8_t	actSG,
		uint8_t	numOfSGs
	)

create a setting group control block (SGCB)

Create a new setting group control block (SGCB) and add it to the given logical node (LN).

Parameters

parent	the parent LN.
the	active setting group on server startup (1..N)
the	number of setting groups (N)

Returns

the new SGCB instance

SVControlBlock_addPhyComAddress()

LIB61850_API void SVControlBlock_addPhyComAddress	(	SVControlBlock *	self,
		PhyComAddress *	phyComAddress
	)

SVControlBlock_create()

LIB61850_API SVControlBlock* SVControlBlock_create	(	const char *	name,
		LogicalNode *	parent,
		const char *	svID,
		const char *	dataSet,
		uint32_t	confRev,
		uint8_t	smpMod,
		uint16_t	smpRate,
		uint8_t	optFlds,
		bool	isUnicast
	)

create a new Multicast/Unicast Sampled Value (SV) control block (SvCB)

Create a new Sampled Value control block (SvCB) and add it to the given logical node (LN)

Parameters

name	name of the SvCB relative to the parent LN
parent	the parent LN
svID	the application ID of the SvCB
dataSet	the data set reference to be used by the SVCB
confRev	the configuration revision
smpMod	the sampling mode used
smpRate	the sampling rate used
optFlds	the optional element configuration

Returns

the new SvCB instance