Mapper Engine. More...

#include <attribute_mapper_engine.hpp>

Public Member Functions
void	reset ()
	Reset the mapper engine and clear all releations. More...

bool	load_path (const std::string &uam_path)
	Load engine with all uam file in a given directory. More...

bool	load_file (std::string uam_file_name)
	Load engine with single uam file. More...

bool	add_expression (const std::string expression)
	Add uam expression to the ast. More...

bool	update_dependencies (const ast::ast_tree &ast)
	Re-calculate dependencies of a the ast,. More...

bool	has_unknown_functions_in_tree (const ast::ast_tree &ast)
	Checks the AST for built-in function names and return true if one or more functions are unknown. More...

void	set_common_parent_type (attribute_store_type_t t)
	Set the Common Attribute type which should be used as start context for all attribute evaluations. More...

void	on_attribute_updated (attribute_store_node_t node, attribute_store_node_value_state_t state, attribute_store_change_t change)
	Called when an attribute is updated. More...

Static Public Member Functions
static MapperEngine &	get_instance ()
	Get the singletron. More...

Private Member Functions
attribute_store::attribute	get_destination_for_attribute (const attribute_store::attribute &endpoint, const ast::attribute &attribute, bool create_if_missing) const
	Get the destination for attribute. More...

equivalent_assignments_t	get_equivalent_assignments (std::shared_ptr< ast::assignment > assignment)
	Checks if the engine has other assigments assigning the same attribute type / value type. More...

attribute_store::attribute	get_assigment_potential_destination (std::shared_ptr< ast::assignment > assignment, attribute_store::attribute original_node)
	Checks what would be the destination attribute affected by an assigment, if applied. More...

bool	assignment_matches_destination (std::shared_ptr< ast::assignment > assignment, attribute_store::attribute destination)
	Checks if an assignment (lhs) path matches the attribute for a destination. More...

void	run_assignments (equivalent_assignments_t assignments_to_check, attribute_store::attribute assigment_destination, attribute_store::attribute original_node)
	Takes a list of assignments with a possible destination, and run. More...

bool	run_assignment (std::shared_ptr< ast::assignment > assignment, attribute_store::attribute assigment_destination, attribute_store::attribute original_node)
	Runs a single assigment and verifies if a value was applied. More...

bool	apply_regular_assignment (attribute_store::attribute common_parent, attribute_store::attribute destination, attribute_store::attribute original_node, const ast::scope_settings_t &settings, result_type_t evaluated_value, std::shared_ptr< ast::assignment > assignment) const
	Applies a regular assigment. More...

bool	apply_instance_assignment (attribute_store::attribute common_parent, float evaluated_value, std::shared_ptr< ast::assignment > assignment, bool chain_reaction)
	Applies an instance assigment, which will verify if an attribute path with a certain value exists. More...

bool	apply_clearance_assignment (attribute_store::attribute common_parent, float evaluated_value, std::shared_ptr< ast::assignment > assignment)
	Applies a clearance assigment, which may undefine values. More...

Private Attributes
std::multimap< ast::attribute_dependency_t, std::shared_ptr< ast::assignment > >	relations

std::map< std::shared_ptr< ast::assignment >, std::shared_ptr< ast::scope_settings_t > >	assignment_settings

std::map< std::shared_ptr< ast::assignment >, assignment_properties_t >	assignment_properties

attribute_store_type_t	common_parent_type = ATTRIBUTE_STORE_INVALID_NODE

Detailed Description

Mapper Engine.

The purpose of the mapping engine define relations between attributes in the attribute store, in general the relation between the Z-Wave attribute and the Zigbee attributes. The actions performed by the mapping engine is quite similar to the actions performed by a compiler. A compiler parses a text document and builds an Abstract Syntax Tree(AST). The AST is then optimized and the AST nodes are translated into machine op codes. In the attribute mapper we are not translating AST nodes to opcodes but instead we are keeping the AST in memory.

The mapping engine only interacts with the attribute store. An example of a simple mapping is the relation between the zigbee attribute OnOf.value and the Z-Wave attribute binary_switch.value, if desired of OnOf.value is update the binary_switch.value should be update. The the same applies to the reported value in the reverse direction. So in a meta description we could describe this behaviour with the following:

r'OnOff_Value = r'BinarySwitch_Value d'BinarySwitch_Value = d'OnOff_Value

This means when the reported value of BinarySwitch_Value changes we would like to update the repported value of OnOff_Value. Actually we will also create the OnOff_Value if it does not exists (this will only happen with reported values). For the desired value we update BinarySwitch_Value if OnOff_Value changes.

For simplicity the attribute mapper evaluates every thing as int32. This mean that All attributes the mapper deals with must be int32.

The AST of the rule set is stored in memory because when an attribute changes, we should locate dependencies using the AST. The value of each AST node can be calculated in the context of an attribute node. Let's look at the example where an attribute is updated and the node type of that attribute is a leaf nodes in the AST. Then we need to try to re-calculate the value of all AST nodes that depends on the updated node. The update may lead to a write of another attribute. In the example above an update leads to an update of the OnOff value. There could be cases where some node in the AST cannot be evaluated in a given context, for example if one attribute depends on two other attributes but only one of them is defined. Then the AST will not be fully evaluated in the given context (the node does not support all the required command classes). In this case the update will not lead to an attribute write.

In some cases there could be multiple ways to calculate a mapping. Let's take a fictive example of some ZigBee LED color command class. On the Zigbee side colors are defined as RGBW on the Z-Wave side the color may be in RGBW or may be in just RGB.

A mapping could look like this

zbColorW = zwColor[W] or ((zwColor[R] + zwColor[G] + zwColor[B])*1000 ) / 3333

Here we would persue the relation using zwColor[W] first, if that is not possible we would fall back to ((zwColor[R] + zwColor[G] + zwColor[B])*1000) /3333

The mapping engine uses a number of C++ classes to perform its tasks.

The ast::UAMGrammar class defnies how we translate a text document into our ast using the boost spirit framework.
The ast::dep_evel class is used to build a graph of relations between attributes.
The ast::eval class is used to evaluate expressions when a change in a attribute value occurs

Member Function Documentation

◆ add_expression()

bool MapperEngine::add_expression ( const std::string expression )

Add uam expression to the ast.

Parameters

expression Expression given as string

Returns: true If load succeed; false Some error occurred in parsing of AST validation

◆ apply_clearance_assignment()

bool MapperEngine::apply_clearance_assignment	(	attribute_store::attribute	common_parent,
		float	evaluated_value,
		std::shared_ptr< ast::assignment >	assignment
	)

private

Applies a clearance assigment, which may undefine values.

Parameters

common_parent	Common parent Attribute for the assignment
evaluated_value	Evaluated value from the right-hand side of the assignment
assignment	Pointer to the assignment

Returns: true if a value was applied to the left-hand side; false otherwise

◆ apply_instance_assignment()

bool MapperEngine::apply_instance_assignment	(	attribute_store::attribute	common_parent,
		float	evaluated_value,
		std::shared_ptr< ast::assignment >	assignment,
		bool	chain_reaction
	)

private

Applies an instance assigment, which will verify if an attribute path with a certain value exists.

Parameters

common_parent	Common parent Attribute for the assignment
evaluated_value	Evaluated value from the right-hand side of the assignment
assignment	Pointer to the assignment
chain_reaction	Chain reaction setting from the scope

Returns: true if a value was applied to the left-hand side; false otherwise

◆ apply_regular_assignment()

bool MapperEngine::apply_regular_assignment	(	attribute_store::attribute	common_parent,
		attribute_store::attribute	destination,
		attribute_store::attribute	original_node,
		const ast::scope_settings_t &	settings,
		result_type_t	evaluated_value,
		std::shared_ptr< ast::assignment >	assignment
	)		const

private

Applies a regular assigment.

Parameters

common_parent	Common parent Attribute for the assignment
destination	Destination Attribute for the assignment
original_node	Original node that triggered the assignment evaluation
settings	Score settings associated with the assignment
evaluated_value	Evaluated value from the right-hand side of the assignment
assignment	Pointer to the assignment

Returns: true if a value was applied to the left-hand side; false otherwise

◆ assignment_matches_destination()

bool MapperEngine::assignment_matches_destination	(	std::shared_ptr< ast::assignment >	assignment,
		attribute_store::attribute	destination
	)

private

Checks if an assignment (lhs) path matches the attribute for a destination.

Parameters

assignment	Assignemnt to check if the lhs path matches the destination attribute
destination	Destination attribute to match with the assignment LHS.

Returns: true If it matches; false if it does not match

◆ get_assigment_potential_destination()

attribute_store::attribute MapperEngine::get_assigment_potential_destination	(	std::shared_ptr< ast::assignment >	assignment,
		attribute_store::attribute	original_node
	)

private

Checks what would be the destination attribute affected by an assigment, if applied.

Returns INVALID_NODE if the destination

Parameters

assignment	The assignment to look for a destination
original_node	Original attribute that was updated

Returns: Attribute Store node

◆ get_destination_for_attribute()

attribute_store::attribute MapperEngine::get_destination_for_attribute	(	const attribute_store::attribute &	endpoint,
		const ast::attribute &	attribute,
		bool	create_if_missing
	)		const

private

Get the destination for attribute.

Try to resolve the attribute node from the AST attribute path.

Parameters

endpoint	endpoint to start from
attribute	Attribute (path) to resolve
create_if_missing	If true the destination attribute is created if it does not exists

Returns: destination attribute, if no destination is found we return INVALID_ATTRIBUTE

◆ get_equivalent_assignments()

equivalent_assignments_t MapperEngine::get_equivalent_assignments ( std::shared_ptr< ast::assignment > assignment )

private

Checks if the engine has other assigments assigning the same attribute type / value type.

Try to resolve the attribute node from the AST attribute path.

Parameters

assignment The assignment to take for a start. comparing with all others

Returns: A map of assignments assigning the same value tyep and attribute type, sorted by priority.

◆ get_instance()

static MapperEngine & MapperEngine::get_instance ( )

static

Get the singletron.

Returns: The singletron

◆ has_unknown_functions_in_tree()

bool MapperEngine::has_unknown_functions_in_tree ( const ast::ast_tree & ast )

Checks the AST for built-in function names and return true if one or more functions are unknown.

Parameters

ast	AST loaded from the UAM files.

Returns: true if there are some unknown functions in the AST, false otherwise

◆ load_file()

bool MapperEngine::load_file ( std::string uam_file_name )

Load engine with single uam file.

Parameters

uam_file_name

Returns: true; false

◆ load_path()

bool MapperEngine::load_path ( const std::string & uam_path )

Load engine with all uam file in a given directory.

Parameters

uam_path

Returns: true If load succeed; false Some error occurred in parsing of AST validation

◆ on_attribute_updated()

void MapperEngine::on_attribute_updated	(	attribute_store_node_t	node,
		attribute_store_node_value_state_t	state,
		attribute_store_change_t	change
	)

Called when an attribute is updated.

This function will do a look up the updated attribute in the relation table and evaluate the expressios which depends on the attribute.

Parameters

node	Node that has been updated
state	What updated desired or reported
change	Type of update, create, delete, value change

◆ reset()

void MapperEngine::reset ( )

Reset the mapper engine and clear all releations.

◆ run_assignment()

bool MapperEngine::run_assignment	(	std::shared_ptr< ast::assignment >	assignment,
		attribute_store::attribute	assigment_destination,
		attribute_store::attribute	original_node
	)

private

Runs a single assigment and verifies if a value was applied.

Parameters

assignment	Pointer to the assignment
assigment_destination	Destination attribute for the assignment
original_node	Original node that triggered the assignment evaluation

Returns: true if a value was applied to the left-hand side; false otherwise

◆ run_assignments()

void MapperEngine::run_assignments	(	equivalent_assignments_t	assignments_to_check,
		attribute_store::attribute	assigment_destination,
		attribute_store::attribute	original_node
	)

private

Takes a list of assignments with a possible destination, and run.

the highest priority assigment if the destination exists
All of them from low to high priority if the destination does not exist

Parameters

assignments_to_check	List of assigment to execute
assigment_destination	Destination attribute
original_node	Original attribute that triggered these assignments

◆ set_common_parent_type()

void MapperEngine::set_common_parent_type ( attribute_store_type_t t )

Set the Common Attribute type which should be used as start context for all attribute evaluations.

Parameters

t	Type to use as start context

◆ update_dependencies()

bool MapperEngine::update_dependencies ( const ast::ast_tree & ast )

Re-calculate dependencies of a the ast,.

this should be called if the AST is updated.

Returns: true If load succeed; false Some error occurred in parsing of AST validation

Member Data Documentation

◆ assignment_properties

std::map<std::shared_ptr<ast::assignment>, assignment_properties_t> MapperEngine::assignment_properties

private

◆ assignment_settings

std::map<std::shared_ptr<ast::assignment>, std::shared_ptr<ast::scope_settings_t> > MapperEngine::assignment_settings

private

◆ common_parent_type

attribute_store_type_t MapperEngine::common_parent_type = ATTRIBUTE_STORE_INVALID_NODE

private

◆ relations

std::multimap<ast::attribute_dependency_t, std::shared_ptr<ast::assignment> > MapperEngine::relations

private

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

components/uic_attribute_mapper/src/attribute_mapper_engine.hpp

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ add_expression()

◆ apply_clearance_assignment()

◆ apply_instance_assignment()

◆ apply_regular_assignment()

◆ assignment_matches_destination()

◆ get_assigment_potential_destination()

◆ get_destination_for_attribute()

◆ get_equivalent_assignments()

◆ get_instance()

◆ has_unknown_functions_in_tree()

◆ load_file()

◆ load_path()

◆ on_attribute_updated()

◆ reset()

◆ run_assignment()

◆ run_assignments()

◆ set_common_parent_type()

◆ update_dependencies()

Member Data Documentation

◆ assignment_properties

◆ assignment_settings

◆ common_parent_type

◆ relations