When using the pylon Viewer, make sure the Polling option in the Features pane is selected:
Make sure the camera is idle, i.e., not capturing images.
If you haven't done so yet, connect the light devices and controllers.
Set the BslLightControlMode parameter to On.
Execute the BslLightControlEnumerateDevices command. This enables light device communication via GPIO line and assigns a light device ID.
If you have multiple light devices in your environment, set the BslLightDeviceSelector parameter to the device that you want to configure. Make sure the device is properly connected, i.e., the BslLightDeviceLastError parameter returns NoError.
If you use a Basler SLP Strobe Controller:
Set the BslLightDeviceControlMode parameter to specify how you want to control the light device. Every light can be controlled via current control (Current). For lights designed for a 12 VDC or 24 VDC connection, it is recommended to use voltage control (Voltage12V or Voltage24V).
Set the BslLightDeviceOperationMode parameter to Off.
Set the BslLightDeviceMaxCurrent parameter to the nominal current rating of your light in continuous operation (in mA).
NOTICE – Specifying a nominal current rating that is too high will damage your lights.
When using current control, make sure to specify a nominal current rating that your light can withstand.
Otherwise, your light will be damaged during operation.
Set the BslLightDeviceBrightness parameter to the desired brightness. A value of 100.0 corresponds to 100 % of the nominal current rating of your light device. 50 % reduces the current by a factor of 2. You can also set the brightness to more than 100 %. This is called overdriving.
Set the BslLightDeviceOperationMode parameter to the desired mode:
If you use a Basler Camera Light, the BslLightDeviceControlMode and BslLightDeviceMaxCurrent parameters are set automatically.
Every time you're switching from current to voltage or vice versa, there is a short initialization phase of the controller during which the connected light lights up. This can last for up to 15 s and is normal behavior.
The strobe mode allows you to operate a light device like a flash when needed instead of operating it continuously.
Using strobe mode has the following advantages:
It can help to increase the life expectancy of your lights. By operating the lights only when needed, less heat is generated in the LEDs. This slows down the aging process of the lights.
While in strobe mode, you can overdrive the lights, i.e., increase the current supplied to a maximum of 500 % (for the light controller), which increases the brightness of your lights.
To enable strobe mode, select a light device and set the BslLightDeviceOperationMode parameter to Strobe.
To configure the trigger signals and strobe duration on ace 2, boost R, and dart M cameras:
Set the BslLightControlTriggerSource parameter to the source that you want to use to turn on the connected lights, e.g., FlashWindow.
If applicable, set the BslLightControlTriggerActivation parameter to one of the following values:
RisingEdge (default): All connected lights are turned on when the signal rises, i.e., when the signal status changes from low to high.
FallingEdge: All connected lights are turned on when the signal falls, i.e., when the signal status changes from high to low.
AnyEdge: All connected lights are turned on when the signal falls or rises.
Set the BslLightDeviceStrobeMode parameter to one of the following values:
Automatic: The strobe duration is controlled by the camera's flash window duration (BslFlashWindowDuration parameter). The BslLightDeviceStrobeDuration parameter becomes read-only and displays the calculated strobe duration.
Manual: You can define the strobe duration yourself using the BslLightDeviceStrobeDuration parameter.
If you chose the Manual strobe mode, set the BslLightDeviceStrobeDuration parameter to the desired strobe duration (in microseconds).
Info
Don't use the Automatic strobe mode if you're using the Trigger Width exposure mode or the Exposure Auto auto function. Otherwise, the camera and the lights may show unpredictable behavior.
The Automatic strobe mode isn't available if you're using the Sequencer feature.
In Automatic strobe mode, the calculated strobe duration may be shorter than the flash window duration. This is done to compensate for the time it takes for the light to be turned on, i.e., the turn-on delay.
If you're operating the camera at the upper end of its capabilities, overtriggering may occur.
To configure the trigger signals and strobe duration on ace U/L cameras:
If you're using a rolling shutter camera, set the BslLightControlTriggerMode parameter to one of the following values:
ExposureActive: All connected lights are turned on when exposure starts. Use this mode only if you're not overlapping image acquisitions.
FlashWindow: All connected lights are turned on when the camera's Flash Window signal rises. If you use this mode, make sure that the Flash Window signal is available for your camera model.
On global shutter cameras, all connected lights are always turned on when exposure starts.
Set the BslLightDeviceStrobeMode parameter to one of the following values:
Automatic: The strobe duration is controlled by the ExposureTimeAbs parameter of the camera.
Manual: You can define the strobe duration yourself using the BslLightDeviceStrobeDuration parameter.
If you chose the Manual strobe mode, set the BslLightDeviceStrobeDuration parameter to the desired strobe duration.
Carefully read the instructions in this section to avoid damaging the connected lights and to ensure that the lights don't age prematurely.
Overdriving your light means that you can increase the current, resulting in a higher light intensity, while the light is in strobe mode.
To overdrive a light device:
If you're using a Basler Standard Light or a third-party light device:
Calculate the maximum allowed current for your device given the current duty cycle and strobe duration. On Basler ace 2, boost R, and dart M cameras, you can read the BslLightDeviceDutyCycle parameter to determine the current duty cycle.
Set the BslLightDeviceOverdriveLimit parameter accordingly. For example, if your light can withstand 200 % of its nominal current rating, set the overdrive limit to 200.0.
If you're using a Basler Camera Light, the overdrive limit is calculated automatically, and the BslLightDeviceOverdriveLimit parameter is not available.
Set the BslLightDeviceBrightness to a value greater than 100.0.
When overdriving, consider the following aspects to avoid damaging your light:
Check with the manufacturer of your light if you're not sure what the maximum current is that your light can withstand in strobe mode.
As the increased current flow will cause the LEDs to heat up more, you must allow sufficient time between individual strobe pulses for the light to cool down again. As a general rule of thumb, the higher the intensity of the pulse, the more time you should leave between pulses.
Consider the exposure time as this affects the length and the duty cycle of the pulses.
On Basler Camera Lights, if the chosen brightness is too high in respect to the strobe duration and the duty cycle, the strobe duration will be reduced or triggers will be ignored. See table below.
The camera communicates with the light devices via one of the camera's GPIO lines:
On ace 2, boost R, and dart M cameras, the camera always uses Line 3 for light communication. Accordingly, when the Light Control feature is enabled, the line mode of Line 3 is set to InOut and the line connection is set to LightControl.
On ace U/L cameras, the BslLightControlSource parameter shows which GPIO line the camera uses for light communication.
Every light device connected via SLP protocol has a light device ID. The ID is stored on the device.
Valid light device IDs are 1, 2, 3, 4, and 7. All devices are shipped with the ID set to 7 (factory setting).
When enumerating devices using the BslLightControlEnumerateDevices command, the camera automatically searches for a device with its ID set to 7 and assigns the next available ID between 1 and 4 to it.
When using more than one light device, you must make sure that their IDs are all different. Using devices with identical IDs causes communication errors.
Example 1: Assume you connect a new light device and enumerate devices. The camera assigns ID 1 to the device. Then, you disconnect the device, connect the next light device, and enumerate devices again. The camera also assigns ID 1 to this device.
Example 2: Assume you connect two new light devices and enumerate devices. The camera finds two devices with their ID set to 7 and assigns the next available ID to each, which is 1.
In both examples, when you connect both light devices to the camera, communication errors will occur. You must change one of the IDs to resolve the conflict.
Tip
The best way to prevent conflicts is to connect devices one after the other and always assign a new and unique ID after having connected a device.
Set the BslLightDeviceOperationMode parameter to Off.
Set the BslLightDeviceSelector parameter to the Basler light device whose ID you want to change.
Set the BslLightDeviceChangeID parameter to the desired ID, e.g., Device1. On ace U/L cameras, the ID is changed immediately.
On ace 2, boost R, and dart M cameras, execute the BslLightDeviceNewIDSave command.
Considerations When Using the Light Control Feature#
When the BslLightControlMode is set to On, the Serial Communication feature is disabled. This is because the Light Control feature also uses serial communication.
Basler Camera Lights use pulse width modulation (PWM), the Basler SLP Strobe Controller doesn't. If you're using very short exposure times (<500 µs) and a brightness value other than 100 %, PWM can lead to brightness fluctuations or to stripes in rolling shutter cameras.
Avoid using very short Flash Window signals. Otherwise, some lines in the resulting images may be too bright while others are too dark.
When setting the BslLightControlMode parameter to On, there is a delay of up to 1 second until the light device is actually turned on. Because of this, the first image may be too dark. Either discard this image, or, if you need all images, start image acquisition after a suitable delay.
When overdriving a Basler Camera Light, don't operate the camera at more than 60 frames per second. Otherwise, the camera and the lights may show unpredictable behavior.
Basler ace 2, boost R, and dart M cameras: When loading the light device settings from a user set, the settings are only applied after executing the BslLightControlEnumerateDevices command.
If you're operating the camera at the upper end of its capabilities, overtriggering of the light device may occur. Overtriggering means that the light device receives a trigger while it isn't ready for it, e.g., because it is still in the process of switching off the light. This would mean that the trigger is ignored and the light would not come on for the next exposure.
To better understand this problem, consider the following example.
A camera that is capable of 100 fps is operated with the exposure time set to 50 ms. Therefore, the camera acquires 20 frames per second in quick succession without any pause between the exposures. This means that the trigger for the light device would have to come exactly at the edge between two exposures.
In practice, this is almost impossible because of an inherent jitter that causes the trigger to sometimes arrive while the light is still switching off. In those cases, the trigger will be ignored and the resulting image will be too dark.
Because the jitter is irregular, there is no precise method to prevent this happening. If you notice that some of your images are darker than the others, consider operating the light in continuous mode. You could also try adjusting the frame rate using the Acquisition Frame Rate feature.
On ace 2, boost R, and dart M cameras, the BslLightControlOvertriggerCount parameter is available. It allows you to monitor how many trigger signals were sent while at least one of the connected light devices wasn't ready for it.
Example: Assume 4 light devices are connected to your camera. You send a trigger signal while 3 of the devices aren't ready for it. As a result, the BslLightControlOvertriggerCount parameter increases by 1.
The parameter counts up to a maximum value of 65 535. Then, it stops counting.
To reset the overtrigger counter, execute the BslLightControlOvertriggerCountReset command.
The BslLightDeviceErrorStatus parameter can take the following values:
Value
Meaning
Communication Error
A communication error occurs if the data transmission between the light device and the camera is faulty. This can be caused by using cables that are too long or by too much noise on the line.
Connection Lost
The connection to a previously connected light device has been lost. This can happen, for example, if a cable has become loose.
Hardware Error
The light device is experiencing a technical fault. For more information about the kind of hardware error, execute the BslLightDeviceErrorStatusReadAndClear command to retrieve an error code.a
Light Device Error
The light device is experiencing an internal error.a
No Error
No error was detected.
Not Connected
The light device is not connected to the camera or has not been enumerated yet. Execute the BslLightControlEnumerateDevices command to enumerate the device.
Unsupported Device Version
The light device is not compatible with the current camera. Contact support to find out whether firmware updates are available.
Basler ace U/L cameras can read a list of errors from connected light devices.
Up to 25 errors can be stored. If a 26th error occurs, the oldest error will be overwritten and so on.
Checking and clearing errors is an iterative process, depending on how many errors have occurred.
To check and clear errors:
If you have several devices connected:
Check the BslLightControlErrorStatus parameter to find out which device is experiencing problems, e.g., Device2.
Set the BslLightDeviceSelector parameter to the device that is experiencing problems.
Get the value of the BslLightDeviceLastError parameter and look up its meaning in the table below.
Correct the corresponding error.
To delete the last error from the list of errors, execute the BslLightDeviceClearLastError command.
Continue getting and deleting the last error until the BslLightDeviceLastError parameter shows NoError.
Value
Meaning
Communication Error
A communication error occurs if the data transmission between the light device and the camera is faulty. This can be caused by using cables that are too long or by too much noise on the line.
Connection Error
A connection error occurs if the connection between the light device and the camera is broken or if a communication error has already occurred. Other reasons may be loose connections or the controller being disconnected completely.
Hardware Error
The light device is experiencing a technical fault.a
Insufficient Current
The light controller is unable to supply the requested current. Try lowering the LightDeviceMaxCurrent parameter value.
No Error
The light device hasn't detected any errors since the last time the error memory was cleared.
Short Circuit
There is a short circuit at the lighting connector of the light controller. This can be caused by a faulty light unit.
Disconnecting and reconnecting the power supply may solve the issue. To ensure power-cycling, the controller needs to be disconnected from electricity for five minutes. This is normal behavior. If you're using more than one controller, the other controllers must be power-cycled as well, even if they haven't experienced any faults.
// Enable the light control modecamera.BslLightControlMode.SetValue(BslLightControlMode_On);//Enumerate the light devicescamera.BslLightControlEnumerateDevices.Execute();//Select light device 1camera.BslLightDeviceSelector.SetValue(BslLightDeviceSelector_Device1);//Set the nominal current of device 1 to 100 mAcamera.BslLightDeviceCurrent.SetValue(100.0);//Set the brightness to 100 %camera.BslLightDeviceBrightness.SetValue(100.0);//Set the operation mode to Strobecamera.BslLightDeviceOperationMode.SetValue(BslLightDeviceOperationMode_Strobe);
INodeMap&nodemap=camera.GetNodeMap();// Enable the light control modeCEnumParameter(nodemap,"BslLightControlMode").SetValue("On");// Enumerate the light devicesCCommandParameter(nodemap,"BslLightControlEnumerateDevices").Execute();// Select light device 1CEnumParameter(nodemap,"BslLightDeviceSelector").SetValue("Device1");// Set the nominal current of device 1 to 100 mACFloatParameter(nodemap,"BslLightDeviceCurrent").SetValue(100.0);// Set the brightness to 100 %CFloatParameter(nodemap,"BslLightDeviceBrightness").SetValue(100.0);// Set the operation mode to StrobeCEnumParameter(nodemap,"BslLightDeviceOperationMode").SetValue("Strobe");
// Enable the light control modecamera.Parameters[PLCamera.BslLightControlMode].SetValue(PLCamera.BslLightControlMode.On);// Enumerate the light devicescamera.Parameters[PLCamera.BslLightControlEnumerateDevices].Execute();// Select light device 1camera.Parameters[PLCamera.BslLightDeviceSelector].SetValue(PLCamera.BslLightDeviceSelector.Device1);// Set the nominal current of device 1 to 100 mAcamera.Parameters[PLCamera.BslLightDeviceCurrent].SetValue(100.0);// Set the brightness to 100 %camera.Parameters[PLCamera.BslLightDeviceBrightness].SetValue(100.0);// Set the operation mode to Strobecamera.Parameters[PLCamera.BslLightDeviceOperationMode].SetValue(PLCamera.BslLightDeviceOperationMode.Strobe);
/* Macro to check for errors */#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)GENAPIC_RESULTerrRes=GENAPI_E_OK;/* Return value of pylon methods *//* Enable the light control mode */errRes=PylonDeviceFeatureFromString(hdev,"BslLightControlMode","On");CHECK(errRes);/* Enumerate the light devices */errRes=PylonDeviceExecuteCommandFeature(hdev,"BslLightControlEnumerateDevices");CHECK(errRes);/* Select light device 1 */errRes=PylonDeviceFeatureFromString(hdev,"BslLightDeviceSelector","Device1");CHECK(errRes);/* Set the nominal current of device 1 to 100 mA */errRes=PylonDeviceSetFloatFeature(hdev,"BslLightDeviceCurrent",100.0);CHECK(errRes);/* Set the brightness to 100 % */errRes=PylonDeviceSetFloatFeature(hdev,"BslLightDeviceBrightness",100.0);CHECK(errRes);/* Set the operation mode to Strobe */errRes=PylonDeviceFeatureFromString(hdev,"BslLightDeviceOperationMode","Strobe");CHECK(errRes);
# Enable the light control modecamera.BslLightControlMode.Value="On"# Enumerate the light devicescamera.BslLightControlEnumerateDevices.Execute()# Select light device 1camera.BslLightDeviceSelector.Value="Device1"# Set the nominal current of device 1 to 100 mAcamera.BslLightDeviceCurrent.Value=100.0# Set the brightness to 100 %camera.BslLightDeviceBrightness.Value=100.0# Set the operation mode to Strobecamera.BslLightDeviceOperationMode.Value="Strobe"
// Enable the light control modecamera.BslLightControlMode.SetValue(BslLightControlMode_On);//Enumerate the light devicescamera.BslLightControlEnumerateDevices.Execute();//Select light device 1camera.BslLightDeviceSelector.SetValue(BslLightDeviceSelector_Device1);//Set the nominal current of device 1 to 100 mAcamera.BslLightDeviceMaxCurrent.SetValue(100.0);//Set the brightness to 100 %camera.BslLightDeviceBrightness.SetValue(100.0);//Set the operation mode to Strobecamera.BslLightDeviceOperationMode.SetValue(BslLightDeviceOperationMode_Strobe);
INodeMap&nodemap=camera.GetNodeMap();// Enable the light control modeCEnumParameter(nodemap,"BslLightControlMode").SetValue("On");// Enumerate the light devicesCCommandParameter(nodemap,"BslLightControlEnumerateDevices").Execute();// Select light device 1CEnumParameter(nodemap,"BslLightDeviceSelector").SetValue("Device1");// Set the nominal current of device 1 to 100 mACFloatParameter(nodemap,"BslLightDeviceMaxCurrent").SetValue(100.0);// Set the brightness to 100 %CFloatParameter(nodemap,"BslLightDeviceBrightness").SetValue(100.0);// Set the operation mode to StrobeCEnumParameter(nodemap,"BslLightDeviceOperationMode").SetValue("Strobe");
// Enable the light control modecamera.Parameters[PLCamera.BslLightControlMode].SetValue(PLCamera.BslLightControlMode.On);// Enumerate the light devicescamera.Parameters[PLCamera.BslLightControlEnumerateDevices].Execute();// Select light device 1camera.Parameters[PLCamera.BslLightDeviceSelector].SetValue(PLCamera.BslLightDeviceSelector.Device1);// Set the nominal current of device 1 to 100 mAcamera.Parameters[PLCamera.BslLightDeviceMaxCurrent].SetValue(100.0);// Set the brightness to 100 %camera.Parameters[PLCamera.BslLightDeviceBrightness].SetValue(100.0);// Set the operation mode to Strobecamera.Parameters[PLCamera.BslLightDeviceOperationMode].SetValue(PLCamera.BslLightDeviceOperationMode.Strobe);
/* Macro to check for errors */#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)GENAPIC_RESULTerrRes=GENAPI_E_OK;/* Return value of pylon methods *//* Enable the light control mode */errRes=PylonDeviceFeatureFromString(hdev,"BslLightControlMode","On");CHECK(errRes);/* Enumerate the light devices */errRes=PylonDeviceExecuteCommandFeature(hdev,"BslLightControlEnumerateDevices");CHECK(errRes);/* Select light device 1 */errRes=PylonDeviceFeatureFromString(hdev,"BslLightDeviceSelector","Device1");CHECK(errRes);/* Set the nominal current of device 1 to 100 mA */errRes=PylonDeviceSetFloatFeature(hdev,"BslLightDeviceMaxCurrent",100.0);CHECK(errRes);/* Set the brightness to 100 % */errRes=PylonDeviceSetFloatFeature(hdev,"BslLightDeviceBrightness",100.0);CHECK(errRes);/* Set the operation mode to Strobe */errRes=PylonDeviceFeatureFromString(hdev,"BslLightDeviceOperationMode","Strobe");CHECK(errRes);
# Enable the light control modecamera.BslLightControlMode.Value="On"# Enumerate the light devicescamera.BslLightControlEnumerateDevices.Execute()# Select light device 1camera.BslLightDeviceSelector.Value="Device1"# Set the nominal current of device 1 to 100 mAcamera.BslLightDeviceMaxCurrent.Value=100.0# Set the brightness to 100 %camera.BslLightDeviceBrightness.Value=100.0# Set the operation mode to Strobecamera.BslLightDeviceOperationMode.Value="Strobe"