A single LightHub item (virtual channel). More...

#include <item.h>

Public Member Functions
	Item (char name, aJsonObject _items=items)
	Create an item by name from the items object.
	Item (aJsonObject obj, aJsonObject _items=items)
	Adopt an existing items-array element as this item.
	Item (uint16_t num, uint8_t subItem, aJsonObject *_items=items)
	Create an item by CAN id (CANDRV builds).
	~Item ()
boolean	isValid ()
boolean	Setup ()
void	Stop ()
int	Ctrl (itemCmd cmd, char *subItem=NULL, uint8_t flags=0, bool authorized=false)
	Main control entry point: execute a command/value on this item.
int	Ctrl (char payload, char subItem=NULL, int remoteID=0)
int	remoteCtrl (itemCmd cmd, int remoteID, char subItem=NULL, char authToken=NULL)
int	getArg (short n=0)
float	getFloatArg (short n=0)
short	getArgCount ()
long int	getVal ()
uint8_t	getSubtype ()
uint8_t	getCmd ()
long int	getExt ()
void	setExt (long int par)
chPersistent *	getPersistent ()
chPersistent *	setPersistent (chPersistent *par)
void	setCmd (uint8_t cmdValue)
uint32_t	getFlag (uint32_t flag=FLAG_MASK)
void	setFlag (uint32_t flag)
void	clearFlag (uint32_t flag)
void	setVal (long int par)
void	setFloatVal (float par)
void	setSubtype (uint8_t par)
int	Poll (int cause)
int	SendStatus (long sendFlags, char *subItem=NULL)
int	SendStatusImmediate (itemCmd st, long sendFlags, char *subItem=NULL, bool tetain=true)
int	isActive ()
int	getChanType ()
int	On ()
int	Off ()
int	Toggle ()
int	scheduleCommand (itemCmd cmd, bool authorized)
int	scheduleOppositeCommand (itemCmd cmd, short isActiveNow, bool authorized)
int	isScheduled ()
char *	getSubItemStrById (uint8_t subItem)
uint8_t	getSubitemId (char *subItem)

Public Attributes
aJsonObject *	rootItems
	Pointers into the items JSON tree (root object, item array, its arg/val/ext elements).
aJsonObject *	itemArr
aJsonObject *	itemArg
aJsonObject *	itemVal
aJsonObject *	itemExt
uint8_t	itemType
	Channel type (CH_*) resolved from I_TYPE.
abstractOut *	driver
	Linked output driver instance (shared per channel type) or NULL.

Protected Member Functions
bool	digGroup (aJsonObject itemArr, itemCmd cmd=NULL, char *subItem=NULL, bool authorized=false, uint8_t ctrlFlags=0)
long int	limitSetValue ()
int	VacomSetFan (itemCmd st)
int	VacomSetHeat (itemCmd st)
int	modbusDimmerSet (itemCmd st)
int	modbusDimmerSet (int addr, uint16_t _reg, int _regType, int _mask, uint16_t value)
void	mb_fail (int result=0)
void	Parse ()
int	checkModbusDimmer ()
int	checkModbusDimmer (int data)
int	checkRetry ()
void	sendDelayedStatus ()
int	checkFM ()

Protected Attributes
char	defaultSubItem [16]
int	defaultSuffixCode

Detailed Description

A single LightHub item (virtual channel).

Item wraps one entry of the global items JSON object: a virtual channel of a given type (CH_*) with its arguments, current value, last command, optional extension data and a driver instance. Items are the core abstraction of the system: physical outputs (relays, DMX, Modbus, AC), groups and services are all items, addressed by name ("name", "name/subItem" or "name/subItem/suffix").

All external control is funneled through the Ctrl() overloads; the resulting state is published to MQTT (and CAN when enabled) via SendStatus()/SendStatusImmediate().

Constructor & Destructor Documentation

◆ Item() [1/3]

Item::Item	(	char *	name,
		aJsonObject *	_items = items )

Create an item by name from the items object.

Parameters

name	- item name, optionally "item/subItem" or "item/subItem/suffix"; the tail sets the default subItem/suffix used by later Ctrl() calls
_items	- root items object (global items by default)

◆ Item() [2/3]

Item::Item	(	aJsonObject *	obj,
		aJsonObject *	_items = items )

Adopt an existing items-array element as this item.

Parameters

obj	- pointer to the item array inside the items object

◆ Item() [3/3]

Item::Item	(	uint16_t	num,
		uint8_t	subItem,
		aJsonObject *	_items = items )

Create an item by CAN id (CANDRV builds).

Parameters

num	- CAN identifier of the item
subItem	- default subItem id, optionally OR'ed with SUBITEM_IS_COMMAND

◆ ~Item()

Item::~Item ( )

Destructor: releases the driver if it is not shared with another item.

Member Function Documentation

◆ checkFM()

int Item::checkFM ( )

protected

(Legacy) Poll Vacom fan motor registers and publish the state as JSON.

◆ checkModbusDimmer() [1/2]

int Item::checkModbusDimmer ( )

protected

(Legacy) Poll the Modbus dimmer register and update stored value/status.

◆ checkModbusDimmer() [2/2]

int Item::checkModbusDimmer ( int data )

protected

(Legacy) Compare a polled Modbus register data with the stored value and resync status.

◆ checkRetry()

int Item::checkRetry ( )

protected

Retry the last failed transaction if FLAG_SEND_RETRY is set.

◆ clearFlag()

void Item::clearFlag ( uint32_t flag )

Clear FLAG_* bits in I_CMD, preserving the CMD_* bits.

◆ Ctrl() [1/2]

int Item::Ctrl	(	char *	payload,
		char *	subItem = NULL,
		int	remoteID = 0 )

Parse a text payload (command word, number, color, optional "token@command" authorization prefix) and route it to Ctrl(itemCmd, ...).

Parameters

remoteID - if non-zero, forward the command to that remote node via CAN

possible problem here with truncated default

◆ Ctrl() [2/2]

int Item::Ctrl	(	itemCmd	cmd,
		char *	subItem = NULL,
		uint8_t	flags = 0,
		bool	authorized = false )

Main control entry point: execute a command/value on this item.

Parameters

cmd	- command and/or value (see itemCmd)
subItem	- subchannel name or NULL (default subItem is used)
flags	- CTRL_* group execution flags
authorized	- true if the caller is authorized (unlocks DISABLE, etc.)

Returns: 1 - executed, 3 - no action needed (target state reached), -1 - error, -4 - invalid argument, -5 - unauthorized, -6 - disabled

possible problem here with truncated default

DELAYED COMMANDS processing

Common (GRP & NO GRP) commands

bool oppositeCommandToBeSchedulled = (suffixCode==S_CMD) && allowRecursion && cmd.isValue();

rest of Legacy monolite core code (to be refactored ) BEGIN ///

rest of Legacy monolite core code (to be refactored ) END ///

◆ digGroup()

bool Item::digGroup	(	aJsonObject *	itemArr,
		itemCmd *	cmd = NULL,
		char *	subItem = NULL,
		bool	authorized = false,
		uint8_t	ctrlFlags = 0 )

protected

Recursively walk a group's member list. If cmd is given - execute it on every member (non-recursively); otherwise check members' activity and return true if any is active.

◆ getArg()

int Item::getArg ( short n = 0 )

Returns: n-th argument (I_ARG) as int; 0 if absent.

◆ getArgCount()

short Item::getArgCount ( )

Returns: number of arguments in I_ARG (0, 1 or array size).

◆ getChanType()

int Item::getChanType ( )

Returns: effective channel type (CH_*) - from the driver if present, else I_TYPE.

◆ getCmd()

uint8_t Item::getCmd ( )

Returns: last command code (CMD_*) stored in I_CMD, or -1.

◆ getExt()

long int Item::getExt ( )

Returns: channel extension data (I_EXT) as int.

◆ getFlag()

uint32_t Item::getFlag ( uint32_t flag = FLAG_MASK )

Returns: subset of stored FLAG_* bits matching flag (default: all).

◆ getFloatArg()

float Item::getFloatArg ( short n = 0 )

Returns: n-th argument (I_ARG) as float; 0.0 if absent.

◆ getPersistent()

chPersistent * Item::getPersistent ( )

Returns: pointer to driver-persistent data attached to I_EXT, or NULL.

◆ getSubitemId()

uint8_t Item::getSubitemId ( char * subItem )

Returns: id of the subItem with the given name, or NO_SUBITEM.

◆ getSubItemStrById()

char * Item::getSubItemStrById ( uint8_t subItem )

Returns: name of the subItem with the given id, or NULL.

◆ getSubtype()

uint8_t Item::getSubtype ( )

Returns: storage subtype (ST_*) of the stored value.

◆ getVal()

long int Item::getVal ( )

Returns: latest stored value (I_VAL) as int, from a scalar or first array element.

◆ isActive()

int Item::isActive ( )

Returns: 1 if the channel is active (ON), 0 if OFF, -1 if invalid.

◆ isScheduled()

int Item::isScheduled ( )

Returns: the scheduled command code (CMD_*), 0 if nothing is armed.

◆ isValid()

boolean Item::isValid ( )

Returns: true if the item was found in config and is a valid array.

◆ limitSetValue()

long int Item::limitSetValue ( )

protected

Returns: maximum settable value for this channel type (255, 80 for thermostat, 0 for counter).

◆ mb_fail()

void Item::mb_fail ( int result = 0 )

protected

Mark the last Modbus transaction as failed (sets FLAG_SEND_RETRY).

◆ modbusDimmerSet() [1/2]

int Item::modbusDimmerSet	(	int	addr,
		uint16_t	_reg,
		int	_regType,
		int	_mask,
		uint16_t	value )

protected

(Legacy) Low-level Modbus write of value to register _reg of slave addr.

◆ modbusDimmerSet() [2/2]

int Item::modbusDimmerSet ( itemCmd st )

protected

(Legacy) Write dimmer value to the Modbus register of this item.

◆ Off()

int Item::Off ( )

inline

Turn the channel OFF.

◆ On()

int Item::On ( )

inline

Turn the channel ON.

◆ Parse()

void Item::Parse ( )

protected

Parse the item array: resolve type, arg/val/cmd/ext elements and the driver.

◆ Poll()

int Item::Poll ( int cause )

Periodic poll of the item. Fires armed delayed (S_DELAYED) commands, retries failed transactions and delegates to the driver.

Parameters

cause - POLLING_SLOW/POLLING_FAST/POLLING_INT/POLLING_1S

◆ remoteCtrl()

int Item::remoteCtrl	(	itemCmd	cmd,
		int	remoteID,
		char *	subItem = NULL,
		char *	authToken = NULL )

Forward a command to a remote LightHub node over CAN.

Parameters

cmd	- command to send,
remoteID	- target node id
authToken	- optional authorization token

◆ scheduleCommand()

int Item::scheduleCommand	(	itemCmd	cmd,
		bool	authorized )

Arm a delayed command: execute cmd's command code after the delay stored in cmd parameter (ms).

Parameters

authorized - stored with the timer.

◆ scheduleOppositeCommand()

int Item::scheduleOppositeCommand	(	itemCmd	cmd,
		short	isActiveNow,
		bool	authorized )

Arm the opposite command after the given delay (momentary action): e.g. CMD_ON -> CMD_OFF after N ms, CMD_XON -> CMD_XOFF, etc.

Parameters

isActiveNow - current activity state of the channel

◆ sendDelayedStatus()

void Item::sendDelayedStatus ( )

protected

Publish a pending (deferred) status if the network is up.

◆ SendStatus()

int Item::SendStatus	(	long	sendFlags,
		char *	subItem = NULL )

Publish current command/value/flags to MQTT.

Parameters

sendFlags - FLAG_COMMAND/FLAG_PARAMETERS/FLAG_FLAGS and FLAG_SEND_IMMEDIATE/FLAG_SEND_DEFFERED options Defers the publish (sets a pending flag) if the network is busy or RAM is low.

◆ SendStatusImmediate()

int Item::SendStatusImmediate	(	itemCmd	st,
		long	sendFlags,
		char *	subItem = NULL,
		bool	tetain = true )

Publish the given status to MQTT immediately without deferral.

subItem

◆ setCmd()

void Item::setCmd ( uint8_t cmdValue )

Store a command code in I_CMD, preserving the FLAG_* bits.

◆ setExt()

void Item::setExt ( long int par )

Store an integer extension value in I_EXT.

◆ setFlag()

void Item::setFlag ( uint32_t flag )

Set FLAG_* bits in I_CMD, preserving the CMD_* bits.

◆ setFloatVal()

void Item::setFloatVal ( float par )

Store a float value in I_VAL (only if I_VAL is a scalar).

◆ setPersistent()

chPersistent * Item::setPersistent ( chPersistent * par )

Attach driver-persistent data to I_EXT.

Returns: the stored pointer.

◆ setSubtype()

void Item::setSubtype ( uint8_t par )

Store the storage subtype (ST_*) of I_VAL.

◆ Setup()

boolean Item::Setup ( )

Initialize the driver hardware.

Returns: true on success (driver present and started)

◆ setVal()

void Item::setVal ( long int par )

Store an integer value in I_VAL (only if I_VAL is a scalar).

◆ Stop()

void Item::Stop ( )

Stop the driver and release its hardware resources.

◆ Toggle()

int Item::Toggle ( )

inline

Toggle the channel ON/OFF.

◆ VacomSetFan()

int Item::VacomSetFan ( itemCmd st )

protected

(Legacy) Set Vacom fan speed over Modbus.

◆ VacomSetHeat()

int Item::VacomSetHeat ( itemCmd st )

protected

(Legacy) Set Vacom heat temperature over Modbus.

Member Data Documentation

◆ defaultSubItem

char Item::defaultSubItem[16]

protected

◆ defaultSuffixCode

int Item::defaultSuffixCode

protected

◆ driver

abstractOut* Item::driver

Linked output driver instance (shared per channel type) or NULL.

◆ itemArg

aJsonObject * Item::itemArg

◆ itemArr

aJsonObject * Item::itemArr

◆ itemExt

aJsonObject * Item::itemExt

◆ itemType

uint8_t Item::itemType

Channel type (CH_*) resolved from I_TYPE.

◆ itemVal

aJsonObject * Item::itemVal

◆ rootItems

aJsonObject* Item::rootItems

Pointers into the items JSON tree (root object, item array, its arg/val/ext elements).

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

lighthub/item.h
lighthub/item.cpp

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Item() [1/3]

◆ Item() [2/3]

◆ Item() [3/3]

◆ ~Item()

Member Function Documentation

◆ checkFM()

◆ checkModbusDimmer() [1/2]

◆ checkModbusDimmer() [2/2]

◆ checkRetry()

◆ clearFlag()

◆ Ctrl() [1/2]

◆ Ctrl() [2/2]

◆ digGroup()

◆ getArg()

◆ getArgCount()

◆ getChanType()

◆ getCmd()

◆ getExt()

◆ getFlag()

◆ getFloatArg()

◆ getPersistent()

◆ getSubitemId()

◆ getSubItemStrById()

◆ getSubtype()

◆ getVal()

◆ isActive()

◆ isScheduled()

◆ isValid()

◆ limitSetValue()

◆ mb_fail()

◆ modbusDimmerSet() [1/2]

◆ modbusDimmerSet() [2/2]

◆ Off()

◆ On()

◆ Parse()

◆ Poll()

◆ remoteCtrl()

◆ scheduleCommand()

◆ scheduleOppositeCommand()

◆ sendDelayedStatus()

◆ SendStatus()

◆ SendStatusImmediate()

◆ setCmd()

◆ setExt()

◆ setFlag()

◆ setFloatVal()

◆ setPersistent()

◆ setSubtype()

◆ Setup()

◆ setVal()

◆ Stop()

◆ Toggle()

◆ VacomSetFan()

◆ VacomSetHeat()

Member Data Documentation

◆ defaultSubItem

◆ defaultSuffixCode

◆ driver

◆ itemArg

◆ itemArr

◆ itemExt

◆ itemType

◆ itemVal

◆ rootItems