A routine to automatically refine latency offsets of LED blink times using constellation samples. More...

#include "util/u_time.h"
#include "util/u_logging.h"
#include "os/os_threading.h"
#include "tracking/t_time_sync.h"
#include "tracking/t_constellation.h"

Include dependency graph for t_led_sync_refinement.h:

Go to the source code of this file.

Data Structures
struct	t_led_sync_refinement_options
	Options for the LED sync refinement. More...

struct	t_led_sync_sample
	A sample read out from the driver, to pass to the device in question. More...

struct	t_led_sync_refinement

Macros
#define	T_LED_SYNC_DEFAULT_RESYNC_TIME (time_duration_ns)(U_TIME_1S_IN_NS * 5LL)
	10 seconds after last visually seen sample to resync

Enumerations
enum	t_led_sync_refinement_flags { T_LED_SYNC_REFINEMENT_FLAGS_NONE = 0 , T_LED_SYNC_REFINEMENT_FLAGS_BLINK_DURATION = 1 << 0 , T_LED_SYNC_REFINEMENT_FLAGS_OPTICAL_DRIVEN_OFFSET = 1 << 1 , T_LED_SYNC_REFINEMENT_FLAGS_HAS_LATENCY_CAP = 1 << 2 }
	Flags to control the behavior of the LED sync refinement routine. More...

enum	t_led_sync_sample_timestamp_mode { T_LED_SYNC_SAMPLE_TIMESTAMP_MODE_INVALID = 0 , T_LED_SYNC_SAMPLE_TIMESTAMP_MODE_DEVICE_HOST_LATENCY = 1 , T_LED_SYNC_SAMPLE_TIMESTAMP_MODE_HOST_DEVICE_CLOCK_OFFSET = 2 }

enum	t_led_sync_phase { T_LED_SYNC_SEARCH_PHASE_INIT = 0 , T_LED_SYNC_SEARCH_PHASE_FIND_INITIAL_OFFSET = 1 , T_LED_SYNC_SEARCH_PHASE_FIND_RIGHT_EDGE = 2 , T_LED_SYNC_SEARCH_PHASE_FIND_LEFT_EDGE = 3 , T_LED_SYNC_SEARCH_PHASE_REFINE_BLINK_DURATION = 4 , T_LED_SYNC_SEARCH_PHASE_MAINTAIN_OFFSET = 5 }

Functions
int	t_led_sync_refinement_init (struct t_led_sync_refinement refinement, const struct t_led_sync_refinement_options options)

void	t_led_sync_refinement_destroy (struct t_led_sync_refinement *refinement)

void	t_led_sync_push_timing_event (struct t_led_sync_refinement refinement, const struct t_timing_event_camera_exposure_start event)

void	t_led_sync_push_constellation_sample (struct t_led_sync_refinement refinement, const struct t_constellation_tracker_sample sample)

bool	t_led_sync_get_sample (struct t_led_sync_refinement refinement, struct t_led_sync_sample out_sample)

void	t_led_sync_mark_latest_sample_applied (struct t_led_sync_refinement *refinement, timepoint_ns apply_time_ns)

void	t_led_sync_push_host_device_clock_offset (struct t_led_sync_refinement *refinement, time_duration_ns clock_offset_ns)
	Pushes a clock offset to the refinement routine, this is the offset from the host to the device.

Detailed Description

A routine to automatically refine latency offsets of LED blink times using constellation samples.

Author: Beyley Cardellio ep1cm.nosp@m.1n10.nosp@m.n123@.nosp@m.gmai.nosp@m.l.com

Macro Definition Documentation

◆ T_LED_SYNC_DEFAULT_RESYNC_TIME

#define T_LED_SYNC_DEFAULT_RESYNC_TIME (time_duration_ns)(U_TIME_1S_IN_NS * 5LL)

10 seconds after last visually seen sample to resync

Enumeration Type Documentation

◆ t_led_sync_phase

enum t_led_sync_phase

Enumerator
T_LED_SYNC_SEARCH_PHASE_INIT	The initial phase, where we haven't made any adjustments yet.
T_LED_SYNC_SEARCH_PHASE_FIND_INITIAL_OFFSET	Trying to find some offset that gets us in sync at all.
T_LED_SYNC_SEARCH_PHASE_FIND_RIGHT_EDGE	Trying to align the rising edge of the LED blinks with the falling edge of the camera exposure.
T_LED_SYNC_SEARCH_PHASE_FIND_LEFT_EDGE	Trying to align the falling edge of the LED blinks with the rising edge of the camera exposure.
T_LED_SYNC_SEARCH_PHASE_REFINE_BLINK_DURATION	We've found an offset, now we can optimize the blink duration to something that keeps it tracking.
T_LED_SYNC_SEARCH_PHASE_MAINTAIN_OFFSET	We've found an offset and optimized the center of the LED blink to the center of the exposure.

◆ t_led_sync_refinement_flags

enum t_led_sync_refinement_flags

Flags to control the behavior of the LED sync refinement routine.

Enumerator

T_LED_SYNC_REFINEMENT_FLAGS_BLINK_DURATION

Whether to try to optimize the blink duration after finding an offset, to lessen power usage.

T_LED_SYNC_REFINEMENT_FLAGS_OPTICAL_DRIVEN_OFFSET

Whether to lock in a clock offset and have it be driven entirely by the sync refinement, utilizing the optical samples to measure clock skew/offset between the device and host, rather than the driver's normal remote clock synchronization.

Use this flag when the driver's clock tracking is very noisy and is causing LED sync to be unreliable. But currently will cause LED sync to eventually drift as clock skew between the devices takes effect.

T_LED_SYNC_REFINEMENT_FLAGS_HAS_LATENCY_CAP

Whether the device has specified a maximum latency cap.

This prevents the sync refinement from searching parts of the exposure that aren't possible, which can cause refinement to sometimes take longer.

◆ t_led_sync_sample_timestamp_mode

enum t_led_sync_sample_timestamp_mode

Enumerator
T_LED_SYNC_SAMPLE_TIMESTAMP_MODE_DEVICE_HOST_LATENCY	Used when the LED sync refinement is just computing a basic latency offset.
T_LED_SYNC_SAMPLE_TIMESTAMP_MODE_HOST_DEVICE_CLOCK_OFFSET	Used when the LED sync refinement is fully deriving the clock offset, latency included.

Function Documentation

◆ t_led_sync_push_host_device_clock_offset()

void t_led_sync_push_host_device_clock_offset	(	struct t_led_sync_refinement *	refinement,
		time_duration_ns	clock_offset_ns
	)

Pushes a clock offset to the refinement routine, this is the offset from the host to the device.

To convert a timestamp from host -> device domain, you would do: device_timestamp = host_timestamp + clock_offset_ns

References t_led_sync_refinement::driver_host_device_clock_offset_ns, and t_led_sync_refinement::initialized.

Referenced by pssense_add_clock_offset_sample().

Data Structures

Macros

Enumerations

Functions