VisionBox Interface Library  1.7.5.0 (2021-12-10)
VIB::DigitalInput Class Reference
+ Inheritance diagram for VIB::DigitalInput:

Detailed Description

This class controls a group of digital input signals.

The following table shows the different implementations for the VisionBox / VisionCam and for the VisionSensor.

VisionBox / VisionCam VisionSensor
Features:
  • Reading of the current input state, see Get() and GetBit().
  • Adjustable debouncing of the input signals.
  • Blocking function for waiting on input events.
  • Use input signals as source for the Multiplexer.
Features:
  • Reading of the current input state, see Get() and GetBit().
  • Adjustable debouncing of the input signals.
  • Blocking function for waiting on input events.
  • Use input signal IN0 for triggering the sensor exposure

Electrical:

DigitalInput_VisionBox

Each group of digital input signals requires an external GND reference. Different groups are electrically isolated from each other, as well as from other VisionBox circuits and interfaces.

Electrical:

DigitalInput_VisionSensor

All input signals use a Schmitt trigger circuit with the power supply GND as reference.

For a detailed electrical specification, please take a look into the hardware manual.

Multiplexer

The Multiplexer in the VisionBox and VisionCam has direct access to the digital input signals. 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.

  • Debouncing is also applied to the digital input signals used by the Multiplexer.
  • 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 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.

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:
  • 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 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...
 
iDeviceoperator= (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()

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.

Parameters
nsLowTime in nano-seconds the signal must stay low before it takes effect (falling edge)
nsHighTime 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).

◆ 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
SensitivityMaskIf 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
SensitivityMaskRisingBinary representation of signals that trigger events on the rising edge
SensitivityMaskFallingBinary 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
InputStateBinary 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
BitIndexInput signal index, 0 ... (GetNumberOfInputs() - 1)
BitStateState 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
NumberOfInputsNumber 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
msTimeoutTimeout in milli-seconds, 0 ... INFINITE
NewInputStateResult 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
Parameters
msTimeoutTimeout in milli-seconds, 0 ... INFINITE
The actual timeout may be twice as high if there are already other threads waiting for an event.
SignalStateAfter success, the function returns the new state of the digital input signals (binary representation).
EventSignalsAfter 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
VIB::DigitalInput::ConfigureInputEvent
bool ConfigureInputEvent(unsigned int SensitivityMask)
Configures the sensitivity of the input events.
Definition: DigitalInput.cpp:277
VIB::DigitalInput::ConfigureDebounceTime
bool ConfigureDebounceTime(unsigned int nsLow, unsigned int nsHigh)
Sets debouncing time for the digital input signals.
Definition: DigitalInput.cpp:254
VIB::DigitalInput
This class controls a group of digital input signals.
Definition: VIB_Interface.h:432
VIB::iDevice::Open
bool Open(unsigned int Index=0)
Opens a device
Definition: iDevice.cpp:109
VIB::DigitalInput::WaitForInputEvent
bool WaitForInputEvent(unsigned int msTimeout, unsigned int &NewInputState)
Waits for an input event.
Definition: DigitalInput.cpp:327