Light Control#

The Light Control camera feature allows you to control up to 4 light devices.

The feature is based on the SLP protocol that enables cameras and light devices to communicate directly with each other.

This topic describes the Light Control feature for Basler ace 2, boost R, and dart M cameras. See Transition Period for ace 2, boost R, and dart M Cameras.

Transition Period for ace 2, boost R, and dart M Cameras#

During the transition to the Peripheral Devices Control feature, ace 2, boost R, and dart M cameras may be shipped either with or without the Peripheral Devices Control feature.

As a result, there are two Light Control topics:

• Light Control (ace U/L):
  This topic applies to ace U/L cameras, which continue to use firmware without the Peripheral Devices Control feature. Basler ace U/L cameras will not be migrated to the new firmware architecture.
  It also applies to ace 2, boost R, and dart M cameras that are shipped with firmware without the Peripheral Devices Control feature during the transition period.
• Light Control topic:
  This topic applies to cameras running firmware that includes the Peripheral Devices Control feature. The Light Control feature is described together with the Optic Control feature as these features share common parameters under Peripheral Devices Control.
• Basler ace 2, boost R, and dart M cameras with legacy firmware can be upgraded to a newer firmware version. To migrate a camera to a new firmware, contact Basler Support.

Depending on the light you use, the communication between camera and light varies:

• If you use a Basler Light with ILC (intelligent light control), or a Basler Camera Light, a separate controller isn't required as the controller features are already included.
• If you use a Basler Light without ILC (intelligent light control) or an LED lighting solution by another manufacturer, you need an external controller, e.g., Basler SLP Strobe Controller, to enable the communication between the camera and the light.

Using the Feature#

To use the Light Control feature, you need the following:

• A Basler Light with intelligent light control (ILC)
• A suitable Basler Sync Cable to connect a Basler Light with intelligent light control (ILC) to a camera. The sync cable allows you to attach a light device and, if necessary, a lens, and control them via a single GPIO port of the camera. Which Basler Sync Cable you need depends on the peripheral devices you want to operate.
  For information about the available cable variants and their supported use cases, see Basler Sync Cables.
• A compatible camera running firmware that includes the Peripheral Devices Control feature

Initializing Light Devices#

To initialize your light devices (cameras with Peripheral Devices Control function):

1. Follow the steps described in Preparing Peripheral Devices and Checking and Clearing Errors.
2. Continue with Configuring Light Devices.

Configuring Light Devices#

To configure your light devices:

1. 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 BslLightDeviceErrorStatus parameter returns NoError.

2. If you use a Basler SLP Strobe Controller:
   For information about when to use a Basler SLP Controller, see When is a Basler SLP Strobe Controller Required.

   1. Set the BslLightDeviceControlMode parameter to Current.
   2. Set the BslLightDeviceOperationMode parameter to Off.
   3. 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.

3. 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 may can set the brightness to more than 100 % if you are in strobe mode. This is called overdriving.

4. Set the BslLightDeviceOperationMode parameter to the desired mode:
   • On: Makes the light shine continuously.
   • Strobe: Sets the light to strobe mode.
5. If desired, save the settings in a user set.

Strobe Mode#

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.
• It helps reduce power consumption by illuminating the scene only when required. Because the exposure time is usually much shorter than the time between consecutive images, the average energy usage can be significantly lower than in continuous operation.
• While in strobe mode, you can overdrive the lights by increasing the drive current up to 500 % of the nominal value (depending on the light controller and duty cycle), resulting in increased light output.

To enable strobe mode, select a light device and set the BslLightDeviceOperationMode parameter to Strobe.

Configuring Trigger Signals and Strobe Duration#

Generally, triggering a light device in strobe mode works like this:

• Initially, the light is off.
• The light is turned on by a trigger signal.
• The light stays on for a certain amount of time, which is the strobe duration.
• After the strobe duration has expired, the light is turned off again.

To configure the trigger signals:

1. Set the BslPeripheralTriggerSource parameter to the source that you want to use to turn on the connected lights, e.g., FlashWindow.
2. If applicable, set the BslPeripheralTriggerActivation 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.

To configure the strobe duration:

1. 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.
2. If you chose the Manual strobe mode, set the BslLightDeviceStrobeDuration parameter to the desired strobe duration (in microseconds).

Overdriving Light Devices#

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:

1. If you're using a Legacy Basler Light or a third-party light device:

   1. 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.
   2. 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.

   For legacy Basler Camera Light, the overdrive limit is calculated automatically, and the BslLightDeviceOverdriveLimit parameter is not available.

2. Set the BslLightDeviceBrightness to a value greater than 100.0.

When overdriving a light using an external controller, such as the SLP Strobe Controller, consider the following aspects to avoid damaging the light device:

• If you're unsure about the maximum current your light can withstand in strobe mode, consult the light manufacturer's specifications or contact the manufacturer directly.
• Because the increased current causes the LEDs to generate more heat, allow sufficient cooling time between individual strobe pulses. As a general rule, higher pulse intensities require longer intervals between pulses.
• Take the exposure time into account, as it directly affects the pulse duration and, consequently, the duty cycle.

Safety Features#

The following safety features are implemented in Basler light devices to avoid damaging the hardware:

Safety Features on SLP Light Controllers#

Currents above 2 A in combination with long exposure times and high duty cycles may damage the controller hardware.

To avoid this, you can't set the nominal current (BslLightDeviceMaxCurrent parameter) of Basler SLP Light Controllers to more than 2000 mA.

However, if you're overdriving the device, you may end up with currents above 2 A.

In this case, the camera automatically adjusts the maximum values of certain light device settings. See table below.

Safety Features on Camera Lights#

Documentation for legacy Basler lights without ILC and for discontinued Basler Camera Lights is no longer included in the current Basler Product Documentation. If you need information about these products, refer to the offline documentation of an earlier release, that you can download by clicking here.

GPIO Line Configuration#

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 automaticaly to InOut and the line connection is set to LightControl.

Light Device IDs#

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 BslPeripheralEnumerateDevices or 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.

Changing the Light Device ID#

To change the ID of a light:

1. Make sure the light device is initialized; see Initializing Light Devices.
2. Set the BslLightDeviceOperationMode parameter to Off.
3. Set the BslLightDeviceSelector parameter to the Basler light device whose ID you want to change.
4. Set the BslLightDeviceChangeID parameter to the desired ID, e.g., Device1.
5. 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.
• 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.
• 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.

Overtriggering#

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.
In most cases, the light is in overtrigger because of the ongoing communication (status check) or cooldown in overdrive. Shutting down the light will almost never take longer than 2 µs.

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. In this configuration, the camera acquires 20 frames per second with no gap between consecutive exposures. As a result, the light trigger must occur exactly at the transition between two exposures.

In practice, this operating point is critical because the available timing window is extremely small. While the light pulse itself is generated with highly accurate timing, the light device requires a short amount of time to report that the previous pulse has completed. Due to variations in this status update delay (up to approximately 2 µs), the camera may occasionally trigger the next pulse before the light is reported as ready again. In such cases, the trigger is ignored and the resulting image may appear darker than expected.

Monitoring Overtriggering#

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.

Checking and Clearing Errors#

Basler ace 2, boost R, and dart M cameras can read the following error data from connected light devices:

• The error status can help to correct errors yourself.
• The error code provides additional information about the kind of error and can be evaluated by Basler support.

To check and clear errors:

1. If you have several devices connected:
   1. Check the BslPeripheralErrorSummary or BslLightControlErrorSummary parameter to find out which device is experiencing problems, e.g., Device2.
   2. Set the BslLightDeviceSelector parameter to the device that is experiencing problems.
2. Get the value of the BslLightDeviceErrorStatus parameter and look up its meaning in the Error Statuses table below.
3. If the error status is "Hardware Error":
   1. Execute the BslLightDeviceErrorStatusReadAndClear command.
   2. Get the value of the BslLightDeviceErrorCode parameter and look up its meaning in the Error Codes table below.
   3. Correct the error, if possible.
4. If the error status is not "Hardware Error":
   1. Correct the error, if possible.
   2. Execute the BslLightDeviceErrorStatusReadAndClear command to reset the error status to NoError.

Error Statuses#

The BslLightDeviceErrorStatus parameter can take the following values:

Error Codes (ILC Mode)#

When a new Basler Light is operated in intelligent light control mode (ILC), the BslLightDeviceErrorCode parameter can take the following values:

Error Codes (Other Light Control Modes)#

When a Basler Light is operated in other light control modes, i.e., Trigger Control Mode or Current Control Mode, the BslLightDeviceErrorCode parameter can take the following values:

Sample Code#

ace 2, boost R, dart M Cameras#

// Enable the light control mode
camera.BslPeripheralControlMode.SetValue(BslPeripheralControlMode_On);
//Enumerate the light devices
camera.BslPeripheralEnumerateDevices.Execute();
//Select light device 1
camera.BslPeripheralDeviceSelector.SetValue(BslPeripheralDeviceSelector_Device1);
//Set the nominal current of device 1 to 100 mA
camera.BslLightDeviceCurrent.SetValue(100.0);
//Set the brightness to 100 %
camera.BslLightDeviceBrightness.SetValue(100.0);
//Set the operation mode to Strobe
camera.BslLightDeviceOperationMode.SetValue(BslLightDeviceOperationMode_Strobe);

INodeMap& nodemap = camera.GetNodeMap();
// Enable the light control mode
CEnumParameter(nodemap, "BslPeripheralControlMode").SetValue("On");
// Enumerate the light devices
CCommandParameter(nodemap, "BslPeripheralEnumerateDevices").Execute();
// Select light device 1
CEnumParameter(nodemap, "BslPeripheralDeviceSelector_Device1").SetValue("Device1");
// Set the nominal current of device 1 to 100 mA
CFloatParameter(nodemap, "BslLightDeviceCurrent").SetValue(100.0);
// Set the brightness to 100 %
CFloatParameter(nodemap, "BslLightDeviceBrightness").SetValue(100.0);
// Set the operation mode to Strobe
CEnumParameter(nodemap, "BslLightDeviceOperationMode").SetValue("Strobe");

// Enable the light control mode
camera.Parameters[PLCamera.BslPeripheralControlMode].SetValue(PLCamera.BslPeripheralControlMode.On);
// Enumerate the light devices
camera.Parameters[PLCamera.BslPeripheralEnumerateDevices].Execute();
// Select light device 1
camera.Parameters[PLCamera.BslPeripheralDeviceSelector_Device1].SetValue(PLCamera.BslPeripheralDeviceSelector.Device1);
// Set the nominal current of device 1 to 100 mA
camera.Parameters[PLCamera.BslLightDeviceCurrent].SetValue(100.0);
// Set the brightness to 100 %
camera.Parameters[PLCamera.BslLightDeviceBrightness].SetValue(100.0);
// Set the operation mode to Strobe
camera.Parameters[PLCamera.BslLightDeviceOperationMode].SetValue(PLCamera.BslLightDeviceOperationMode.Strobe);

/* 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, "BslPeripheralControlMode", "On");
CHECK(errRes);
/* Enumerate the light devices */
errRes = PylonDeviceExecuteCommandFeature(hdev, "BslPeripheralEnumerateDevices");
CHECK(errRes);
/* Select light device 1 */
errRes = PylonDeviceFeatureFromString(hdev, "BslPeripheralDeviceSelector_Device1", "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 mode
camera.BslPeripheralControlMode.Value = "On"
# Enumerate the light devices
camera.BslPeripheralEnumerateDevices.Execute()
# Select light device 1
camera.BslPeripheralDeviceSelector_Device1.Value = "Device1"
# Set the nominal current of device 1 to 100 mA
camera.BslLightDeviceCurrent.Value = 100.0
# Set the brightness to 100 %
camera.BslLightDeviceBrightness.Value = 100.0
# Set the operation mode to Strobe
camera.BslLightDeviceOperationMode.Value = "Strobe"

You can also use the pylon Viewer to easily set the parameters.