Skip to navigation
API referenceModule APIClasses

hololink::module::PtpPpsOutputInterfaceV1

View as Markdown

Configure an output pin to pulse at a rate driven by PLL from the PTP PPS signal.

A common use of this output is to drive a camera sensor’s VSYNC input: when multiple HSB units are driven from the PTP of a single host, these output signals have been shown to have less than 1us difference across those HSB devices.

Typical use:

  1. Call enable() with the frame rate to configure the frequency; this does not yet enable the actual output signal.
  2. Configure each sensor for external-trigger operation.
  3. Once all sensors are waiting for their triggers, call start(). This starts driving the actual PPS output.
  4. Call stop() to halt the pulses, and disable() when the output is no longer needed.

The start(), stop() and is_enabled() operations are inherited from VsyncInterfaceV1. Code that needs only those can obtain the same object as a VsyncInterfaceV1, without knowing which kind of source is driving the trigger.

#include <hololink/module/ptp_pps_output.hpp>

Inherits from: hololink::module::VsyncInterfaceV1 (public), hololink::module::ConfigurableService< PtpPpsOutputInterfaceV1 > (public)

Methods

enable

virtual hololink_module_status_t hololink::module::PtpPpsOutputInterfaceV1::enable(
    unsigned frequency_hz
)

Configure the trigger output to produce pulses at the given rate.

After a successful call is_enabled() returns true. This only configures the output; pulses are not produced until start() is called.

Calling this again with the frequency already configured succeeds and changes nothing. Asking for a different frequency while the output is enabled is rejected.

Returns: HOLOLINK_MODULE_OK on success. HOLOLINK_MODULE_INVALID_PARAMETER if the hardware does not support frequency_hz, or the output is already enabled at a different frequency.

Parameters

frequency_hz
unsigned

Pulse rate, in Hz.

disable

virtual hololink_module_status_t hololink::module::PtpPpsOutputInterfaceV1::disable()

Remove the trigger output configuration.

Afterwards is_enabled() returns false. Does nothing if the output is not enabled.

Returns: HOLOLINK_MODULE_OK on success, or an error status.

is_enabled

virtual bool hololink::module::PtpPpsOutputInterfaceV1::is_enabled() const

Whether the source has been configured to produce pulses.

Camera drivers consult this while configuring, to decide whether to put their sensor in external-trigger mode. start() and stop() are only meaningful while this is true.

Returns: true if the source is configured; false otherwise.

start

virtual hololink_module_status_t hololink::module::PtpPpsOutputInterfaceV1::start()

Begin generating trigger pulses.

The application normally calls this once, after every camera has been put into external-trigger mode and is waiting, so that the first pulse reaches all of them at the same time. Calling it while pulses are already being generated has no effect. If the source is not enabled (see is_enabled()), no pulses are generated.

Returns: HOLOLINK_MODULE_OK on success, or an error status.

stop

virtual hololink_module_status_t hololink::module::PtpPpsOutputInterfaceV1::stop()

Stop generating trigger pulses.

The source remains configured, so start() can resume the pulses. Calling it when no pulses are being generated has no effect.

Returns: HOLOLINK_MODULE_OK on success, or an error status.

module

std::shared_ptr<Module> hololink::module::ServiceBase::module() const

The Module that this service was published from.

The service holds no strong reference to its Module, so this does not extend the Module’s lifetime.

Returns: The owning Module, or an empty pointer if the service has not been published or its Module no longer exists.

configure

virtual void hololink::module::ConfigurableService<PtpPpsOutputInterfaceV1>::configure(
    const EnumerationMetadata &
)

Use metadata contents to initialize this instance.

This routine is guaranteed to be called the first time a call to get_service(metadata) is called on a specific service instance.

Static methods

get_service

inline
static std::shared_ptr<VsyncInterfaceV1> hololink::module::Service<VsyncInterfaceV1>::get_service(
    std::shared_ptr<Module> module,
    const char *instance_id,
    bool allow_null = false
)

Type-safe way to fetch a std::shared_ptr to an instance of <Derived> from a Module.

Note that Module usually caches instances, it’s likely that calls to get_service with the same locator_id will return pointers to the same implementation object.

Returns: A shared pointer to the service instance.

Parameters

module
std::shared_ptr<Module>

Is the shared object that owns the instance we wish to fetch

instance_id
const char *

Names the specific object, usually expressed as a set of “name=value;…” pairs, as defined by the implementations themselves. This name is normally fetched by calling Derived::locator_id(enumeration_metadata).

allow_null
boolDefaults to false

The default value of false causes this routine to throw a std::runtime_error if the service cannot be found within the module; this would be expected to terminate the calling program. If the application wants to handle the error, pass in true here and get_service will return nullptr when this module doesn’t provide the requested service.

for_each_type_id

static bool hololink::module::Service<VsyncInterfaceV1>::for_each_type_id(
    Callback &&cb
)

Iterate over every type_id supported by this instance.

The callback signature is bool(const char*) — returning false halts the walk; true continues. Iteration is depth-first, so you’ll see the most specific implementation types first.