Defines a device descriptor object pool. More...

#include <isobus_device_descriptor_object_pool.hpp>

Public Member Functions
	DeviceDescriptorObjectPool ()=default
	Default constructor for a DDOP. Sets TC compatibility to version 4.

	DeviceDescriptorObjectPool (std::uint8_t taskControllerServerVersion)
	This constructor allows customization of the TC compatibility level.

bool	add_device (std::string deviceDesignator, std::string deviceSoftwareVersion, std::string deviceSerialNumber, std::string deviceStructureLabel, std::array< std::uint8_t, task_controller_object::DeviceObject::MAX_STRUCTURE_AND_LOCALIZATION_LABEL_LENGTH > deviceLocalizationLabel, std::vector< std::uint8_t > deviceExtendedStructureLabel, std::uint64_t clientIsoNAME)
	Adds a device object to the DDOP.

bool	add_device_element (std::string deviceElementDesignator, std::uint16_t deviceElementNumber, std::uint16_t parentObjectID, task_controller_object::DeviceElementObject::Type deviceElementType, std::uint16_t uniqueID)
	Adds a device element object to the DDOP.

bool	add_device_process_data (std::string processDataDesignator, std::uint16_t processDataDDI, std::uint16_t deviceValuePresentationObjectID, std::uint8_t processDataProperties, std::uint8_t processDataTriggerMethods, std::uint16_t uniqueID)
	Adds a device process data object to the DDOP.

bool	add_device_property (std::string propertyDesignator, std::int32_t propertyValue, std::uint16_t propertyDDI, std::uint16_t valuePresentationObject, std::uint16_t uniqueID)
	Adds a device property object to the DDOP.

bool	add_device_value_presentation (std::string unitDesignator, std::int32_t offsetValue, float scaleFactor, std::uint8_t numberDecimals, std::uint16_t uniqueID)
	Adds a device value presentation object to the DDOP.

bool	deserialize_binary_object_pool (std::vector< std::uint8_t > &binaryPool, NAME clientNAME=NAME(0))
	Attempts to take a binary object pool and convert it back into C++ objects. Useful for a task controller server or to view the content of a DDOP captured in a CAN log, for example.

bool	deserialize_binary_object_pool (const std::uint8_t *binaryPool, std::uint32_t binaryPoolSizeBytes, NAME clientNAME=NAME(0))
	Attempts to take a binary object pool and convert it back into C++ objects. Useful for a task controller server or to view the content of a DDOP captured in a CAN log, for example.

bool	generate_binary_object_pool (std::vector< std::uint8_t > &resultantPool)

bool	generate_task_data_iso_xml (std::string &resultantString)

std::shared_ptr< task_controller_object::Object >	get_object_by_id (std::uint16_t objectID)
	Gets an object from the DDOP that corresponds to a certain object ID.

std::shared_ptr< task_controller_object::Object >	get_object_by_index (std::uint16_t index)
	Gets an object from the DDOP by index based on object creation.

bool	remove_object_by_id (std::uint16_t objectID)
	Removes an object from the DDOP using its object ID.

void	set_task_controller_compatibility_level (std::uint8_t tcVersion)
	Sets the TC version to use when generating a binary DDOP.

std::uint8_t	get_task_controller_compatibility_level () const
	Returns the current TC version used when generating a binary DDOP.

void	clear ()
	Clears the DDOP back to an empty state.

std::uint16_t	size () const
	Returns the number of objects in the DDOP.

Static Public Member Functions
static std::uint8_t	get_max_supported_task_controller_version ()
	Returns The maximum TC version supported by the CAN stack's DDOP generator.

Private Member Functions
bool	resolve_parent_ids_to_objects ()
	Checks to see that all parent object IDs correspond to an object in this DDOP.

bool	check_object_id_unique (std::uint16_t uniqueID) const
	Checks the DDOP to see if an object ID has already been used.

Private Attributes
std::vector< std::shared_ptr< task_controller_object::Object > >	objectList
	Maintains a list of all added objects.

std::uint8_t	taskControllerCompatibilityLevel = MAX_TC_VERSION_SUPPORTED
	Stores the max TC version.

Static Private Attributes
static constexpr std::uint8_t	MAX_TC_VERSION_SUPPORTED = 4
	The max TC version a DDOP object can support as of today.

Detailed Description

Defines a device descriptor object pool.

This class can be used to build up a task controller DDOP by adding objects to it in a hierarchy, then calling generate_binary_object_pool to get the object pool in binary form.

Note: To ensure maximum compatibility with task controllers, it may be best to stick to limits that were defined for TC 3 and older when providing things like labels for device element designators.

Definition at line 27 of file isobus_device_descriptor_object_pool.hpp.

Constructor & Destructor Documentation

◆ DeviceDescriptorObjectPool()

isobus::DeviceDescriptorObjectPool::DeviceDescriptorObjectPool ( std::uint8_t taskControllerServerVersion )

explicit

This constructor allows customization of the TC compatibility level.

Parameters

[in] taskControllerServerVersion The version of TC server to support with this DDOP

Definition at line 24 of file isobus_device_descriptor_object_pool.cpp.

Member Function Documentation

◆ add_device()

bool isobus::DeviceDescriptorObjectPool::add_device	(	std::string	deviceDesignator,
		std::string	deviceSoftwareVersion,
		std::string	deviceSerialNumber,
		std::string	deviceStructureLabel,
		std::array< std::uint8_t, task_controller_object::DeviceObject::MAX_STRUCTURE_AND_LOCALIZATION_LABEL_LENGTH >	deviceLocalizationLabel,
		std::vector< std::uint8_t >	deviceExtendedStructureLabel,
		std::uint64_t	clientIsoNAME )

Adds a device object to the DDOP.

Note: There can only be one of these per DDOP

Attention: Pay close attention to which values are UTF-8 and which are byte arrays

Parameters

[in]	deviceDesignator	Descriptive text for the object, UTF-8, 32 chars max
[in]	deviceSoftwareVersion	Software version indicating text
[in]	deviceSerialNumber	Device and manufacturer-specific serial number of the Device (UTF-8)
[in]	deviceStructureLabel	This label allows the device to identify the current version of the device descriptor object pool
[in]	deviceLocalizationLabel	Defined by the language command PGN
[in]	deviceExtendedStructureLabel	Continuation of the Label given by Device to identify the Device descriptor Structure
[in]	clientIsoNAME	NAME of client device as defined in ISO 11783-5

Returns: true if the object was added to the DDOP, false if the object cannot be added (duplicate or some other error)

Definition at line 30 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

◆ add_device_element()

bool isobus::DeviceDescriptorObjectPool::add_device_element	(	std::string	deviceElementDesignator,
		std::uint16_t	deviceElementNumber,
		std::uint16_t	parentObjectID,
		task_controller_object::DeviceElementObject::Type	deviceElementType,
		std::uint16_t	uniqueID )

Adds a device element object to the DDOP.

Parameters

[in]	deviceElementDesignator	Descriptive text for the object, UTF-8, 32-128 chars max depending on TC version
[in]	deviceElementNumber	The Element number for process data variable addressing
[in]	parentObjectID	Object ID of parent DeviceElementObject or DeviceObject in order to establish a hierarchical order of DeviceElements
[in]	deviceElementType	The type of element, such as "device" or "bin"
[in]	uniqueID	The object ID of the object. Must be unique in the DDOP.

Returns: true if the object was added to the DDOP, false if the object cannot be added (duplicate or some other error)

Definition at line 136 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ add_device_process_data()

bool isobus::DeviceDescriptorObjectPool::add_device_process_data	(	std::string	processDataDesignator,
		std::uint16_t	processDataDDI,
		std::uint16_t	deviceValuePresentationObjectID,
		std::uint8_t	processDataProperties,
		std::uint8_t	processDataTriggerMethods,
		std::uint16_t	uniqueID )

Adds a device process data object to the DDOP.

Parameters

[in]	processDataDesignator	Descriptive text for the object, UTF-8, 32-128 chars max
[in]	processDataDDI	Identifier of process data variable (DDI) according to definitions in Annex B and ISO 11783 - 11
[in]	deviceValuePresentationObjectID	Object identifier of a DeviceValuePresentationObject, or the null ID
[in]	processDataProperties	A bitset of properties associated to this object. Some combination of `PropertiesBit`
[in]	processDataTriggerMethods	A bitset of available trigger methods, built from some combination of `AvailableTriggerMethods`
[in]	uniqueID	The object ID of the object. Must be unique in the DDOP.

Returns: true if the object was added to the DDOP, false if the object cannot be added (duplicate or some other error)

Definition at line 180 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ add_device_property()

bool isobus::DeviceDescriptorObjectPool::add_device_property	(	std::string	propertyDesignator,
		std::int32_t	propertyValue,
		std::uint16_t	propertyDDI,
		std::uint16_t	valuePresentationObject,
		std::uint16_t	uniqueID )

Adds a device property object to the DDOP.

Parameters

[in]	propertyDesignator	Descriptive text for the object, UTF-8, 32-128 chars max
[in]	propertyValue	The value of the property
[in]	propertyDDI	Identifier of property (DDI) according to definitions in Annex B and ISO 11783 - 11.
[in]	valuePresentationObject	Object identifier of DeviceValuePresentationObject, or NULL object ID
[in]	uniqueID	The object ID of the object. Must be unique in the DDOP.

Returns: true if the object was added to the DDOP, false if the object cannot be added (duplicate or some other error)

Definition at line 242 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ add_device_value_presentation()

bool isobus::DeviceDescriptorObjectPool::add_device_value_presentation	(	std::string	unitDesignator,
		std::int32_t	offsetValue,
		float	scaleFactor,
		std::uint8_t	numberDecimals,
		std::uint16_t	uniqueID )

Adds a device value presentation object to the DDOP.

Parameters

[in]	unitDesignator	Unit designator for this value presentation
[in]	offsetValue	Offset to be applied to the value for presentation.
[in]	scaleFactor	Scale to be applied to the value for presentation.
[in]	numberDecimals	Specifies the number of decimals to display after the decimal point.
[in]	uniqueID	The object ID of the object. Must be unique in the DDOP.

Returns: true if the object was added to the DDOP, false if the object cannot be added (duplicate or some other error)

Definition at line 295 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ check_object_id_unique()

bool isobus::DeviceDescriptorObjectPool::check_object_id_unique ( std::uint16_t uniqueID ) const

private

Checks the DDOP to see if an object ID has already been used.

Parameters

[in] uniqueID The ID to check against in the DDOP for uniqueness

Returns: true if the object ID parameter is unique in the DDOP, otherwise false

Definition at line 1214 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

◆ clear()

void isobus::DeviceDescriptorObjectPool::clear ( )

Clears the DDOP back to an empty state.

Definition at line 1051 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

◆ deserialize_binary_object_pool() [1/2]

bool isobus::DeviceDescriptorObjectPool::deserialize_binary_object_pool	(	const std::uint8_t *	binaryPool,
		std::uint32_t	binaryPoolSizeBytes,
		NAME	clientNAME = NAME(0) )

Attempts to take a binary object pool and convert it back into C++ objects. Useful for a task controller server or to view the content of a DDOP captured in a CAN log, for example.

Parameters

binaryPool	The binary object pool, as an array of bytes.
binaryPoolSizeBytes	The size of the DDOP to process in bytes.
clientNAME	The ISO NAME of the source ECU for this DDOP, or NAME(0) to ignore checking against actual ECU NAME

Returns: True if the object pool was successfully deserialized, otherwise false. NOTE: This only means that the pool was deserialized. It does not mean that the relationship between objects is valid. You may have to do additional checking on the pool before using it.

Definition at line 353 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

◆ deserialize_binary_object_pool() [2/2]

bool isobus::DeviceDescriptorObjectPool::deserialize_binary_object_pool	(	std::vector< std::uint8_t > &	binaryPool,
		NAME	clientNAME = NAME(0) )

Attempts to take a binary object pool and convert it back into C++ objects. Useful for a task controller server or to view the content of a DDOP captured in a CAN log, for example.

Parameters

binaryPool	The binary object pool, as an array of bytes.
clientNAME	The ISO NAME of the source ECU for this DDOP, or NAME(0) to ignore checking against actual ECU NAME

Returns: True if the object pool was successfully deserialized, otherwise false. NOTE: This only means that the pool was deserialized. It does not mean that the relationship between objects is valid. You may have to do additional checking on the pool before using it.

Definition at line 348 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generate_binary_object_pool()

bool isobus::DeviceDescriptorObjectPool::generate_binary_object_pool ( std::vector< std::uint8_t > & resultantPool )

Constructs a binary DDOP using the objects that were previously added

Parameters

[in,out] resultantPool The binary representation of the DDOP, or an empty vector if this function returns false

Returns: true if the object pool was generated and is valid, otherwise false.

Definition at line 769 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

◆ generate_task_data_iso_xml()

bool isobus::DeviceDescriptorObjectPool::generate_task_data_iso_xml ( std::string & resultantString )

Constructs a ISOXML formatted TASKDATA.xml file inside a string using the objects that were previously added.

Parameters

[in,out] resultantString The XML representation of the DDOP, or an empty string if this function returns false

Returns: true if the object pool was generated and is valid, otherwise false.

Definition at line 807 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

◆ get_max_supported_task_controller_version()

std::uint8_t isobus::DeviceDescriptorObjectPool::get_max_supported_task_controller_version ( )

static

Returns The maximum TC version supported by the CAN stack's DDOP generator.

Returns: The maximum TC version supported by the CAN stack's DDOP generator

Definition at line 1046 of file isobus_device_descriptor_object_pool.cpp.

◆ get_object_by_id()

std::shared_ptr< task_controller_object::Object > isobus::DeviceDescriptorObjectPool::get_object_by_id ( std::uint16_t objectID )

Gets an object from the DDOP that corresponds to a certain object ID.

Parameters

[in] objectID The ID of the object to get

Returns: Pointer to the object matching the provided ID, or nullptr if no match was found

Definition at line 985 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

◆ get_object_by_index()

std::shared_ptr< task_controller_object::Object > isobus::DeviceDescriptorObjectPool::get_object_by_index ( std::uint16_t index )

Gets an object from the DDOP by index based on object creation.

Parameters

[in] index The index of the object to get

Returns: Pointer to the object matching the index, or nullptr if no match was found

Definition at line 1000 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

◆ get_task_controller_compatibility_level()

std::uint8_t isobus::DeviceDescriptorObjectPool::get_task_controller_compatibility_level ( ) const

Returns the current TC version used when generating a binary DDOP.

Returns: the current TC version used when generating a binary DDOP.

Definition at line 1041 of file isobus_device_descriptor_object_pool.cpp.

◆ remove_object_by_id()

bool isobus::DeviceDescriptorObjectPool::remove_object_by_id ( std::uint16_t objectID )

Removes an object from the DDOP using its object ID.

Note: This will not fix orphaned parent/child relationships. Also, if two or more objects were created with the same ID, only one match will be removed. You should consider the case where 2 objects have the same ID undefined behavior.

Parameters

[in] objectID The ID of the object to remove

Returns: true if the object with the specified ID was removed, otherwise false

Definition at line 1011 of file isobus_device_descriptor_object_pool.cpp.

◆ resolve_parent_ids_to_objects()

bool isobus::DeviceDescriptorObjectPool::resolve_parent_ids_to_objects ( )

private

Checks to see that all parent object IDs correspond to an object in this DDOP.

Returns: true if all object IDs were validated, otherwise false

Definition at line 1061 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_task_controller_compatibility_level()

void isobus::DeviceDescriptorObjectPool::set_task_controller_compatibility_level ( std::uint8_t tcVersion )

Sets the TC version to use when generating a binary DDOP.

Note: If you do not call this, TC version 4 is used by default

Parameters

[in] tcVersion The version of TC you are targeting for this DDOP

Definition at line 1027 of file isobus_device_descriptor_object_pool.cpp.

Here is the call graph for this function:

◆ size()

std::uint16_t isobus::DeviceDescriptorObjectPool::size ( ) const

Returns the number of objects in the DDOP.

Note: The number of objects in the DDOP is limited to 65535.

Returns: The number of objects in the DDOP

Definition at line 1056 of file isobus_device_descriptor_object_pool.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ MAX_TC_VERSION_SUPPORTED

constexpr std::uint8_t isobus::DeviceDescriptorObjectPool::MAX_TC_VERSION_SUPPORTED = 4

staticconstexprprivate

The max TC version a DDOP object can support as of today.

Definition at line 192 of file isobus_device_descriptor_object_pool.hpp.

◆ objectList

std::vector<std::shared_ptr<task_controller_object::Object> > isobus::DeviceDescriptorObjectPool::objectList

private

Maintains a list of all added objects.

Definition at line 194 of file isobus_device_descriptor_object_pool.hpp.

◆ taskControllerCompatibilityLevel

std::uint8_t isobus::DeviceDescriptorObjectPool::taskControllerCompatibilityLevel = MAX_TC_VERSION_SUPPORTED

private

Stores the max TC version.

Definition at line 195 of file isobus_device_descriptor_object_pool.hpp.

The documentation for this class was generated from the following files:

isobus/include/isobus/isobus/isobus_device_descriptor_object_pool.hpp
isobus/src/isobus_device_descriptor_object_pool.cpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DeviceDescriptorObjectPool()

Member Function Documentation

◆ add_device()

◆ add_device_element()

◆ add_device_process_data()

◆ add_device_property()

◆ add_device_value_presentation()

◆ check_object_id_unique()

◆ clear()

◆ deserialize_binary_object_pool() [1/2]

◆ deserialize_binary_object_pool() [2/2]

◆ generate_binary_object_pool()

◆ generate_task_data_iso_xml()

◆ get_max_supported_task_controller_version()

◆ get_object_by_id()

◆ get_object_by_index()

◆ get_task_controller_compatibility_level()

◆ remove_object_by_id()

◆ resolve_parent_ids_to_objects()

◆ set_task_controller_compatibility_level()

◆ size()

Member Data Documentation

◆ MAX_TC_VERSION_SUPPORTED

◆ objectList

◆ taskControllerCompatibilityLevel