A building block of the Motorcortex components. More...

#include <ct_module.h>

Inheritance diagram for mcx::container::Module:

[legend]

Public Types
enum	ModuleStates { NOT_INITIALIZED = 0, PHASE_0 = 1, PHASE0 = 2, PHASE0_1 = 3, PHASE1 = 4, PHASE1_2 = 5, PHASE2 = 6, PHASE2_OP = 7, OP = 8, OP_PHASE2 = 9, PHASE2_NOT_INIT = 10 }

enum	ModuleErrors { NO_ERROR = 0, NO_CALLBACK_DEFINED = 1, CALLBACK_FAILED = 2, WRONG_STATE = 3 }

enum	ModuleEvents { EMPTY = -1, STOP = 0, START = 1, PAUSE = 2, ACK = 0xFF }

Public Member Functions
	Module ()
	Default constructor.

virtual	~Module ()=default
	Default destructor.

	Module (const Module &orig)=delete
	Copy constructors are deleted.

Module &	operator= (const Module &)=delete
	Copy constructors are deleted.

void	create (const char name, parameter_server::Parameter parameter_server, uint64_t dt_micro_s=0)
	Executes 'Create' phase of initialization. More...

void	create (const char name, parameter_server::Parameter parameter_server, uint64_t dt_micro_s, parameter_server::UserGroup owner_group, uint32_t permissions=parameter_server::default_permissions)
	Extended interface with access permissions. More...

bool	initPhase1 ()
	Executes initialization of the parameter tree phase. More...

bool	initPhase2 ()
	Initialization, which require parameter tree to be complete and loaded. More...

bool	startOp ()
	Final initialization before entering Operation mode. More...

bool	stopOp ()
	Stops Operation mode, switches back to PHASE2. More...

bool	iterate (const TaskTime &task_time, UserTime *user_time)
	Iterates an execution cycle of the module. More...

void	setName (const char *name)
	Sets the name of the module. More...

const char *	getName () const
	Returns the name of the module. More...

void	setDtMicroSec (uint64_t micro_sec)
	Sets a cycle time of module and its submodules in microseconds. More...

uint64_t	getDtMicroSec () const
	Returns a cycle time as an integer in microseconds. More...

void	setDtSec (double sec)
	Sets a cycle time of module and its submodules in seconds. More...

double	getDtSec () const

ModuleStates	getState () const
	Returns an actual state. More...

void	setEvent (ModuleEvents event)
	Command an event. More...

ModuleErrors	getError () const
	Returns active error code. More...

Protected Member Functions
virtual void	create_ (const char name, parameter_server::Parameter parameter_server, uint64_t dt_micro_s)=0
	User-defined callback, which is executed during 'Create' phase. More...

virtual bool	initPhase1_ ()=0
	User-defined callback to register parameters in the tree. More...

virtual bool	initPhase2_ ()=0
	User-defined callback after the parameter tree is ready. More...

virtual bool	startOp_ ()=0
	User-defined callback before entering Operation mode. More...

virtual bool	stopOp_ ()=0
	User-defined callback before to stop Operation mode. More...

virtual bool	iteratePreOp_ (const TaskTime &system_time, UserTime *user_time)
	User-defined callback which is called during Phase 2. More...

virtual bool	iterateOp_ (const TaskTime &system_time, UserTime *user_time)=0
	User-defined callback which is called during Operation mode. More...

void	createSubmodule (Module module, const char name)
	Creates and registers submodule. More...

template<typename T >
void	createSubmodules (utils::span< T > module_array, const char *basename)
	Creates and registers an array of submodules. More...

void	setType (const char *name)
	Sets a type of the module. More...

template<size_t buffer_size = parameter_server::DEFAULT_INPUT_BUFFER_LENGTH>
parameter_server::ParamHandle	addParameter (const char id, parameter_server::ParameterType param_type, char str_ptr, size_t length)
	Helper function to register C-string member variable in the parameter tree. More...

template<typename T , size_t buffer_size = parameter_server::DEFAULT_INPUT_BUFFER_LENGTH, add_visitable::EnableIfNotVisitable< T > = true>
parameter_server::ParamHandle	addParameter (const char id, parameter_server::ParameterType param_type, T value_ptr, size_t length=1, parameter_server::Unit param_unit=parameter_server::Unit::undefined)
	Helper function to register member variable of in the parameter tree. More...

template<typename T , size_t buffer_size = parameter_server::DEFAULT_INPUT_BUFFER_LENGTH, add_visitable::EnableIfVisitable< T > = true>
parameter_server::GroupHandle	addParameter (const char id, parameter_server::ParameterType param_type, T value_ptr, size_t length=1, parameter_server::Unit param_unit=parameter_server::Unit::undefined)
	Helper function to register visitable PODs in the parameter tree. More...

template<typename T , size_t buffer_size = parameter_server::DEFAULT_INPUT_BUFFER_LENGTH>
parameter_server::ParamHandle	addParameter (const char id, parameter_server::ParameterType param_type, parameter_server::DataType data_type, T value_ptr, size_t length=1, parameter_server::Unit param_unit=parameter_server::Unit::undefined)
	Helper function to register types, which cannot be deduced. More...

parameter_server::SubHandle	subscribe (const char *path)
	Helper function to subscribe for the parameter's update. More...

parameter_server::ReqHandle	request (const char *path)
	Helper function to request a parameter's value. More...

parameter_server::PubHandle	publish (const char *path)
	Helper function to update parameter's value. More...

parameter_server::Parameter *	getParameterRoot ()
	Returns the root of the parameter tree. More...

parameter_server::Parameter *	getLocalBranch ()
	Returns the root of the local branch. More...

Friends
class	Task

Detailed Description

A building block of the Motorcortex components.

State machine of the Motorcortex module

 Module:                                        Task:
 ┌──────────────────────────────┐
 │   Not Initialized            │
 └───┬──────────────────────────┘               ┌─────────────────────────────────────┐
     │ (Event: create)                          │ Creates modules and submodules.     │
 ┌───v───────┐                                  └───┬─────────────────────────────────┘
 │   Phase0  │                                      │ (Event: configure)
 └───┬───────┘                                  ┌───v─────────────────────────────────┐
     │ (Event: initPhase1)                      │ Add parameters to the tree          │
     │                                          │                                     │
 ┌───v───────┐                                  └───┬─────────────────────────────────┘
 │   Phase1  │                                      │ (Event: start)
 └───┬───────┘                                  ┌───v─────────────────────────────────┐
     │ (Event: initPhase2)                      │ Parameter tree is ready,            │
     │                                          │                                     │
 ┌───v──────────────────────────┐               └───┬─────────────────────────────────┘
 │   Phase2                     │                   │
 └───┬──────────────────────^───┘               ┌───v─────────────────────────────────┐
     │ (Event: startOp)     │ (Event: stopOp)   │  Real-time event loop is            │
     │                      │                   │  ready to start.                    │
 ┌───v──────────────────────┴───┐               └─────────────────────────────────────┘
 │   Operation                  │
 └───┬──────────────────────────┘
     │ (Event: exit)
 ┌───v───────┐
 │ Destroyed │
 └───────────┘

Member Enumeration Documentation

◆ ModuleErrors

enum mcx::container::Module::ModuleErrors

strong

Module Errors are available via parameter: 'module_error' or a member function call getErrors().

◆ ModuleEvents

enum mcx::container::Module::ModuleEvents

strong

Module Events can be set via parameter: 'module_event' or a member function call setEvent().

◆ ModuleStates

enum mcx::container::Module::ModuleStates

strong

Module States are available via parameter: 'module_state' or a member function call getState().

Member Function Documentation

◆ addParameter() [1/4]

template<size_t buffer_size>

parameter_server::ParamHandle mcx::container::Module::addParameter	(	const char *	id,
		parameter_server::ParameterType	param_type,
		char *	str_ptr,
		size_t	length
	)

protected

Helper function to register C-string member variable in the parameter tree.

Parameters

id	- name of the module.
param_type	- IO type of the parameter.
str_ptr	- pointer to a C-string.
length	- maximum length of the C-string.

Template Parameters

buffer_size - size of the input buffer (default: DEFAULT_INPUT_BUFFER_LENGTH).

Returns: handle to the created parameter.

Example Usage:: char* log[255] = "Hello world!";

...

log_handle = addParameter("logOut", ParamHandle::OUTPUT, log, 255);

◆ addParameter() [2/4]

template<typename T , size_t buffer_size>

parameter_server::ParamHandle mcx::container::Module::addParameter	(	const char *	id,
		parameter_server::ParameterType	param_type,
		parameter_server::DataType	data_type,
		T *	value_ptr,
		size_t	length = `1`,
		parameter_server::Unit	param_unit = `parameter_server::Unit::undefined`
	)

protected

Helper function to register types, which cannot be deduced.

Parameters

id	- name of the module.
param_type	- IO type of the parameter.
data_type	- a data type from the parameter_server::DataType
value_ptr	- pointer to a member variable.
length	- number of elements in case of the array.
param_unit	- measurement unit.

Template Parameters

T	- a data type of the registered variable.
buffer_size	- size of the input buffer. (default: DEFAULT_INPUT_BUFFER_LENGTH).

Returns: handle to the created parameter.

Example Usage:: struct {

const char* text{"All work and no play makes Jack a dull robot"};

double numbers[2]{4,5};

...

} blob;

input1_handle_ = addParameter("internal_data", ParamHandle::OUTPUT,

DataType::USER_TYPE, &blob);

input1_handle_.setOwner(UserGroup::SYSTEM, 770); // Available for the

// internal use only.

◆ addParameter() [3/4]

template<typename T , size_t buffer_size, add_visitable::EnableIfNotVisitable< T > >

parameter_server::ParamHandle mcx::container::Module::addParameter	(	const char *	id,
		parameter_server::ParameterType	param_type,
		T *	value_ptr,
		size_t	length = `1`,
		parameter_server::Unit	param_unit = `parameter_server::Unit::undefined`
	)

protected

Helper function to register member variable of in the parameter tree.

A Helper function, which automatically deduce standard numerical types.

Parameters

id	- name of the module.
param_type	- IO type of the parameter.
value_ptr	- pointer to a member variable.
length	- number of elements in case of the array.
param_unit	- measurement unit.

Template Parameters

T	- a data type of the registered variable.
buffer_size	- size of the input buffer. (default: DEFAULT_INPUT_BUFFER_LENGTH).

Returns: handle to the created parameter.

Example Usage:: double input1_ = 1.34;

input1_handle_ = addParameter("input1_", ParamHandle::INPUT, &input1_);

...

double input2_[2] = {2.3, 4.5};

input2_handle_ = addParameter("input2_", ParamHandle::INPUT, input2_, 2);

◆ addParameter() [4/4]

template<typename T , size_t buffer_size, add_visitable::EnableIfVisitable< T > >

parameter_server::GroupHandle mcx::container::Module::addParameter	(	const char *	id,
		parameter_server::ParameterType	param_type,
		T *	value_ptr,
		size_t	length = `1`,
		parameter_server::Unit	param_unit = `parameter_server::Unit::undefined`
	)

protected

Helper function to register visitable PODs in the parameter tree.

A Helper function, which automatically deduce visitable PODs.

Parameters

id	- name of the module.
param_type	- IO type of the parameter.
value_ptr	- pointer to a member variable.
length	- number of elements in case of the array (Only length = 1 is supported).
param_unit	- measurement unit.

Template Parameters

T	- a data type of the registered variable.
buffer_size	- size of the input buffer. (default: DEFAULT_INPUT_BUFFER_LENGTH).

Returns: handle to the created parameter.

Example Usage:: struct foo {

BEGIN_VISITABLES(foo);

VISITABLE(bool, b);

VISITABLE(int, i);

VISITABLE(double, d);

END_VISITABLES;

};

foo input1_{};

input1_handle_ = addParameter("input1_", ParamHandle::INPUT, &input1_);

◆ create() [1/2]

void mcx::container::Module::create	(	const char *	name,
		parameter_server::Parameter *	parameter_server,
		uint64_t	dt_micro_s,
		parameter_server::UserGroup	owner_group,
		uint32_t	permissions = `parameter_server::default_permissions`
	)

Extended interface with access permissions.

Extended interface in addition to the previous one, which can set User Group and Permissions of the module branch.

Parameters

name	- unique name.
parameter_server	- pointer to the root.
dt_micro_s	- cycle time in microseconds.
owner_group	- owner group of the module's branch.
permissions	- POSIX-like permissions for the parameter access.

See also: Module::create_; parameter_server::Permission

Example Usage:: control::MainControlLoop main_loop;

main_loop.create("Control", &param_server, 1000, UserGroup::OPERATOR, 770);

◆ create() [2/2]

void mcx::container::Module::create	(	const char *	name,
		parameter_server::Parameter *	parameter_server,
		uint64_t	dt_micro_s = `0`
	)

Executes 'Create' phase of initialization.

Before any operations on the module can be performed, it must be created, assigned a unique name, set its location in the parameter tree and set its cycle time.

Parameters

name	- unique name.
parameter_server	- pointer to the root.
dt_micro_s	- cycle time in microseconds.

See also: Module::create_

Example Usage:: control::MainControlLoop main_loop;

main_loop.create("Control", &param_server, 1000);

◆ create_()

virtual void mcx::container::Module::create_	(	const char *	name,
		parameter_server::Parameter *	parameter_server,
		uint64_t	dt_micro_s
	)

protectedpure virtual

User-defined callback, which is executed during 'Create' phase.

Parameters

name	- unique name.
parameter_server	- pointer to the root.
dt_micro_s	- cycle time in microseconds.

See also: Module::create

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, mcx::drive::Diagnostics, and MyModule1.

◆ createSubmodule()

void mcx::container::Module::createSubmodule	(	Module *	module,
		const char *	name
	)

protected

Creates and registers submodule.

This is a helper function, which creates a submodule and registers it in the branch as a child node. If submodule is created via createSubmodule, its state machine during initialization and deinitialization will be managed automatically. However the user is responsible to call submodule's Module::iterate() and trigger its event cycle.

Parameters

module	- pointer to the module instance.
name	- name of the module in the parameter tree.

Example Usage:: IIRFilter irr_filter;

createSubmodule(&irr_filter, "MyIIRFilter1");

◆ createSubmodules()

template<typename T >

void mcx::container::Module::createSubmodules	(	utils::span< T >	module_array,
		const char *	basename
	)

inlineprotected

Creates and registers an array of submodules.

This is a helper function, which creates an array of submodule and registers them in the branch as a child nodes. For more information check createSubmodule.

Parameters

module_array	- iterable object with the array of modules.
basename	- base name of the module in the parameter tree, index is added automatically

Example Usage:: std::array<IIRFilter, 3> irr_filters;

createSubmodule<IIRFilter>(irr_filter, "MyIIRFilter");

◆ getDtMicroSec()

uint64_t mcx::container::Module::getDtMicroSec ( ) const

inline

Returns a cycle time as an integer in microseconds.

Returns: cycle time in microseconds

◆ getDtSec()

double mcx::container::Module::getDtSec ( ) const

inline

Returns a cycle time as a float in seconds.

Returns: cycle time in seconds.

◆ getError()

Module::ModuleErrors mcx::container::Module::getError ( ) const

Returns active error code.

Returns: active error code.

See also: ModuleErrors

◆ getLocalBranch()

parameter_server::Parameter * mcx::container::Module::getLocalBranch ( )

inlineprotected

Returns the root of the local branch.

Returns: a pointer to the parameter, which represents the module.

◆ getName()

const char * mcx::container::Module::getName ( ) const

Returns the name of the module.

Returns: name of the module.

◆ getParameterRoot()

parameter_server::Parameter * mcx::container::Module::getParameterRoot ( )

inlineprotected

Returns the root of the parameter tree.

Returns: a pointer to the root of the parameter tree.

◆ getState()

Module::ModuleStates mcx::container::Module::getState ( ) const

Returns an actual state.

Returns: actual state.

See also: ModuleStates

◆ initPhase1()

bool mcx::container::Module::initPhase1 ( )

Executes initialization of the parameter tree phase.

The next step after the Create. During initPhase1 parameters are added to the parameter tree. Parameter values are loaded from the configuration file

Returns: true on success.

See also: Module::initPhase1_

◆ initPhase1_()

virtual bool mcx::container::Module::initPhase1_ ( )

protectedpure virtual

User-defined callback to register parameters in the tree.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::initPhase1

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, mcx::drive::Diagnostics, and MyModule1.

◆ initPhase2()

bool mcx::container::Module::initPhase2 ( )

Initialization, which require parameter tree to be complete and loaded.

After the tree is built and values are loaded, additional initialization might be required. For example preparing the state machine, where state timeouts are the values from the parameter tree.

Returns: true on success.

See also: Module::initPhase2_

◆ initPhase2_()

virtual bool mcx::container::Module::initPhase2_ ( )

protectedpure virtual

User-defined callback after the parameter tree is ready.

This callback could be used for additional initialization. During initPhase2_ tree structure is complete, initial values are NOT loaded.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::initPhase2

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, mcx::drive::Diagnostics, and MyModule1.

◆ iterate()

bool mcx::container::Module::iterate	(	const TaskTime &	task_time,
		UserTime *	user_time
	)

Iterates an execution cycle of the module.

Parameters

task_time	- various input timers, application and system time.
user_time	- user defined timer, an external clock source.

Returns: true on success.

See also: Module::iterateOp_

◆ iterateOp_()

virtual bool mcx::container::Module::iterateOp_	(	const TaskTime &	system_time,
		UserTime *	user_time
	)

protectedpure virtual

User-defined callback which is called during Operation mode.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::iterate

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, and mcx::drive::Diagnostics.

◆ iteratePreOp_()

virtual bool mcx::container::Module::iteratePreOp_	(	const TaskTime &	system_time,
		UserTime *	user_time
	)

inlineprotectedvirtual

User-defined callback which is called during Phase 2.

Optional callback, which is useful for the modules which needs to start iterating before the system switches to OP. For example a Logger module start to print output before OP. Real-time behaviour is this callback is not guaranteed.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::iterate

◆ publish()

parameter_server::PubHandle mcx::container::Module::publish ( const char * path )

protected

Helper function to update parameter's value.

Note: A better approach is to use Module::addParameter inside the modules to create inputs and outputs, which are linked by Parameter::link outside the modules in the application specific configuration code.

Returns: a request handle.

See also: parameter_server::PubHandle

◆ request()

parameter_server::ReqHandle mcx::container::Module::request ( const char * path )

protected

Helper function to request a parameter's value.

Note: A better approach is to use Module::addParameter inside the modules to create inputs and outputs, which are linked by Parameter::link outside the modules in the application specific configuration code.

Returns: a request handle.

See also: parameter_server::ReqHandle

◆ setDtMicroSec()

void mcx::container::Module::setDtMicroSec ( uint64_t micro_sec )

inline

Sets a cycle time of module and its submodules in microseconds.

Parameters

micro_sec - new cycle time of the module.

◆ setDtSec()

void mcx::container::Module::setDtSec ( double sec )

inline

Sets a cycle time of module and its submodules in seconds.

Parameters

sec	- new cycle time of the module.

◆ setEvent()

void mcx::container::Module::setEvent ( Module::ModuleEvents event )

Command an event.

Requests a state machine to execute an event.

See also: ModuleEvents

◆ setName()

void mcx::container::Module::setName ( const char * name )

Sets the name of the module.

Parameters

name	- name of the module.

◆ setType()

void mcx::container::Module::setType ( const char * name )

protected

Sets a type of the module.

This is a helper function to set the type of the module, which can be used by the client to get additional information. If the type is not set, it will be generated automatically in the following form: Namespace::ClassName<Number of Channels>.

Parameters

name	- type name.

◆ startOp()

bool mcx::container::Module::startOp ( )

Final initialization before entering Operation mode.

Just before entering Operation mode startOp is called. Module could be started and stopped multiple times. startOp could be used to reset counter, state variable etc.

Returns: true on success.

See also: Module::startOp_

◆ startOp_()

virtual bool mcx::container::Module::startOp_ ( )

protectedpure virtual

User-defined callback before entering Operation mode.

During startOp_ callback user can safely access initialized parameter tree. startOp_ operation is part of the first iterateOp_ cycle, that is why it should be relatively short. Otherwise fist cycle time will be violated.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::startOp

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, mcx::drive::Diagnostics, and MyModule1.

◆ stopOp()

bool mcx::container::Module::stopOp ( )

Stops Operation mode, switches back to PHASE2.

User may decide to stop the module by calling stopOp. iterateOp_ is not called anymore, but input requests are still processed. To restart the module startOp should be called.

Returns: true on success.

See also: Module::stopOp_

◆ stopOp_()

virtual bool mcx::container::Module::stopOp_ ( )

protectedpure virtual

User-defined callback before to stop Operation mode.

Returns: user callback should return true on success, otherwise the state machine won't progress.

See also: Module::stopOp

Implemented in mcx::drive::Module, mcx::watchdog::Module, mcx::parameter_server::Persistence, mcx::drive::Diagnostics, and MyModule1.

◆ subscribe()

parameter_server::SubHandle mcx::container::Module::subscribe ( const char * path )

protected

Helper function to subscribe for the parameter's update.

Note: A better approach is to use Module::addParameter inside the modules to create inputs and outputs, which are linked by Parameter::link outside the modules in the application specific configuration code.

Returns: a subscription handle.

See also: parameter_server::SubHandle

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

container/ct_module.h
container/ct_module.cpp

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ ModuleErrors

◆ ModuleEvents

◆ ModuleStates

Member Function Documentation

◆ addParameter() [1/4]

◆ addParameter() [2/4]

◆ addParameter() [3/4]

◆ addParameter() [4/4]

◆ create() [1/2]

◆ create() [2/2]

◆ create_()

◆ createSubmodule()

◆ createSubmodules()

◆ getDtMicroSec()

◆ getDtSec()

◆ getError()

◆ getLocalBranch()

◆ getName()

◆ getParameterRoot()

◆ getState()

◆ initPhase1()

◆ initPhase1_()

◆ initPhase2()

◆ initPhase2_()

◆ iterate()

◆ iterateOp_()

◆ iteratePreOp_()

◆ publish()

◆ request()

◆ setDtMicroSec()

◆ setDtSec()

◆ setEvent()

◆ setName()

◆ setType()

◆ startOp()

◆ startOp_()

◆ stopOp()

◆ stopOp_()

◆ subscribe()