VIB::DigitalInput Class Reference

Inheritance diagram for VIB::DigitalInput:

Detailed Description

This class controls a group of digital input signals.

Features

• Reading of the current input state, see Get() and GetBit().
• Adjustable debouncing of the input signals.
• Blocking function for waiting on input events.
• VisionBox / VisionCam:
  Use input signals as source for the Multiplexer to feed the signal to other RTCC units.
• VisionSensor:
  Use input signal for triggering the image sensor (controlled by the FG Camera library)

For a detailed electrical specification, please take a look at the Hardware Manual for the specific device.

Multiplexer

The Multiplexer in the VisionBox and VisionCam has direct access to the digital input signals after debouncing. The DigitalInput device doesn't have to be opened when going through the Multiplexer.

Debouncing

Digital input signals can be filtered by a digital debounce logic. It is configured with the function ConfigureDebounceTime().

The debouncing affects the values returned by Get() / GetBit() and the event function WaitForInputEvent().

Debouncing for VisionBox and VisionCam (RTCC hardware)

The debouncing logic is implemented in the FPGA.

• The RTCC uses a default debouncing setting of 200 ns after power-up.
• The maximum debouncing time is 10 ms.
• The debouncing logic introduces a jitter which is about 1/8 of the debouncing time.
• Debouncing is also applied to the digital input signals when used by the Multiplexer.

Debouncing for the VisionSensor PV

• Debouncing is also applied to the input when used as trigger for the sensor.
• VisionSensor PV and PV2:
  • The debouncing logic is implemented in the Programmable Realt-Tme Unit (PRU) of the SoC.
  • The minimal non-zero debouncing time is 1 us
  • The debouncing is turned off by default.
• VisionSensor PV3:
  • The debouncing logic is implemented in the FPGA.
  • The maximum debouncing time is 10 ms.
  • The default debouncing setting is 200 ns after power-up.
  • The debouncing logic introduces a jitter which is about 1/8 of the debouncing time.
  • For the VisionSensor PV3 with I/O Expansion, the debouncing is also applied to the digital input signals when used by the Multiplexer.

Digital input events

Digital input events can be used to avoid polled reading of the input state:

First, the desired input signals for generating an event are configured with ConfigureInputEvent.
Then, the blocking function WaitForInputEvent() can be used to wait for the event. It is usually called by a dedicated thread in the application.
AbortWaitingForInputEvent() can be used to interrupt waiting threads.

Example code

The following example configures the debouncing time and waits for input events in a loop:

VIB::DigitalInput digitalInput;
unsigned int unit = 0;
unsigned int sensitivityMaskRising = 0;
unsigned int sensitivityMaskFalling = 0;
 
// Open the first DigitalInput device:
digitalInput.Open(0);
 
// Configure one micro-second debouncing time:
digitalInput.ConfigureDebounceTime(1000, 1000);
 
// Configure input event:
// Input 2 uses both edges:
sensitivityMaskRising |= (1 << 2);
sensitivityMaskFalling |= (1 << 2);
// Input 3 uses rising edge:
sensitivityMaskRising |= (1 << 3);
// Input 4 uses falling edge:
sensitivityMaskFalling |= (1 << 4);
digitalInput.ConfigureInputEvent(sensitivityMaskRising, sensitivityMaskFalling);
 
// Wait for input events in a loop:
while (1)
{
    unsigned int inputState, changedSignals;
 
    if (!digitalInput.WaitForInputEvent(1000, inputState, changedSignals))
    {
        printf("WaitForInputEvent() timeout.\n");
        break;
    }
    
    printf("New input state: 0x%02x, changed signals: 0x%02x\n", inputState, changedSignals);
}

Please note that error checking was removed to keep the code as simple as possible.

Note

• For debouncing support and input events on the VisionSensor PV / PV2, the following package versions are required:
  • vspv-init ≥ 1.0.1.0
  • linux-image ≥ 1.0.2.0
  • pru-firmware-visionsensor-pv ≥ 1.2.0.0
• WaitForInputEvent() timeout handling:
  • On Windows, the resolution of the timeout value depends on the Windows timer resolution, which defaults to 15.6 ms. A timeout value smaller than this may result in an immediate timeout. The resolution can be changed with the Windows function timeBeginPeriod().
  • For Linux SDK version < 1.7.5.0 and Windows SDK < 1.7.10.0:
    After a timeout, the function ConfigureInputEvent() must be called again, which results in dropping of all pending events.
  • For Linux SDK version ≥ 1.7.5.0:
    After a timeout, WaitForInputEvent() can be called again without losing any events between calls. Calling ConfigureInputEvent() after a timeout is not required.
• The Multiplexer unit also provides events with additional RTCC features (event FIFO, event timestamps).

Public Member Functions
bool	AbortWaitingForInputEvent ()
	Aborts all threads waiting for events. More...
bool	ConfigureDebounceTime (unsigned int nsLow, unsigned int nsHigh)
	Sets debouncing time for the digital input signals. More...
bool	ConfigureDebounceTime (unsigned int nsLow, unsigned int nsHigh, unsigned int enableMask)
	Sets debouncing time for the digital input signals. More...
bool	ConfigureInputEvent (unsigned int SensitivityMask)
	Configures the sensitivity of the input events. More...
bool	ConfigureInputEvent (unsigned int SensitivityMaskRising, unsigned int SensitivityMaskFalling)
	Configures the sensitivity of the input events. More...
	DigitalInput ()
	Default constructor for the device object More...
bool	Get (unsigned int &InputState)
	Reads the state of the digital input signals. More...
bool	GetBit (unsigned int BitIndex, bool &BitState)
	Reads the state of the specified digital input signal. More...
bool	GetNumberOfInputs (unsigned int &NumberOfInputs)
	Returns number of digital input channels. More...
bool	Reset ()
	Resets the device to default settings. More...
bool	WaitForInputEvent (unsigned int msTimeout, unsigned int &NewInputState)
	Waits for an input event. More...
bool	WaitForInputEvent (unsigned int msTimeout, unsigned int &SignalState, unsigned int &EventSignals)
	Waits for an input event. More...
Public Member Functions inherited from VIB::iDevice
bool	Close ()
	Closes a device More...
	iDevice (const iDevice &device)
	The copy constructor makes a copy of the existing device object More...
bool	isOpen (bool &state)
	Returns the open state of a device object More...
bool	Open (unsigned int Index=0)
	Opens a device More...
iDevice &	operator= (const iDevice &device)
	The assignment operator makes a copy of the existing device object More...
virtual	~iDevice ()
	Deletes the device object More...

Constructor & Destructor Documentation

DigitalInput()

VIB::DigitalInput::DigitalInput

(

)

Default constructor for the device object

The device must be opened with Open() before it can be used.

Member Function Documentation

AbortWaitingForInputEvent()

bool VIB::DigitalInput::AbortWaitingForInputEvent

(

)

Aborts all threads waiting for events.

The function wakes up all threads waiting in WaitForInputEvent(), which will then return with an error.

Note

After abort, events must be configured with ConfigureInputEvent() before WaitForInputEvent() can be used again.

ConfigureDebounceTime() [1/2]

bool VIB::DigitalInput::ConfigureDebounceTime	(	unsigned int	nsLow,
		unsigned int	nsHigh
	)

Sets debouncing time for the digital input signals.

The time values are specified for high and low state separately. A value of 0 deactivates the debouncing function.

The same debouncing setting is applied to all input signals.

Parameters

nsLow	Time in nano-seconds the signal must stay low before it takes effect (falling edge)
nsHigh	Time in nano-seconds the signal must stay high before it takes effect (rising edge)

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Note

• The debouncing time values are given in nano-seconds, but the actual resolution is lower (e.g. 100 ns).
  

ConfigureDebounceTime() [2/2]

bool VIB::DigitalInput::ConfigureDebounceTime	(	unsigned int	nsLow,
		unsigned int	nsHigh,
		unsigned int	enableMask
	)

Sets debouncing time for the digital input signals.

The time values are specified for high and low state separately. A value of 0 deactivates the debouncing function.

Debouncing can be enabled for specific inputs only by using the enableMask argument.

Parameters

nsLow	Time in nano-seconds the signal must stay low before it takes effect (falling edge)
nsHigh	Time in nano-seconds the signal must stay high before it takes effect (rising edge)
enableMask	Binary representation of signals with debouncing enabled

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Note

• The debouncing time values are given in nano-seconds, but the actual resolution is lower (e.g. 100 ns).
  

ConfigureInputEvent() [1/2]

bool VIB::DigitalInput::ConfigureInputEvent

(

unsigned int

SensitivityMask

)

Configures the sensitivity of the input events.

See overloaded version of ConfigureInputEvent() for a detailed description.

Parameters

SensitivityMask

If bits 16...31 are zero, the corresponding bits 0...15 activate events for both edges (0: no events, 1: rising and falling edge). If bits 16...31 are set, the corresponding bits 0...15 configure the edge for each signal (0: falling edge, 1: rising edge).

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

ConfigureInputEvent() [2/2]

bool VIB::DigitalInput::ConfigureInputEvent	(	unsigned int	SensitivityMaskRising,
		unsigned int	SensitivityMaskFalling
	)

Configures the sensitivity of the input events.

This function must be called before WaitForInputEvent().

The parameters specify which input lines will be used to generate events. The signal edge can be specified for each line individually.

Note

The function will clear all pending events on the first call or after a WaitForInputEvent() timeout or abort.

Parameters

SensitivityMaskRising	Binary representation of signals that trigger events on the rising edge
SensitivityMaskFalling	Binary representation of signals that trigger events on the falling edge

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Get()

bool VIB::DigitalInput::Get

(

unsigned int &

InputState

)

Reads the state of the digital input signals.

Parameters

InputState

Binary representation of the input signals, LSB is input 0

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetBit()

bool VIB::DigitalInput::GetBit	(	unsigned int	BitIndex,
		bool &	BitState
	)

Reads the state of the specified digital input signal.

Parameters

BitIndex	Input signal index, 0 ... (GetNumberOfInputs() - 1)
BitState	State of the input

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

GetNumberOfInputs()

bool VIB::DigitalInput::GetNumberOfInputs

(

unsigned int &

NumberOfInputs

)

Returns number of digital input channels.

Parameters

NumberOfInputs

Number of inputs

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

Reset()

bool VIB::DigitalInput::Reset

(

)

Resets the device to default settings.

• The debouncing time will be reset to default (RTCC: 200 ns, VisionSensor PV: 0)
• Wakes up blocked threads in WaitForInputEvent()

Returns

true for success, use VIBSystem::GetLastErrorString() for an error description

WaitForInputEvent() [1/2]

bool VIB::DigitalInput::WaitForInputEvent	(	unsigned int	msTimeout,
		unsigned int &	NewInputState
	)

Waits for an input event.

See overloaded version of WaitForInputEvent() for a detailed description.

Parameters

msTimeout	Timeout in milli-seconds, 0 ... INFINITE
NewInputState	Result value containing the current state of the digital inputs and the changed signals: NewInputState bits 0...7: binary representation of the input signals NewInputState bits 8...15: binary representation of changed input signals since last call

Returns

true: success, new event
false: timeout, abort or other errors; use VIBSystem::GetLastErrorString() for an error description

WaitForInputEvent() [2/2]

bool VIB::DigitalInput::WaitForInputEvent	(	unsigned int	msTimeout,
		unsigned int &	SignalState,
		unsigned int &	EventSignals
	)

Waits for an input event.

The function waits for events on digital input lines which are selected with ConfigureInputEvent(). The function blocks until a new input event occurs, the timeout expires, or AbortWaitingForInputEvent() gets called.

Note

• Waiting threads can be interrupted with AbortWaitingForInputEvent(). ConfigureInputEvent() must then be called before waiting again.
• Multiple threads can call this function simultaneously. The first caller returns first with the next event.
• Linux SDK version < 1.7.5.0 / Windows SDK < 1.7.10.0: ConfigureInputEvent() must be called again after a timeout has occured, pending events may be lost.

Parameters

msTimeout	Timeout in milli-seconds, 0 ... INFINITE The actual timeout may be twice as high if there are already other threads waiting for an event.
SignalState	After success, the function returns the new state of the digital input signals (binary representation).
EventSignals	After success, the function returns the input signals which triggered the event (binary representation).

Returns

true: success, new event
false: timeout, abort or other errors; use VIBSystem::GetLastErrorString() for an error description