The sampled values (SV) subscriber API consists of three different objects. The SVReceiver object is responsible for handling all SV Ethernet messages for a specific Ethernet interface. If you want to receive SV messages on multiple Ethernet interfaces you have to use several SVReceiver instances. An SVSubscriber object is associated to a SV data stream that is identified by its appID and destination Ethernet address. The \reg SVSubscriber object is used to install a callback handler SVUpdateListener that is invoked for each ASDU (application service data unit) received for the associated stream. An SVSubscriber_ASDU is an object that represents a single ASDU. Each ASDU contains some meta information that can be obtained by specific access functions like e.g. SVSubscriber_ASDU_getSmpCnt to access the "SmpCnt" (sample count) attribute of the ASDU. The actual measurement data contained in the ASDU does not consist of structured ASN.1 data but stored as raw binary data. Without a priori knowledge of the dataset associated with the ASDU data stream it is not possible to interpret the received data correctly. Therefore you have to provide the data access functions with an index value to indicate the data type and the start of the data in the data block of the ASDU. E.g. reading a data set consisting of two FLOAT32 values you can use two subsequent calls of SVSubscriber_ASDU_getFLOAT32 one with index = 0 and the second one with index = 4.
| IEC 61850 type | required bytes |
| BOOLEAN | 1 byte |
| INT8 | 1 byte |
| INT16 | 2 byte |
| INT32 | 4 byte |
| INT64 | 8 byte |
| INT8U | 1 byte |
| INT16U | 2 byte |
| INT24U | 3 byte |
| INT32U | 4 byte |
| INT64U | 8 byte |
| FLOAT32 | 4 byte |
| FLOAT64 | 8 byte |
| ENUMERATED | 4 byte |
| CODED ENUM | 4 byte |
| OCTET STRING | 20 byte |
| VISIBLE STRING | 35 byte |
| TimeStamp | 8 byte |
| EntryTime | 6 byte |
| BITSTRING | 4 byte |
| Quality | 4 byte |
The SV subscriber API can be used independent of the IEC 61850 client API. In order to access the SVCB via MMS you have to use the IEC 61850 client API. Please see ClientSVControlBlock object in section Client side SV control block handling functions.
◆ SVReceiver
opaque handle to a SV receiver instance
◆ SVSubscriber
opaque handle to a SV subscriber instance
A subscriber is an instance associated with a single stream of measurement data. It is identified by the Ethernet destination address, the appID value (both are on SV message level) and the svID value that is part of each ASDU (SVSubscriber_ASDU object).
◆ SVSubscriber_ASDU
opaque handle to a SV ASDU (Application service data unit) instance.
Sampled Values (SV) ASDUs (application service data units) are the basic units for sampled value data. Each ASDU represents a single sample consisting of multiple measurement values with a single dedicated timestamp.
NOTE: SVSubscriber_ASDU are statically allocated and are only valid inside of the SVUpdateListener function when called by the library. If you need the data contained in the ASDU elsewhere you have to copy and store the data by yourself!
◆ SVUpdateListener
Callback function for received SV messages.
Will be called for each ASDU contained in a SV message!
- Parameters
-
| subscriber | the subscriber that was associated with the received SV message |
| parameter | a user provided parameter that is simply passed to the callback |
| asdu | SV ASDU data structure. This structure is only valid inside of the callback function |
◆ SVReceiver_addSubscriber()
Add a subscriber instance to the receiver.
The given subscriber will be connected to the receiver instance.
- Parameters
-
| self | the receiver instance reference |
| subscriber | the subscriber instance to connect |
◆ SVReceiver_create()
| LIB61850_API SVReceiver SVReceiver_create |
( |
void |
| ) |
|
Create a new SV receiver instance.
A receiver is responsible for processing all SV message for a single Ethernet interface. In order to process messages from multiple Ethernet interfaces you have to create multiple instances.
- Returns
- the newly created receiver instance
◆ SVReceiver_destroy()
| LIB61850_API void SVReceiver_destroy |
( |
SVReceiver |
self | ) |
|
Destroy receiver instance (cleanup resources)
- Parameters
-
| self | the receiver instance reference |
◆ SVReceiver_disableDestAddrCheck()
| LIB61850_API void SVReceiver_disableDestAddrCheck |
( |
SVReceiver |
self | ) |
|
Disable check for destination address of the received SV messages.
- Parameters
-
| self | the receiver instance reference |
◆ SVReceiver_enableDestAddrCheck()
| LIB61850_API void SVReceiver_enableDestAddrCheck |
( |
SVReceiver |
self | ) |
|
Enable check for destination address of the received SV messages.
Per default only the appID is checked to identify relevant SV messages and the destination address is ignored for performance reasons. This only works when the appIDs are unique in the local system. Otherwise the destination address check has to be enabled.
- Parameters
-
| self | the receiver instance reference |
◆ SVReceiver_isRunning()
| LIB61850_API bool SVReceiver_isRunning |
( |
SVReceiver |
self | ) |
|
Check if SV receiver is running.
Can be used to check if SVReceiver_start has been successful.
- Parameters
-
| self | the receiver instance reference |
- Returns
- true if SV receiver is running, false otherwise
◆ SVReceiver_removeSubscriber()
Disconnect subscriber and receiver.
- Parameters
-
| self | the receiver instance reference |
| subscriber | the subscriber instance to disconnect |
◆ SVReceiver_setInterfaceId()
| LIB61850_API void SVReceiver_setInterfaceId |
( |
SVReceiver |
self, |
|
|
const char * |
interfaceId |
|
) |
| |
Set the Ethernet interface ID for the receiver instance.
Use this function if you want to use a different interface than the default interface set by CONFIG_ETHERNET_INTERFACE_ID (stack_config.h) NOTE: This function has to be called before calling SVReceiver_start.
- Parameters
-
| self | the receiver instance reference |
| interfaceId | the Ethernet interface id (platform specific e.g. eth0 for linux). |
◆ SVReceiver_start()
| LIB61850_API void SVReceiver_start |
( |
SVReceiver |
self | ) |
|
Receiver starts listening for SV messages.
NOTE: This call will start a new background thread.
- Parameters
-
| self | the receiver instance reference |
◆ SVReceiver_startThreadless()
| LIB61850_API EthernetSocket SVReceiver_startThreadless |
( |
SVReceiver |
self | ) |
|
◆ SVReceiver_stop()
| LIB61850_API void SVReceiver_stop |
( |
SVReceiver |
self | ) |
|
Receiver stops listening for SV messages.
- Parameters
-
| self | the receiver instance reference |
◆ SVReceiver_stopThreadless()
| LIB61850_API void SVReceiver_stopThreadless |
( |
SVReceiver |
self | ) |
|
◆ SVReceiver_tick()
| LIB61850_API bool SVReceiver_tick |
( |
SVReceiver |
self | ) |
|
Parse SV messages if they are available.
Call after reception of ethernet frame and periodically to to house keeping tasks
- Parameters
-
- Returns
- true if a message was available and has been parsed, false otherwise
◆ SVSubscriber_create()
| LIB61850_API SVSubscriber SVSubscriber_create |
( |
const uint8_t * |
ethAddr, |
|
|
uint16_t |
appID |
|
) |
| |
◆ SVSubscriber_destroy()
◆ SVSubscriber_setListener()
Set a callback handler to process received SV messages.
If the received SV message contains multiple ASDUs (application service data units) the callback function will be called for each ASDU separately. If a callback function has already been installed for this SVSubscriber object the old callback will be replaced.
- Parameters
-
| self | The subscriber object |
| listener | the callback function to install |
| a | user provided parameter that is provided to the callback function |
1.9.1