Day/Night Mode Switching

This topic describes the APIs used to switch between day and night mode and how the internal process works.

Feature description

The switchable day and night mode of an IPC is implemented by turning on or off the infrared cut (IR cut) filter.

• In day mode, the IR cut filter is turned on to block IR and let only the visible light pass through, resulting in the production of color images.

• In night mode, the IR cut filter is turned off to capture visible and IR light, resulting in black-and-white images.

How it works

The component measures ambient light using either the light sensor hardware or software-based image brightness with the image signal processor (ISP). It then determines the current day/night status and notifies other components to control the IR light, IR cut filter, and DSP modes for day/night mode switching.

Development guide

Runtime environment

Components

• tkl_media: used to get the software-based light level. It loads image effects for day/night mode and controls frame rate, as well as switching between the color and black-and-white modes.
• app_sys_msg: used to send the command for switching between day and night mode.
• app_user_event: used to receive and execute the command for switching between day and night mode.
• (Optional) app_sys_ad: used to get the light level from the light sensor hardware.

How to

• Set the initial parameters with TY_SYS_DN_ATTR_S and the callback to invoke when the peripheral parameters are returned to get the light level.
• Call the initialization function ty_sys_dn_switch_init.
• After a successful call, the day/night switching thread is started. It will automatically call the callback to get the current light level and switch between day and night mode.

Data structure

typedef struct TY_SYS_DN_ATTR_
{
    unsigned int u32lock_time;                             ///< The duration to lock the IR cut filter after it is repeatedly switched on/off five times within one minute. The value 0 means not to lock the IR cut filter.
    unsigned int u32trigger_interval;                      ///< The interval to check whether to switch to day/night mode, in seconds. It cannot be set to 0.
    unsigned int u32trigger_times;                         ///< The number of consecutive times day/night mode is repeatedly switched. It cannot be set to 0.
    int s32day2night_threshold;                            ///< Day to night threshold.
    int s32night2day_threshold;                            ///< Night to day threshold.
    int whiteled_patch1;                                   ///< Supplemental white light.
    int whiteled_patch2;                                   ///< Supplemental white light.
    TKL_ISP_DN_MODE_E e32init_mode;                        ///< Initial mode (day mode by default).
    TY_GET_PERIPHERAL_PARAM_CB get_peripheral_param_cb;    ///< (Required) Get the peripheral parameters.
} TY_SYS_DN_ATTR_S;

API description

Initialize day/night mode switching

Initialize day/night mode switching and start the thread accordingly. Be sure to set the input parameter get_peripheral_param_cb and the initial mode. u32trigger_interval and u32trigger_times cannot be set to 0.

/**
 * @brief
 *
 * @param dn_attr
 * @return int
 */
int ty_sys_dn_switch_init(TY_SYS_DN_ATTR_S *dn_attr);

Enable day/night mode switching

/**
 * @brief  Enable day/night mode switching.
 *
 * @param on_off 0-off 1-on
 */
void ty_sys_dn_set_enable(bool on_off);

Get the on/off status of day/night mode

/**
 * @brief  Get the on/off status of day/night mode.
 *
 * @param on_off 0-off 1-on
 */
void ty_sys_dn_get_enable(bool *on_off);

Set the day/night switching mode

/**
 * @brief
 *
 * @param mode day and night mode
 */
void ty_sys_dn_set_config_mode(TKL_ISP_DN_MODE_E mode);

Get the day/night switching mode

/**
 * @brief
 *
 * @param mode
 */
void ty_sys_dn_get_config_mode(TKL_ISP_DN_MODE_E *mode);

Get the current day/night mode

/**
 * @brief
 *
 * @return int
 */
int ty_sys_dn_get_cur_mode(void);

Get the current day/night switching mode

/**
 * @brief  Get the current day/night switching mode.
 *
 * @param mode
 */
void ty_sys_dn_get_cur_mode_config(TKL_ISP_DN_MODE_E *mode);

Initialize the color mode

/**
 * @brief  Initialize the color mode.
 *
 * @param dn_attr
 * @param color_mode_init
 * @return int
 */
int ty_sys_dn_color_mode_init(TY_SYS_DN_ATTR_S *dn_attr, int color_mode_init);

Turn siren on/off

/**
 * @brief  Turn siren on/off.
 *
 * @param status
 * @return int
 */
int ty_sys_siren_switch(int status);

Set the day/night mode threshold

/**
 * @brief  Set the day/night mode threshold.
 *
 * @param s32day2night_threshold  Day to night threshold.
 * @param s32night2day_threshold  Night to day threshold.
 * @return void
 */
void ty_user_dn_threshold_set(int s32day2night_threshold, int s32night2day_threshold);

Set the white light trigger event and the light on-time

/**
 * @brief  Set the white light trigger event and the light on-time.
 *
 * @param human_flag  Human shape event.
 * @param flight_warn_on_off  Sub-device alert detection on/off event.
 * @param whiteled_time  The white light on-time.
 * @return int
 */

void ty_user_dn_light(int human_flag, int flight_warn_on_off, int whiteled_time);

FAQs

Why doesn’t the day/night mode switching work?

• Check if the IR cut filter is powered and works properly.
• Check if the day/night mode threshold is set incorrectly, such as being set to 0 or an extremely high value.

Why is the image completely black in night mode?

• Check if the IR light is on.
• Check the setting of the IR cut filter and ensure that it is turned off in night mode to let the IR light in.

What causes a color shift to red in day mode?

Check the setting of the IR cut filter and ensure that it is turned on in day mode to block IR and let only the visible light pass through.

Why does the illuminance to switch between day and night mode deviate from what is expected?

Check if the day/night mode threshold is correct. Consider the following factors and adjust the threshold if needed.

• Day to night threshold: A lower value makes the IPC switch to night mode at a lower light level. Night to day threshold: A higher value makes the IPC switch to day mode at a higher light level.
• Repeated switching may occur if the day to night and night to day thresholds are identical or the gap between them is too small. It is recommended that the night to day threshold be at least four times greater than the day to night threshold.

Why can’t the IPC switch to day mode in the morning when it is placed near a window or reflective object?

The reflector reflects IR light back into the lens, causing inaccurate raw data to be fed to the algorithm for day/night mode switching. The algorithm determines that the night to day threshold is not met and keeps the IPC in night mode.

First, try removing the reflective object or changing the position of the IPC. If that does not work, consider modifying the day/night mode threshold.

Why does the IPC switch between day and night mode repeatedly and then lock up for over 10 minutes when placed near a reflective object?

The reflector reflects IR light back into the lens, causing inaccurate raw data to be fed to the algorithm for day/night mode switching. Therefore, the IPC repeatedly toggles between day and night mode.

• First, try removing the reflective object or changing the position of the IPC. If that does not work, consider modifying the day/night mode threshold.
• When the IR cut filter is repeatedly switched five times for a short time, the algorithm triggers a 15-minute lockup to ensure the service life of the IR cut filter as it considers the ambient light unstable. The IR cut filter will resume normal functioning after 15 minutes.