Light Control Feature Set#

The Light Control feature set allows you to control up to 4 light devices via the pylon software.

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 (available from December 2019). 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#

  1. If you haven't done so yet, connect the controller and the light.
  2. Enable the Polling option in the pylon Viewer.
  3. Set the BslLightControlMode parameter to On.
    The BslLightControlSource parameter 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.
  4. Execute the BslLightControlEnumerateDevices command.
  5. If you have several Basler lights or light controllers in your environment, set the BslLightDeviceSelector parameter to the device that you want to configure.
    Make sure that there are no light device ID conflicts.
  6. Set the BslLightDeviceMaxCurrent parameter to the maximum current rating of your light.
    This ensures that your light will not get damaged and that you can safely use the whole current range of your light using the BslLightDeviceBrightness parameter.
    You can only change the BslLightDeviceMaxCurrent parameter value, when the BslLightDeviceOperationMode parameter is set to Off.
  7. Set the BslLightDeviceBrightness parameter 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 BslLightDeviceMaxCurrent parameter. 50 % will reduce the current by a factor of 2. The controller doesn't use pulse width modulation (PWM).
  8. Set the BslLightDeviceOperationMode parameter 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 BslLightDeviceStrobeMode and BslLightDeviceStrobeDuration parameters.

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 10 A, which increases the brightness of your light. Before you do so, read the instructions in the Overdrive Mode section.

If you have set the BslLightDeviceOperationMode parameter to Strobe, use the BslLightControlTriggerMode parameter to determine how to trigger the light. Depending on your camera model, different trigger modes are available:

Info

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 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 BslLightDeviceStrobeMode parameter.

  • Automatic: The duration of the individual strobe pulses is controlled by the ExposureTime parameter. The strobe lasts for the duration of the exposure time that you have specified.
  • Manual: You can define the duration of the individual strobe pulses yourself using the BslLightDeviceStrobeDuration parameter.

Info

If you're using the Trigger Width exposure mode, the Sequencer feature, or any of the camera's auto functions (e.g., Auto Exposure, Auto Gain) you have to use the Manual strobe mode.

Info

The camera uses the same line for triggering the light and transmitting any changes of light control parameter settings. As parameter changes take precedence, 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.

Overdrive Mode#

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:

  • 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.
  • Be careful not to accidentally switch to continuous light operation. The overdrive current may damage your light immediately.
  • 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. Normally, it's much less than the 10 A that the Basler SLP Strobe Controller can supply.
  • Consider the exposure time as this affects the length and the duty cycle of the pulses.

Changing the Light Device ID#

To change the ID of a light:

  1. Set the BslLightControlMode parameter to On.
  2. Set the BslLightDeviceOperationMode parameter to Off.
  3. Set the BslLightDeviceSelector parameter to the Basler light / controller whose ID you want to change.
  4. Set the BslLightDeviceChangeID parameter to the desired value.
    The ID will be changed immediately.

Info

Using More Than One Light Controller

When using more than one light controller, you have to make sure that their IDs are all different. Using controllers with identical IDs will cause communication errors. Duplicate IDs can occur, if you're connecting new controllers for the first time because all controllers are shipped with the light device ID set to 7. It can also occur when connecting existing controllers from another system as light device IDs are remembered by the controller once they have been set. The best way to prevent conflicts, is to connect controllers one after the other and always assign a new and unique ID after having connected a controller.

Troubleshooting#

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#

Checking and clearing errors is an iterative process, depending on how many errors have occurred.

  1. To check the last error that has occurred, get the value of the BslLightDeviceLastError parameter.
  2. Correct the corresponding error.
  3. To delete the last error from the list of errors, execute the BslLightDeviceClearLastError command.
  4. Continue getting and deleting the last error until the BslLightDeviceLastError parameter shows NoError.

Available Error Codes#

Value Meaning
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.

Power-Cycling the Controller#

After power-cycling the controller, it can take up to five minutes for the controller to become available again. 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 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.

Specifics#

Show all camera models

Camera Model Available Light Control Trigger Modes
a2A1920-51gcBAS Feature not supported
a2A1920-51gmBAS Feature not supported
a2A1920-160ucBAS Feature not supported
a2A1920-160umBAS Feature not supported
a2A3840-13gcBAS tbd
a2A3840-13gmBAS tbd
a2A3840-45ucBAS tbd
a2A3840-45umBAS tbd
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
acA640-300gc Exposure Active
acA640-300gm Exposure Active
acA640-750uc Exposure Active
acA640-750um Exposure Active
acA720-290gc Exposure Active
acA720-290gm Exposure Active
acA720-520uc Exposure Active
acA720-520um Exposure Active
acA780-75gc Feature not supported
acA780-75gm Feature not supported
acA800-200gc Exposure Active
acA800-200gm Exposure Active
acA800-510uc Exposure Active
acA800-510um Exposure Active
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
acA1300-75gc Exposure Active
acA1300-75gm Exposure Active
acA1300-200uc Exposure Active
acA1300-200um Exposure Active
acA1440-73gc Exposure Active
acA1440-73gm Exposure Active
acA1440-220uc Exposure Active
acA1440-220um Exposure Active
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-40gc Exposure Active
acA1920-40gm Exposure Active
acA1920-40uc Exposure Active
acA1920-40ucMED Feature not supported
acA1920-40um Exposure Active
acA1920-40umMED Feature not supported
acA1920-48gc Exposure Active
acA1920-48gm Exposure Active
acA1920-50gc Exposure Active
acA1920-50gm Exposure Active
acA1920-150uc Exposure Active
acA1920-150um Exposure Active
acA1920-155uc Exposure Active
acA1920-155ucMED Feature not supported
acA1920-155um Exposure Active
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-35gc Exposure Active
acA2040-35gm Exposure Active
acA2040-55uc Exposure Active
acA2040-55um Exposure Active
acA2040-90uc Feature not supported
acA2040-90um Feature not supported
acA2040-90umNIR Feature not supported
acA2040-120uc Exposure Active
acA2040-120um Exposure Active
acA2440-20gc Exposure Active
acA2440-20gm Exposure Active
acA2440-35uc Exposure Active
acA2440-35ucMED Feature not supported
acA2440-35um Exposure Active
acA2440-35umMED Feature not supported
acA2440-75uc Exposure Active
acA2440-75ucMED Feature not supported
acA2440-75um Exposure Active
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-20gc Exposure Active
acA2500-20gcMED Feature not supported
acA2500-20gm Exposure Active
acA2500-20gmMED Feature not supported
acA2500-60uc Exposure Active
acA2500-60um Exposure Active
acA3088-16gc Exposure Active
Flash Window
acA3088-16gm Exposure Active
Flash Window
acA3088-57uc Exposure Active
Flash Window
acA3088-57um Exposure Active
Flash Window
acA3800-10gc Feature not supported
acA3800-10gm Feature not supported
acA3800-14uc Feature not supported
acA3800-14um Feature not supported
acA4024-8gc Exposure Active
Flash Window
acA4024-8gm Exposure Active
Flash Window
acA4024-29uc Exposure Active
Flash Window
acA4024-29um Exposure Active
Flash Window
acA4096-11gc Exposure Active
acA4096-11gm Exposure Active
acA4096-30uc Exposure Active
acA4096-30ucMED Feature not supported
acA4096-30um Exposure Active
acA4096-30umMED Feature not supported
acA4096-40uc Exposure Active
acA4096-40ucMED Feature not supported
acA4096-40um Exposure Active
acA4096-40umMED Feature not supported
acA4112-8gc Exposure Active
acA4112-8gm Exposure Active
acA4112-20uc Exposure Active
acA4112-20ucMED Feature not supported
acA4112-20um Exposure Active
acA4112-20umMED Feature not supported
acA4112-30uc Exposure Active
acA4112-30ucMED Feature not supported
acA4112-30um Exposure Active
acA4112-30umMED Feature not supported
acA4600-7gc Feature not supported
acA4600-10uc Feature not supported
acA5472-5gc Exposure Active
Flash Window
acA5472-5gm Exposure Active
Flash Window
acA5472-17uc Exposure Active
Flash Window
acA5472-17um Exposure Active
Flash Window
boA4096-93cc Feature not supported
boA4096-93cm Feature not supported
boA4112-68cc Feature not supported
boA4112-68cm 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
daA2500-14lc Feature not supported
daA2500-14lm Feature not supported
daA2500-14uc Feature not supported
daA2500-14um Feature not supported
daA2500-60mc 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

Sample Code#

// 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
CEnumerationPtr(nodemap.GetNode("BslLightControlMode"))->FromString("On");
// Enumerate the light devices
CCommandPtr(nodemap.GetNode("BslLightControlEnumerateDevices"))->Execute();
// Select light device 1
CEnumerationPtr(nodemap.GetNode("BslLightDeviceSelector"))->FromString("Device1");
// Set the maximum current of device 1 to 100 mA
CFloatPtr(nodemap.GetNode("BslLightDeviceMaxCurrent"))->SetValue(100.0);
// Set the brightness to 100 %
CFloatPtr(nodemap.GetNode("BslLightDeviceBrightness"))->SetValue(100.0);
// Set the operation mode to continuous
CEnumerationPtr(nodemap.GetNode("BslLightDeviceOperationMode"))->FromString("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);
// Enable the light control mode
Pylon.DeviceFeatureFromString(hdev, "BslLightControlMode", "On");
// Enumerate the light devices
Pylon.DeviceExecuteCommandFeature(hdev, "BslLightControlEnumerateDevices");
// Select light device 1
Pylon.DeviceFeatureFromString(hdev, "BslLightDeviceSelector", "Device1");
// Set the maximum current of device 1 to 100 mA
Pylon.DeviceSetFloatFeature(hdev, "BslLightDeviceMaxCurrent", 100.0);
// Set the brightness to 100 %
Pylon.DeviceSetFloatFeature(hdev, "BslLightDeviceBrightness", 100.0);
// Set the operation mode to continuous
Pylon.DeviceFeatureFromString(hdev, "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.