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

Detailed Description

This class controlls the LED Strobe Controller.

The LED strobe controller is designed as a current source. It allows generation of pulses with programmable duration and current value.

The following schematic shows a simplified strobe output:

VisionBox / VisionCam with integrated LED controller

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

The typical workflow for programming the Strobe Unit with this API is as follows:

Note
The strobe unit will be deactivated when closing the device object.
+ Example code
// open the Strobe device
VIB::Strobe strobe;
if (!strobe.Open(0))
return -1;
//internal initialization, reset all strobe settings
if (!strobe.Init(true))
goto error;
//set information about your light
int minOffTime;
if (!strobe.SetFixedCurrent(
24, // Supply voltage: 24 V
20, // Load voltage: 20 V
300, // Maximum ON time: 300 µs
0, // Minimum OFF time: allow steady ON state if possible
1000, // Current: 1 A
minOffTime)) // the calculated minimum off time [us]
return -1;
printf("Minimum OFF time: %d us\n", minOffTime);
//set duration time to 1 ms
if (!strobe.SetOnTime(1000))
return -1;
//set the trigger mode to software (one)
int NewTriggerMode;
return -1;
// trigger strobe by software
if (!strobe.SwTrigger(1))
return -1;
// ...

Operating conditions

The internal calculations of this API ensure that the hardware will not be damaged by overload. These calculations are based on the operating conditions given to SetLimits() or SetFixedCurrent():

  • Supply voltage for the Strobe Unit
  • Load voltage while the output is active with the maximum allowed current
  • Maximum ON-time to be used
  • Minimum allowed OFF-time between pulses
  • Maximum allowed output current for SetLimits() or fixed current for SetFixedCurrent()
Warning
In the case of wrong parameters the hardware can be damaged!

For VisionBox / VisionCam hardware with integrated LED controllers, the supply voltage for the strobe unit is equal to the power supply voltage used.

With the information provided to the functions, the library calculates the allowed parameters for maximum allowed output power. When using SetLimits(), the parameter LimitCurrent specifies if the API should limit the minimum allowed OFF-time between pulses, or if the current will be adjusted to avoid overload. SetFixedCurrent() will always limit the minimum OFF-time.

During operation, the FPGA ensures that the maximum ON-time is not exceeded and that the minimum OFF-time is not undercut. Trigger signals will be ignored under such conditions.

The following calculator can be used to estimate the results for SetFixedCurrent() and SetLimits() depending on the hardware and operating conditions:

Calculator
V
V
µs
µs (use 0 to allow steady ON state)
mA
SetFixedCurrent(): Min. OFF time: Code: SetFixedCurrent(...)
SetLimits(0, ...): Min. OFF time: Code: SetLimits(...)
SetLimits(1, ...): Max. current: Code: SetLimits(...)

Maximizing output power

  • A lower difference between the supply voltage and the maximum load voltage reduces power losses. Make sure that the values given to SetLimits() are close to real values. If the difference between both values gets smaller than reality, the hardware can be damaged!
  • If the difference between the supply voltage and the load voltage is small, set a fixed operating point by using SetFixedCurrent() instead of using SetLimits().

Using sequences of pulses

Consider the following sequence of output pulses:

When using the original firmware, a pause of MinOffTime is required after each pulse. The timing parameters have to be adjusted as follows:

  • MaxOnTime: 1 ms
  • MinOffTime: 1 ms

This results in a duty cycle of 0.5. The calculated power losses do not account for the longer pause time for each period.

With newer firmware versions it is possible to add up both parameters across multiple pulses. In the example above, we can use the sum for one time period between position 2 ms and 10 ms:

  • MaxOnTime: 2 ms
  • MinOffTime: 6 ms

The resulting duty cycle is now 0.25, which allows the use of higher output currents under the same conditions. The user could also decide to add up the values for multiple periods. But please note that higher absolute time values will also reduce the maximum output current.

Note
This feature requires firmware version ≥ 1.0.0.22.

Public Types

enum  STROBE_MODE
 Mode definitions for the strobe unit, used by SetTriggerMode() More...
 
enum  STROBE_OUTPUT_TYPE
 Type definitions for setting the output channel of the Strobe unit, used by SetOutputType() More...
 
enum  STROBE_SOURCE
 Trigger source definitions for the strobe unit, used by SetTriggerSource() More...
 

Public Member Functions

bool Calibrate (char LogText[20 *1024])
 Calibrates the strobe unit More...
 
bool GetCurrent (int &Current)
 Gets the current value of the strobe output. More...
 
bool GetLimits (unsigned int &MaxOnTime, unsigned int &MinOffTime, unsigned int &MaxCurrent)
 Returns the power related limits currently used. More...
 
bool GetOnTime (int &OnTime)
 Returns the ON-time of the strobe output. More...
 
bool GetOutputType (STROBE_OUTPUT_TYPE &OutputType)
 Return the OutputType of the Strobe unit. More...
 
bool GetTemp (unsigned short &Temp)
 Reads temperature of the FlashBox Strobe unit. More...
 
bool GetTriggerDelay (int &TriggerDelay)
 Returns the trigger delay. More...
 
bool GetTriggerMode (int &TriggerMode)
 Returns the trigger mode. More...
 
bool GetTriggerSource (STROBE_SOURCE &TriggerSource, int &InvertTrigger)
 Returns the trigger source. More...
 
bool GetVoltage (int &Voltage)
 Returns the voltage value of the strobe output. More...
 
bool Init (bool ResetParameter=true)
 Initializes the Strobe unit. More...
 
bool SetCurrent (int Current, int Validate=0)
 Sets the current value of the strobe output. More...
 
bool SetFixedCurrent (int SupplyVoltage, int LoadVoltage, unsigned int MaxOnTime, unsigned int MinOffTime, unsigned int Current, int &Result)
 Sets a fixed operating point for the strobe output. More...
 
bool SetLimits (int LimitCurrent, int MaxSupplyVoltage, int MaxLoadVoltage, unsigned int MaxOnTime, unsigned int MinOffTime, unsigned int MaxCurrent, int &Result)
 Calculates the minimum permitted OFF-time or the maximum permitted current. More...
 
bool SetOnTime (unsigned int OnTime)
 Sets the ON-time of the strobe output for edge triggered modes. More...
 
bool SetOutputType (STROBE_OUTPUT_TYPE OutputType)
 Selects the output channel for the Strobe unit. More...
 
bool SetTriggerDelay (unsigned int TriggerDelay)
 Sets the trigger delay. More...
 
bool SetTriggerMode (STROBE_MODE TriggerMode, int &Result)
 Sets the trigger mode. More...
 
bool SetTriggerSource (STROBE_SOURCE TriggerSource, int InvertTrigger)
 Sets the trigger source for hardware triggered modes. More...
 
 Strobe ()
 Default constructor for the device object More...
 
bool SwTrigger (int Value)
 Sets the trigger signal for software triggered and manual mode. 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...
 

Member Enumeration Documentation

◆ STROBE_MODE

Mode definitions for the strobe unit, used by SetTriggerMode()

Enumerator
STROBE_MODE_SOFTWARE_EDGE 

Software triggered.

STROBE_MODE_SOFTWARE_COPY 

Manual ON/OFF by Software.

STROBE_MODE_HARDWARE_EDGE 

Hardware triggered by edge.

STROBE_MODE_HARDWARE_COPY 

Hardware triggered by level.

◆ STROBE_OUTPUT_TYPE

Type definitions for setting the output channel of the Strobe unit, used by SetOutputType()

Enumerator
STROBE_OUTPUT_TYPE_OFF 

The LED voltage is disconnected.

STROBE_OUTPUT_TYPE_DEFAULT 

Sets the default value.

STROBE_OUTPUT_TYPE_EXTERNAL 

External connectors are used (default)

STROBE_OUTPUT_TYPE_INTERNAL 

The internal ring light is used (only valid for the VisionCam XM)

◆ STROBE_SOURCE

Trigger source definitions for the strobe unit, used by SetTriggerSource()

Note
The VisionBox AGE-X1 doesn't have a Multiplexer and therefore uses different source signals than new hardware generations.
Enumerator
STROBE_SOURCE_MUX_OUT0 

Multiplexer Output 0.

STROBE_SOURCE_MUX_OUT1 

Multiplexer Output 1.

STROBE_SOURCE_MUX_OUT2 

Multiplexer Output 2.

STROBE_SOURCE_MUX_OUT3 

Multiplexer Output 3.

STROBE_SOURCE_MUX_OUT4 

Multiplexer Output 4.

STROBE_SOURCE_MUX_OUT5 

Multiplexer Output 5.

STROBE_SOURCE_MUX_OUT6 

Multiplexer Output 6.

STROBE_SOURCE_MUX_OUT7 

Multiplexer Output 7.

STROBE_SOURCE_MUX_OUT8 

Multiplexer Output 8.

STROBE_SOURCE_MUX_OUT9 

Multiplexer Output 9.

STROBE_SOURCE_MUX_OUT10 

Multiplexer Output 10.

STROBE_SOURCE_MUX_OUT11 

Multiplexer Output 11.

STROBE_SOURCE_MUX_OUT12 

Multiplexer Output 12.

STROBE_SOURCE_MUX_OUT13 

Multiplexer Output 13.

STROBE_SOURCE_MUX_OUT14 

Multiplexer Output 14.

STROBE_SOURCE_MUX_OUT15 

Multiplexer Output 15.

STROBE_SOURCE_MUX_OUT16 

Multiplexer Output 16.

STROBE_SOURCE_MUX_OUT17 

Multiplexer Output 17.

STROBE_SOURCE_MUX_OUT18 

Multiplexer Output 18.

STROBE_SOURCE_MUX_OUT19 

Multiplexer Output 19.

STROBE_SOURCE_MUX_OUT20 

Multiplexer Output 20.

STROBE_SOURCE_MUX_OUT21 

Multiplexer Output 21.

STROBE_SOURCE_MUX_OUT22 

Multiplexer Output 22.

STROBE_SOURCE_MUX_OUT23 

Multiplexer Output 23.

STROBE_SOURCE_DIG_IN0 

Digital input 0 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN1 

Digital input 1 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN2 

Digital input 2 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN3 

Digital input 3 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN4 

Digital input 4 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN5 

Digital input 5 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN6 

Digital input 6 (VisionBox AGE-X1 only)

STROBE_SOURCE_DIG_IN7 

Digital input 7 (VisionBox AGE-X1 only)

STROBE_SOURCE_RS422_IN0 

RS422 input 0 (VisionBox AGE-X1 only)

STROBE_SOURCE_RS422_IN1 

RS422 input 1 (VisionBox AGE-X1 only)

STROBE_SOURCE_RS422_IN2 

RS422 input 2 (VisionBox AGE-X1 only)

STROBE_SOURCE_TRIGGEN_OUT0 

Trigger Generator output 0 (VisionBox AGE-X1 only)

STROBE_SOURCE_TRIGGEN_OUT1 

Trigger Generator output 1 (VisionBox AGE-X1 only)

STROBE_SOURCE_TRIGGEN_OUT2 

Trigger Generator output 2 (VisionBox AGE-X1 only)

STROBE_SOURCE_TRIGGEN_OUT3 

Trigger Generator output 3 (VisionBox AGE-X1 only)

Constructor & Destructor Documentation

◆ Strobe()

VIB::Strobe::Strobe ( )

Default constructor for the device object

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

Member Function Documentation

◆ Calibrate()

bool VIB::Strobe::Calibrate ( char  LogText[20 *1024])

Calibrates the strobe unit

Calibration of the strobe unit is normally not required because the hardware is delivered calibrated.

Connect a zero Ohm bridge between the LED+ and LED- terminals before calling this function.
After success, the calibration values are stored permanently.

Returns
Text containing the calibration result data
Parameters
LogTextText containing the calibration result data
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetCurrent()

bool VIB::Strobe::GetCurrent ( int &  Current)

Gets the current value of the strobe output.

Parameters
Current≥ 0: Current in mA
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetLimits()

bool VIB::Strobe::GetLimits ( unsigned int &  MaxOnTime,
unsigned int &  MinOffTime,
unsigned int &  MaxCurrent 
)

Returns the power related limits currently used.

Parameters
MaxOnTimeMaximum allowed ON-time (µs)
MinOffTimeMinimum allowed OFF-time (µs)
MaxCurrentMaximum allowed current (mA)
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetOnTime()

bool VIB::Strobe::GetOnTime ( int &  OnTime)

Returns the ON-time of the strobe output.

Parameters
OnTime> 0: ON-time in µs
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetOutputType()

bool VIB::Strobe::GetOutputType ( STROBE_OUTPUT_TYPE OutputType)

Return the OutputType of the Strobe unit.

Parameters
OutputTypeThe current used sink type
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetTemp()

bool VIB::Strobe::GetTemp ( unsigned short &  Temp)

Reads temperature of the FlashBox Strobe unit.

Parameters
TempTemperature in °C
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetTriggerDelay()

bool VIB::Strobe::GetTriggerDelay ( int &  TriggerDelay)

Returns the trigger delay.

Parameters
TriggerDelay≥ 0: Trigger delay in µs
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetTriggerMode()

bool VIB::Strobe::GetTriggerMode ( int &  TriggerMode)

Returns the trigger mode.

Parameters
TriggerMode≥ 0: Trigger mode (see STROBE_MODE)
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetTriggerSource()

bool VIB::Strobe::GetTriggerSource ( STROBE_SOURCE TriggerSource,
int &  InvertTrigger 
)

Returns the trigger source.

Parameters
TriggerSourceTrigger source
InvertTriggerPolarity of the trigger signal
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ GetVoltage()

bool VIB::Strobe::GetVoltage ( int &  Voltage)

Returns the voltage value of the strobe output.

Parameters
Voltage≥ 0: Voltage in mV
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ Init()

bool VIB::Strobe::Init ( bool  ResetParameter = true)

Initializes the Strobe unit.

Parameters
ResetParameterThe parameter is ignored, the strobe unit is always reset to default settings
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetCurrent()

bool VIB::Strobe::SetCurrent ( int  Current,
int  Validate = 0 
)

Sets the current value of the strobe output.

If the Validate parameter is set to 0, the characteristics value of the analog strobe circuit stored within an EEPROM is used without validation.
The Validate parameter can be set to 1 in order to measure and adjust the current. The deviation of the desired current can be minimized in this mode. If the deviation is too high, this function will return with an error. The strobe output is activated multiple times for 200 µs at the given current when calling this function. Please note that the Max. ON-time parameter must be 200 µs or more in this mode.

Parameters
CurrentDesired current in mA
Validate0: Don't validate current
1: Validate current
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetFixedCurrent()

bool VIB::Strobe::SetFixedCurrent ( int  SupplyVoltage,
int  LoadVoltage,
unsigned int  MaxOnTime,
unsigned int  MinOffTime,
unsigned int  Current,
int &  Result 
)

Sets a fixed operating point for the strobe output.

This function can be used as an alternative to SetLimits() and SetCurrent(). It allows for higher output power, if the difference between SupplyVoltage and LoadVoltage is small.

The output current will be set to the specified value and this function returns the calculated minimum OFF-time. The current can't be changed with SetCurrent() after calling this function. But SetCurrent() can still be used with the same current value in order to validate the actual current.

Background: SetLimits() assumes a resistive load characteristic, which can lead to higher internal power losses at lower currents. Because the current can be decreased by the user, SetLimits() will calculate the limits based on the worst-case current.

Parameters
SupplyVoltageSupply voltage used for the strobe output:
ValueEffect
12...30 The actual power supply voltage used.
LoadVoltageThe voltage across the load when the output current is equal to Current
MaxOnTimeMaximum allowed ON-time in µs (max. ~ 4s)
MinOffTimeMinimum allowed OFF-time in µs (max. ~ 4s, use 0 to allow steady ON state)
CurrentOutput current in mA
Result≥ 0: Minimum allowed OFF-time (µs)
< 0: Error
Warning
In the case of wrong parameters the hardware can be damaged!
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description
Note
This function was introduced with library version 1.5.2.0.

◆ SetLimits()

bool VIB::Strobe::SetLimits ( int  LimitCurrent,
int  SupplyVoltage,
int  LoadVoltage,
unsigned int  MaxOnTime,
unsigned int  MinOffTime,
unsigned int  Current,
int &  Result 
)

Calculates the minimum permitted OFF-time or the maximum permitted current.

The operating parameters for the strobe output can be limited by the strobe unit or by the lighting hardware connected to the output. This function is be used to calculate and limit these parameters.

The MaxOnTime, MinOffTime and Current parameters should first be chosen by the user in a way, that the limits of the lighting unit are not exceeded.
Based on these parameters, this function ensures that the limits of the strobe unit are not exceeded. The parameter LimitCurrent controls whether the minimum OFF-time or the maximum current will be reduced.

If the strobe active time exceeds the maximum ON-time, the output will be turned off by the FPGA, until the inactive time reaches the minimum OFF-time.

Parameters
LimitCurrent0: Calculate the minimum allowed OFF-time
1: Calculate the maximum allowed current
SupplyVoltageSupply voltage used for the strobe output:
ValueEffect
12...30 The actual power supply voltage used.
-1 The worst case supply voltage is assumed to calculate the limits (30 V).
LoadVoltageThe load voltage when the output current is equal to Current (set to -1 to use worst-case value)
MaxOnTimeMaximum allowed ON-time in µs (max. ~ 4 s; set MinOffTime to 0 to allow steady ON state)
MinOffTimeMinimum allowed OFF-time in µs (max. ~ 4 s)
CurrentMaximum allowed output current in mA
ResultLimitCurrent = 0: New minimum allowed OFF-time (µs)
LimitCurrent = 1: New maximum allowed current (mA)
Warning
In the case of wrong parameters the hardware can be damaged!
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetOnTime()

bool VIB::Strobe::SetOnTime ( unsigned int  OnTime)

Sets the ON-time of the strobe output for edge triggered modes.

Parameters
OnTimeOn time in µs
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetOutputType()

bool VIB::Strobe::SetOutputType ( STROBE_OUTPUT_TYPE  OutputType)

Selects the output channel for the Strobe unit.

This function is primarily used by the VisionCam XM which can provide the LED current to the supply and I/O connector, or to the internal ring light (default).

Parameters
OutputTypeThe desired channel
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetTriggerDelay()

bool VIB::Strobe::SetTriggerDelay ( unsigned int  TriggerDelay)

Sets the trigger delay.

The trigger delay is only used in software triggered and edged triggered hardware mode.

Parameters
TriggerDelayDelay in µs (max. ~4s)
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetTriggerMode()

bool VIB::Strobe::SetTriggerMode ( STROBE_MODE  TriggerMode,
int &  Result 
)

Sets the trigger mode.

The strobe output can be triggered using four different modes:

  • Software triggered (STROBE_MODE_SOFTWARE_EDGE):
    The strobe output is activated by calling SwTrigger(1). The output will be reset after the ON-time has expired.
  • Manual Software (STROBE_MODE_SOFTWARE_COPY):
    The strobe output is set to ON/OFF by calling SwTrigger(1) / SwTrigger(0). If the minimum OFF-time is greater than 0, the mode will be set to software triggered instead.
  • Hardware by edge (STROBE_MODE_HARDWARE_EDGE):
    The strobe output is activated on rising (non-inverted) or falling (inverted) edge of the selected trigger signal. Polarity can be changed with SetTriggerSource(). The strobe output will be reset after the ON-time has expired.
  • Hardware by level (STROBE_MODE_HARDWARE_COPY):
    The strobe output is activated by the level of the external trigger input. If the minimum OFF-time is greater than 0, the trigger mode will be set to hardware by edge instead.
Parameters
TriggerModeDesired trigger mode
Result≥ 0: New trigger mode
< 0: Error
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SetTriggerSource()

bool VIB::Strobe::SetTriggerSource ( STROBE_SOURCE  TriggerSource,
int  InvertTrigger 
)

Sets the trigger source for hardware triggered modes.

Hardware triggered mode must be selected first with SetTriggerMode().

Parameters
TriggerSourceSelect the signal used as trigger source
InvertTriggerPolarity of the trigger signal
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description

◆ SwTrigger()

bool VIB::Strobe::SwTrigger ( int  Value)

Sets the trigger signal for software triggered and manual mode.

Parameters
Value1: Activates the strobe output
0: Deactivates the strobe output (only used in level/copy mode)
Returns
true for success, use VIBSystem::GetLastErrorString() for an error description
VIB::Strobe::SetOnTime
bool SetOnTime(unsigned int OnTime)
Sets the ON-time of the strobe output for edge triggered modes.
Definition: Strobe.cpp:408
VIB::Strobe::Init
bool Init(bool ResetParameter=true)
Initializes the Strobe unit.
Definition: Strobe.cpp:216
VIB::Strobe::SwTrigger
bool SwTrigger(int Value)
Sets the trigger signal for software triggered and manual mode.
Definition: Strobe.cpp:568
VIB::Strobe::SetFixedCurrent
bool SetFixedCurrent(int SupplyVoltage, int LoadVoltage, unsigned int MaxOnTime, unsigned int MinOffTime, unsigned int Current, int &Result)
Sets a fixed operating point for the strobe output.
Definition: Strobe.cpp:348
VIB::Strobe::SetTriggerMode
bool SetTriggerMode(STROBE_MODE TriggerMode, int &Result)
Sets the trigger mode.
Definition: Strobe.cpp:452
VIB::Strobe::STROBE_MODE_SOFTWARE_EDGE
@ STROBE_MODE_SOFTWARE_EDGE
Software triggered.
Definition: VIB_Interface.h:295
VIB::Strobe
This class controlls the LED Strobe Controller.
Definition: VIB_Interface.h:284
VIB::iDevice::Open
bool Open(unsigned int Index=0)
Opens a device
Definition: iDevice.cpp:109