LCC producer for UOD sensor cards with adaptive polling. More...

#include <UodConfiguredProducer.h>

Inheritance diagram for UodConfiguredProducer:

Collaboration diagram for UodConfiguredProducer:

[legend]

Classes
struct	SensorRange
	Holds configured min/max range values for all sensors on a card. More...

Public Types
typedef UodCardConfig	CardConfig_type

typedef UodConfig	LineGroupConfig_type

typedef UodLineConfig	LineConfig_type

Public Member Functions
template<unsigned NUM_CARDS>
	UodConfiguredProducer (openlcb::Node pNode, const openlcb::RepeatedGroup< CardConfig_type, NUM_CARDS > &configOffset, uint8_t numDevicesPerCard, EventDeviceTypes eventDeviceType, const char cardDescription) __attribute__((noinline))
	constructor More...

UpdateAction	apply_configuration (int fd, bool initial_load, BarrierNotifiable *done) OVERRIDE
	Invoked on initial load of CDI and when CDI is udpated. Register configured events with OpenMRN. More...

void	factory_reset (int fd) OVERRIDE

bool	ensureUniqueI2cOffset (uint8_t cardIndex, uint8_t bus, uint8_t offset)

Public Attributes
union I2cCardHelper::EventUserArgsUnion	userArgs

Protected Member Functions
void	_do_unregister ()
	Unregisters this event handler from the global registry.

void	handle_identify_consumer (const openlcb::EventRegistryEntry &registry_entry, openlcb::EventReport event, BarrierNotifiable done) OVERRIDE
	Process request to identify produced events.

void	handle_identify_producer (const openlcb::EventRegistryEntry &registry_entry, openlcb::EventReport event, BarrierNotifiable done) OVERRIDE
	Process request to identify produced events.

virtual void	SendEventIdentified (const openlcb::EventRegistryEntry &registry_entry, openlcb::EventReport event, BarrierNotifiable done)
	Sends Producer- or Consumer-Identified for `registry_entry`. More...

void	applyI2cInfo (int fd, uint8_t cardIndex, i2cInfoConfig_type cfgI2cInfoRef)
	sets up the MCP card's I2C connection using the user provided (CDI) configuration information (bus and address offset) More...

void	resetCardInfo (int fd, cardInfoConfig_type cfgI2cInfoRef)
	resets the card configuration information (description field). More...

void	resetI2cInfo (int fd, i2cInfoConfig_type cfgI2cInfoRef)
	resets the card's I2C configuration information (bus and address fields). More...

virtual void	drive_pin (uint8_t card, uint8_t pin, bool set)

virtual void	drive_pin_ext (uint8_t card, uint8_t pin, bool set, uint8_t intArg)

EventUserArgsUnion	unpack_user_args (const openlcb::EventRegistryEntry &re) const
	Small helper to unpack our 4-byte user_arg payload from the registry entry.

void	handle_event_report (const openlcb::EventRegistryEntry &registry_entry, openlcb::EventReport event, BarrierNotifiable done) OVERRIDE

Private Member Functions
bool	_updateSensorValues (uint8_t cardIndex)
	Fetches the current sensor bitmap from a UOD Card. More...

void	_sendSensorRangesIfNeeded (uint8_t cardIndex)
	Initialize (or re-initialize) range handling and I²C callbacks for one card. More...

bool	_sendSensorRanges (uint8_t cardIndex)
	Sends the configured min/max distance ranges to a UOD Card. More...

uint8_t	_getSensorState (uint8_t sensorNum)
	Returns the current state of a single sensor bit. More...

bool	_processSensorState (int cardIndex, int sensorIndex)
	Process a single sensor's state and dispatch events if needed. More...

void	_initI2cCards (bool isProducer)
	Initializes the array of I2C card objects using the configured card type. More...

Private Attributes
ProducerEventIds	producerEventIds_
	Object for I2C connection to UOD cards.

uint16_t	sensorStates_
	Shadow copy of the event IDs produced by each of the UOD cards.

Detailed Description

LCC producer for UOD sensor cards with adaptive polling.

This class monitors multiple Ultrasonic Occupancy Detection (UOD) sensors connected via I²C UOD Cards. For each sensor it exports two OpenLCB/LCC events (ON/OFF).

Polling strategy

Integrated into the OpenMRN refresh loop and nominally invoked at ~33 Hz.
Uses a simple two-gear scheduler:
- Fast gear: after any event is detected, polling runs every tick for a short window to maintain low latency.
- Idle gear: when no events occur, polling slows to reduce I²C traffic. Cycles are skipped until the idle delay expires.
Within each poll cycle, only one sensor state change is processed to spread load evenly over time.

Responsibilities

Reads 16-bit bitmaps from UOD Cards over I²C.
Applies per-sensor debounce filtering.
Dispatches ON/OFF events when debounced state changes are detected.
Manages per-card sensor range configuration (min/max distance).

This design balances responsiveness with bus efficiency while keeping the implementation simple and predictable.

Definition at line 136 of file UodConfiguredProducer.h.

Member Typedef Documentation

◆ CardConfig_type

typedef UodCardConfig UodConfiguredProducer::CardConfig_type

Type for the uod card CDI configuration entry

Definition at line 141 of file UodConfiguredProducer.h.

◆ LineConfig_type

typedef UodLineConfig UodConfiguredProducer::LineConfig_type

Type for the uod line CDI configuration entry

Definition at line 143 of file UodConfiguredProducer.h.

◆ LineGroupConfig_type

typedef UodConfig UodConfiguredProducer::LineGroupConfig_type

Type for the uod CDI configuration entry

Definition at line 142 of file UodConfiguredProducer.h.

Constructor & Destructor Documentation

◆ UodConfiguredProducer()

template<unsigned NUM_CARDS>

UodConfiguredProducer::UodConfiguredProducer	(	openlcb::Node *	pNode,
		const openlcb::RepeatedGroup< CardConfig_type, NUM_CARDS > &	configOffset,
		uint8_t	numDevicesPerCard,
		EventDeviceTypes	eventDeviceType,
		const char *	cardDescription
	)

inline

constructor

Parameters

pNode	OpenLCB node object from the stack
configOffset	repeated group object from the configuration space that represents all the events for each UOD sensor, for all UOD Cards
numDevicesPerCard	number of UOD lines configured for each UOD Card.
eventDeviceType	EventDeviceTypes value identify the type of device, used when setting default event ID
cardDescription	text descripton of the card - "UOD CARD"

Usage:: REGISTER_CARD(UodConfiguredPC, cfg.uodCardsSeg().uodCardConfig(), "Producer", "UOD Card", NUM_UOD_SENSORS_PER_CARD, EventDeviceTypes::UOD)

REGISTER_CARD
#define REGISTER_CARD(_ClassName, _CdiCardConfig, _CardType, _CardDescription, _CardNumDevices, _Card_Event_Type)
creates a unqiue name for the objects used in registering the card, then registers the card
Definition: LccNodeMacros.h:104

Definition at line 158 of file UodConfiguredProducer.h.

Member Function Documentation

◆ _getSensorState()

uint8_t UodConfiguredProducer::_getSensorState ( uint8_t sensorNum )

inlineprivate

Returns the current state of a single sensor bit.

Checks the bitmap last read from a UOD Card to determine whether the specified sensor is currently active. This function does not itself perform an I²C read; call _updateSensorValues first to refresh the bitmap.

Parameters

sensorNum Index of the sensor to query.

Returns: 1 if the sensor’s bit is set (active), 0 otherwise.

Definition at line 402 of file UodConfiguredProducer.h.

Here is the caller graph for this function:

◆ _initI2cCards()

void I2cCardHelper::_initI2cCards ( bool isProducer )

inlineprivateinherited

Initializes the array of I2C card objects using the configured card type.

Allocates and initializes each I2C card in the array to the type specified by the cardType_ member. If isProducer is true, registers each card's polling callback.

Parameters

isProducer True if the card is used as a producer and requires polling.

Definition at line 460 of file I2cCardHelper.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _processSensorState()

bool UodConfiguredProducer::_processSensorState	(	int	cardIndex,
		int	sensorIndex
	)

inlineprivate

Process a single sensor's state and dispatch events if needed.

Reads the current state of the specified sensor, applies the debounce filter, and compares against its last stable state. If a valid state change is detected, the corresponding ON or OFF event is looked up and sent via the polling helper.

Parameters

cardIndex	Index of the UOD card containing the sensor.
sensorIndex	Index of the sensor on that card to evaluate.

Returns: true if a debounced state change was detected and an event was dispatched, false if no change occurred.

Definition at line 419 of file UodConfiguredProducer.h.

Here is the call graph for this function:

◆ _sendSensorRanges()

bool UodConfiguredProducer::_sendSensorRanges ( uint8_t cardIndex )

inlineprivate

Sends the configured min/max distance ranges to a UOD Card.

Copies the contents of

See also: sensorRange_ into a temporary buffer and transmits it over I²C to the specified card. The card uses these thresholds to evaluate sensor distance readings against occupancy detection criteria.

Parameters

cardIndex Index of the UOD Card to receive the range data.

Returns: true when range sent successfully

Definition at line 377 of file UodConfiguredProducer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _sendSensorRangesIfNeeded()

void UodConfiguredProducer::_sendSensorRangesIfNeeded ( uint8_t cardIndex )

inlineprivate

Initialize (or re-initialize) range handling and I²C callbacks for one card.

Sends the sensor range block once, clears the resend flag needsRange_, and registers connect/disconnect callbacks so we resend ranges after a reconnect.

Definition at line 344 of file UodConfiguredProducer.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _updateSensorValues()

bool UodConfiguredProducer::_updateSensorValues ( uint8_t cardIndex )

inlineprivate

Fetches the current sensor bitmap from a UOD Card.

Performs an I²C read of the two-byte bitmap that encodes all sensor states for the specified card. Each bit represents whether a sensor currently detects an object within its configured range.

On success, sensorStates_ is updated.
On failure (e.g., card not connected), sensorStates_ is left unchanged and the caller should skip processing this card this cycle.

Parameters

cardIndex Index of the UOD Card to query.

Returns: true if the I²C read succeeded, false otherwise.

Definition at line 318 of file UodConfiguredProducer.h.

Here is the call graph for this function:

◆ apply_configuration()

UpdateAction UodConfiguredProducer::apply_configuration	(	int	fd,
		bool	initial_load,
		BarrierNotifiable *	done
	)

inline

Invoked on initial load of CDI and when CDI is udpated. Register configured events with OpenMRN.

Parameters

fd	file descriptor used to access CDI data
initial_load	is true when CDI is loaded after a reboot
done

Removed registration of this event handler from the global event registry.

Definition at line 185 of file UodConfiguredProducer.h.

Here is the call graph for this function:

◆ applyI2cInfo()

void I2cCardHelper::applyI2cInfo	(	int	fd,
		uint8_t	cardIndex,
		i2cInfoConfig_type	cfgI2cInfoRef
	)

inlineprotectedinherited

sets up the MCP card's I2C connection using the user provided (CDI) configuration information (bus and address offset)

Note

producer/consumers apply_configuration() callback invoke this method to initialize the I2C / MCP connection information for the card

all I2C connected cards have CDI section for user provided bus and address information (which must match the settings of the I2C enabeled card)

HOOK: Typical call site is within your apply_configuration() loop:

read bus & offset from CDI
initialize the corresponding i2cCards[cardIndex]

Parameters

fd	file handle to access the CDI configuration information (provided by openmrn)
cardIndex	specifies which card the configuration is for. Used to update the i2cCards[] array and initialize the connection
cfgI2cInfoRef	offset into the intenal configuration space for the CDI configuration for the MCP card

Definition at line 295 of file I2cCardHelper.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ drive_pin()

virtual void I2cCardHelper::drive_pin	(	uint8_t	card,
		uint8_t	pin,
		bool	set
	)

inlineprotectedvirtualinherited

Hook for consumers: drive one output pin (simple case). Default does nothing; simple consumers override this.

Parameters

card	card index (as stored in user_arg)
pin	pin index (as stored in user_arg)
set	desired logical state from the event semantics (SET/ON = true, CLR/OFF = false)

Reimplemented in IoConfiguredPC, OutputConfiguredConsumer, ServoConfiguredConsumer, TurnoutConfiguredPC, and NeoPixelConfiguredConsumer.

Definition at line 392 of file I2cCardHelper.h.

Here is the caller graph for this function:

◆ drive_pin_ext()

virtual void I2cCardHelper::drive_pin_ext	(	uint8_t	card,
		uint8_t	pin,
		bool	set,
		uint8_t	intArg
	)

inlineprotectedvirtualinherited

Extended hook for consumers that also need the CDI intArg (e.g., audio message index). Default forwards to drive_pin(...) so existing consumers remain unchanged.

Reimplemented in AudioConfiguredConsumer.

Definition at line 402 of file I2cCardHelper.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ensureUniqueI2cOffset()

bool I2cCardHelper::ensureUniqueI2cOffset	(	uint8_t	cardIndex,
		uint8_t	bus,
		uint8_t	offset
	)

inlineinherited

Check for duplicate offsets on the same I2C bus. Automatically resets the tracker on the first call per config pass.

Remarks: Call this once per card during your apply_configuration loop, with the CDI values.

Parameters

cardIndex	Index of the card in the config loop.
bus	I2C bus number (0 or 1).
offset	I2C offset (0–7).

Returns: true if this (bus, offset) was already claimed.

Definition at line 183 of file I2cCardHelper.h.

Here is the caller graph for this function:

◆ factory_reset()

void UodConfiguredProducer::factory_reset ( int fd )

inline

Reset CDI configuration entries to their initial (default) values

Parameters

fd	used to access the CDI information in the file system

Definition at line 230 of file UodConfiguredProducer.h.

Here is the call graph for this function:

◆ handle_event_report()

void I2cCardHelper::handle_event_report	(	const openlcb::EventRegistryEntry &	registry_entry,
		openlcb::EventReport *	event,
		BarrierNotifiable *	done
	)

inlineprotectedinherited

Default consumer handler: maps an incoming Event Report to (card,pin,set,intArg) and calls drive_pin_ext(...). Producers are ignored.

Definition at line 418 of file I2cCardHelper.h.

Here is the call graph for this function:

◆ resetCardInfo()

void I2cCardHelper::resetCardInfo	(	int	fd,
		cardInfoConfig_type	cfgI2cInfoRef
	)

inlineprotectedinherited

resets the card configuration information (description field).

Note: invoke from the consumer/producer factory_reset() to reset the card configuration

Parameters

fd	file handle to access the CDI configuration information (provided by openmrn)
cfgI2cInfoRef	offset into the intenal configuration space for the CDI configuration block for the card's info (description, etc)

Definition at line 309 of file I2cCardHelper.h.

Here is the caller graph for this function:

◆ resetI2cInfo()

void I2cCardHelper::resetI2cInfo	(	int	fd,
		i2cInfoConfig_type	cfgI2cInfoRef
	)

inlineprotectedinherited

resets the card's I2C configuration information (bus and address fields).

Note: invoke from the consumer/producer factory_reset() to reset the card configuration

Parameters

fd	file handle to access the CDI configuration information (provided by openmrn)
cfgI2cInfoRef	offset into the intenal configuration space for the CDI configuration for card's I2C info (bus/offset)

Definition at line 321 of file I2cCardHelper.h.

Here is the caller graph for this function:

◆ SendEventIdentified()

virtual void I2cCardHelper::SendEventIdentified	(	const openlcb::EventRegistryEntry &	registry_entry,
		openlcb::EventReport *	event,
		BarrierNotifiable *	done
	)

inlineprotectedvirtualinherited

Sends Producer- or Consumer-Identified for registry_entry.

Identification type is inferred from the registry entry’s packed user args (see

See also: isProducer). Override to customize the MTI or payload.

Reimplemented in TurnoutConfiguredPC.

Definition at line 273 of file I2cCardHelper.h.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ userArgs

union I2cCardHelper::EventUserArgsUnion I2cCardHelper::userArgs

inherited

event arguments

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

Node_Card/UodConfiguredProducer.h

Classes

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Polling strategy

Responsibilities

Member Typedef Documentation

◆ CardConfig_type

◆ LineConfig_type

◆ LineGroupConfig_type

Constructor & Destructor Documentation

◆ UodConfiguredProducer()

Member Function Documentation

◆ _getSensorState()

◆ _initI2cCards()

◆ _processSensorState()

◆ _sendSensorRanges()

◆ _sendSensorRangesIfNeeded()

◆ _updateSensorValues()

◆ apply_configuration()

◆ applyI2cInfo()

◆ drive_pin()

◆ drive_pin_ext()

◆ ensureUniqueI2cOffset()

◆ factory_reset()

◆ handle_event_report()

◆ resetCardInfo()

◆ resetI2cInfo()

◆ SendEventIdentified()

Member Data Documentation

◆ userArgs