Light Control Feature Set#
The Light Control feature set is based on the SLP protocol that enables cameras and light devices to communicate directly with each other. A light device can be a third-party light or a light from the Basler Camera Light portfolio. If you want to use a third-party light, you need the Basler SLP Strobe Controller to enable the communication between the camera and the light. If you choose a Basler light, a separate controller is not required as the controller features are already included. Both options are plug-and-play.
Using the Feature#
Configuring the Basler Light / Light Controller#
- If you haven't done so yet, connect the controller and the light.
- Enable the Polling option in the pylon Viewer.
- Set the
BslLightControlSourceparameter will show which GPIO line of the camera is used to control the light features.
If you're connecting a new controller, it will automatically be assigned the next available light device ID.
- Execute the
- If you have several Basler lights or light controllers in your environment, set the
BslLightDeviceSelectorparameter to the device that you want to configure.
Make sure that there are no light device ID conflicts.
If you use a Basler SLP Strobe Controller, specify whether you want to control the light device using current or voltage via the
BslLightDeviceControlModeparameter. Every light can be controlled via current control. For lights designed for a 12 V or 24 V connection, it is recommended to use voltage control. If you use a Basler Camera Light, you can skip this step. The parameter is set automatically in this case.
Note that 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.
If you use a Basler SLP Strobe Controller, set the
BslLightDeviceMaxCurrentparameter to the maximum current rating of your light in continuous operation.
If you use a Basler Camera Light, the maximum current is set automatically.
This ensures that your light will not get damaged and that you can safely use the whole current range of your light using the
You can only change the
BslLightDeviceMaxCurrentparameter value, when the
BslLightDeviceOperationModeparameter is set to
- Set the
BslLightDeviceBrightnessparameter to the desired brightness.
This parameter can be set in a range from 0 to 100 %. 100 % corresponds to the current that you have specified with the
BslLightDeviceMaxCurrentparameter. 50 % will reduce the current by a factor of 2. The Basler Camera Light uses pulse width modulation (PWM), the Basler SLP Strobe Controller doesn't. PWM can lead to brightness fluctuations for short exposure times (< 500 µs) or to stripes in rolling shutter cameras.
- Set the
BslLightDeviceOperationModeparameter to the desired mode:
On: This will make the light shine continuously.
Strobe: This will set the light to strobe mode. You can configure the strobe mode with the
Configuring the Strobe Mode#
One of the advantages of the strobe mode is that it can help to increase the life expectancy of your light. By not operating it continuously but like a flash when needed, less heat is generated in the LEDs. This slows down the aging process of the lights. The other advantage is that 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 light. Before you do so, read the instructions in the Overdrive Mode section.
On rolling shutter cameras, if you have set the
BslLightDeviceOperationMode parameter to
Strobe, use the
BslLightControlTriggerMode parameter to determine how to trigger the light. Different trigger modes are available:
ExposureActive: Use this mode only if you're not overlapping image acquisitions.
FlashWindow: If you use this mode, make sure that the camera generates a Flash Window signal.
On global shutter cameras, the trigger mode is preset.
There is a delay of approx. 23 µs between exposure start and the light being turned on.
The implementation of the Flash Window signal in connection with the Light Control feature set is still under development. Especially with very short Flash Window signals, the results may not be satisfactory (some lines in the resulting images may be too bright while others are too dark).
To control the duration of the individual strobe pulses, you have to specify whether you want automatic or manual strobe operation using the
Automatic: The duration of the individual strobe pulses is controlled by the
ExposureTimeparameter of the camera. The strobe lasts for the duration of the exposure time that you have specified. For more information, see the Troubleshooting section.
Manual: You can define the duration of the individual strobe pulses yourself using the
BslLightDeviceStrobeDurationparameter. If you're operating the camera at the upper end of its capabilities, overtriggering may occur.
The camera uses the same line for triggering the light and transmitting any changes of light control parameter settings. As parameter changes take precedence, during this time the line will not be available for the trigger signal and strobe operation will be disrupted. To avoid this, check the
BslLightControlStatus. If the value is
Ready, it means that the light device is ready to receive a trigger. Alternatively, only change parameter settings while the strobe mode is disabled.
Overdriving your light means that you can increase the current, resulting in a higher light intensity, while the light is in strobe mode.
NOTICE – Incorrect operation may damage your lights.
Carefully read the instructions in this section to avoid damaging the connected lights and to ensure that the lights don't age prematurely.
When using the overdrive mode, you have to consider the following aspects to avoid damaging your light:
- In strobe mode, the
BslLightDeviceBrightnessparameter can be set to values above 100 %. The maximum value depends on the strobe pulse duration and the duty cycle. For Basler Camera Lights, the maximum allowed brightness is calculated automatically and the range of the brightness slider will be adjusted accordingly. When using a third-party light and the Basler SLP Strobe Controller, you have to calculate the maximum brightness value yourself and enter this value in the
BslLightDeviceOverdriveLimitparameter. For example, 200 % means that the maximum current in strobe operation will be twice as high as the
- 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. The Basler SLP Strobe Controller allows setting the
BslLightDeviceOverdriveLimitparameter to 500 % but most lights are not able to withstand the currents that would result from this overdrive limit.
- As the increased current flow will cause the LEDs to heat up more, you have to 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.
Safety features that avoid damaging the controller hardware.
- Currents above 2 A in combination with long exposure times and high duty cycles may damage the controller hardware. In order to avoid this, the maximum allowed current is calculated automatically and the maximum allowed brightness is reduced accordingly (see Table 1 below).
The duty cycle calculation is based on the maximum possible frame rate of the camera. The maximum possible frame rate of the camera can be reduced by using the Acquisition Frame Rate feature.
Safety features that avoid damaging the light.
- If the chosen overdrive brightness is too high in respect to the strobe duration and the duty cycle (see Table 2), the strobe duration will be reduced or triggers will be ignored.
Table 1 (Controller Protection)#
|Output Current |
|Max. Strobe Duration||Max. Duty Cycle|
|Under 2 A||-||100 %|
|2 A to <3 A||5 ms||15 %|
|3 A to <4 A||5 ms||8 %|
|4 A to <5 A||5 ms||6 %|
|5 A to <6 A||5 ms||4 %|
|6 A to <8 A||1 ms||4 %|
|8 A to <9 A||1 ms||3 %|
|9 A to <10 A||1 ms||2 %|
Table 2 (Light Protection)#
|Required Brightness||Max. Strobe Duration||Max. Duty Cycle|
|0–100 %||-||100 %|
|101–200 %||30 ms||30 %|
|201–300 %||10 ms||20 %|
|301–500 %||2 ms||10 %|
|501–1000 %||1 ms||5 %|
Changing the Light Device ID#
To change the ID of a light:
- Set the
- Set the
- Set the
BslLightDeviceSelectorparameter to the Basler light / controller whose ID you want to change.
- Set the
BslLightDeviceChangeIDparameter to the desired value.
The ID will be changed immediately.
Using More Than One Light Device or Basler Camera Light
When using more than one light device, you have to make sure that their IDs are all different. Using devices with identical IDs will cause communication errors. Duplicate IDs can occur, if you're connecting new devices for the first time because all devices are shipped with the light device ID set to 7. It can also occur when connecting existing devices from another system as light device IDs are remembered by the device once they have been set. 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.
Checking and Clearing Errors#
The light / light controller can detect errors that you can correct yourself. Check the
BslLightDeviceLastError parameter to find out which error has occurred. After you have corrected the error, you can clear it from the list.
Up to 25 errors can be stored. If a 26th error occurs, the oldest error will be overwritten and so on.
If you have several lights / light controllers connected, the
BslLightControlErrorStatus tells you which device is experiencing problems.
Checking and clearing errors is an iterative process, depending on how many errors have occurred.
To check and clear errors:
- To check the last error that has occurred, get the value of the
- Correct the corresponding error.
- To delete the last error from the list of errors, execute the
- Continue getting and deleting the last error until the
Available Error Codes
|No Error||The light / light controller hasn't detected any errors since the last time the error memory was cleared.|
|Communication Error||A communication error occurs if the data transmission between the light / light controller 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 / light controller 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 / light controller is experiencing a technical fault. Disconnecting and reconnecting the power supply may solve the issue. See Power-Cycling the Controller for more information.|
Overtriggering in Automatic Strobe Mode#
If you're operating the camera at the upper end of its capabilities, overtriggering of the light / light controller may occur. Overtriggering means that the light / light controller 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, i.e., the camera would acquire 20 frames per second in quick succession without any pause between the exposures. This means that the trigger for the light / light controller 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 if operating the light in continuous mode is an option. You could also try adjusting the frame rate, e.g., using 19 fps instead of 20 fps.
Power-Cycling the Controller#
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 need to be power-cycled as well even if they haven't experienced any faults.
First Image 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, only start image acquisition after a suitable delay, e.g., by using a timer.
|Camera Model||Available Light Control Trigger Modes|
|a2A1920-51gcBAS||Feature not supported|
|a2A1920-51gcPRO||Feature not supported|
|a2A1920-51gmBAS||Feature not supported|
|a2A1920-51gmPRO||Feature not supported|
|a2A1920-160ucBAS||Feature not supported|
|a2A1920-160ucPRO||Feature not supported|
|a2A1920-160umBAS||Feature not supported|
|a2A1920-160umPRO||Feature not supported|
|a2A2590-22gcBAS||Feature not supported|
|a2A2590-22gcPRO||Feature not supported|
|a2A2590-22gmBAS||Feature not supported|
|a2A2590-22gmPRO||Feature not supported|
|a2A2590-60ucBAS||Feature not supported|
|a2A2590-60ucPRO||Feature not supported|
|a2A2590-60umBAS||Feature not supported|
|a2A2590-60umPRO||Feature not supported|
|a2A3840-13gcBAS||Feature not supported|
|a2A3840-13gcPRO||Feature not supported|
|a2A3840-13gmBAS||Feature not supported|
|a2A3840-13gmPRO||Feature not supported|
|a2A3840-45ucBAS||Feature not supported|
|a2A3840-45ucPRO||Feature not supported|
|a2A3840-45umBAS||Feature not supported|
|a2A3840-45umPRO||Feature not supported|
|a2A4504-5gcBAS||Feature not supported|
|a2A4504-5gcPRO||Feature not supported|
|a2A4504-5gmBAS||Feature not supported|
|a2A4504-5gmPRO||Feature not supported|
|a2A4504-18ucBAS||Feature not supported|
|a2A4504-18ucPRO||Feature not supported|
|a2A4504-18umBAS||Feature not supported|
|a2A4504-18umPRO||Feature not supported|
|a2A5320-7gcBAS||Feature not supported|
|a2A5320-7gcPRO||Feature not supported|
|a2A5320-7gmBAS||Feature not supported|
|a2A5320-7gmPRO||Feature not supported|
|a2A5320-23ucBAS||Feature not supported|
|a2A5320-23ucPRO||Feature not supported|
|a2A5320-23umBAS||Feature not supported|
|a2A5320-23umPRO||Feature not supported|
|a2A5328-4gcBAS||Feature not supported|
|a2A5328-4gcPRO||Feature not supported|
|a2A5328-4gmBAS||Feature not supported|
|a2A5328-4gmPRO||Feature not supported|
|a2A5328-15ucBAS||Feature not supported|
|a2A5328-15ucPRO||Feature not supported|
|a2A5328-15umBAS||Feature not supported|
|a2A5328-15umPRO||Feature not supported|
|acA640-90gc||Feature not supported|
|acA640-90gm||Feature not supported|
|acA640-90uc||Feature not supported|
|acA640-90um||Feature not supported|
|acA640-120gc||Feature not supported|
|acA640-120gm||Feature not supported|
|acA640-120uc||Feature not supported|
|acA640-120um||Feature not supported|
|acA640-121gm||Feature not supported|
|acA780-75gc||Feature not supported|
|acA780-75gm||Feature not supported|
|acA1280-60gc||Feature not supported|
|acA1280-60gm||Feature not supported|
|acA1300-22gc||Feature not supported|
|acA1300-22gm||Feature not supported|
|acA1300-30gc||Feature not supported|
|acA1300-30gm||Feature not supported|
|acA1300-30uc||Feature not supported|
|acA1300-30um||Feature not supported|
|acA1300-60gc||Feature not supported|
|acA1300-60gm||Feature not supported|
|acA1300-60gmNIR||Feature not supported|
|acA1600-20gc||Feature not supported|
|acA1600-20gm||Feature not supported|
|acA1600-20uc||Feature not supported|
|acA1600-20um||Feature not supported|
|acA1600-60gc||Feature not supported|
|acA1600-60gm||Feature not supported|
|acA1920-25gc||Feature not supported|
|acA1920-25gm||Feature not supported|
|acA1920-25uc||Feature not supported|
|acA1920-25um||Feature not supported|
|acA1920-40ucMED||Feature not supported|
|acA1920-40umMED||Feature not supported|
|acA1920-155ucMED||Feature not supported|
|acA1920-155umMED||Feature not supported|
|acA2000-50gc||Feature not supported|
|acA2000-50gm||Feature not supported|
|acA2000-50gmNIR||Feature not supported|
|acA2000-165uc||Feature not supported|
|acA2000-165um||Feature not supported|
|acA2000-165umNIR||Feature not supported|
|acA2040-25gc||Feature not supported|
|acA2040-25gm||Feature not supported|
|acA2040-25gmNIR||Feature not supported|
|acA2040-90uc||Feature not supported|
|acA2040-90um||Feature not supported|
|acA2040-90umNIR||Feature not supported|
|acA2440-35ucMED||Feature not supported|
|acA2440-35umMED||Feature not supported|
|acA2440-75ucMED||Feature not supported|
|acA2440-75umMED||Feature not supported|
|acA2500-14gc||Feature not supported|
|acA2500-14gm||Feature not supported|
|acA2500-14uc||Feature not supported|
|acA2500-14um||Feature not supported|
|acA2500-20gcMED||Feature not supported|
|acA2500-20gmMED||Feature not supported|
|acA3088-16gc||Exposure Active |
|acA3088-16gm||Exposure Active |
|acA3088-57uc||Exposure Active |
|acA3088-57ucMED||Feature not supported|
|acA3088-57um||Exposure Active |
|acA3088-57umMED||Feature not supported|
|acA3800-10gc||Feature not supported|
|acA3800-10gm||Feature not supported|
|acA3800-14uc||Feature not supported|
|acA3800-14um||Feature not supported|
|acA4024-8gc||Exposure Active |
|acA4024-8gm||Exposure Active |
|acA4024-29uc||Exposure Active |
|acA4024-29um||Exposure Active |
|acA4096-30ucMED||Feature not supported|
|acA4096-30umMED||Feature not supported|
|acA4096-40ucMED||Feature not supported|
|acA4096-40umMED||Feature not supported|
|acA4112-20ucMED||Feature not supported|
|acA4112-20umMED||Feature not supported|
|acA4112-30ucMED||Feature not supported|
|acA4112-30umMED||Feature not supported|
|acA4600-7gc||Feature not supported|
|acA4600-10uc||Feature not supported|
|acA5472-5gc||Exposure Active |
|acA5472-5gm||Exposure Active |
|acA5472-17uc||Exposure Active |
|acA5472-17ucMED||Feature not supported|
|acA5472-17um||Exposure Active |
|acA5472-17umMED||Feature not supported|
|boA4096-93cc||Feature not supported|
|boA4096-93cm||Feature not supported|
|boA4112-68cc||Feature not supported|
|boA4112-68cm||Feature not supported|
|boA4500-45cc||Feature not supported|
|boA4500-45cm||Feature not supported|
|boA6500-36cc||Feature not supported|
|boA6500-36cm||Feature not supported|
|boA8100-16cc||Feature not supported|
|boA8100-16cm||Feature not supported|
|daA1280-54lc||Feature not supported|
|daA1280-54lm||Feature not supported|
|daA1280-54uc||Feature not supported|
|daA1280-54um||Feature not supported|
|daA1600-60lc||Feature not supported|
|daA1600-60lm||Feature not supported|
|daA1600-60uc||Feature not supported|
|daA1600-60um||Feature not supported|
|daA1920-15um||Feature not supported|
|daA1920-30uc||Feature not supported|
|daA1920-30um||Feature not supported|
|daA1920-160uc||Feature not supported|
|daA1920-160um||Feature not supported|
|daA2500-14lc||Feature not supported|
|daA2500-14lm||Feature not supported|
|daA2500-14uc||Feature not supported|
|daA2500-14um||Feature not supported|
|daA3840-45uc||Feature not supported|
|daA3840-45um||Feature not supported|
|puA1280-54uc||Feature not supported|
|puA1280-54um||Feature not supported|
|puA1600-60uc||Feature not supported|
|puA1600-60um||Feature not supported|
|puA1920-30uc||Feature not supported|
|puA1920-30um||Feature not supported|
|puA2500-14uc||Feature not supported|
|puA2500-14um||Feature not supported|
// Enable the light control mode camera.BslLightControlMode.SetValue(BslLightControlMode_On); //Enumerate the light devices camera.BslLightControlEnumerateDevices.Execute(); //Select light device 1 camera.BslLightDeviceSelector.SetValue(BslLightDeviceSelector_Device1); //Set the maximum current of device 1 to 100 mA camera.BslLightDeviceMaxCurrent.SetValue(100.0); //Set the brightness to 100 % camera.BslLightDeviceBrightness.SetValue(100.0); //Set the operation mode to continuous camera.BslLightDeviceOperationMode.SetValue(BslLightDeviceOperationMode_On);
INodeMap& nodemap = camera.GetNodeMap(); // Enable the light control mode CEnumParameter(nodemap, "BslLightControlMode").SetValue("On"); // Enumerate the light devices CCommandParameter(nodemap, "BslLightControlEnumerateDevices").Execute(); // Select light device 1 CEnumParameter(nodemap, "BslLightDeviceSelector").SetValue("Device1"); // Set the maximum current of device 1 to 100 mA CFloatParameter(nodemap, "BslLightDeviceMaxCurrent").SetValue(100.0); // Set the brightness to 100 % CFloatParameter(nodemap, "BslLightDeviceBrightness").SetValue(100.0); // Set the operation mode to continuous CEnumParameter(nodemap, "BslLightDeviceOperationMode").SetValue("On");
// Enable the light control mode camera.Parameters[PLCamera.BslLightControlMode].SetValue(PLCamera.BslLightControlMode.On); // Enumerate the light devices camera.Parameters[PLCamera.BslLightControlEnumerateDevices].Execute(); // Select light device 1 camera.Parameters[PLCamera.BslLightDeviceSelector].SetValue(PLCamera.BslLightDeviceSelector.Device1); // Set the maximum current of device 1 to 100 mA camera.Parameters[PLCamera.BslLightDeviceMaxCurrent].SetValue(100.0); // Set the brightness to 100 % camera.Parameters[PLCamera.BslLightDeviceBrightness].SetValue(100.0); // Set the operation mode to continuous camera.Parameters[PLCamera.BslLightDeviceOperationMode].SetValue(PLCamera.BslLightDeviceOperationMode.On);
/* Macro to check for errors */ #define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc) GENAPIC_RESULT errRes = 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 maximum 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 continuous */ errRes = PylonDeviceFeatureFromString(hdev, "BslLightDeviceOperationMode", "On"); CHECK(errRes);
You can also use the pylon Viewer to easily set the parameters.