diff --git a/src/doxygen.config b/src/doxygen.config index 917788cd..b8d9b434 100644 --- a/src/doxygen.config +++ b/src/doxygen.config @@ -220,8 +220,8 @@ INPUT += "iec61850/inc/iec61850_cdc.h" INPUT += "goose/goose_subscriber.h" INPUT += "goose/goose_receiver.h" INPUT += "sampled_values/sv_subscriber.h" -INPUT += "sampled_values/sv_receiver.h" -INPUT += "sampled_values/sv_subscriber.h" +INPUT += "sampled_values/sv_publisher.h" +INPUT += "sampled_values/sv_publisher_deprecated.h" INPUT += "mms/inc/mms_device_model.h" INPUT += "mms/inc/mms_types.h" INPUT += "mms/inc/mms_common.h" diff --git a/src/sampled_values/sv_publisher.h b/src/sampled_values/sv_publisher.h index 8123eec8..fcf1b2c0 100644 --- a/src/sampled_values/sv_publisher.h +++ b/src/sampled_values/sv_publisher.h @@ -43,6 +43,11 @@ typedef struct sCommParameters { #endif +/** + * \defgroup sv_publisher_api_group IEC 61850 Sampled Values (SV) publisher API + */ +/**@{*/ + #define IEC61850_SV_SMPSYNC_NOT_SYNCHRONIZED 0 #define IEC61850_SV_SMPSYNC_SYNCED_UNSPEC_LOCAL_CLOCK 1 #define IEC61850_SV_SMPSYNC_SYNCED_GLOBAL_CLOCK 2 @@ -51,89 +56,230 @@ typedef struct sCommParameters { #define IEC61850_SV_SMPMOD_SAMPLES_PER_SECOND 1 #define IEC61850_SV_SMPMOD_SECONDS_PER_SAMPLE 2 +/** + * \brief An opaque type representing an IEC 61850-9-2 Sampled Values publisher. + */ typedef struct sSVPublisher* SVPublisher; +/** + * \brief An opaque type representing an IEC 61850-9-2 Sampled Values Application Service Data Unit (ASDU). + */ typedef struct sSV_ASDU* SV_ASDU; +/** + * \brief Create a new IEC61850-9-2 Sampled Values publisher. + * + * \param[in] interfaceId the name of the interface over which the SV publisher should send SV packets. + * \param[in] parameters optional parameters for setting VLAN options and destination MAC address. Use NULL for default values. + * \return the new SV publisher instance. + */ SVPublisher SVPublisher_create(CommParameters* parameters, const char* interfaceId); +/** + * \brief Create an Application Service Data Unit (ASDU) and add it to an existing Sampled Values publisher. + * + * \param[in] svID + * \param[in] datset + * \param[in] confRev Configuration revision number. Should be incremented each time that the configuration of the logical device changes. + * \return the new ASDU instance. + */ SV_ASDU SVPublisher_addASDU(SVPublisher self, char* svID, char* datset, uint32_t confRev); +/** + * \brief Prepare the publisher for publishing. + * + * This method must be called before SVPublisher_publish(). + * + * \param[in] self the Sampled Values publisher instance. + */ void SVPublisher_setupComplete(SVPublisher self); +/** + * \brief Publish all registered ASDUs + * + * \param[in] self the Sampled Values publisher instance. + */ void SVPublisher_publish(SVPublisher self); +/** + * \brief Destroy an IEC61850-9-2 Sampled Values instance. + * + * \param[in] self the Sampled Values publisher instance. + */ void SVPublisher_destroy(SVPublisher self); +/** + * \addtogroup sv_publisher_asdu_group Values Application Service Data Unit (ASDU) + * @{ + */ + +/** + * \brief Reset the internal data buffer of an ASDU. + * + * All data elements added by SV_ASDU_add*() functions are removed. + * SVPublisher_setupComplete() must be called afterwards. + * + * \param[in] self the Sampled Values ASDU instance. + */ void SV_ASDU_resetBuffer(SV_ASDU self); +/** + * \brief Reserve memory for a signed 8-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \return the offset in bytes within the ASDU data block. + */ int SV_ASDU_addINT8(SV_ASDU self); +/** + * \brief Set the value of a 8-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] index The offset within the data block of the ASDU in bytes. + * \param[in] value The value which should be set. + */ void SV_ASDU_setINT8(SV_ASDU self, int index, int8_t value); +/** + * \brief Reserve memory for a signed 32-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \return the offset in bytes within the ASDU data block. + */ int SV_ASDU_addINT32(SV_ASDU self); +/** + * \brief Set the value of a 32-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] index The offset within the data block of the ASDU in bytes. + * \param[in] value The value which should be set. + */ void SV_ASDU_setINT32(SV_ASDU self, int index, int32_t value); +/** + * \brief Reserve memory for a signed 64-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \return the offset in bytes of the new element within the ASDU data block. + */ int SV_ASDU_addINT64(SV_ASDU self); +/** + * \brief Set the value of a 64-bit integer in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] index The offset within the data block of the ASDU in bytes. + * \param[in] value The value which should be set. + */ void SV_ASDU_setINT64(SV_ASDU self, int index, int64_t value); +/** + * \brief Reserve memory for a single precission floating point number in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \return the offset in bytes of the new element within the ASDU data block. + */ int SV_ASDU_addFLOAT(SV_ASDU self); +/** + * \brief Set the value of a single precission floating point number in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] index The offset within the data block of the ASDU in bytes. + * \param[in] value The value which should be set. + */ void SV_ASDU_setFLOAT(SV_ASDU self, int index, float value); +/** + * \brief Reserve memory for a double precission floating point number in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \return the offset in bytes of the new element within the ASDU data block. + */ int SV_ASDU_addFLOAT64(SV_ASDU self); +/** + * \brief Set the value of a double precission floating pointer number in the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] index The offset within the data block of the ASDU in bytes. + * \param[in] value The value which should be set. + */ void SV_ASDU_setFLOAT64(SV_ASDU self, int index, double value); +/** + * \brief Set the sample count attribute of the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + * \param[in] value the new value of the attribute. + */ void SV_ASDU_setSmpCnt(SV_ASDU self, uint16_t value); +/** + * \brief Get the sample count attribute of the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + */ uint16_t SV_ASDU_getSmpCnt(SV_ASDU self); +/** + * \brief Increment the sample count attribute of the ASDU. + * + * The parameter SmpCnt shall contain the values of a counter, which is incremented each time a new sample of the analogue value is taken. + * The sample values shall be kept in the right order. + * If the counter is used to indicate time consistency of various sampled values, the counter shall be reset by an external synchronization event. + * + * \param[in] self the Sampled Values ASDU instance. + */ void SV_ASDU_increaseSmpCnt(SV_ASDU self); +/** + * \brief Set the refresh time attribute of the ASDU. + * + * \param[in] self the Sampled Values ASDU instance. + */ void SV_ASDU_setRefrTm(SV_ASDU self, uint64_t refrTm); /** - * \brief Set the sample mode of the ASDU - * - * If not set the transmitted ASDU will not contain an sampleMod value + * \brief Set the sample mode attribute of the ASDU. * - * \param self the SV_ASDU + * The attribute SmpMod shall specify if the sample rate is defined in units of samples per nominal period, samples per second or seconds per sample. + * If it is missing, the default value is samples per period. * + * \param[in] self the Sampled Values ASDU instance. * \param smpMod one of IEC61850_SV_SMPMOD_PER_NOMINAL_PERIOD, IEC61850_SV_SMPMOD_SAMPLES_PER_SECOND or IEC61850_SV_SMPMOD_SECONDS_PER_SAMPLE */ void SV_ASDU_setSmpMod(SV_ASDU self, uint8_t smpMod); /** - * \brief Set the sample rate of the ASDU. + * \brief Set the sample rate attribute of the ASDU. * - * If not set the transmitted ASDU will not contain an smpRate value. - * - * \param self the SV_ASDU + * The attribute SmpRate shall specify the sample rate. + * The value shall be interpreted depending on the value of the SmpMod attribute. * + * \param[in] self the Sampled Values ASDU instance. * \param smpRate Amount of samples (default per nominal period, see SmpMod). */ void @@ -143,6 +289,8 @@ SV_ASDU_setSmpRate(SV_ASDU self, uint16_t smpRate); } #endif +/**@} @}*/ + #include "sv_publisher_deprecated.h" #endif /* LIBIEC61850_SRC_SAMPLED_VALUES_SV_PUBLISHER_H_ */ diff --git a/src/sampled_values/sv_publisher_deprecated.h b/src/sampled_values/sv_publisher_deprecated.h index 5ce6cd5a..d463fb68 100644 --- a/src/sampled_values/sv_publisher_deprecated.h +++ b/src/sampled_values/sv_publisher_deprecated.h @@ -37,7 +37,18 @@ extern "C" { #define DEPRECATED #endif -typedef struct sSVPublisher* SampledValuesPublisher DEPRECATED; +/** + * \addtogroup sv_publisher_deprecated_api_group Deprecated API + * \ingroup sv_publisher_api_group IEC 61850 Sampled Values (SV) publisher API + * \deprecated + * @{ + */ + +/** + * \brief An opaque type representing an IEC 61850-9-2 Sampled Values publisher. + * \deprecated + */ +typedef DEPRECATED struct sSVPublisher* SampledValuesPublisher; /** * \brief This function is deprecated and will be removed in the next major release. Use SVPublisher_create() instead. @@ -94,6 +105,10 @@ SampledValuesPublisher_destroy(SampledValuesPublisher self) SVPublisher_destroy(self); } +/** + * @} + */ + #ifdef __cplusplus } #endif diff --git a/src/sampled_values/sv_subscriber.h b/src/sampled_values/sv_subscriber.h index 16ae7443..adb8e76c 100644 --- a/src/sampled_values/sv_subscriber.h +++ b/src/sampled_values/sv_subscriber.h @@ -31,7 +31,7 @@ extern "C" { #endif /** - * \defgroup sv_subscriber_api_group IEC 61850 sampled values (SV) subscriber API + * \defgroup sv_subscriber_api_group IEC 61850 Sampled Values (SV) subscriber API * * The sampled values (SV) subscriber API consists of three different objects. * The \ref SVReceiver object is responsible for handling all SV Ethernet messages @@ -242,6 +242,11 @@ SVSubscriber_destroy(SVSubscriber self); * SVClientASDU object methods **************************************************************************/ +/** + * \addtogroup sv_subscriber_asdu_group Values Application Service Data Unit (ASDU) + * @{ + */ + /** * \brief return the SmpCnt value included in the SV ASDU * @@ -409,7 +414,7 @@ SVClientASDU_getFLOAT64(SVClientASDU self, int index); int SVClientASDU_getDataSize(SVClientASDU self); -/**@}*/ +/**@} @}*/ #ifdef __cplusplus }